Anthropic 长跑 Agent 模式解析

核心问题:上下文窗口有限,agent 如何在离散会话中连续开发一个项目?Anthropic 用「初始化 Agent + 编码 Agent」两阶段方案回答,配套 feature list、进度文件与 git commit checkpoint。

本文基于 Anthropic Engineering 博客 2025-11-26 的《Effective harnesses for long-running agents》(作者 Justin Young),该模式后续已被官方 Agent SDK 文档化,是长跑 agent 领域至今唯一的官方权威阐述。原文:https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents 配套代码:https://github.com/anthropics/claude-quickstarts/tree/main/autonomous-coding

一、核心问题

长跑 agent 必须在离散会话中工作,每个新会话对前次一无所知。

“想象一个软件项目,工程师轮班工作,每个新工程师到岗时对前一班发生了什么毫无记忆。”

上下文窗口有限,大多数复杂项目无法在单窗口内完成。需要桥接会话之间的鸿沟。

两个失败模式

失败模式	描述
One-shotting	agent 试图一次做完所有事,上下文中途耗尽,下个会话面对半成品无文档代码,要花大量时间猜发生了什么
过早宣布胜利	看到已有进展,直接宣布任务完成,即使大量功能未实现

→ 即使有 compaction(上下文压缩),也不够。compaction 不总能把清晰指令传给下个 agent。

二、两阶段解决方案

方案概览

┌────────────────────────────────────────────────┐
│  首次会话:Initializer Agent                    │
│  - 写 init.sh(启动开发服务器)                   │
│  - 写 claude-progress.txt(进度日志)            │
│  - 写 feature_list.json(结构化功能列表)         │
│  - 初始 git commit                             │
└────────────────────────────────────────────────┘
                    ↓
┌────────────────────────────────────────────────┐
│  每个后续会话:Coding Agent                     │
│  1. pwd(查看工作目录)                          │
│  2. 读 git log + 进度文件                       │
│  3. 读 feature_list,选最高优先级未完成功能      │
│  4. 启动开发服务器,跑基础端到端测试              │
│  5. 实现新功能                                  │
│  6. 自我验证后,在 feature_list 标记 passing    │
│  7. git commit + 更新进度文件                   │
└────────────────────────────────────────────────┘

关键洞察

找到一种方法让 agent 在启动新上下文窗口时快速理解工作状态 — 通过 claude-progress.txt 文件 + git 历史。

灵感来自有效软件工程师每天做的事。

三、组件详解

1. Feature List(功能列表)

为解决 one-shotting 和 过早宣布胜利 问题,提示 initializer agent 写一个全面的功能需求文件,扩展用户初始 prompt。

claude.ai 克隆案例

200+ 功能,例如:“用户能打开新聊天,输入查询,按回车,看到 AI 响应”。所有功能初始标记为 “failing”。

Feature 的 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
}

关键规则

Coding agent 只能修改 passes 字段
用强措辞指令:“It is unacceptable to remove or edit tests because this could lead to missing or buggy functionality.”
用 JSON 而非 Markdown — agent 不太可能不恰当地修改或覆盖结构化数据

2. Incremental Progress(增量推进)

每次 coding agent 会话只做一个功能。这解决了"做得太多"的倾向。

留下干净状态

会话结束后环境必须处于"可合并到 main 分支"的状态:

无重大 bug
代码有序、文档齐全
新工程师能直接开始新功能,无需先清理无关的烂摊子

最佳实践

提示模型用 git commit + 描述性消息 保存进度
在进度文件中写总结
让模型能用 git revert 撤销坏代码改动,恢复可用状态

这些方法也提升效率——agent 不必猜发生了什么、不必花时间让基础 app 重新跑起来。

3. Testing

最后一个主要失败模式:未做端到端测试就标记完成。

问题

Claude 倾向于:

改代码
跑单元测试 / curl 开发服务器
但未能识别功能端到端不工作

解决方案

显式提示 agent 用浏览器自动化工具像人类用户一样测试。

在 web app 场景,Claude 一旦被提示用浏览器自动化工具并像人类那样做所有测试,就能很好地端到端验证功能。

工具:Puppeteer MCP

提供 Puppeteer MCP server 后,agent 能识别和修复仅从代码层面无法看到的 bug。

剩余问题

Claude 视觉和浏览器自动化工具有限,难以识别所有 bug
例如:看不到浏览器原生 alert modal → 依赖这些 modal 的功能更易出 bug

四、Coding Agent 会话启动序列

[Assistant] I'll start by getting my bearings and understanding the current state of the project.
[Tool Use] <bash - pwd>
[Tool Use] <read - claude-progress.txt>
[Tool Use] <read - feature_list.json>

[Assistant] Let me check the git log to see recent work.
[Tool Use] <bash - git log --oneline -20>

[Assistant] Now let me check if there's an init.sh script to restart the servers.
<Starts the development server>

[Assistant] Excellent! Now let me navigate to the application and verify that
some fundamental features are still working.
<Tests basic functionality>

[Assistant] Based on my verification testing, I can see that the fundamental
functionality is working well. The core chat features, theme switching,
conversation loading, and error handling are all functioning correctly.
Now let me review the tests.json file more comprehensively to understand
what needs to be implemented next.
<Starts work on a new feature>

这套启动序列的价值

节省 token — 不必每次重新搞清怎么测试代码
让 agent 用 init.sh 启动开发服务器
跑基础端到端测试 — 快速识别 app 是否处于坏状态
如果直接开始实现新功能,可能让问题更糟

五、四大失败模式与对策矩阵

问题	Initializer Agent 行为	Coding Agent 行为
Claude 过早宣布项目完成	建立功能列表文件(结构化 JSON,列出端到端功能描述)	会话开始时读功能列表,选单个功能开始
环境中遗留 bug 或未文档化进度	写初始 git 仓库和进度记录文件	开始时读进度文件和 git 日志;结束时提交更新
Claude 过早标记功能完成	建立功能列表文件	自我验证所有功能,仅在仔细测试后才标记 “passing”
Claude 花时间弄清如何运行应用	写 `init.sh` 脚本运行开发服务器	会话开始时读 `init.sh`

六、为什么有效

灵感来源:人类工程师的工作习惯

“Inspiration for these practices came from knowing what effective software engineers do every day.”

人类工程师的做法	Harness 对应
写 README 让接手人快速上手	写 `claude-progress.txt`
用 issue tracker 跟踪未完成功能	写 `feature_list.json`
用 setup 脚本一键启动开发环境	写 `init.sh`
每天提交 git,写描述性 commit message	每会话结束 git commit + 更新
不要一次性重写整个模块	每会话只做一个功能
接手前先跑测试确认基线	启动后跑基础端到端测试

七、术语澄清

我们这里称它们为"分开的 agent",只是因为它们有不同的初始用户 prompt。系统 prompt、工具集、整体 agent harness 其他方面完全相同。

→ 这是关键:不是真的多 agent,而是同一个 agent 用不同 prompt 扮演不同角色。这是 Anthropic 的简化设计选择。

八、作者实践:TypeScript 实现要点

说明:本节有实践规划(与上文忠实转述的 Anthropic 方案区分开),供想动手实现的读者参考。

要在 TypeScript MVP 中实现这个模式,需要:

会话 1 触发器:检测是首次会话(检查 feature_list.json 是否存在)
Initializer prompt:专门用于初始化的 system prompt
Coding prompt:用于后续会话的 system prompt
工具:
- read_file(读进度文件、feature list)
- write_file(更新 feature list、进度文件)
- bash(跑 git、init.sh、测试)
- web_fetch / puppeteer(端到端测试)— 可选
状态管理:git commit 当 checkpoint
强措辞指令:“It is unacceptable to remove or edit tests”

→ 具体代码骨架见本系列第 10 篇《从零实现 TypeScript Harness MVP》。

附:2026 年 8 月更新与补充阅读

配套 quickstart(autonomous-coding)仍活跃(仓库 17.4K stars):README 确认两 agent 模式,feature_list.json 可生成 200 个测试用例;首轮初始化"需要几分钟,看起来像卡住属正常";每个 coding 会话 5-15 分钟,跑完 200 个功能需数小时;默认模型 claude-sonnet-4-5-20250929;目录含 prompts/initializer_prompt.md 与 prompts/coding_prompt.md,并配有安全模型(OS 沙箱、bash 白名单、文件系统限制)。
原文细节补充:demo 运行在 Claude Agent SDK 上,以 Opus 4.5 为例证;原文"multi-context-window workflows"的提议出处是 Claude 4 prompting guide。
官方续篇:Anthropic《Harness design for long-running application development》(2026-03-24)进一步讲长跑 agent 的 harness 设计(状态持久化、日志、checkpoint 等),是本文的后续更新。
半年后的行业印证:Anthropic《How we built our multi-agent research system》(2025-06-13)的结论是"多数 coding 任务可并行化程度低于研究,且 LLM agent 尚不擅长实时协调委派"——与本文第七章"单 agent vs 多 agent 开放问题"直接呼应。

参考来源

Anthropic《Effective harnesses for long-running agents》(2025-11-26):https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
配套 quickstart:https://github.com/anthropics/claude-quickstarts/tree/main/autonomous-coding
Anthropic《Harness design for long-running application development》(2026-03-24):https://www.anthropic.com/engineering/harness-design-long-running-apps
Anthropic《How we built our multi-agent research system》:https://www.anthropic.com/engineering/multi-agent-research-system