Anthropic Claude Code 工程博客精读：构建可靠长时运行AI代理的有效框架实践

Anthropic 工程博客精读：构建可靠长时运行AI代理的有效框架实践

在AI代理（Agent）领域，长时运行任务一直是个痛点。Claude等大模型在单次会话中表现优秀，但一旦任务跨越多个上下文窗口（context window），就容易出现"一口气想干完整个项目"（one-shotting）、半途留下bug、过早宣布完成，或者完全丢失前序进度等问题。Anthropic的这篇工程博客《Effective Harnesses for Long-Running Agents》直击这些问题，提出了一套双代理框架（Initializer Agent + Coding Agent），结合外部记忆机制和工程化实践，让Claude代理能在多轮会话中稳定、增量地推进复杂任务。

这篇文章不仅是理论探讨，更提供了大量可落地的实践细节，包括文件结构、提示策略、工具调用流程和代码示例。对想用Claude API或Agent SDK构建长时代理的开发者来说，绝对是必读指南。下面我结合原文，提炼出一份实践导向的综述，帮助你快速上手。

核心问题：为什么长时代理容易翻车？

传统代理在长任务中常见失败模式：

上下文窗口限制：每次新会话都从"空白"开始，前序工作容易遗忘。
过度激进：试图一次性完成整个项目，导致代码混乱或崩溃。
过早收工：只实现了部分功能就宣布"任务完成"。
状态不洁：留下未文档化代码、未修复bug，下一轮接手时一头雾水。
缺乏验证：没有端到端测试，表面看起来OK，实际跑不起来。

Anthropic的解决方案灵感来自人类软件工程：不靠模型"记住一切"，而是用外部工件（artifacts）来承载状态，让代理像接力赛一样稳定推进。

解决方案：双代理框架 + 结构化环境

核心思路是把任务拆成初始化阶段 和迭代阶段：

Initializer Agent（初始化代理）

只在第一次运行，负责搭建"脚手架"：
- 创建Git仓库并初始commit
- 编写init.sh启动脚本
- 生成feature_list.json（功能清单）
- 创建claude-progress.txt（进度日志）
Coding Agent（编码代理）

后续所有会话都用这个代理，职责：
- 读取历史状态（Git log + 进度文件 + 功能清单）
- 挑选一个未完成的功能，专注实现
- 自验通过后更新状态
- 提交干净的Git commit + 进度更新

这种分离让系统更健壮：初始化只做一次，迭代代理永远在"干净工地"上干活。

关键实践组件

1. 功能清单：feature_list.json（核心外部记忆）

用JSON格式定义所有需求，每个功能包含：

json 复制代码

{
  "category": "functional",
  "description": "点击New Chat按钮能创建新对话",
  "steps": [
    "进入主界面",
    "点击'New Chat'按钮",
    "验证新对话被创建",
    "检查聊天区显示欢迎状态",
    "验证侧边栏出现新对话"
  ],
  "passes": false
}

实践要点：

用JSON而非Markdown，避免代理随意改描述
代理只能改passes字段，且必须自验通过后才能改
优先级可通过排序控制，代理每次只挑一个passes: false的功能

2. 进度跟踪：claude-progress.txt + Git

claude-progress.txt：纯文本日志，记录"已完成什么、接下来打算做什么"
Git：每次改动必须commit，消息要清晰（如"Implement feature: New chat button"）

这样即使上下文窗口清零，下一轮代理也能通过git log和进度文件快速"补课"。

3. 启动例程：每轮会话必跑的"热身"

代理启动时固定流程（写进系统提示）：

pwd确认目录
读取claude-progress.txt
读取feature_list.json
git log --oneline -20 查看最近提交
执行./init.sh启动开发服务器
跑基础端到端测试，确认应用没坏

这个例程能节省token、减少幻觉，还能及早发现回归问题。

4. 自验测试：用浏览器自动化工具

推荐集成Puppeteer MCP等工具，让代理模拟真实用户操作进行端到端测试。

实践提示：

测试脚本写在初始化阶段
代理实现功能后，必须跑测试通过才能标记passes: true
注意局限：某些浏览器原生弹窗（如alert）可能检测不到

5. 增量原则：一次只干一件事，离开时必须"干净"

禁止跨多个功能
禁止留下重大bug或未文档代码
每次结束必须：测试通过 → 更新JSON → Git commit → 写进度日志

常见失败模式与应对表

问题	初始化代理应对	编码代理应对
过早宣布完成	定义完整feature_list.json	严格按清单检查，只改passes
留下bug/无文档代码	创建Git + init.sh	启动时自测 + 必须干净commit
不知道怎么跑应用	写init.sh	每次运行init.sh + 基础测试
随意修改需求描述	用JSON固定格式	禁止编辑steps/description

最佳实践总结（直接可抄）

第一轮用专用提示做初始化，后续轮次统一迭代提示
所有关键状态用结构化文件（JSON > Markdown）
强制增量+干净离开，像代码审查一样严格
必须自验，优先用浏览器自动化工具
固定启动例程，永远先验证环境再动手
善用Claude Agent SDK管理工具调用和循环
Git是最佳外部记忆，别省

结语：不止编码，适用于所有长时任务

这套框架目前主要演示在Web开发场景，但作者明确提到可扩展到科研、金融建模等长周期任务。未来方向包括多代理协作（专职测试代理、QA代理等）。

如果你正在用Claude做代理项目，强烈建议：

先跑一次初始化，搭好feature_list.json和init.sh
把启动例程写死在系统提示里
集成Git和浏览器测试工具

实践下来，你会发现代理从"易飘的创意机器"变成"可靠的工程搭档"。这篇博客的最大价值在于把"长时可靠"从玄学变成了可复制的工程规范，值得每位Agent开发者反复阅读和实践。

欢迎留言讨论你的长时代理实践经验！