长时Agent交接班实战：基于Anthropic方案

### 长时Agent的稳定性，关键不在模型，而在“交接” Anthropic工程团队最近发布了一篇文章《Effective harnesses for long-running agents》。乍看之下，文章并未聚焦模型参数或提示词技巧，而是把一个更实际、也更棘手的核心问题摆上台面：当Agent需要连续运行数小时，甚至跨越多个上下文窗口时，如何确保项目不会越做越混乱，最终变成一团乱麻？ 只要任务复杂一点，几类典型故障就会迅速暴露： * **一次想做太多**：Agent倾向于一口气消化整个项目，结果上下文耗尽，留下一堆半成品。 * **上下文断联**：新session接手时，面对的只有上一轮留下的零散碎片和未完成状态，几乎需要从头理解一遍。 * **过早收工**：看到项目里已经有了页面、功能和提交记录，新session很容易误判“差不多完成了”，于是草草收尾。 * **虚假验证**：没有执行真正的端到端测试，就把功能标记为“已完成”。 文章将问题根源直指 **harness（工具链/框架）**。长时Agent的稳定性，本质上是一个跨session的交接难题。每一次新的session，都像“一个刚入职的新员工”。如果没有清晰、完整的交接文档，它只能靠猜测来推进。 ### 文章要解决的核心问题 Claude Agent SDK本身内置了压缩整理和上下文管理能力，理论上足够支持Agent持续运行。但Anthropic在内部实验中反复验证：仅靠这些基础能力远远不够。 他们发现，即便是在编码任务上表现强劲的模型，面对类似“做一个claude.ai的克隆”这样的高层级任务，一旦跨越多个上下文窗口，依然会掉进两个常见陷阱。 * **第一类问题：一次做太多。** 模型试图一次性完成整个应用，结果上下文耗尽，留下一套半成品的实现和一堆模糊的状态说明。 * **第二类问题：过早收工。** 后续session接手时，看到项目里已有页面、功能和代码提交，就轻易给出“差不多了”的错误判断。 这两个问题叠加，长任务几乎必然跑偏。因此，文章的核心目标非常明确，只有两个： 1. **第一步：** 先把初始环境搭建好，让它处在适合分轮推进的状态。 2. **第二步：** 确保每一轮session只做增量工作，并且将状态交接得清清楚楚。 ### Anthropic的解法：拆成两个Agent角色 整套harness被拆分为两个角色，分工明确。 #### 1. Initializer Agent（初始化Agent） 这个角色只在第一轮运行。它不负责长期开发，而是负责为后续所有session准备“基础设施”和“交接材料”。文章重点提及几个关键产物： * `init.sh`（环境启动脚本） * `claude-progress.txt`（进度记录文件） * 一份结构化的feature list（功能清单） * 一个初始的git commit 这一步的价值在于，打好后续几十轮session都要依赖的“地基”。 #### 2. Coding Agent（编码Agent） 这个角色负责后面每一轮的增量开发。它不再需要重新理解整个项目，而是遵循一套固定的流程做增量推进： * 先读取交接材料。 * 确认当前环境正常。 * 只挑选一个feature来执行。 * 完成后留下清晰的git commit和进度记录。 文章里有一句话点明了整个设计的核心：“每一轮session的目标不是‘完成产品’，而是‘完成这一轮交接前那个小目标’。” ### 五大具体做法 #### 1. 用结构化文件管理Feature List Anthropic的做法是，让initializer agent将用户最初的需求展开成一份完整的feature list。在文章提到的`claude.ai`克隆例子中，这份清单最终超过200个功能项。每一项都包含步骤描述，且初始统一标记为`passes: false`。 这一步直接解决了两个痛点：Agent不再凭感觉判断“项目差不多了”；每一轮session都清楚接下来还有哪些具体功能等待实现并通过测试。文章特别指出，他们最终选择JSON格式而非Markdown。原因很直接：模型在处理JSON时，更不容易随意改坏结构或擅自删除需求。很多人习惯给Agent写长篇Markdown任务清单，对人友好，但对会反复编辑文件的模型而言，结构化格式反而更稳定。 #### 2. 每轮只做一个Feature 这是文中另一个关键约束。前面的失败案例，根源都是“做太多”。所以Anthropic把规则写死：每一轮coding agent只做一个feature。将粒度压到“每轮只推进一个点”，session的目标变得极其清晰： * 开始前知道自己要补哪一项。 * 过程中不易发散。 * 结束时更容易留下干净的状态。 Agent负责的不是“完成产品”，而是“完成这一轮交接前的一个小目标”。 #### 3. 进度写进文件，代码写进Git Anthropic要求coding agent在每轮结束前必须完成两件事： * 写git commit。 * 更新`claude-progress.txt`。 这两个工具分工明确：git commit负责记录代码状态；`claude-progress.txt`负责记录这一轮做了什么、修了什么、还剩什么。下一轮session开始时，不需要在目录里乱翻，也不用猜上一轮做到哪了，只要读progress文件，再扫几条git log，就能快速接上。许多开发者习惯要求Agent“写完代码记得提交”，但很少要求它把对下一轮有用的状态说明也写下来。没有这层交接文本，下一轮session往往要花费大量token重新调查现场。 #### 4. 每轮开工前先做一套固定的“上岗动作” 文章专门列出了coding agent每轮开始时必须执行的一系列检查动作： 1. 运行`pwd`确认当前目录。 2. 读progress文件。 3. 读feature list。 4. 看git log。 5. 找到`init.sh`。 6. 启动开发环境。 7. 先做一次基础验证。 不是一上来就继续写代码，而是先确认：“我在哪个目录？”“上一轮做到哪了？”“当前基础功能是否还活着？”文章提到，在`claude.ai`克隆的例子中，agent每轮都会先把本地服务跑起来，再用浏览器自动化发一条消息，确认最基础的聊天流程没有损坏。因为如果项目已经处于坏状态，在此基础上叠加功能只会让问题更严重。 #### 5. 必须做端到端测试 这是文中另一条重要约束。Anthropic观察到，如果没有明确要求，模型常常会把以下行为当成“已经测试过了”： * 跑单元测试。 * 用`curl`调一下开发服务器。 * 看代码逻辑觉得没问题。 但这些都不等同于真正的端到端验证。在Web app场景下，他们发现一旦明确要求Claude使用浏览器自动化工具，按真实用户路径去点击、输入、查看页面，效果会显著提升。这也是文章反复提及Puppeteer MCP的原因。当然，Anthropic也承认浏览器工具和视觉能力仍有盲区——比如浏览器原生alert modal，Claude通过Puppeteer MCP就看不到。这恰恰说明文章想表达的核心：如果你想让长时Agent跑得更稳，端到端测试必须被纳入harness，而不是一个可有可无的附加项。 ### 读完后的核心收获 表面上最显眼的是“initializer agent + coding agent”这个二分法。但更容易落地到日常工作流中的，其实是后面那套工程纪律： * **需求外部化**：用结构化的feature list管理。 * **进度外部化**：用progress文件和git日志记录。 * **环境启动方式外部化**：用`init.sh`脚本固化。 * **每轮开始先重新确认现场**：通过固定的检查流程。 * **每轮结束必须留下可交接状态**：保证下一轮能顺利接班。 换言之，长时Agent想跑稳，靠的是“让每一轮都能顺利接班”。这套思路放到Claude Code、Codex、OpenClaw等工具中同样适用。为什么很多长任务做到后面越来越乱？因为没有稳定的交接文件。为什么下一轮session总要花大量时间调查现场？因为上轮没有留下结构化状态。为什么Agent经常做着做着就宣布完成？因为没有一份独立于当前上下文的feature checklist。 文章没有把问题继续往模型能力上推，而是老老实实地回到harness设计本身，给出了一个非常务实、可操作的方案。 ### 边界与展望 Anthropic在文末也留下了几个清晰的边界。 * 首先，这套方法目前主要围绕全栈Web app开发验证出来。能否无缝迁移到科研或金融建模等其他长任务场景，文章的说法仍是“有可能”，而非“已经证明”。 * 其次，单一通用coding agent是否就是最优解，文章没有下定论。它明确提到，多agent架构也许能做得更好，比如引入专门的testing agent、QA agent、cleanup agent。 * 最后，浏览器自动化和视觉识别仍然不是完整解法，某些类型的bug，今天的工具链依然会漏掉。 所以，这篇文章更适合被理解为一套已经在工程实践中验证过、能明显提升长时Agent稳定性的**harness设计范本**。它还不是终局，但已经足够具体，也足够有启发性。 如果你平时也在跑长任务Agent，这篇文章最终留下的，或许是这五个关键的外部化对象：**feature list、progress file、`init.sh`、git commit、以及每轮固定的开工检查。** 它们合在一起，才是长时Agent能跨越多个上下文窗口，稳定前进的真正基础。 --- *原文标题：`Effective harnesses for long-running agents` | 发布日期：`2025-11-26` | 来源：Anthropic Engineering*

来源：互联网