一、核心挑战：跨越上下文窗口

• 根本障碍：“智能体如何跨越多个、离散的上下文窗口，保持记忆和状态，从而持续推进任务？”
• 典型失败模式：
  • “一次性做太多（Trying to do too much at once）”：智能体试图在单个会话内“一蹴而就”，结果耗尽上下文，留下一堆半成品。
  • “过早宣布胜利（Declaring victory too early）”：智能体看到已取得部分进展，便错误地判断任务已经完成，停止了工作。

二、核心解决方案：两段式智能体 Harness

借鉴人类软件工程师的协作模式，将任务分解为两个由专门智能体执行的阶段。

• 1. Initializer Agent：环境的奠基者
  • 职责：“仅在项目启动的第一个会话中运行”，接收高层指令，“将其分解、结构化，为后续所有工作创建一个清晰、规范的初始环境。”
  • 产出：
    • “功能列表 (Feature List)”：将模糊需求具体化为详尽清单，以 JSON 存储。
    • “初始代码仓库 (Git Repository)”
    • “进度日志 (Progress Log)”
    • “启动脚本 (Init Script)”
• 2. Coding Agent：增量的推进者
  • 职责：“在 Initializer Agent 完成使命后，Coding Agent 接管所有后续会话。”
  • 工作循环：
    1. 状态同步：在每个会话开始时，通过读取工件理解项目状态。
    2. 单点突破：“从功能列表中选择一个最高优先级的未完成项，并只专注于这一个特性的开发。”
    3. 端到端验证：“使用浏览器自动化工具（如 Puppeteer）进行端到端测试。”
    4. 清洁收尾：“提交有意义的 Git Commit，并更新进度日志，确保工作区处于一个随时可以交接的‘干净’状态。”

三、环境管理：四大关键工件与策略

这些工件构成了一个“外部记忆”系统。

• 1. 全量功能列表：定义“完成”的标尺
  • 目的：为了解决“过早宣布胜利”。
  • 内容：“每一项都是一个端到端的用户故事或功能描述”。
  • 格式：“使用 JSON 格式比 Markdown 更为稳健。”
  • 使用约束：“只允许修改 passes 字段的状态，绝不允许删除或修改任何功能描述”。
• 2. 增量推进与清洁收尾：Git 与进度日志
  • Git 的作用：“原子提交”和“可回滚性”，是“智能体的安全网”。
  • 进度日志 (claude-progress.txt)：“一个简单的文本文件，用于记录每个会话的关键决策和进展摘要”，比 git log 更具可读性。
• 3. 端到端测试：Puppeteer 作为“眼睛”和“手”
  • 作用：“这相当于给了智能体一双‘眼睛’和一双‘手’，让它能像真实用户一样与 Web 应用交互”，能发现“布局问题、交互错误、状态未同步等”隐性 Bug。
• 4. 起步流程：标准化的“上手三步”
  • 流程：1. pwd 建立空间感；2. 通过 git log 和进度日志了解历史；3. 读取 feature_list.json 选择任务。
  • init.sh 的作用：“一键启动开发服务器”，并“先运行一个基本的端到端测试，确保应用当前处于健康状态”。

四、失败模式与应对策略总结

原文链接