长任务代理的有效 Harness¶

原文链接：https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents [62]
发布时间：2025-11-26
作者：Justin Young

长任务的核心难题不是能力，而是跨上下文窗口的连续性与状态传递。[62]

长任务代理的问题¶

Agent SDK 能通过 compaction 等机制延长任务寿命，但这仍不足以让代理稳定完成长任务。现实中，代理会出现两类典型失败：[62]

一次性“写完”冲动：代理尝试在一个上下文窗口内完成全部功能，结果中途耗尽上下文，留下半成品；后续会话只能猜测已完成内容。
过早宣告胜利：后续会话看到已有进展就判定任务结束，未完成的需求被忽略。

因此问题被拆成两部分：

初始化阶段：先把“任务全貌”与工程基础搭好。
增量阶段：每轮只推进小步，并在结束时留下清晰可接手的状态。[62]

解决方案：初始化代理 + 编码代理¶

Anthropic 采用双代理结构：

Initializer agent：首次会话执行初始化，创建 init.sh、进度文件与初始 git commit。
Coding agent：后续会话只做增量进展，并在结束时写入结构化更新。[62]

核心洞察是：通过进度文件与 git 历史，使新会话能快速理解“当前状态”。这模仿了人类工程师交接的方式。[62]

环境管理¶

功能清单（Feature list）¶

为防止“一次性完成”或“提前结束”，初始化代理会把需求扩展成完整功能清单，并将每项标记为失败（passes: false）。这使后续代理有清晰目标。[62]

示例（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",
    "Check that chat area shows welcome state",
    "Verify conversation appears in sidebar"
  ],
  "passes": false
}

编码代理只能修改 passes 字段，禁止删除或改写测试条目。实验发现 JSON 比 Markdown 更不易被模型误改。[62]

增量推进¶

每轮只实现一个功能项，然后提交 git 记录并更新进度文件。这样既减少“猜测前情”的成本，又能依赖 git 回滚坏改动。[62]

测试¶

如果没有明确要求，代理常会“写完就算”，甚至局部测试后仍错误地标记完成。强制使用端到端测试（例如通过浏览器自动化）能显著提升质量。[62]

新会话如何快速上手¶

每轮开始时执行固定步骤：

pwd 确认目录。
阅读 git 日志和进度文件。
查看功能清单，选择最高优先级未完成项。
运行 init.sh 启动服务并做一次基础验证测试。

这样能保证代理不会在破损状态上继续加错，而是先恢复到可工作的基线。[62]

失败模式与解决方案¶

问题	初始化代理行为	编码代理行为
过早宣告项目完成	建立功能清单 JSON	开始时读取清单，挑选一个未完成项
环境混乱、进度不清	初始化 git repo 与进度记录	先读进度与 git log，并运行基础测试；结束时提交 commit 与更新进度
过早标记功能完成	建立功能清单	只有在充分测试后才标记通过
不知道如何运行项目	写 `init.sh`	会话开始先读 `init.sh`

未来方向¶

仍有开放问题：单一通用编码代理是否最优？多代理分工（测试、QA、代码清理等）可能带来更好表现。此外，当前 demo 偏向全栈 Web 应用，未来需要推广到科研、金融等长任务场景。[62]

致谢¶

作者 Justin Young；感谢 David Hershey、Prithvi Rajasakeran、Jeremy Hadfield、Naia Bouscal、Michael Tingley、Jesse Mu、Jake Eaton、Marius Buleandara、Maggie Vo、Pedram Navid、Nadine Yasser、Alex Notov 的贡献。本工作来自多支团队协作，尤其是 code RL 与 Claude Code 团队。[62]

脚注¶

文中称为“两个代理”仅因初始提示不同；系统提示、工具与整体 harness 相同。[62]