第 2 天：精读《SDD 和 Harness：AI 编程的两大支柱》

SDD + Harness 四周学习计划 · Week 1 · Day 2（认知打底第 2 课）

今日主题：把 Day 1 的「两把钥匙」拼成一张完整闭环图——文档流 spec.md / plan.md / tasks.md / delta spec × 机制层 CLAUDE.md+Skills / Plan Mode+Permission / Hooks / Subagents

建议用时：60–90 分钟｜参考文章：资源 1《SDD 和 Harness：AI 编程的两大支柱》（CSDN，见文末延伸阅读）

输出物：自己动手画一张完整闭环图（文字/手绘均可）——这是 Day 7 学习笔记与 Day 8 四大护栏的核心底稿

0. 一句话剧透

Day 1 讲了「两大支柱的分工」，今天要把它变成一张能讲给别人听的闭环图。

Day 2 的答案一句话：SDD 负责让「对的东西」沿着 spec → plan → tasks → 代码这条流水线流下去；Harness 负责在流水线外面装围栏——规则（CLAUDE.md+Skills）、闸门（Plan Mode+Permission）、验货（Hooks）、小隔间（Subagents）——保证流水线不会流歪、漏检、翻车。

学会的标准不是「背下四个文件名」，而是：把任何一段需求放进这张图，你能说出它在每一站该变成什么、被谁检查、错了往哪退。

1. 今日目标（学完你能做到）

能不看资料画出「文档流四件套」（spec → plan → tasks → 代码 + delta spec）的走向，并说明每一份是谁、在什么时间写的、管什么
能解释 delta spec 为什么是「增量」而不是「重写」，以及它治的是哪种病（规格腐烂）
能逐一说出四大机制（CLAUDE.md+Skills / Plan Mode+Permission / Hooks / Subagents）各自管住哪个环节、堵住哪个漏洞
能说清 Hooks 与「让 AI 自觉」的本质区别（确定性门禁，不由模型决定）
能把文档流与机制层合成一张完整闭环图，并用它讲一遍「改一个需求」的完整旅程

目标对应 Day 8「四大护栏」与 Day 7 学习笔记的地基。今天不要求实操（那是第 2 周），要求的是结构。

2. 学习动线（建议时间分配）

步骤	内容	用时
1	读之前：把文章当成「一张图」来读	5 分钟
2	精读正文：资源 1《两大支柱》（CSDN）全文	25–35 分钟
3	拆主线（一）：文档流四件套 spec / plan / tasks / delta	15 分钟
4	拆主线（二）：机制层四大护栏	15 分钟
5	合起来：亲手画完整闭环图 + 当日自测 + 打卡	15 分钟

先读讲义「3」再决定阅读策略：本文讲义把原文拆成「一条流水线 + 一圈围栏」，你带着这个框架去读原文，会比通读容易抓到结构。读的时候，在原文里把上面两层的词都圈出来。

3. 读之前：把文章当成「一张图」来读

3.1 为什么 Day 2 是「精读一张图」

Day 1 你建立了两个概念：SDD 管「做什么」，Harness 管「怎么做 / 做对」。但概念之间没有连线，就记不住、用不了。Day 2 这篇精读文章的价值，就是把概念变成一张有起点、有流向、有回路的图——也就是这个领域反复被提到的「闭环」。

闭环的意思是：不是「写完 spec 就完事」，而是 spec 会跟着代码一起长大、一起被验证、出问题能退回去改，改完再往前走。 没有回路的「流水线」是半成品；有了 delta spec + 验证打回，才叫闭环。

3.2 全文骨架先记住三句话

读完原文，无论细节多密，能复述出这三句话就算抓住了骨架：

AI 编程 = 两件事拼起来：先说清要什么（SDD），再保证 AI 把事做对、做可靠（Harness）。用一个式子记：Agent = Model + Harness——模型给「智能」，Harness 把智能变成「可交付的产物」。
SDD 落地为一份会流动的文档流：spec.md（做什么）→ plan.md（怎么做）→ tasks.md（怎么落地）→ 代码；需求一变，追加 delta spec，而不是推翻重来。
Harness 落地为一圈围栏：规则（CLAUDE.md+Skills）、流程与权限（Plan Mode+Permission）、事后验证（Hooks）、上下文隔离（Subagents）。围栏存在的全部理由：不靠 AI 自觉。

3.3 今天的思维体操：同一张图，两副眼镜

戴 SDD 的眼镜看：图里流动的「东西」是什么？（一份份规格文档，越来越细，最后变成代码）
戴 Harness 的眼镜看：图里静止的「围栏」是什么？（不管文档流到哪，谁在约束它、卡它、验它、隔离它）

戴两副眼镜看同一张图，你就能解释 Day 1 那张「全景图」了：SDD 让东西往下游流得对，Harness 让这条河流不出堤、坏了能被发现。

4. 精读主线（一）：文档流四件套 spec / plan / tasks / delta spec

4.1 一条从「模糊」到「可执行」的流水线

为什么不是只写一份 spec？因为一份文档无法同时服务三个不同的角色和三种不同的目的。流水线把它拆成四站，一站比一站更接近代码：

 人（意图，还模糊）
      │  第 1 站：写「做什么」
      ▼
  spec.md ──────► plan.md ──────► tasks.md ──────► AI Agent 写代码 ──► 产物 + 自证
  （WHAT/验收）    （HOW/架构）     （拆成可勾清单）        │
                                                          │ 错了？回到对应文档改

文档	谁写	在哪一步写	管什么	一句话作用
spec.md	人（Product Owner 角色）	动手规划之前	做什么（目标、用户故事、验收标准）	把「模糊需求」固化成可验收契约；AI 不用猜
plan.md	architect 角色	动代码之前	怎么做（技术方案、模块拆解、关键决策）	在动手前把实现路径想清楚，而不是写一半再想
tasks.md	architect → developer	动手之后逐条执行	怎么落地（有序任务清单）	把大工程切成小步，每完成一条勾一条
delta spec	人 + AI 迭代中	需求变更 / 发现 BUG / 做完一轮后	增量变更	承接「新出现的需求」，防止 spec 与代码脱节

4.2 为什么四份而不是一份：每一份都是「给不同角色的契约」

Day 1 讲过 One-shot 综合征——单个任务塞得越满，AI 越容易忘了开头约好的事。四份文档的分层，本质是把「信息密度」控制在每一步刚好够用：

spec.md 很薄、很稳定：只回答「要什么、怎么算完成」。它不该写「用什么技术栈」这类 HOW——那是 plan.md 的事。写混了，spec 就退化成「自然语言伪代码」，又长又没人维护。
plan.md 只在动手前需要：agent 拿着它规划，不需要在写代码时还背着一整份需求文档。
tasks.md 最细、最易变：是执行时的勾选清单，粒度小到 AI「做一步、验一步」，不会一口气跑偏两千行才发现。
delta spec 是唯一会「回填」的文档：下面单独讲。

4.3 delta spec：闭环之所以是「环」的关键

先记住这个词背后的病：规格腐烂（spec rot）。症状很常见——当初写的 spec 是真的，可是需求改了三次、代码迭代了五轮，spec 再也没人更新，于是 AI 以后读到的 spec 是过期的，它会拿一张错地图去开新车。

delta spec（增量 spec）就是治这个病的药，两个要点：

它是「增量」不是「重写」：需求变了，不需要推翻原 spec 全文重写（那又贵又容易引入新错误），而是在 delta spec 里追加/覆盖这一处变更，原 spec 保持稳定。改动可追溯：谁、什么时候、因为什么、改了哪一处。
它是「迭代的呼吸」：做完一轮、或线上冒出 BUG、或产品改了主意——先补一段 delta spec，再让 AI 动代码。等于每次变轨前先更新地图，杜绝「AI 按旧 spec 自由发挥」。

一句话记忆：spec 管「第一次是对的」，delta spec 管「一直是对的」。

4.4 文档流这一段，各自治了 Day 1 的哪个病？

Day 1 的瓶颈	文档流里的「药」
上下文失控（AI 忘了约束）	spec 在动手前固化了意图，AI 不用靠猜
One-shot 综合征（一次塞太多）	plan / tasks 把大任务切成可逐条勾的小步
隐性知识丢失（约定不在代码库里）	spec 把「为什么这么设计」变成机器可读的仓库资产
返工不可控（改漏、改歪）	delta spec 让每一次变轨都有据可查、可回退

5. 精读主线（二）：机制层四大护栏

文档流只解决了「方向对」。AI 会不会跑偏、闯祸、骗你，文档管不住——所以还要一圈围栏。围栏的哲学是 Day 1 引过的那句话的反面：不能指望每次多叮嘱两句，要靠工程化让它「想犯错也犯不成」。

5.1 CLAUDE.md + Skills：让 AI「懂规矩、有手艺」（规则层）

CLAUDE.md：项目级「宪法」。放这个项目的领域术语、编码约定、不许碰的红线、历史踩坑……每次会话自动加载进上下文，解决「新开对话就要把约定重讲一遍」的隐性知识问题。它由人写、由人维护，AI 不该擅自改写它。
Skills：把某类专家经验打包成可复用、可触发的技能（例如「verify 技能」「SDD 编排技能」）。名字或描述命中就触发，让 AI 不只「能写代码」，还会「按这个项目的方式干活、守这个项目规矩」。

这一组管的是「AI 知道规则吗」——把存在人脑、聊天记录里的规矩，搬进仓库，让 AI 看得见。

5.2 Plan Mode + Permission：动手前的一道闸 + 动手时的权限围栏（流程/权限层）

Plan Mode（规划模式）：默认是只读的。做非平凡改动前，AI 先只读探索、产出一份方案给你批准——没批准不能动文件。这就把 Day 1 的「过早宣布胜利 / 自由发挥」挡在动手之前：方向你确认过了，它才往下写。
Permission（权限）：即便方案获批，具体执行时 AI 能碰什么仍被围住——危险命令（rm -rf、强推、越权脚本）进黑名单或必须人工确认，不是「AI 觉得危险才停下」，而是系统层面就拦。

这一组管的是「AI 能越权吗」——把「先规划、再动手」「可碰 / 不可碰」从人的口头叮嘱，变成工具的强制流程。

5.3 Hooks：不靠自觉的确定性验货（验证层）

Hooks 是挂在 AI 生命周期事件上的外壳脚本（会话开始、工具调用前/后、本轮结束……）。它的本质和上面截然不同，也是全图最关键的一点：

Hooks 是确定性的：由人写、由机器跑，不由模型「决定要不要做」。

举例：

Stop hook：AI 说「完成了」想结束前，先跑你的验证脚本，验证不过就阻止它停止——「完成」=「门禁绿灯」，而不是 AI 的一句话。
Pre/PostToolUse：调用危险命令前硬拦截；生成完代码后自动格式化。
提交前钩子（pre-commit）：这就是第 2 周你要亲手装的那个——「只改了代码、没写 spec → 提交被拦」，把 SDD 的规矩焊进 Git，AI 想绕过也绕不过。

Day 1 的「无法验证」靠什么解？一半靠人（Review、验收标准），另一半靠 Hooks 这种机器门禁——它能审计、能拦截、可回退，且不受模型发挥波动影响。

5.4 Subagents：上下文隔离的小隔间（隔离层）

AI 的主上下文是有限的（Day 1 讲过）。Subagents 的做法是：为某个专门任务开一个独立上下文的子代理，让它在自己的小隔间里干活，只把结论交回主对话。

典型用法是多角色分工：写 spec 的、写 plan 的、写代码的、只读审查的、跑验证的……各自冷启动、各读各需要的文件，谁也不背着整份项目历史干活。效果：主上下文不被无关文件污染，每个子代理「装得少、想得清」，且只读角色（reviewer）天然无法改代码——审查就干净了。

这一组管的是「AI 的注意力会不会被稀释」——用物理隔离，代替靠提示词祈祷它「别忘事」。

5.5 四大护栏合并成一句话

护栏	对应组件	一句话（守什么）
规则护栏	CLAUDE.md + Skills	让 AI 懂规矩、有手艺（解决隐性知识）
流程/权限护栏	Plan Mode + Permission	让 AI 先规划、不越权（解决自由发挥/闯祸）
验证护栏	Hooks	让 AI 完成 = 门禁过（解决无法验证）
隔离护栏	Subagents	让 AI 上下文不打架（解决注意力稀释）

记忆口诀：规则管得住、流程卡得住、结果验得出、上下文分得开。

6. 合起来：完整闭环图（今天的核心输出物）

现在把两条线拼成一张图。请你自己也画一遍——能徒手画出来，才算学会：

        【SDD 半圆：管「流什么」——把对的东西流向代码】
 人(意图)
   │ 写 spec
   ▼
 spec.md ──► plan.md ──► tasks.md ──► AI Agent 实现 ──► 产物
 (做什么/验收) (怎么做)  (拆任务)           │               │
      ▲                                    │ 自证/测试     ▼
      │◄────────────── Hooks 门禁 / 人工 Review ◄───── 验证  ◄── 不通过就打回
      │（回到 spec/plan/tasks 改）                              │ 通过
      │                                                         ▼
  上线 → 新需求 / BUG                                         提交入库（Git = 记忆 / 回退）
      │                                                          
      ▼                                                          
 delta spec（增量变更）──── 回到循环起点，继续流                   

        【Harness 半圆：管「怎么流」——给流水线装围栏】
 CLAUDE.md+Skills（规则）＝ 河道两边的护栏，全程约束
 Plan Mode + Permission（流程/权限）＝ 上游水闸：先批准方案，才放水进下一段
 Hooks（验证）＝ 每道闸口自动验货，验不过拦下
 Subagents（隔离）＝ 不同河段（角色）各走各的支流，互不污染

用这张图讲一个「改需求」的完整旅程（检验你是否真懂）：

产品要加个新字段 → 人先写 delta spec（增量，不推翻旧的）；
AI 读 spec + 现有代码，进 Plan Mode 产出方案 → 你批准后它才动；
它照着 plan 拆成 tasks 一条条做，边做边自证；
想提交？pre-commit / Stop hook 先查：spec 更新了吗？测试过吗？没过就拦；
提交入库，Git 记下这轮一切 → 下次再改，历史可回退；
全程，CLAUDE.md 在约束风格红线、Permission 在拦它碰不该碰的东西、Subagents 让审查者在只读小隔间里干净地 review。

记住闭环的三个回环：① delta spec 回填（需求变了更新地图）；② 验证打回（做错了退回改 spec/plan）；③ Git 存底（一切可追溯、可回退）。没有这三条回环，它只是一条「看着很规范的单向流水线」，不是闭环。

7. 精读时怎么记笔记（防走神三连）

读到原文哪一段，就用下面三问过一遍，保证不白读：

这一段属于哪个半圆？（SDD 文档流 / Harness 机制层 / 还是两者的接口？）
它治的是 Day 1 的哪个病？（上下文失控 / 无法验证 / 出码率≠提效 / 隐性知识……）
它堵的是「自觉」还是「漏洞」？（凡 Harness 组件，答案都应是后者——这正是它存在的理由。）

如果三问中有一个答不上来，就把原文那句话抄进你的 Day2 草稿，标个「？」，Day 7 复盘时回来解决。

8. 当日自测

先合上讲义作答，再对照文末「参考答案」。

选择题（单选）

关于「文档流四件套」，下列说法正确的是？
- A. spec.md 由 developer 在写代码的同时撰写，负责记录实现细节
- B. spec.md 描述「怎么做」，plan.md 描述「做什么」
- C. spec.md 定义「做什么」、plan.md 规划「怎么做」、tasks.md 把方案拆成可勾选清单、delta spec 承接迭代中的变更
- D. delta spec 要求每个功能每次迭代都全文重写一份 spec
关于 Hooks，下列说法最准确的是？
- A. Hooks 是让 AI 自己决定何时该运行格式化与测试的工具
- B. Hooks 是挂在生命周期事件上的确定性门禁脚本，由人写、由机器跑，不由模型决定是否执行
- C. Hooks 只能用来做代码格式化
- D. Hooks 与权限无关，只负责事后清理
delta spec 存在的主要目的是治理？
- A. 单次请求的上下文过大
- B. 规格腐烂——迭代后 spec 与代码脱节，AI 拿到过期地图
- C. 模型权重漂移
- D. 权限配置混乱
Subagents 的主要作用是？
- A. 让单个 agent 跑得更快
- B. 用独立上下文隔离任务，避免主上下文被无关文件污染、保证只读角色干净审查
- C. 替代 Hooks 完成验证
- D. 只是给 AI 起个角色名字，无实际机制
关于「闭环」，最接近文章主张的是？
- A. spec 写一次便永久有效，之后代码随意迭代
- B. 写了 spec 就等同于完成需求评审，可以跳过 Code Review
- C. 人确认意图 → AI 产出 spec/plan/任务并实现 → Hooks 与人工验证 → delta spec 承接变化 → 回到循环；CLAUDE.md 与 Plan Mode/Permission 全程约束
- D. Harness 只在 CI 阶段生效，与写代码过程无关

简答题

请用 5 句话讲一遍「完整闭环图」：必须包含四份文档、四大护栏，以及「需求变了」这一轮里它流经了哪些环节、在哪一步可能被打回。
为什么 delta spec 是「增量」而不是「全文重写」？请在你自己的项目（或一个想象的项目）里，指出一处最可能发生「规格腐烂」的地方。

9. 今日打卡输出

建议新开一个文件（同一目录下，命名如 Day2-闭环图草稿.md），放三样东西：

你亲手画的闭环图（文字版 / 手绘拍照 / 在线图都行）——越简单越好，能讲给别人听就行。
一张自查表：把上文的四大护栏列出来，对照你手头项目，如实勾「已落地 / 部分有 / 完全没有」。第 2 周 Day 8–10 装 harness 时，这张表就是你的验收清单。
三个问题：读完原文你「以为懂了、其实没懂」的三处，各写一句卡在哪。

这份草稿是 Day 7「周复盘 + 第一篇学习笔记」与 Day 8「四大护栏」课的另一份原料，和 Day 1 的 Day1-反思草稿 放一起存好。

10. 术语速查卡（Day 2 版）

术语	一句话解释
spec.md	定义「做什么 / 怎么算完成」的规格文档，人写、先于代码，SDD 的核心契约
plan.md	规划「怎么做」的技术方案，动代码前由 architect 产出
tasks.md	把 plan 拆成可勾选任务清单，developer 逐条实现并打勾
delta spec	迭代 / 需求变更 / BUG 时追加的增量规格，治「规格腐烂」，不必全文重写
规格腐烂	spec 与代码脱节、spec 过期，AI 拿旧地图开新车
CLAUDE.md	项目「宪法」：领域术语 / 约定 / 红线，每次会话自动加载，让 AI 看得见规则
Skills	打包的专家技能，命中触发，让 AI 按项目方式干活
Plan Mode	只读规划模式：非平凡改动先产出方案、经人批准后才允许动文件
Permission	权限围栏：危险命令 / 工具白黑名单，由系统拦截而非靠 AI 自觉
Hooks	挂载在事件（会话开始 / 工具调用前 / 停止前…）上的确定性门禁脚本
Stop hook	在 AI 想宣布「完成 / 停止」时先跑验证，不过就阻止其停止
Subagents	独立上下文的子代理，隔离任务、只交结论，防上下文污染
Agent = Model + Harness	模型提供智能，Harness 把智能变成可交付、可验证的产物

11. 延伸阅读

今日精读（必读）

资源 1《SDD 和 Harness：AI 编程的两大支柱》（CSDN）——今天的全部骨架都来自这里，务必读原文原文中圈出两组词：spec / plan / tasks / delta spec；CLAUDE.md+Skills / Plan Mode / Permission / Hooks / Subagents
- https://blog.csdn.net/qq_43284469/article/details/164267908
- 阅读时带着 7. 节的「防走神三连」去读。

机制层官方文档（可选，把 Harness 组件查实）

Claude Code 内置帮助：在 Claude Code 里用 /config、/permissions 和 /help 查 Settings；Hooks 配置见项目 .claude/settings.json（SessionStart / PreToolUse / PostToolUse / Stop 等事件）。第 2 周实操时会逐个接触。

对照阅读（可选，进阶 5 分钟）

资源 4《AI 编程可闭环协作·卷三：Harness 与 SDD》（掘金）——今天只需扫「合并前自动检查 / 书面审查」这一节，看另一个团队怎么把同一条闭环落地成协作流程（Day 25 会精读）
- https://juejin.cn/post/7647333934796537919
资源 1 之外可搜同主题：以「Agent = Model + Harness」「Spec 是代码的压缩表示」为关键词看更多实现

完整八条资源清单见计划主文件《SDD+Harness四周学习计划.md》的「学习资源清单」一节。

附录 A：参考答案

选择题

C —— A 反了（spec 是人先于代码写，不是 developer 写实现）；B 把 spec 与 plan 分工说反；D 是全文重写，恰好违背「增量」。
B —— Hooks 的确定性是它与「让 AI 自觉」的本质区别；A/C/D 都错（不止格式化、与权限无关的说法也是错的，验证本身就是权限与质量的延伸，但最本质区别在「不由模型决定」）。
B —— delta spec 的靶子就是规格腐烂；A 属上下文管理，C/D 是第 3 周才会遇到的模型 / 配置问题。
B —— 隔离是目的；A/C 都是对 Subagents 职责的误读；D 忽略了它确实有独立上下文的机制。
C —— 只有 C 同时包含了文档流、护栏、验证打回与 delta 回填四条要素。A 违背 delta spec；B 是常见陷阱——spec 替代需求文档，不替代 Code Review；D 把 Harness 缩窄成 CI。

简答题（要点，供自评）

评分看五点是否齐全：① 有人 → spec 的起点；② 有 spec → plan → tasks → 代码的文档流向；③ 有 Hooks / 人工 Review 的验证与「打回」；④ 有 delta spec 承接需求变化并回填；⑤ 有 CLAUDE.md、Plan Mode/Permission、Subagents 作为全程约束（规则 / 闸门 / 隔离）。缺「打回」或「delta 回填」都不算闭环。
要点：全文重写成本高、易引入新错、且丢掉了变更历史；增量只追加「这一处变化」，原 spec 稳定可追溯。自评「规格腐烂」风险点时，找需求常变但文档没人维护的地方（如接口契约、数据字典、业务规则描述），并指出补救 = 每次变轨前先补 delta spec。

SDD+Harness 四周学习计划 · Week 1 · Day 2