模板使用指南

这些模板可以直接复制到你的项目里用。每个文件在 agent 的工作流程中各有分工。复制过去后，把里面的命令、路径、功能名称和验证步骤换成你自己项目的。

怎么开始

先把这四个文件复制到项目根目录：

1. AGENTS.md 或 CLAUDE.md
2. init.sh
3. claude-progress.md
4. feature_list.json

等项目变复杂了，再补其余的文件。

---

AGENTS.md

根指令文件。agent 每次开工会先读这个文件。它定义了工作规则：写代码前要做什么、工作过程中怎么守规矩、收尾时要检查什么。

怎么用：

• 复制到项目根目录
• 把开工流程里的步骤换成你自己项目的路径和命令
• 工作规则按你们团队的约定调整
• 完成定义那一段别改——那是整个 harness 最关键的部分

它帮 agent 做什么：

• 让它在开始工作前先读进度和功能状态
• 逼它一次只做一个功能
• 要求它拿出证据才能标记完成
• 定义了什么叫"干净收尾"

用 AGENTS.md 给 Codex 或其他 agent。用 CLAUDE.md 给 Claude Code——内容一样，格式按 Claude 的指令风格来的。

init.sh

启动脚本。一条命令完成依赖安装、验证和打印启动命令。

怎么用：

• 复制到项目根目录
• 改顶部这三个变量：
  • INSTALL_CMD — 你的依赖安装命令（比如 npm install、pip install -r requirements.txt）
  • VERIFY_CMD — 你的基础验证命令（比如 npm test、pytest）
  • START_CMD — 你的开发服务器启动命令（比如 npm run dev）
• 加执行权限：chmod +x init.sh

它做什么：

1. 打印当前目录（确认跑在正确的地方）
2. 安装依赖
3. 跑验证命令
4. 打印启动命令（如果设了 RUN_START_COMMAND=1 就直接启动）

如果验证失败了，agent 应该停下来先修基础状态，不要在坏的基础上继续叠新功能。

claude-progress.md

进度日志。每轮会话往里写，每轮新会话先读它。

怎么用：

• 复制到项目根目录
• 把"当前已验证状态"那段填上你的项目信息
• 每轮会话结束后更新会话记录

每个字段的意思：

• 当前已验证状态 — 项目当前进展的唯一真相
  • 仓库根目录 — 项目在哪
  • 标准启动路径 — 把项目跑起来的命令
  • 标准验证路径 — 跑测试的命令
  • 当前最高优先级未完成功能 — 下一轮该做什么
  • 当前 blocker — 哪里卡住了
• 会话记录 — 每轮一条
  • 本轮目标 — 打算做什么
  • 已完成 — 实际做了什么
  • 运行过的验证 — 跑了什么测试
  • 已记录证据 — 留下了什么证明
  • 提交记录 — 提了什么 commit
  • 已知风险或未解决问题 — 哪里可能有问题
  • 下一步最佳动作 — 下一轮从哪开始

feature_list.json

功能清单。机器可读的功能列表，每个功能有状态、验证步骤和证据。

怎么用：

• 复制到项目根目录
• 把示例功能换成你自己的
• 每个功能需要填：
  • id — 短的唯一标识
  • priority — 整数，越小越优先
  • area — 属于应用的哪块（比如 "chat"、"import"、"search"）
  • title — 简短描述
  • user_visible_behavior — 功能正常时用户能看到什么
  • status — 四种状态之一：not_started、in_progress、blocked、passing
  • verification — 逐步验证步骤
  • evidence — 验证通过的记录（agent 填）
  • notes — 额外说明

状态规则：

• not_started — 还没碰
• in_progress — 当前正在做的那个（同一时间只能有一个）
• blocked — 有记录的阻塞问题，推不动
• passing — 验证通过，证据已记录

agent 任何时候只能有一个功能处于 in_progress。

session-handoff.md

会话交接摘要。一轮会话结束时写，下一轮开始时读。让接手的人（或 agent）快速了解现状。

怎么用：

• 复制到项目根目录
• 每轮会话结束时填写（也可以让 agent 自己填）

每段写什么：

• 当前已验证 — 哪些是确认能用的，跑过什么验证
• 本轮改动 — 改了什么代码或基础设施
• 仍损坏或未验证 — 已知问题和风险区
• 下一步最佳动作 — 下一轮该做什么，哪些东西不要动
• 命令 — 启动、验证、调试命令，方便快速参考

短会话可以不写这个文件。会话长了或者项目有多个并行区域时，它就很关键了。

clean-state-checklist.md

收尾检查清单。每次会话结束前过一遍，确保仓库处于下一轮可以直接开工的状态。

怎么用：

• 复制到项目根目录
• 关掉会话前逐项检查
• agent 的收尾流程里也应该包含这些检查

检查什么：

• 标准启动路径还能用
• 标准验证还能跑
• 进度日志已更新
• 功能清单真实反映了 passing 和未验证的边界（没有假 passing）
• 没有半成品处于未记录状态
• 下一轮会话不需要人工修复就能继续

evaluator-rubric.md

评审评分表。会话结束后或到里程碑时，用它评估 agent 做的东西够不够格。

怎么用：

• 复制到项目根目录
• 一轮（或几轮）会话后，按六个维度打分
• 每个维度 0-2 分

六个维度：

1. 正确性 — 实现出来的行为是否符合目标功能
2. 验证 — 要求的检查是否真的跑过，并留下证据
3. 范围纪律 — 是否基本保持在选定功能范围内
4. 可靠性 — 结果是否能在重启或重跑后继续工作
5. 可维护性 — 代码和文档是否清楚到足以交给下一轮会话
6. 交接准备度 — 新会话是否能只靠仓库内文件继续推进

结论选项：

• Accept — 达标
• Revise — 需要修补才能接受
• Block — 有根本性问题，需要先解决

Evaluator 需要校准。 开箱即用的 agent 做评审很弱——它会发现问题，然后把自己说服到通过。你需要反复校准：

1. 用 evaluator 给一个已完成的 sprint 打分。
2. 把它的分数和你自己的人工判断对比。
3. 有分歧的地方，把 rubric 里的通过/失败标准写得更具体。
4. 对同一个输出重新跑 evaluator，看对齐了没有。
5. 重复直到 evaluator 的判断和人工评审基本一致。

预计需要 3-5 轮校准。每轮记录改了什么、为什么改。

quality-document.md

质量快照。给项目的每个产品领域和架构层打分，跟踪代码库随时间是变强了还是变弱了。

怎么用：

• 复制到项目根目录
• 开始会话前：读它，了解代码库哪里最弱
• 会话结束后：更新评级
• 长期：对比不同时间点的快照，看哪些 harness 改动真正改善了代码库健康度

评什么：

• 产品领域（如文档导入、问答流程、索引）：每个领域按验证状态、Agent 可读性、测试稳定性、关键缺口打分
• 架构层（如 Main Process、Preload、Renderer、Services）：每层按边界执行和 Agent 可读性打分

为什么需要它：

Evaluator rubric 评的是单次 agent 输出的质量。Quality document 评的是代码库本身的质量。它们回答的是不同的问题：

• Evaluator rubric："这轮 agent 做得好不好？"
• Quality document："这个项目是在变强还是变弱？"

什么时候更新：

• 每轮重要会话之后
• 做基准对比之前
• 做清理或简化之后
• 换新 agent 或新模型时

和 harness 简化的关系：

Quality document 也可以用来验证 harness 是否可以简化。Harness 里的每个组件都编码了一个假设——"模型做不到这件事"。模型变强后，这些假设就过时了。检查某个组件是否还有必要：

1. 拍一份 quality document 快照。
2. 移除一个 harness 组件。
3. 跑基准测试。
4. 再拍一份快照。
5. 对比——评级没降，说明那个组件是多余的。降了，就恢复。