Effective Harnesses for Long-Running Agents（长时运行 Agent 的有效 Harness）

当 AI Agent 处理跨越多个上下文窗口的复杂项目时，会面临连续性和一致性的难题——每个新会话开始时都对之前的工作毫无记忆。Anthropic 设计了一套由「初始化 Agent + 迭代编码 Agent」组成的两段式架构，让 Claude 能在大型软件项目上持续取得进展而不丢失上下文。

文章用了一个类比：想象一群软件工程师轮班工作，但每个人上班时对前一班的工作完全没有记忆——如果没有显式的知识传递机制，项目无法保持连贯。

两种典型失败模式

1. 过度野心（Over-ambition）： Agent 试图在单个上下文窗口内完成整个应用，导致实现不完整、代码无文档，后续会话浪费大量精力从损坏状态中恢复。
2. 过早宣告完成（Premature completion）： 后续的 Agent 实例看到部分已完成的功能，就错误地宣布整个项目已经完成，尽管规格说明远未实现。

架构方案：两段式 Agent 框架

初始化 Agent（仅第一个会话）

• 通过专门的提示词创建基础设施
• 生成 init.sh 脚本用于启动开发环境
• 建立 claude-progress.txt 文件用于记录会话进度
• 创建初始 git commit 记录基线状态
• 构建完整的功能规格清单

编码 Agent（后续所有会话）

• 接收强调「增量进展」的标准提示词
• 一次只做一个功能，按顺序推进
• 保持代码处于干净、可交付的状态
• 通过结构化更新记录进度
• 在标记功能完成前进行严格的端到端测试

两种 Agent 的区别仅在于初始提示词，其余系统基础设施完全相同。

环境管理组件

功能清单（Feature List）

初始化 Agent 用 JSON 格式生成完整的功能规格。在 Claude.ai 克隆项目的演示中包含 200+ 个功能项，初始全部标记为 "failing"。每个功能条目结构类似：

{
    "category": "functional",
    "description": "New chat button creates fresh conversation",
    "steps": ["...详细步骤..."],
    "passes": false
}

为什么用 JSON 而不是 Markdown？ 因为模型更不容易随意修改或覆盖 JSON 文件。同时明确禁止 Agent 删除功能条目，确保开发覆盖完整。

增量推进策略

• 不追求一次性完成所有功能，而是逐个功能顺序开发
• 每次变更都要用有描述性的 git commit 提交
• 更新进度文档，使问题变更可回滚、可恢复到已知稳定状态

测试机制

Claude 起初难以识别未完成的功能实现。提供浏览器自动化工具（Puppeteer MCP server）后效果显著改善——Agent 像真人用户一样点击按钮、验证视觉变化、确认数据持久化，能发现纯代码审查发现不了的 bug。

标准会话工作流

每个编码会话遵循固定的初始化流程：

1. 确认当前工作目录
2. 查看 git 日志和进度文档
3. 找出优先级最高的未完成功能
4. 执行 init.sh 启动开发服务器
5. 运行基线端到端测试确认应用稳定
6. 开始专注开发选定的功能

典型会话开场是「我先了解一下项目当前状态」，然后立即运行诊断命令，避免浪费 token 重新摸索项目状况。

失败模式与对策一览

关键洞察

• 借鉴人类工程实践： 整个框架反映了优秀软件工程师的日常习惯——清晰的文档、带说明的 commit、保持可合并状态、验证后再算完成。
• JSON 优于 Markdown： 关键跟踪文件用结构化数据格式，减少模型意外破坏项目元数据。
• 像人一样测试： 明确要求 Agent 用真实 UI 交互（而非仅单元测试）来验证，能发现代码检查遗漏的 bug。
• 上下文感知： 利用 git 历史和进度文件，Agent 能快速了解项目状态而不用瞎猜。

成果验证

该方案使 Claude Opus 4.5 成功构建了一个可运行的 Claude.ai 克隆——一个跨越多个上下文窗口、包含数十个功能的完整全栈 Web 应用。

未解问题与未来方向

• 多 Agent 架构： 专门化的 Agent（测试 Agent、QA Agent、代码清理 Agent）是否会优于单一通用 Agent？
• 领域泛化： 当前优化针对全栈 Web 开发，在科研、金融建模等长周期自主任务上的应用尚未探索。
• 工具局限： Claude 无法通过当前自动化工具感知浏览器原生 alert 弹窗，依赖这些 UI 元素的功能容易有 bug。

结论

长时运行的 Agent 需要超越原始上下文窗口管理的显式架构支持。通过功能规格、进度文档、版本控制集成和严格测试协议等环境脚手架，开发者可以让 Claude 在跨会话的长期项目中持续高效工作。该框架把 Agent 的局限转化为可管理的工作流模式，同时保持代码质量和项目连贯性。