SDD + Harness 四周学习计划 · Week 3 · Day 20（工程化闭环第 6 课 / 全计划第 2 个实操日）
今日主题：实操：端到端功能——spec → plan → implement → verify → merge，全程留文档与证据
建议用时：120 分钟（实操日可稍多）｜ 前置：Day 5 的
Day5-spec-<功能名>.md+ Day 18 的可执行验收 + Week 2 的 sdd-harness输出物：一个走完全链路的 PR——spec 文件、plan、tasks、代码 diff、verify 结果、merge 记录六样证据齐备
0. 一句话剧透
全计划第 2 个关键实操日，也是 Week 3 的压轴。Week 2 你跑通了 spec-first 提交（改代码必须带 spec），Day 18 你把验收变成了可执行的 Gherkin。今天把两样合起来：拿 Day 5 的 spec 走 spec → plan → implement → verify → merge 全链路，每一步留下文档与证据——这就是计划评估标准里「完整交付一个功能：spec → code → verify 全链路有文档可查、可回退」的实操版。
1. 今日目标（学完你能做到）
- 能独立走完 spec → plan → implement → verify → merge 五步
- 能说出每一步的证据是什么（spec 文件 / plan / tasks / 代码 diff / verify 结果 / merge 记录）
- 能在 verify 阶段跑 Day 18 的可执行验收（Gherkin 场景或契约测试）
- 能用一个 PR 把「规范 + 代码 + 证据」打包交付
- 能如实记录「AI 在哪里猜错、spec 哪里不清、harness 哪里没拦住」（Day 21 复盘素材）
2. 学习动线（实操专用时间盒）
| 步骤 | 内容 | 用时 |
|---|---|---|
| 1 | 第 3 节：五步总览与证据清单 | 10 分钟 |
| 2 | 第 4 节：复用 Week 2 harness（七命令循环 + hook） | 10 分钟 |
| 3 | 实操第 5 节：spec → plan → implement | 55–65 分钟 |
| 4 | 实操第 6 节：verify → merge | 30–40 分钟 |
| 5 | 证据清点 + 记录 | 10 分钟 |
3. 五步总览：每一步的输入、输出、证据
| 步骤 | 输入 | 输出 | 证据（留档） |
|---|---|---|---|
| spec | Day 5 spec（今天定稿） | 定稿 spec 文件 | Day5-spec-<功能名>.md（进仓） |
| plan | spec | 技术方案 plan | plan.md |
| implement | plan + tasks | 代码 + 测试 | 代码 diff（git diff） |
| verify | Day 18 的 Gherkin/契约测试 | 验收结果 | verify 结果（通过/失败记录） |
| merge | 全部证据 | 合并后的主干 | merge 记录（PR 链接/commit） |
核心原则：每一步的「证据」必须是文件或记录，不是记忆。 六样证据都齐，这个功能才算「可控」地交付了。
4. 复用 Week 2 的 harness
Week 2 的 sdd-harness 提供七命令循环（已核验）：spec → story → implement → verify → review → release → phase-close。今天至少走通前五环：
- spec：把 Day 5 的 spec 作为起点（七命令里的 spec 环节，必要时用 delta spec 表达「本次变更」）；
- implement：在
feat/*分支实现——pre-commit hook 会检查「改了代码有没有同步 spec」，被拦就按 Day 13 学过的方式处理（补 spec 或显式SH_SDD_SKIP=1例外并注明原因）； - verify：跑 Day 18 的可执行验收；
- review：PR 评审（对应 Day 17 的「生产前人工 approval」前一步）。
5. 实操 Step 1–3：spec → plan → implement（约 60 分钟）
Step 1 定稿 spec（10 分钟）
拿出 Day5-spec-<功能名>.md（优先用 Day 7 修订的 v2）。做三件事：
- 确认七要素齐全、验收可量化（不合格先补，这是全链路的根）；
- 如有 Day 18 转写时发现的问题，一并修订；
- 把 spec 提交进
feat/<功能名>分支（原子提交的「规范半边」）。
Step 2 写 plan（15 分钟）
写 plan.md，只回答 HOW：
- 技术栈与文件结构
- 数据契约怎么落（Schema/Pydantic）
- 行为契约怎么落（接口定义）
- 质量与可观测性怎么落（指标、日志）
记住 Day 6 的铁律：HOW 进 plan，不进 spec。 今天 spec 已经定稿，不要回头污染它。
Step 3 拆 tasks 并实现（35–40 分钟）
拆 3–5 个任务（可参照 Spec-Kit 的 tasks 形态）：
1
2
3
4
T1 数据层：按数据契约实现结构 + 校验
T2 接口层：按行为契约实现 API + 异常
T3 验收：把 Day 18 的 Gherkin 落成可执行验收脚本
T4 质量：补指标/日志埋点
逐任务实现，每个任务完成即 commit（git diff 就是证据）。被 pre-commit hook 拦截时，按 Day 13 的流程处理并记录。
6. 实操 Step 4–5：verify → merge（约 30–40 分钟）
Step 4 verify（20 分钟）
跑 Day 18 的可执行验收：
- Gherkin 场景逐条执行，记录每条 Given/When/Then 的通过/失败；
- 有契约测试就跑契约测试；
- 结果存为
verify-结果.md：哪些 AC 过、哪些没过、失败原因。
失败不可怕，如实记录就是证据。Day 21 复盘要用的正是「哪里失败了、为什么」。
Step 5 merge（10 分钟）
- 确认证据齐备：spec 文件、plan、tasks、代码 diff、verify 结果；
- 发起 PR，附上证据清单与 verify 结果摘要；
- 走完 review（自审或请人审）后 merge，记录 merge 的 commit/PR 号。
证据清点（10 分钟）
用清单勾一遍（这是今天的交付）：
- spec 文件（进仓、可 diff）
- plan.md
- tasks 清单
- 代码 diff（git log/diff 可查）
- verify 结果（Day 18 场景 + 本次新增）
- merge 记录（PR/commit 号）
7. 自测题
- 五步全链路是哪五步？每步的证据是什么？
- spec 为什么必须在第一步定稿？中途改会怎样？
- pre-commit hook 拦截时你有哪两条路？
- verify 失败的证据有什么用？
- plan 和 spec 的职责边界是什么？
- 为什么说「证据是文件或记录，不是记忆」？
- Day 18 的 Gherkin 在今天的哪一步被消费？
答案与提示：
- spec（spec 文件）/ plan（plan.md）/ implement（代码 diff）/ verify（verify 结果）/ merge（merge 记录）。
- spec 是全链路输入，中途改会让 plan/代码/验收全部失准——要改就走新的变更（delta spec），而不是偷偷改。
- 补 spec 后重新提交，或显式
SH_SDD_SKIP=1并注明原因（Day 13 内容）。- 失败记录定位「哪里不符合契约」，是修订的依据，也是 Day 21 复盘的素材。
- spec 管 WHAT（做什么/怎么算成功），plan 管 HOW（技术方案）。
- 记忆会过期、无法回溯；文件与记录可 diff、可回退、可被 CI/CD 消费。
- verify 步骤——把 Gherkin 落成可执行验收脚本并逐条执行。
延伸阅读
- sdd-harness 仓库（七命令循环与 hook 落地）：https://github.com/iMark21/sdd-harness
- SDD-Agent-Harness（Spec → Plan → Build → Verify → Report 固定工作流参考）：https://github.com/LeoninCS/SDD-Agent-Harness
- harness-sdd（可移植多 CLI 的 harness）：https://github.com/araozmd/harness-sdd
本工作纸依据《SDD+Harness四周学习计划.md》Day 20 主题编制。整理日期：2026-09-09
