长运行 AI Agent 在处理跨越数小时甚至数天的复杂任务时，面临核心挑战：上下文窗口有限，每个新会话如 “无记忆新工程师” 接班，导致进度丢失或重复修复。Anthropic 通过 Claude Agent SDK 工程实践，提出双 Agent 架构和结构化环境管理方案，实现运行时检查点、故障恢复和监控，确保 Agent 无需停止即可稳定推进。
核心观点是模拟人类工程师工作流：使用 Git 提交、进度日志和功能清单作为持久化检查点，让每个会话 Agent 快速 “上手” 并增量贡献，避免 “一锤子” 式失败或过早结束。Anthropic 实验显示，仅靠上下文压缩不足以支撑生产级 web app（如 claude.ai 克隆），Agent 常 “一口气做太多” 导致半途崩溃，或后期 “看到部分功能即宣布完成”。解决方案分解为初始化 Agent（首次会话搭建脚手架）和编码 Agent（后续增量进展），关键 artifacts 包括 init.sh 脚本、claude-progress.txt、feature_list.json 和 Git 仓库。
首先，初始化 Agent 负责环境搭建。根据用户提示（如 “构建 claude.ai 克隆”），生成超过 200 个端到端功能点清单（JSON 格式），每个条目含 category、description、steps（如 “点击 New Chat 按钮，验证新对话创建并显示侧边栏”）和 passes: false 状态。Anthropic 强调 JSON 优于 Markdown，因模型不易误改结构。同时创建 init.sh（启动开发服务器）、claude-progress.txt（日志）和初始 Git 提交，记录文件添加。这提供全景视图，防止后续 Agent 盲目蛮干。
证据显示，这种脚手架直接解决 “过早胜利” 问题：Agent 无清单易误判进度，而结构化 JSON 强制逐项验证。“Initializer agent: The very first agent session uses a specialized prompt that asks the model to set up the initial environment。”
其次，检查点与恢复机制 是工程核心。每个编码 Agent 会话遵循固定 “上手” 清单：
- pwd 检查目录。
- git log --oneline -20 + read claude-progress.txt，审视近期工作。
- read feature_list.json，选最高优先未完成功能。
- run init.sh 启动服务器。
- 基础 E2E 测试（如 Puppeteer MCP 浏览器自动化：新聊天、发送消息、验证响应），确认无破损状态。
仅验证通过后，才实现一功能：编码 → Git commit（描述性消息）→ 更新 progress.txt → 标记 passes: true（经测试）。Puppeteer 截图反馈让 Agent 识别代码外 Bug，提升准确性。Git 允许回滚坏变更，progress.txt 浓缩历史，避免 token 浪费。
典型会话日志：
[Assistant] 先了解项目状态。
[Tool] <bash - pwd> <read - claude-progress.txt> <read - feature_list.json>
[Assistant] 检查 Git 日志。
[Tool] <bash - git log --oneline -20>
[Assistant] 运行 init.sh，重启服务器。
[Assistant] 验证核心功能正常，现选下一功能。
此流程确保恢复点精确，故障隔离：若工具失败或模型 hallucinate，Git + 测试快速定位。
可落地参数与监控清单：
- 检查点频率：每会话一功能（非定时），优先高影响项（如核心聊天 > UI polish）。
- 文件阈值：feature_list ≤300 项，避免 overload；progress.txt 限最近 10 会话摘要。
- 测试参数：E2E steps ≥5 步 / 功能；Puppeteer timeout=30s，screenshot 每步保留。
- 恢复阈值：基础测试失败率 >10% 触发人类干预；Git commit 消息 ≥20 字描述。
- 监控指标：会话 token 消耗 <80% 窗口；passes 率周增>20%；回滚次数 <5/100 会话。
- Prompt 模板（编码 Agent）：
1. 运行上手清单验证状态。 2. 选一未 passes 功能，实现并 E2E 测试（用 Puppeteer 如用户）。 3. Git commit + progress 更新 + passes=true（严禁编辑 steps）。 4. 环境留 clean：无 bug、文档齐。 - 回滚策略：git bisect 故障 commit；若连续 3 会话失败，切换模型（如 Opus → Sonnet）。
风险控制：浏览器工具盲区（如 native alerts）用备用单元测试补；单 Agent 限制造成瓶颈，可扩展多 Agent（测试专员）。Anthropic 指未来方向：泛化至科研 / 金融，验证单 vs 多架构。
实施此 Harness，长运行 Agent 稳定性提升显著：跨窗口无 halting，故障自愈。通过参数化清单，即插即用，支持生产部署。
资料来源：
- Anthropic 官方：https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
- Claude 4 Prompting Guide 多窗口最佳实践。