SDD + Harness 四周学习计划 · Week 1 · Day 4（认知打底第 4 课）
今日主题：SDD 的三种落地方式——Spec-Kit（自动化）、OpenSpec（手动控制 + delta spec）、轻量手工；理解取舍与适用场景
建议用时：60–90 分钟 ｜ 参考文章：见文末延伸阅读（Spec-Kit 官方、OpenSpec 仓库、多篇选型对比）
输出物：给一个真实/想象项目填一张「三选一决策表」并给出你的选择与理由——这是 Day 7 复盘和《研究式学习手册》4.5「对比/决断日剧本」的第一个案例
0. 一句话剧透
「SDD 三种落地方式」问的从来不是「哪个工具最强」，而是「自动化到什么程度、治理浓度多高、你愿意为规范付出多少仪式成本」——三者是同一条原理的三个档位：
- Spec-Kit：把 spec 流程做成一条门控管道，一步步逼你走完，约束最重（适合从零起步的团队大项目）。
- OpenSpec：轻量得多，以「一次变更」为单位，用 delta spec 增量累积一份「系统真实现状」的主 spec（适合改存量项目、快迭代）。
- 轻量手工：不借任何工具，你自己在 git 里写 spec——本周你 Day 5 就在干这件事，Week 2 的 harness 则是给这种手工流程装上护栏。
今天不要求背命令（Spec-Kit 的四命令、delta spec 怎么用，Day 6 才深讲）。今天只做一件事：给这三种方式选一个主判据，学会在具体项目里对号入座。
1. 今日目标（学完你能做到）
- 能用一句话说出三种方式的本质差别是「自动化程度 × 治理浓度 × 仪式成本」，而不是「谁强谁弱」
- 能说清 Spec-Kit 的重治理、OpenSpec 的 delta spec 累积、轻量手工的零依赖，各解决什么、各牺牲什么
- 能区分 绿地（greenfield）vs 棕地（brownfield），并说出它们各自更该选哪种
- 能给任意一个项目填「决策表」，得出一个有理由的选择（而非凭感觉）
- 能意识到一个共同软肋：没有任何工具真正解决「spec 与代码同步漂移」，以及「spec 纯文本活得比工具久」
目标对应评估标准第 2 条（能讲清三种方式取舍）。Day 4 是选型，Day 6 才是用工具；别混。
2. 学习动线（建议时间分配）
| 步骤 | 内容 | 用时 |
|---|---|---|
| 1 | 「3」：先立认知——三档不是三家人，是一条自动化谱系 | 5 分钟 |
| 2 | 「4」：逐个拆 Spec-Kit / OpenSpec / 轻量手工 | 25 分钟 |
| 3 | 「5」：三线对比总表（本课核心产出） | 15 分钟 |
| 4 | 「6」：选型决策（4 个自问 + 决策表） | 15 分钟 |
| 5 | 当日自测 + 打卡（填决策表） | 10–15 分钟 |
今天是《研究式学习手册》里的对比/决断日：别问「哪个好」，问「什么维度能分出差别」——加判据的过程比答案更值钱。
3. 先立认知：这是同一条原理的三个档位，不是三家公司
Day 3 你已经会判断「一份 spec 好不好」了。今天要回答的上升一层：这份 spec 由什么流程来生产、维护、防漂移？ 三种落地方式就是三种答案，本质区别在谁替你做多少：
1
2
3
轻量手工 ◄────────────────── 自动化谱系 ──────────────────► Spec-Kit
0 工具，全靠人自律 AI 半自动、人点确认 门控管道，一步步卡死
（Week1/2 你自己 + harness） （OpenSpec：改存量、快迭代） （重治理、绿地、团队）
三档不是「高级/低级」，是三个交换：
| 档位 | 用「治理浓度」换到 | 付出「仪式成本」 | 最适合的土壤 |
|---|---|---|---|
| 轻量手工 | 完全的掌控与零依赖 | 全靠人自律，易漂移 | 个人、原型、想打底的人 |
| OpenSpec | 轻快、增量、文档自动累积 | 要学一套 change/delta 概念 | 棕地/存量、快迭代 |
| Spec-Kit | 强约束、可预测、审计痕迹 | 最重（文档多、步骤多） | 绿地、团队、合规要求 |
一个关键心法（后面详述）：工具只是「怎么存放和推进这些文档」的方式，真正值钱的是 spec 里的纯文本本身——它比任何 CLI 活得久，换工具零成本。 所以今天选型，别把自己绑死在某个工具上。
4. 逐个拆三种落地方式
4.1 Spec-Kit：自动化 × 门控管道（治理层）
它是什么：把 SDD 做成一条按顺序执行的命令管道，每步产出、人工确认后进入下一步，防止 AI（和你）跳步。典型最短链路就是你在计划里看到的四命令：
1
/specify（写要什么/为什么）→ /plan（定技术方案）→ /tasks（拆可执行清单）→ /implement（按单写码）
它的门控不只这四步：正式用法通常还有 constitution（先立项目宪法/红线）、clarify（AI 抛结构化问题消歧）、analyze（交叉检查 spec/plan/tasks 一致性）等质量闸门。特点：
- 哲学：代码服务规范，规范是源头；规范即生成实现的依据。
- 换到的：流程严谨、每步有人工卡点、clarify/analyze 显著减少返工、有完整审计痕迹、能把合规要求编码进流程。
- 代价：重。一次变更可能产出数百行文档、八步仪式——改个 5 行的小修复也要走全套。批评者直言这是「重新发明的瀑布流」。
- 适合：绿地项目、多特性复杂系统、需要强约束与高可预测性的团队、合规行业（医疗/金融/政务）。
4.2 OpenSpec：手动控制 + delta spec（连续性层）
它是什么：一个以「变更（change）」为单位的本地 spec 框架，核心假设是「你大多数时间在存量代码上做增量修改」。初始化后目录大致是：
1
2
3
4
5
6
7
8
openspec/
├── specs/<domain>/spec.md # 主 spec：系统「当前真实行为」的单一事实源
├── changes/<change-name>/ # 一次进行中的变更
│ ├── proposal.md # 为什么做、做什么（意图与范围）
│ ├── specs/<domain>/spec.md # ★ delta 增量规格
│ ├── design.md # 怎么做（方案/架构）
│ └── tasks.md # 实现清单（勾选推进）
└── archive/ # 已归档变更（审计历史）
核心机制——delta spec（对应 Day 2 你学的「增量回填」，这里是它的完整实现）：
- 每次变更不重述整个系统规范，只在变更目录里写「我要对主 spec 增/改/删什么」：
1
2
3
4
5
6
7
8
9
10
# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.
#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
## MODIFIED Requirements #（附 Previously 说明改了什么）
## REMOVED Requirements
-
变更完成、人确认后
archive（归档）：ADDED 追加进主 spec、MODIFIED 替换、REMOVED 删除——主 spec 永远等于「已实现的真实现状」，且两个并发变更只要不碰同一需求就不冲突。 -
人通过少量命令手动推进：
new（开变更）→propose（一键生成提案+delta+tasks）→apply（按 spec 实现）→archive（合并归档），另有validate（校验一致性）、ff（一次生成全部规划产物）等。 - 换到的：轻、增量小步、快迭代、文档自动累积成一份「活的系统说明书」、不需要 MCP/API key。
- 代价：无强制门禁（validate 只查结构不阻塞）；对超大复杂需求的经验覆盖还不足；大版本迭代替换整份主 spec 时偏繁琐。
- 适合：棕地/存量项目、重度用 AI 代理、追求快速反馈循环、想把「当前系统到底是什么样」沉淀成知识库的个人与团队。
4.3 轻量手工：零依赖，你 + git 自己来
它是什么：不装任何 SDD 工具。你按 Day 3 的七要素在 git 里手写 spec，流程靠你自己和团队纪律，最多再配点护栏（这正是 Week 2 的 harness 干的事：spec 放 .ai/specs/，用 pre-commit 拦「只改代码没写 spec」的提交）。
- 换到的：完全掌控格式与节奏、零工具依赖/零学习成本、不会被工具绑架。
- 代价：一切靠人自律——没人盯着就容易跳步、spec 漂移；消歧、拆任务、一致性检查全落自己头上。
- 适合：个人学习与原型、团队想彻底掌控、以及只想用 SDD 原理 + 一条 harness 护栏打底的人。本周你走的就是这一档，Day 5 亲手写、Week 2 加护栏。
5. 三线对比总表（本课核心，可抄进打卡）
| 维度 | Spec-Kit | OpenSpec | 轻量手工 |
|---|---|---|---|
| 本质定位 | 治理层（重流程） | 连续性层（重增量） | 你自己 + git（零依赖） |
| 自动化程度 | 高：命令门控管道 | 中：命令帮生成，人确认推进 | 低：全人肉 |
| 核心命令 | /specify→/plan→/tasks→/implement（可加 constitution/clarify/analyze） | new→propose→apply→archive | 无（或用 harness 的 spec 命令） |
| spec 存放 | 每特性多文件 | 主 spec + changes/delta 累积 | 你想放哪放哪（建议 .ai/specs/） |
| delta spec | 有概念，非核心卖点 | ★ 核心：ADDED/MODIFIED/REMOVED 归档合并 | 你自己手写增量 |
| 防 spec 漂移手段 | 流程门禁 + 文档纪律 | archive 让主 spec 永远=真实现状 | 靠纪律 + pre-commit 拦无 spec 提交 |
| 单次变更文档重量 | 重（可达数百行） | 中（约百来行） | 随你 |
| 仪式成本 | 最高（小改动也走全套） | 中（以变更粒度，小修仍要建 change） | 最低（想写就写，想略就略） |
| 治理/门禁 | 有（每步卡点，可出审计） | 弱（validate 不阻塞） | 自己定（可借 harness 强约束） |
| 适合场景 | 绿地、团队、复杂多特性、合规 | 棕地/存量、快迭代、AI 代理重度使用 | 个人、原型、想掌控一切的人 |
| 主要坑 | 过规格化、仪式感劝退、小修 overkill | 无硬门禁，大重构换主 spec 繁琐 | 易漂移、一致性全自己扛 |
6. 怎么选：四个自问 + 一张决策表
6.1 四个自问（按顺序过，答案通常自己就出来了）
- 绿地还是棕地？ 从零写系统 → 值得上 Spec-Kit 的重治理；改已有存量 → OpenSpec 或轻量手工，别把旧代码硬塞进新管道。
- 谁能扛仪式成本？ 单人/小团队、功能常是几行到几百行的小迭代 → 8 步门控会逼人绕过，选轻的；大团队/多特性并行 → 重治理反而省混乱。
- 你要「强制」还是要「快」？ 合规、多人协作、改错了代价高 → 要强制门禁（Spec-Kit，或轻量手工 + harness 钩子）；要快速反馈、愿信纪律 → OpenSpec。
- 你依赖 AI 到什么程度、工具淘汰了怎么办？ 重度用 AI 代理且要文档自动累积 → OpenSpec；不想被工具绑架、spec 要迁移零成本 → 写纯文本，格式自己管（轻量手工），这是唯一「工具换代也死不了」的档位。
6.2 一张决策表（打卡时把三列打勾加权，最后给结论）
| 判断维度 | Spec-Kit | OpenSpec | 轻量手工 |
|---|---|---|---|
| 我的项目：从零建 / 改存量？（绿→棕） | |||
| 我的团队：1 人 / 几人 / 大团队？ | |||
| 我多看重「强约束、可审计」？ | |||
| 我多在乎「每次迭代轻快」？ | |||
| 我愿意维护多少文档？ | |||
| 我担心工具会过气/被弃用吗？ | |||
| 合计（给我一个结论） |
没有标准答案。结论要能说出一句理由，而不是「看起来高级」。参考判据：单人或棕地快迭代→偏 OpenSpec/轻量手工；团队绿地要可预测→偏 Spec-Kit。
6.3 对照：本四周计划自己走哪条？
诚实说：这四周走的是「轻量手工 + harness 护栏」，外加拿 OpenSpec 当学习参照。 Week 1 你手写 spec（轻量手工档），Week 2 装的 harness 就是给这档加确定性护栏。所以今天学 Spec-Kit / OpenSpec 的真正目的，不是「我现在要切过去」，而是看懂工具如何把同样的原理自动化——你已能写七要素 spec，再看工具只是把这份 spec 的生成与维护自动化而已。
7. 当日自测
先合上讲义作答，再对照文末「参考答案」。
选择题（单选）
- 三种落地方式的本质差别是？
- A. Spec-Kit 最强，OpenSpec 次之，轻量手工最弱
- B. 自动化程度 × 治理浓度 × 仪式成本的取舍，不是强弱之分
- C. 只有 Spec-Kit 和 OpenSpec 是 SDD，轻量手工不是
- D. 取决于用哪种编程语言
- OpenSpec 的 delta spec 机制，最准确的说法是？
- A. 每次变更都要重写整份系统 spec 以保证准确
- B. 变更只记录增/改/删的片段，归档时合并进主 spec，使主 spec 始终等于系统真实现状
- C. delta spec 只用于测试，与主 spec 无关
- D. 归档后 delta 会被永久丢弃
- 关于 Spec-Kit，下列说法错误的是？
- A. 它是一套按顺序执行的命令门控流程，典型四命令是 /specify→/plan→/tasks→/implement
- B. 适合从零起步、需要强约束与可预测性的绿地项目
- C. 仪式成本高，小功能修复也走全套流程，有人批评它是「重新发明的瀑布流」
- D. 它完全不需要人工确认，全自动跑完
- 「轻量手工」这一档最贴近的说法是？
- A. 一种低配版 Spec-Kit
- B. 不依赖 SDD 工具、靠人自律在 git 里手写 spec；Week 2 的 harness 可给它加确定性护栏
- C. 只适合玩具项目，生产项目不能这么干
- D. 就是 Vibe Coding 的别名
- 下面哪句话最接近「所有 SDD 工具的共性软肋」？
- A. 工具越贵越好用
- B. spec 越写越长就越不会漂移
- C. 没有任何主流工具真正解决「spec 与代码保持同步」的漂移问题；且 spec 的纯文本比任何 CLI 活得久
- D. 只要用了工具，AI 就不会跑偏
简答题
- 用一句话分别说出：绿地项目该倾向哪种、为什么；棕地项目该倾向哪种、为什么。
- 为什么说「今天选型真正该投入的是 spec 的纯文本，而不是绑死某个工具」？请结合「工具迭代快、spec 需长期存活」解释。
8. 今日打卡输出
建议新开一个文件（同一目录，如 Day4-选型决策表.md），放三样东西：
- 填好的决策表（第 6.2 节那张，选一个真实/想象项目）。
- 一句话选择理由：用四个自问里的证据链写：「因为 __，我选 __；它牺牲了 __，我接受。」（选不出也没关系——写下「我在 __ 维度上拿不准」，这是研究式学习的好产出。）
- 一段 3 行的资料对照：Spec-Kit 命令 → OpenSpec change/delta → 轻量手工三档，各自对应你四周计划里的哪一周/哪件事（Week1 手写 spec、Week2 harness……）。
Day 7 复盘时这张表 + Day 2 闭环图 + Day 3 骨架卡，就是你本周「理解 SDD」的完整证据链。
9. 术语速查卡（Day 4 版）
| 术语 | 一句话解释 |
|---|---|
| 落地方式 | 同一条 SDD 原理的不同「生产/维护 spec 的流程」，区别在自动化与治理浓度 |
| Spec-Kit | 门控命令管道式的 SDD 落地；典型 /specify→/plan→/tasks→/implement，可加 constitution/clarify/analyze |
| constitution | Spec-Kit 里的「项目宪法」：红线、测试底线、技术栈约束 |
| clarify | Spec-Kit 里让 AI 抛结构化问题消除歧义的一步 |
| analyze | Spec-Kit 里交叉检查 spec/plan/tasks 一致性、输出问题表的闸门 |
| OpenSpec | 以「变更（change）」为单位、靠 delta spec 增量累积主 spec 的轻量框架 |
| 主 spec（openspec/specs） | 描述系统「当前真实行为」的单一事实源，经归档合并永远等于真实现状 |
| delta spec | 只记录本次变更对需求的 ADDED/MODIFIED/REMOVED 片段，归档时合并 |
| archive | OpenSpec 归档：合并 delta 进主 spec，变更目录进 archive/（审计历史） |
| 轻量手工 | 不依赖 SDD 工具，人自律在 git 里写 spec；可加 harness 护栏 |
| 治理层 vs 连续性层 | Spec-Kit 重流程门禁=治理层；OpenSpec 重增量累积=连续性层 |
| 绿地 / 棕地 | greenfield 从零建 / brownfield 改存量代码库 |
| 仪式成本 | 每做一次变更要付出的流程与文档代价；小改动也走重流程=高仪式成本 |
| spec 漂移 | spec 与代码脱节、spec 过期（Day 3 的「规格腐烂」） |
| 过规格化 | 把 spec 写得太重（混入 HOW、文档膨胀），反而没人维护 |
10. 延伸阅读
今日精读（选型对比，任选一两篇吃透即可）
- 《一篇文章告诉你，Spec-Kit、OpenSpec 哪个适合你》（腾讯云，中文选型对比）： https://developer.cloud.tencent.cn/article/2663371
- 《OpenSpec vs Spec Kit: Choosing a Spec-Driven Framework for AI-Agent Development》：https://www.bighatgroup.com/blog/openspec-vs-speckit-spec-driven-ai-development/
- 《spec-kit 和 openspec 的对比》（掘金，中文）：https://juejin.cn/post/7594757769557180425
一手源（工具仓库/官方，作为「证据」而非转述）
- OpenSpec（Fission-AI，GitHub）——读 README 的目录结构、commands、delta spec 示例： https://github.com/abdihaikal/OpenSpec
- Spec Kit（GitHub 官方）——命令门控与 constitution 的官方说明，以你实际 init 后看到的为准。
进阶（共同的未解问题 + 一句重要提醒）
- Spec-Driven Development 工具对比与批评（spec-coding.dev，含「工具比工具选型更脆弱」的洞察）： https://spec-coding.dev/blog/spec-driven-development-tools-openspec-spec-kit-superpowers
- 提醒：SDD 工具迭代极快、易换血；真正持久的是 spec 的纯文本——迁移工具零成本。
本讲义按计划把三种方式归类为「Spec-Kit（自动化）/ OpenSpec（手动控制 + delta spec）/ 轻量手工」；真实工具的细节会持续演进，以各工具当前官方文档为准。完整资源清单见计划主文件。
附录 A：参考答案
选择题
- B —— 三种方式是同一条原理的三个自动化档位；A/C/D 都是错误二分。
- B —— delta 只记增量片段，归档合并进主 spec，使主 spec 始终等于真实现状；A/C/D 均误读。
- D —— Spec-Kit 恰恰每步要人工确认/卡点，不是全自动；A/B/C 都对。
- B —— 轻量手工=零工具、人自律手写 spec，harness 可给它加强约束；它不是低配 Spec-Kit，也非玩具专属，更不是 Vibe Coding。
- C —— 所有工具都未真正解决 spec 同步漂移；纯文本 spec 比 CLI 活得久，是真正的资产。A/B/D 皆谬。
简答题（要点，供自评）
- 绿地：倾向 Spec-Kit（或轻量手工+重护栏）——从零起步没有存量包袱，重治理能从一开始就锁定规范，避免后期漂移与返工。棕地：倾向 OpenSpec（或轻量手工）——改存量代码最怕「把旧代码硬塞进新管道」，OpenSpec 的变更粒度与 delta 累积最适合增量小步改造，避免为每个小修付高仪式成本。
- SDD 工具迭代极快、今天选的 CLI 明年可能就不维护；而 spec 的核心资产是纯文本的「要什么、为什么、done 的定义」——它不依赖任何工具就能长期存活、迁移工具零成本。所以选型时把判断力投在「spec 内容写得好不好」（Day 3 七要素），而不是绑死在某个工具的目录格式上；格式是外壳，可换；内容是内核，要留。
