# 模板使用指南

这些模板可以直接复制到你的项目里用。每个文件在 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. 对比——评级没降，说明那个组件是多余的。降了，就恢复。