SDD + Harness 四周学习计划 · Week 4 · Day 25（全计划第 25 课）
今日主题：精读《AI 编程可闭环协作·卷三》：任务单最少内容、书面审查、合并前自动检查
建议用时：90 分钟 ｜ 前置：Day 24 的团队流程 + Day 13 的 hook 实操
输出物：卷三精读笔记（三块：任务单 / 书面审查 / 合并前自动检查，各配一个你项目的落地动作）
0. 一句话剧透
Day 24 讲的是”流程怎么走”，今天精读掘金《AI 编程可闭环协作·卷三：Harness 与 SDD》，补上”每一步要留什么证据“：可检索的任务单让人和 Agent 对齐”什么叫做完”，书面审查把”我看了”变成可追溯记录，合并前自动检查用 hook / CI 门禁保证”不通过不能合并”。三者和 Day 24 的分支/merge 规范正好互补——一个管秩序，一个管证据。
1. 今日目标（学完你能做到）
- 能说出 Harness 协作流程的三大件（可检索任务单 / 书面审查 / 合并前自动检查）
- 能列出任务单的最少内容（什么才算”做完”可对齐）
- 能解释”书面审查”为什么必须书面、要留哪些字段
- 能说清合并前自动检查与 Day 13 pre-commit hook、Day 17 质量门禁的关系
- 完成动手练：把三大件映射到你的项目并写进笔记
2. 学习动线
| 步骤 | 内容 | 用时 |
|---|---|---|
| 1 | 精读「3」：三大件全景（为什么是这三件） | 15 分钟 |
| 2 | 精读「4」：任务单最少内容 | 20 分钟 |
| 3 | 精读「5」：书面审查 | 15 分钟 |
| 4 | 精读「6」：合并前自动检查（hook / CI 门禁） | 15 分钟 |
| 5 | 动手练「7」：映射到你的项目 | 15 分钟 |
| 6 | 自测「8」+ 打卡 | 10 分钟 |
3. 三大件：为什么是这三件
原文一句话概括：Harness 协作流程 = 可检索的任务单 + 书面审查 + 合并前自动检查。
对应三大风险：任务不明确（AI 自由发挥）→ 任务单解决；审查不可追溯（口头”我看了”）→ 书面审查解决；坏代码混入主干（人总会漏）→ 自动检查解决。
| 环节 | 防什么 | 对应前文 |
|---|---|---|
| 任务单 | AI/人”做没做完”对不齐 | Day 11 story + Day 23 commands |
| 书面审查 | review 留不下证据 | Day 24 review/merge + Day 23 review.md |
| 合并前自动检查 | 漏网之鱼进 develop/main | Day 13 pre-commit + Day 17 质量门禁 |
一句话：任务单管”做什么、算做完”，书面审查管”谁确认了、留没留痕”，自动检查管”不通过能不能进主干”。
4. 任务单最少内容
原文核心：人和 Agent 才能对齐”什么叫做完”。
任务单（story / task）最少要有 5 项：
- 任务标题：一句话，可检索——检索 = 事后能翻出来，标题就是索引键
- 关联 spec：指向
.ai/specs/<功能>.md的哪一条 AC（或 delta 的哪一节） - 完成定义（Definition of Done）：可检查的清单——测试过了？证据在哪？
- 验证证据位置：测试报告 / 压测记录 / 样例集路径
- 范围红线：明确不做的事（对齐 spec 的非目标）
示例任务单：
1
2
3
4
5
[TASK] 实现登录接口 POST /api/auth/login
- 关联：specs/user-login.md → AC-1 / AC-2
- DoD：AC-1 / AC-2 自动化测试通过；错误码文案与 spec 一致
- 证据：tests/auth_test.py 运行输出（附件）
- 红线：不做密码找回、不做第三方登录
5. 书面审查
原文核心：不是口头说”我看了”，而是留下可追溯的审查记录。
书面审查记录最少字段：
- 审查对象（commit / PR 链接）
- 审查人 + 日期
- 审查范围（对照哪些 AC）
- 结论：approve / request-changes
- 遗留问题与后续跟踪
与 Day 23 的 review.md command、Day 24 的 merge 前置条件直接对应：没有书面审查记录 → 不允许 merge。这是规范，靠人执行；自动检查管不了”审查质量”，只能管”有没有记录”。
6. 合并前自动检查
三层门禁：
| 层 | 位置 | 内容 | 对应 |
|---|---|---|---|
| 1 | 本地 pre-commit hook | 改代码必须带 spec（feat/* 查、chore/* 豁免） | Day 10/13 |
| 2 | CI 门禁（远端） | 测试 / 构建 / 契约测试不通过 → 不能合并 | Day 17 |
| 3 | 合并策略（平台） | squash merge + 要求 PR 有 review 记录 | Day 24 |
与 Day 24 的衔接：分支规范决定了 hook 检查什么（feat/* 查 spec，chore/* 豁免），CI 在合并到 develop 前兜底，release 分支再回归一次。 三层合起来，就是”合并前自动检查”的完整落地。
7. 动手练（约 15–20 分钟）
写《卷三精读笔记》（≥300 字）：
- 三大件各用一句话总结
- 任务单最少内容清单（5 项）抄进你的 notes/
- 为你的项目写一个真实任务单示例（可基于 Day 26 大作业的选题）
- 回答：你的项目现在缺哪一件？Day 26 怎么补上？
打卡：
Day25-卷三精读笔记.md存盘。Day 26 大作业要按这里的任务单格式写你的任务。
8. 自测题
- Harness 协作流程的三大件是什么？
- 任务单最少要包含哪 5 项内容？为什么标题要”可检索”？
- 完成定义（DoD）和 spec 的验收标准是什么关系？
- 书面审查记录最少要留哪些字段？为什么不能口头 review？
- 合并前自动检查的三层门禁分别是什么？各自守在哪一环？
- pre-commit hook 和 CI 门禁的分工差异是什么？
- 三大件分别对应防住什么风险？
- 书面审查记录在 merge 流程中扮演什么角色（Day 24 衔接）？
提示：第 2 题在 4；第 3 题——DoD 是任务级的”做完”，AC 是 spec 级的”做完”，DoD 通常引用 AC；第 5、6 题在 6。
9. 延伸阅读
- 掘金《AI 编程可闭环协作·卷三：Harness 与 SDD》（今日精读原文）：https://juejin.cn/post/7647333934796537919
- sdd-harness 仓库（hook 与 commands 的落地实现）：https://github.com/iMark21/sdd-harness
本工作纸依据《SDD+Harness四周学习计划.md》Day 25 主题编制。整理日期：2026-09-09
