长时运行 Harness

核心挑战

AI Agent 在离散的会话中运行。每个会话从一个全新的上下文窗口开始 — 对之前发生的事情没有任何记忆。对于跨越数小时或数天的任务，这是一个根本性约束：Agent 必须以某种方式在多个上下文窗口之间保持连贯性，而每个窗口都从零开始。

这与轮班制工程团队面临的挑战相似。每个新的轮班工人到达时对上一班的工作毫无了解。没有结构化的交接协议，工作就会退化：任务被重复，进度丢失，项目偏离方向。

两种失败模式

Anthropic 在测试长时运行自主编码 Agent 时发现了两种关键的失败模式：

失败模式	症状
过度雄心	Agent 试图在单个会话中完成整个实现，在功能完成途中耗尽上下文
提前完成宣告	后续的 Agent 实例看到部分进度后宣布项目已完成

两种失败都源于同一个根本原因：Agent 缺乏对已完成的工作和剩余工作的结构化感知。

双 Agent 方案

方案将 Agent 工作分为两个专门的角色，各有自己的提示词和协议：

初始化 Agent (Initializer)

第一个会话运行一个专门的初始化器来建立项目基础设施：

init.sh — 环境设置的可执行脚本（依赖、开发服务器等）
功能列表 — 所有所需功能的完整 JSON 目录，包含验证步骤
claude-progress.txt — 用于跨会话连续性的工作历史文档
初始 git 提交 — 所有后续工作建立在此基线状态之上

功能列表是关键产物。每个条目包含：

{
  "category": "functional",
  "description": "New chat button creates a fresh conversation",
  "steps": ["Click new chat button", "Verify empty conversation appears", "Verify URL updates"],
  "passes": false
}

关键约束：后续 Agent 只能修改 passes 字段 — 永远不能修改功能描述或步骤。这防止了成功标准在会话之间发生漂移。

编码 Agent (Coder)

每个后续会话遵循结构化的启动协议：

执行 pwd 验证工作目录
读取 claude-progress.txt 和最近的 git log
查阅功能列表，选择最高优先级的未完成项
运行 init.sh 启动开发环境
执行基线测试验证现有功能
实现选定的功能
通过端到端测试验证
更新进度文件，用描述性消息提交

Agent 一次只做一个功能，在继续下一个之前验证完成。Git 作为恢复机制 — 如果某个更改破坏了现有功能，Agent 可以回滚到上一个已知正常的状态。

上下文桥梁 (Context Bridge)

claude-progress.txt 文件配合 git 历史形成了一座上下文桥梁 — 结构化的产物，使新的上下文窗口启动时能够快速定位。

这是一个有意为之的工程选择。与其依赖上下文压缩（会丢失信息）或巨大的上下文窗口（会降低注意力），Harness 将状态外化为持久文件，任何新会话都可以读取。

这个模式映射了专业软件工程师的工作方式：清晰的交接文档、增量式进度跟踪和经验证的完成标准。Harness 不试图让模型变成超人 —它给模型提供了使人类工程师高效的同样工具。

测试策略

一个关键发现：引导 Agent 进行用户视角测试大幅提高了功能可靠性，相比开发者视角测试效果显著。

测试方式	行为	结果
开发者视角	Agent 检查代码逻辑，运行单元测试	遗漏 UI 缺陷和集成失败
用户视角	Agent 使用浏览器自动化（如 Puppeteer MCP）像真实用户一样测试	捕获视觉缺陷、交互故障和端到端问题

Harness 明确指示编码 Agent 使用浏览器自动化工具端到端地验证功能，从用户的视角而非开发者的视角进行测试。

会话流程

会话 1（初始化 Agent）
  ├─ 创建 init.sh
  ├─ 生成完整功能列表
  ├─ 创建 claude-progress.txt
  └─ 初始 git 提交

会话 2..N（编码 Agent）
  ├─ 读取进度 + git log
  ├─ 选择下一个未完成功能
  ├─ 运行 init.sh → 启动开发环境
  ├─ 基线测试现有功能
  ├─ 实现选定功能
  ├─ 端到端验证
  ├─ 更新进度 + git 提交
  └─ （上下文耗尽 → 新会话启动）

每个会话是自包含的：它从持久产物中读取所需的一切，做增量工作，并为下一个会话留下干净的状态。没有任何会话依赖于仅存在于先前会话上下文窗口中的信息。

关键洞察

增量优于雄心 — 试图一次实现所有内容的 Agent 会在功能完成途中耗尽上下文，留下损坏的代码。逐个功能加验证虽然单次会话更慢，但能可靠收敛。

Git 作为安全网 — 版本控制不仅仅是为了历史记录。它是 Agent 的撤销机制。当实现破坏了现有功能时，git revert 能立即恢复到上一个工作状态。

结构化交接优于原始记忆 — 将状态外化到文件中（claude-progress.txt、功能列表、git log）比任何上下文内记忆或压缩策略都更可靠。信息是无损的且始终可用。

受人类启发的实践 — 最有效的 Agent Harness 并不发明新颖的 AI 工作流。它们复制使人类工程团队高效的实践：清晰的文档、增量进度、经验证的完成和干净的交接。

来源

Effective Harnesses for Long-Running Agents — Justin Young, Anthropic, 2025.11.