### 长时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*