原文：Effective harnesses for long-running agents | Anthropic Engineering Blog | 2025.11.26

导语

Agent 能力越来越强，开发者开始让它们承担需要持续数小时甚至数天的复杂任务。但一个核心问题摆在面前：

Agent 必须在离散的会话中工作，而每个新会话开始时，对之前发生的事情一无所知。

想象一个软件项目的工程师轮班工作，每个新工程师对上一班次发生的事情一无所知。这就是长时间运行 Agent 面临的困境。

---

一、两种典型的失败模式

失败模式 1：一次做太多

Agent 试图一次性完成整个应用程序，用完上下文窗口后，留给下一个会话一个功能实现了一半且没有文档的烂摊子。

失败模式 2：过早宣布胜利

在已经构建了一些功能之后，后续的 Agent 实例四处查看，看到已有进展，就宣布工作完成了。

---

二、双 Agent 解决方案

初始化 Agent

第一个会话使用专门的提示，要求模型设置初始环境：

• init.sh 脚本：可以运行开发服务器
• claude-progress.txt：记录 Agent 所做的工作
• feature_list.json：全面的功能需求文件
• 初始 git 提交

编码 Agent

每个后续会话要求模型取得增量进展：

1. 运行 pwd 确认工作目录
2. 阅读 git 日志和进度文件
3. 阅读功能列表，选择最高优先级的未完成功能
4. 实现功能并测试
5. 提交 git 并更新进度文件

---

三、关键设计要素

功能列表（Feature List）

初始化 Agent 编写一个全面的功能需求文件（JSON 格式），扩展用户的初始提示：

{
    "category": "functional",
    "description": "New chat button creates a fresh conversation",
    "steps": [
      "Navigate to main interface",
      "Click the 'New Chat' button",
      "Verify a new conversation is created"
    ],
    "passes": false
}

使用 JSON 而非 Markdown，因为模型不太可能不当更改 JSON 文件。

增量进展

• 一次只处理一个功能
• 通过 git 提交记录进度
• 在进度文件中写入摘要
• 使用 git 恢复错误的代码更改

端到端测试

明确要求 Agent 像人类用户那样使用浏览器自动化工具进行测试。在构建 Web 应用时，使用 Puppeteer MCP 服务器进行端到端验证。

---

四、失败模式与解决方案对照表

问题	初始化 Agent 行为	编码 Agent 行为
过早宣布完成	设置功能列表 JSON	阅读功能列表，选择单个功能
环境有错误或缺文档	写 git 仓库和进度笔记	开始前阅读进度文件和 git 日志
过早标记功能完成	设置功能列表	仔细测试后才标记"通过"
花时间弄清如何运行	编写 init.sh	阅读 init.sh 后启动

---

五、核心洞察

关键见解是找到一种方法，让 Agent 在从新的上下文窗口开始时能够快速理解工作状态。

这通过 claude-progress.txt 文件和 git 历史记录来实现。这些做法的灵感来自于了解有效软件工程师每天所做的工作。

---

六、未来方向

• 单个通用编码 Agent vs 专门的多 Agent 架构（测试 Agent、QA Agent、代码清理 Agent）
• 从 Web 应用开发推广到科学研究、金融建模等领域

---

读后感

这篇文章最有价值的洞察是：像管理一个工程师团队一样管理 Agent。

功能列表、进度文件、git 提交——这些不是什么新发明，而是软件工程师每天都在用的工作方法。最好的 Agent 框架设计，就是把最好的人类工程实践编码化。