Spec-Driven Development：速成课
13 个概念 · 先就 what 达成一致，再生成 how
你让 AI 构建某个东西。它交回一段看起来 没问题 的 code。你运行它，它坏了。或者更糟：它能跑，但解决的是和你脑子里稍微不同的问题。于是你再解释一遍。AI 修好那一处，同时悄悄撤掉两条消息前已经做对的东西。一个小时后，你手里是一堆你不完全信任、也不容易 cleanly change 的 code。
这个 loop 有个名字：vibe coding。你给 AI 一个 vague idea，然后希望它猜对。对于 throwaway prototype，这没问题。但对于任何你打算 keep、deploy，或者交给别人的东西，这就是 trap。
Spec-Driven Development（SDD） 是走出这个 trap 的方式。你不再只是描述自己想要什么然后寄希望于模型，而是把它 写下来，写到 code 出现之前你和 AI 都能 agree。这个 written agreement 就是 spec。Code 变成 spec 产出的东西，而不是反过来。
这门课 end to end 覆盖这套 discipline。学完后，你可以自己用三种方式跑完整的 spec-driven build：在 claude.ai 中，也就是 web app、这里的 main tool；在 Claude Code 中；以及在 OpenCode 中。同一套 discipline 会迁移到三者上。
在 SDD 中，spec 是 source of truth，code 是 build output。 本课中的每个 concept，都是为了写出更好的 spec，更早就它达成一致，或者在 project grow 时让它继续保持 true。
你不需要凭信心接受这点。Anthropic 2026 年对约 400,000 个 agentic coding sessions 的分析发现了清晰的分工：人大多做 planning decisions，也就是决定 build 什么；agent 大多做 execution decisions，也就是决定怎么 build。并且一个 session success 的 strongest predictor 不是 coding skill，而是 domain expertise：人能多精确地 frame 工作、要求 agent verify 什么、以及 drift 时能否把它 steer 回来。SDD 就是让你擅长那一半仍然属于你的工作的 discipline。参见 Anthropic 的 Agentic coding and persistent returns to expertise。
约 400,000 个 sessions 中的 what/how split（Anthropic，2026）。SDD 是让你把 planning half 做好的 discipline。
那门课教你如何和 AI 说话：给 context、清楚地 ask、检查 work。这门课教你在 ask 任何东西之前 该做什么：如何把 fuzzy idea 变成一份 written spec，精确到可以从它 build。它和 Agentic Coding Crash Course 自然配套，后者深入讲 coding tools 的 mechanics。
你不需要是 programmer
SDD 是 thinking discipline，不是 coding skill。你几乎完全在 plain language 中、在普通 chat window 里 practice 它。Output 是一份清楚写好的 document，然后是从它 build 出来的 working result：app、script、report generator，或者 automation。如果你能给 competent colleague 写清楚 brief，你就能写 spec。（为什么这已经是 general skill，而不是 developer-only skill，见 Code You Never Write。）
Study 把这点变得 concrete：coding background 几乎没有改变 session 是否成功；domain expertise 改变了。这里不是让你写 code；而是让你足够了解自己的 problem，把它写下来：rules、edge cases、"done" 的含义。Spec 是你的 expertise 放进去的地方。 一个能 state 每条 reconciliation rule 的 accountant，比一个不懂账本的 developer 更能 build 出正确结果，因为 spec carries knowledge，而 agent supplies code。
三个 tools，一套 discipline
下面所有内容都在三个 tools 中有效。我们从 claude.ai 开始，因为它不需要安装，今天就能在 browser 中做 real spec-driven work，而且 chat-and-document loop 会让 thinking 可见。同样的 moves 可以 cleanly map 到两个 coding agents 上。
| claude.ai (main) | Claude Code | OpenCode | |
|---|---|---|---|
| What it is | The web/desktop chat app | Anthropic's coding agent (terminal/IDE) | Open-source coding agent, any model |
| Where the spec lives | An Artifact (an editable doc beside the chat) in a Project (a saved workspace) | Files in your repo (CLAUDE.md, specs/) | Files in your repo (AGENTS.md, specs/) |
| Best for | Thinking, drafting, non-coders, getting started | Building real software, end-to-end | Same, with model choice and cost control |
| Alternatives | ChatGPT (Projects + Canvas) and Gemini (Gems + Canvas) run the same discipline | (none) | (none) |
本课覆盖什么
| Part | Topic | 你会学到什么 |
|---|---|---|
| 1 | The Shift | Vibe coding 为什么会 fail，spec 到底是什么，SDD 的三个 levels |
| 2 | The Method | Constitution，然后四个 phases：Research → Specify → Clarify → Build |
| 3 | The Three Ways | 在 claude.ai、Claude Code 和 OpenCode 中运行 loop |
| 4 | A Complete Worked Example | 一个 feature，从 start 到 finish，先在 claude.ai，再在 Claude Code 中做 |
| 5 | Judgment | SDD 什么时候值得，什么时候 overkill，以及如何让 spec 保持 alive |
如果你刚开始而且时间少，就读 Concept 1（vibe coding 为什么 fail）、Concept 2（spec 是 product）、Concept 7（Clarify by interview）、Part 2 末尾的 four-prompt block，以及 Part 4 的 worked example。这是 minimal viable read；其余内容 later deepen。当你想真正掌握 discipline 时，最后的 Practice ladder 才是运行 full loop 的地方。这个 split 本身也是 SDD move：spine 是 spec，其余是 plan。
Part 1: The Shift
三个 ideas 会重新 frame 你和 AI 一起工作的方式。掌握它们，剩下的就是 mechanics。
1. Vibe coding vs. spec-driven development
差别在于 你什么时候 thinking。
Vibe coding 中，你在 AI build 的同时思考，通过 react 它交给你的东西来 discover 自己真正想要什么。这感觉很快：screen 上立刻出现东西。但每一轮 round trip 都会丢一点 context，AI 会用 reasonable-but-wrong assumptions 填补 gaps，result 也很少能和 project 的其余部分 match。Cost 会在后来一次性出现，当你想 change 或 trust 这个东西时才爆出来。
Spec-driven development 中，你 先 thinking，然后把它写下来。AI 不会开始 build，直到你们双方 agree "done" 的意思。Build 之后大多是 mechanical：它是在 execute agreement，而不是 guess agreement。
两个 loops：vibe coding 在 prompt、code 和 "not quite" 之间打转；SDD 先 front-load spec，再围绕它跑 short build-and-check loop。
这和你在 prompting 中学到的 same move 一样（context first, then ask），但 stakes 更高：AI 现在不是只回答 question，而是在你的 project 里 写 code。
Rule of thumb： 如果把 result 扔掉会让你 annoyed，你已经越过 vibe coding 的 safe point。写 spec。
2. The spec is the product; code is a build output
这是给 SDD 命名的 mental flip。几十年来，spec 服务 code：你写 brief，build 东西，然后把 brief discard。SDD 把它倒过来。Spec 是你 maintain 的 durable artifact；code 从它 generate， spec 改变时再 generate。"Re-generated" 不是按一个 magic compile button，而是在 updated spec 上重新跑 build loop 并 review result：spec guide 一个仍然可能犯错、仍需你 supervise 的 agent。
Inversion：旧方式把 spec 当成 code 的 scaffolding；SDD 让 spec 成为 source of truth，让 code 成为可重新 derive 的 output。
一份好的 spec 按顺序回答三个问题：
- Why： 我们在解决什么 problem，为谁解决？（多数 vibe sessions 从来不 state 的东西。）
- What： done 时必须 true 的是什么？Behaviours、inputs、outputs、rules、edge cases，以及明确 什么 out of scope。
- What not to build： boundaries。这个 single section 阻止大多数 "it did too much / it did the wrong thing" failures。
注意故意 missing 的是什么：how。Spec 描述 behaviour，不描述 implementation。"Users can reset a forgotten password via an emailed link that expires in 30 minutes" 是 spec。"Use a JWT and a Postgres tokens table" 是 implementation，属于 later phase 的 plan。太早把两者混在一起，是 beginner 最常见的 mistake：你在 agree behaviour 之前就 lock 了 technical choice。
问："Could a competent person build the wrong thing and still technically satisfy this line?" 如果可以，这一行太 vague，要 tighten。Spec finished 不是因为没有东西可加，而是因为没有东西可 misread。
3. The three levels of SDD
SDD 不是 all-or-nothing。有三个 levels，你根据 work 有多重要来选择。
| Level | 含义 | 什么时候用 |
|---|---|---|
| Spec-First | 先 upfront 写一次 spec，再从它 build。之后 spec 可能 drift。 | 大多数 features。Default。 |
| Spec-Anchored | Spec 持续作为 source of truth；behaviour 改变时你 update spec，并从它 re-derive。 | 任何你会 maintain 数月的东西。 |
| Spec-as-Source | Spec 是 the source；code 完全从它 regenerate，是 re-derivable output，但你仍然要 re-run 和 review。 | Mature、high-discipline teams and tooling。 |
本课中，从 Spec-First 开始，再 grow into Spec-Anchored。 Spec-as-Source 是 field 正在走向的地方，但你通过掌握前两个 levels 来 earn 它。Discipline 在每个 level 都一样；改变的只是你多严格地让 spec 保持 in sync。
Part 2: The Method
这个 workflow 有一个基础（constitution）和四个阶段（Research → Specify → Clarify → Build）：
方法概览：constitution 位于四个阶段（Research、Specify、Clarify、Build）之上；build 过程中发现任何 gap，都先回去修 spec。
4. The constitution: the rules above every spec
在任何单个 feature 之前，你先写一份短文档，记录适用于 所有 feature 的持续规则：这就是 constitution。在 coding agent 里，它是 rules file（CLAUDE.md / AGENTS.md）；在 claude.ai 里，它是你的 Project instructions。各处的想法相同：把你希望每个 spec 和 build 都遵守的原则、约束和约定写清楚。
这里有一个必须诚实说明的 caveat，因为它会改变你的用法：constitution 是 persistent context，不是 enforceable law。Agent 每个 session 都会加载它；规则越具体、越精简，它越可能稳定遵守。但「已加载」不等于「保证遵守」。对绝不能破坏的规则（不要碰 production data、绝不提交 secrets），不要只依赖 written rule；要用 tests、pre-commit 或 tool hooks、CI checks、更严格的 permissions，或者由人 review diff。constitution 表达 intent；这些机制负责 enforce。
constitution 是 principles，不是 encyclopedia。它回答「这里永远为真的是什么？」，不是「feature X 如何工作？」保持紧凑；AI 会反复读取它，臃肿的 rules 既昂贵，也会淹没真正重要的规则。好的 constitution 行长这样：
# Constitution — Smart Notes
## Principles
- Plain language over cleverness. A new contributor should understand any file in 5 minutes.
- Prefer well-established libraries over custom code. Research before reinventing.
- Every feature ships with its spec in `specs/`. The spec is the source of truth.
## Constraints
- Stack: keep it to what's already here. Propose, don't add, new dependencies.
- Never touch `published/` or anything in `src/generated/`.
## Definition of done
- Behaviour matches the spec, edge cases included.
- A human has reviewed the diff against the spec before merge.
constitution 会给之后的一切定调：如果一个周末项目也要求 enterprise-grade testing、performance budgets 和 heavy process，后续每个阶段都会继承这个重量，一个待办 app 会变成一座大教堂。让 constitution 匹配 stakes；之后可以再提高标准。
你可以亲眼看到它发生。给一个周末 habit-tracker 写一份要求 90% test coverage、performance budget、每次变更都写 decision record 的 constitution，第一个 feature 就会带出 benchmark harness、三层 abstraction 和 decision log：一个「给列表加一行」的按钮，被拉成一周 process。没人主动要求这些；constitution 要求了，之后每个 phase 都继承了它的重量。
相反的失败同样常见：constitution 太空，等于什么也没说。同一个项目的三种版本：
| 太轻（没用） | 太严（窒息） | 刚好 |
|---|---|---|
| "Write clean code. Be consistent. Use best practices." | 12 条关于 test coverage %、performance budgets、commit-message format 和 review steps 的规则，全给周末 app | 上面的 6–8 行：AI 无法推断的 principles，真正会咬人的 constraints，一个清晰的 "done" |
每条规则的测试和 spec 的每一行一样：删掉它会不会让 AI 犯错？ "Write clean code" 不通过，因为 AI 本来就会尝试这么做，所以这行没有信息量。"Never touch published/" 通过，因为 AI 不可能自己知道这个约束。
5. Phase 1: Research before you write
你无法 spec 一个自己还不理解的东西。在写任何 spec 之前，先让 AI 帮你地图化现场：问题、用户、约束，以及（对现有项目）当前代码如何工作、新东西需要插到哪里。
这里的 power move 是 parallel research：不要让一个长对话一路来回，而是让 AI 同时调查几个问题并汇报。在 chat 里，你要求一个结构化 findings document；在 coding agent 里，你可以真正用 subagents，每个在自己的 context window 研究一个区域，再交回 summary（让主对话保持干净，这正是 Agentic Coding Crash Course 里的 context discipline）。
输出 不是 code，也 还不是 spec。它是一份短 findings document：现状、选项、未知点，并把这些喂给 spec。三个工具里都能用的 prompt：
Research what's involved in building [feature]. Investigate these separately and report each on its own: (1) how this kind of thing is usually done, (2) the main approaches and their trade-offs, (3) anything in our existing project it has to fit, (4) the failure modes and edge cases I should worry about. Give me a one-page findings doc: what exists, the options, and what's still unknown. Don't propose a final design or write any code yet.
6. Phase 2: Write the spec (the what and why, never the how)
现在基于 research 写 spec。不要从空白页开始：和 AI 一起 draft，然后由你把它 sharpen。Concept 2 的三个问题（why、what、what not to build）会展开成六个具体部分。一份可用 spec 至少包含：
- Goal： why，用两三句话说明。
- User scenarios： 「用户做 X 时，得到 Y」的 walkthrough。
- Functional requirements： 可测试的 musts，具体到忽略它就会让 build 明显失败。
- Edge cases & rules： 空输入、超大输入、重复、格式错误、未授权。
- Out of scope： 明确不做什么。不要跳过这一项。
- Acceptance criteria： 说明 "done" 的 checklist（constitution 里的 project-wide done 仍然叠在上面）。
Spec 的 anatomy：六个 section 描述 behaviour，并且刻意不写 HOW（那属于 plan）。
用这样的 prompt 起草，然后亲手收紧：
Using the research above and our constitution, draft
spec.mdfor [feature]. Include: goal (the why), user scenarios, functional requirements, edge cases & rules, out-of-scope, and acceptance criteria. Describe behaviour only, no databases, frameworks, or file layout. Make each requirement specific enough that a build which ignored it would visibly fail.
"tighten by hand" 的意思。 这就是 Concept 2 的 precision test 在真正工作。看一个 requirement 如何从 AI 可以错着满足，变成只能正确满足：
Before: "Users can reset their password."
After: "A signed-out user can request a password reset by email. The link works once, expires after 30 minutes, and a used or expired link shows a 'request a new link' message. The response never reveals whether an email is registered."
第一句可以让 build 给任何请求者发 plaintext password 也算通过。第二句只能通过你真正想要的东西。你漏掉的每个 detail，AI 都会替你决定，所以要在这里用文字决定重要的部分。
让 spec 保持 implementation-free，才让你之后能改变 tooling，而不用重写 intent。
跳过这个 discipline，工具选择会意外变成 requirement。Spec 写了 "store uploads in S3"；plan 和 code 都跟着走；一个月后合规客户要求把存储放在公司自己的服务器上。真正重要的 behaviour（上传内容 durable 且可取回）从未写下，写下的只有 vendor，所以切换时变成 refactor，而不是 plan 里一行修改。
7. Phase 3: Clarify by interview (make the AI ask you)
这是 value 最高、也最常被跳过的一步。build 之前，把提问方向反过来：不要继续给 AI 下指令，而是让它 interview 你，把 spec 中含糊、缺失和未声明的 assumption 全部挖出来。一个 prompt 就能做大半：
Before we build anything, interview me about this spec. Ask one question at a time, focusing on ambiguities, missing edge cases, and unstated assumptions. Keep going until you could hand this spec to a stranger and trust they'd build exactly what I mean. Don't write any code yet.
你会惊讶有多少「显然」的东西其实从未写下。每个在 这里 用文字解决的 ambiguity，都是一个不需要以后通过删除错误 code 来解决的问题。这是整个流程里修错最便宜的地方：在 spec 里修只是一句话；implementation 后修就是 rebuild。
跳过它，问题仍然会被回答，只是晚一点，由 code 回答。团队 spec 了 "users can upload a profile photo"，大家点头，然后上线。一天内：有人上传 40 MB TIFF（从未写 size/type limit），两个用户互相覆盖照片（没有 uniqueness rule），坏文件在全站显示空白（没有 fallback）。三个 unstated assumptions，interview 一句话就会问出来，如今每个都是 bug。
8. Phase 4: Build from the spec
Spec 已经达成一致。现在从它 build，流程重量随 change 的大小调整。没有固定 pipeline 必须每次跑：做 change 需要的最小 planning，然后按 spec supervise build。
- 一句话能描述的 change（typo、一条 rule、一个新 field）：直接 ask。跳过 plan。把 heavy process 强加给一行 fix，是过度工程的另一面。
- approach 不确定或触碰几个文件的 change：先 plan。让 agent 提出 approach，在写 code 前 review。
- 多文件或 architectural change：跑完整 loop，plan → build → verify，把工作拆成小而可检查的步骤。
无论大小，有两件事不变：写 code 前 review approach；完成后按 spec 检查结果。Verify 绝不是可以跳过的步骤。
谁把工作拆成 tasks？Agent 来做。 这是已经改变的部分。你不用手写 task list。Claude Code 和 OpenCode 会 plan，把工作拆成自己的 tracked checklist，并逐项完成、标记 done。你的 job 是 review 那个 breakdown，并把每步按 spec 检查，而不是亲自 author 任务清单。（在 claude.ai 里没有 task tool，所以你自己把 plan 和 tasks 保存成 Artifacts：这是旧式 "write a tasks file" 仍然适用的地方。）
Plan（当 change 值得）：
Based on the agreed spec, propose a technical plan: stack, structure, and the key decisions, each with its trade-off. Match our constitution and reuse what already exists rather than adding new dependencies. Don't write code yet; I'll review the plan first.
Build（supervised）：
Implement the agreed plan in small, checkable steps. Do one step at a time, and after each, check it against the spec and stop for me to confirm before the next. Commit after each so every step has a clean rollback point.
昂贵的 thinking 在 plan 阶段。Approach 达成一致后，building 就是「跟着步骤做」，更便宜或更快的模型通常也做得很好。在 coding agent 里这是一个 setting；在 claude.ai 里，你用最强 chat 做 planning，把 spec 和 plan 当成 handoff。（和 Agentic Coding Crash Course 的 Plan/Execute split 一样。）
Code 能运行，不等于 code 做了你同意的事。把 acceptance criteria 变成真正的 checks（能写 tests 就写 automated tests，不能写就做 manual run-through，或用简短 review questions），每一步之后都跑。如果 check 失败是因为 spec vague，而不是 code 错，先修 spec，再修 code。跳过这一点，SDD 会悄悄退化成它本来要避免的东西：漂亮文档旁边放着没人验证过的 code。
Part 2 on one screen
整个方法，一屏复制。截图 checklist；把 prompts 存成 snippet。
我的 spec 完成了吗？
- Goal： why，用 2–3 句话
- User scenarios： 「用户做 X 时，得到 Y」
- Functional requirements： 每条都具体到忽略它会让 build 失败
- Edge cases & rules： 空、超大、重复、格式错误、未授权
- Out of scope： 明确不做什么
- Acceptance criteria： 说明 "done" 的 checklist
- No HOW： 没有 database、framework 或 file layout（那是 plan）
四个 prompts，按顺序：
RESEARCH: Research what's involved in building [feature]. Investigate separately and
report each on its own: (1) how this is usually done, (2) the main approaches
and trade-offs, (3) what in our existing project it must fit, (4) failure modes
and edge cases. One-page findings doc. No design or code yet.
SPECIFY: Using the research and our constitution, draft spec.md for [feature]: goal,
user scenarios, functional requirements, edge cases & rules, out-of-scope,
acceptance criteria. Behaviour only — no tech choices. Make each requirement
specific enough that a build ignoring it would visibly fail.
CLARIFY: Before we build anything, interview me about this spec, one question at a
time — ambiguities, missing edge cases, unstated assumptions — until there's
nothing left to misread. No code yet.
BUILD: Right-size it. Tiny change: just ask. Otherwise: have the agent propose a
plan and review it, then let it build in small steps, checking each against
the spec and committing as you go. Turn acceptance criteria into checks.
Part 3: The Three Ways
同一个 constitution，同样四个 phases，三个地方可以跑。我们从 claude.ai 开始（无需安装），再到两个 coding agents。
这一部分的具体 mechanics、快捷键（Shift+Tab、Tab）、slash commands（/init、/undo）、model names 和 product features（Projects、Artifacts、Canvas、Gems）截至 2026 年 6 月。它们可能会变；它们承载的四阶段 discipline 不会。
同一种 discipline，三个 spec 的家：同一个 loop 可以在 claude.ai、Claude Code 和 OpenCode 中运行，只是 spec 存放的位置不同。
9. Way 1: claude.ai, the main method
在 web app 中，你的两个 building blocks 是 Projects（带 custom instructions 和 uploaded knowledge 的 persistent workspace）和 Artifacts（位于 chat 旁边的 editable documents）。SDD 可以直接映射到它们。
一次设置 constitution：
- 为你的工作创建一个 Project（例如 "Smart Notes"）。
- 把 constitution 放进 Project 的 custom instructions。把 research、existing docs 或 screenshots 上传到 Project knowledge，让 project 里的每个 chat 都能看到它们。
跑四个 phases，每个 phase 产出一个 Artifact：
- Research → 让 Claude 调查并产出 findings Artifact。（web app 没有 subagents，所以要求它在一份结构化文档里覆盖多个问题。）
- Specify → 让 Claude 把
spec.md起草为 Artifact。在 Artifact panel 里直接编辑，直到正确。 - Clarify → 粘贴 Concept 7 的 interview prompt。回答问题；让 Claude 把答案 fold back 到 spec Artifact。
- Build → 请求
plan.mdArtifact，再请求tasks.mdArtifact，然后逐 task implement。每个 code file 都是一个可以 preview 和 download 的 Artifact。
Project 为什么重要： constitution 和 spec 会跨每个 chat 保持 loaded，因此你可以为 implementation 开一个 fresh conversation，不用重新解释 project。Artifacts 就是 你的 spec files；当你升级到 coding agent 时，把它们 copy 到 repo。
如果你更喜欢另一个 web assistant，discipline 仍然成立，只是 mechanics 不同。ChatGPT： 用 Projects 放 constitution，用 Canvas 做 editable spec/plan documents。Gemini： 用 Gem 放 constitution，用 Canvas 做 documents。Loop（constitution，然后 Research → Specify → Clarify → Build）相同；只是按钮以及每个 "project" memory 的持久性不同。claude.ai 是默认选择，因为 Artifacts + Projects 最干净地映射到 spec files，但这里没有任何东西只属于 Claude。
Chat window 很方便，也正是风险所在。不要把 private source code、customer data、secrets、credentials 或 confidential business material 上传到任何 web assistant，除非你的组织政策允许。敏感工作请在 approved environment 内跑 repo-based agent，并使用 sanitized、fictional examples（如下面 Smart Notes feature）。discipline 相同；data boundary 不同。
10. Way 2: Claude Code, the discipline in your repo
当你的 project 是真实 software 时，Claude Code 会移除 copy-paste：spec、plan 和 tasks 都作为 files 放在 repo 里，紧挨着它们生成的 code。下面这些 native features 已经足够，不需要额外 frameworks。相比 chat loop，它为每个 phase 增加了内置机制：
- constitution 是 Claude 每个 session 都读取的 file。
CLAUDE.md会在每个 conversation 开始时加载，所以你不用重复粘贴，但仍要把它当作 persistent guidance，而不是 hard guarantee（must-never rules 要用 hooks 或 tests 支撑，见 Concept 4）。运行/init，然后删到只剩真实 rules。 - Plan mode 是你的 Specify/Clarify gate，而且是 enforce 的。 用
Shift+Tab进入 plan mode 后，Claude 只读：它能 study code、draft spec，但在你 approve 前不能写一行。这就是工具内置的「build 前先 agree」。 - Subagents 可以 parallel research，并且不污染你的 context。 每个 subagent 在自己的 window 调查一个 area，只交回 summary，让 Phase 1 保持快速，主 session 保持 lean。
- Agent 维护自己的 task list；你 supervise。 你 approve plan 后，Claude 会把工作拆成自己的 tracked checklist，逐项完成并标记 done。你不 author 这个 list；你的工作是 review breakdown，并在每一步后按 spec 运行 relevant checks，再 commit 到下一步，所以每步都有 clean rollback point。commit-after-each 是你驱动的 workflow（也可以写入 constitution）；如果它必须每次发生，就用 hook enforce。
因为四个 artifacts 都是 plain files，spec 现在进入 version control：你可以 diff、在 pull request 中 review，并看清 behaviour 原本何时应该改变。这就是从「我写过一次 spec」到「spec 管理 repo」的跃迁。
11. Way 3: OpenCode, any model
Concept 10 的一切也适用于 OpenCode：rules file（AGENTS.md）作为 constitution（没有 AGENTS.md 时，OpenCode 也会读取已有 CLAUDE.md）、Plan mode（Tab）作为 read-only gate、subagents 做 research、build steps 之间有 git-backed /undo。和 Claude Code 一样，agent 会 self-track task list 并逐项推进，你 review breakdown 并按 spec 检查每步；approve 后用 Tab 切到 Build mode。OpenCode 多出来的一点是 model choice，这正好匹配 SDD 的 natural split：spec 和 plan phases 值得用强 reasoning model，而照着清晰任务清单 build，用 deepseek-v4-flash 这类便宜模型也可以。你决定每一美元的「thinking」花在哪里。（两个 agents 的 setup 细节在 Agentic Coding Crash Course。）
Part 4: A Complete Worked Example
12. One feature, start to finish, twice
我们用一个小而真实的 feature 跑完整 loop：每周一给每个用户发送一封 notes summary 的 "weekly digest" email。它触碰多个文件（scheduled job、notes query、mailer），所以按 Concept 8 的 right-sizing rule，它值得跑完整 loop。我们做 两遍：先在 claude.ai 中做，让 thinking 可见；再在 Claude Code 中做，让 loop 针对 repo 里的真实 files 运行。
在 claude.ai 中
Phase 0: Constitution（已经在 Project 中设置）。 Principles：plain language、prefer existing libraries、每个 feature 都带 spec、永不触碰 published/。
Phase 1: Research。 Prompt：
Research what's involved in a "weekly digest email" for our notes app. Cover: how we'd select which notes to include, scheduling options, email-sending approaches, and the main failure modes (no notes that week, send failures, time zones). Give me a one-page findings doc. Don't propose a final design yet.
Claude 返回一个 findings Artifact。你 skim 一遍；time-zone 问题是你之前没考虑到的。
Phase 2: Specify。 Prompt：
Using those findings and our constitution, draft
spec.mdfor the weekly digest. Include goal, user scenarios, functional requirements, edge cases, out-of-scope, and acceptance criteria. Describe behaviour only, no tech choices yet.
你得到一个 spec Artifact。它不错，但有些地方太 generic。
Phase 3: Clarify。 Prompt：
Before we plan anything, interview me about this spec, one question at a time, until there's nothing left to misread.
Interview 挖出了你从未声明的 decisions：digest 用用户本地的 Monday，而不是 UTC；没有 notes 的一周不发送任何东西，而不是发送空 email；unsubscribed users 被跳过。你回答，Claude 把每个答案 fold into spec Artifact。这就是 SDD 发挥价值的瞬间：三个未来 bugs 作为句子死掉了。
Phase 4: Build。
Now write
plan.md: the technical approach for this spec, given our existing stack. Thentasks.md: an ordered, checkable task list.
你 review plan（它复用 existing mailer，符合 constitution），approve，然后 task by task implement，逐步按 spec 检查并保存。某个 task 暴露出 spec 对某件事沉默时（比如 email subject line），你 先 update spec，再继续。Spec 保持真实。
同一个 feature，在 Claude Code 中
同样四个 phases，同样 prompts；变化在于每个 artifact 都是 file，并且工具 enforce 你在 browser 中靠自律执行的 gates。
- Research： 不再是一份 findings doc，而是启动 subagents，每个负责一个 area，让主 session 保持 lean。Findings 落到
specs/weekly-digest/research.md。 - Specify： 用
Shift+Tab进入 plan mode（read-only）：现在 "don't build yet" 由工具 enforce，而不是靠意志力。 - Build： Claude 把工作拆到自己的 tracked task list，并逐步 build；你按 spec review 每一步并 commit，所以
git log会像那个 task list，每一步都是 clean rollback point。
唯一真正的差异是 spec 最终在哪里：在 claude.ai 里，它住在一个 Artifact 中，之后你 copy forward；在 Claude Code 中，它住在 specs/，与它生成的 code 一起 version-controlled。（OpenCode 相同：把 CLAUDE.md 换成 AGENTS.md，把 Shift+Tab 换成 Tab。）
结果不只是 working code；它是 working code 加上一份解释并管理它的 spec，让下一个人（或未来的你）可以安全地修改。
See the shape of the artifacts: a compact spec.md, plan.md, and tasks.md
方法很抽象，直到你看到它产出什么。下面是三个 artifact 的 trimmed versions，写出来是为了让你看见形状。在 claude.ai 中，三个都会作为 Artifacts 创建；使用 coding agent 时，spec.md 和 plan.md 是 repo files，而 task list 通常由 agent 自己维护（这里写出来，是为了展示好的形状）。真实版本更长；重要的是结构。
# spec.md — Weekly Digest
## Goal
Email each user a once-a-week summary of their own notes so they
re-engage without opening the app. Reduce silent churn.
## User Scenarios
- A user with notes this week gets a Monday-morning digest listing them.
- A user with no notes this week gets nothing (not an empty email).
- An unsubscribed user gets nothing, ever.
## Functional Requirements
FR-1 Digest sends on the user's local Monday at 8:00am.
FR-2 Include only notes created or edited in the prior 7 days.
FR-3 Zero qualifying notes → no email is sent.
FR-4 Unsubscribed users are skipped.
FR-5 A send failure is retried once, then logged; it never blocks others.
## Edge Cases & Rules
- Time zone missing → fall back to UTC.
- 50+ notes → list the 10 most recent, then "and N more."
## Out of Scope
- Digest customization, frequency options, non-email channels.
## Acceptance Criteria
- [ ] A user in Asia/Karachi receives the digest at their local Monday 8am.
- [ ] An empty week sends no email (verified in logs).
- [ ] Unsubscribed users receive nothing.
- [ ] One simulated send failure retries once, then logs, others still send.
# plan.md — Weekly Digest
## Approach
Reuse the existing mailer service (constitution: prefer what exists).
A scheduled job runs hourly, selects users whose local time is Mon 08:00,
builds the digest from the notes query, and hands it to the mailer.
## Key Decisions
- Scheduling: hourly cron + per-user timezone check (no per-user timers).
- Templating: reuse existing email template system.
- Failure handling: wrap each send; retry-once lives in the job, not the mailer.
## Touch Points
- new: jobs/weekly_digest.\* | reuse: services/mailer, models/note
- no schema change required
# tasks.md — Weekly Digest
1. Note-selection query: notes per user from the last 7 days. [FR-2]
2. Eligibility check: local Monday 08:00 + subscribed. [FR-1, FR-4]
3. Digest builder: top 10 + "and N more"; skip if empty. [FR-3, edge]
4. Wire to mailer with retry-once + logging. [FR-5]
5. Tests for each acceptance criterion. [Verify]
注意这些线索：每个 task 都引用它满足的 requirement，最后一个 task 是 verification，直接来自 acceptance criteria。
Part 5: Judgment
13. When SDD pays off, and when it is overkill
SDD 是一种 discipline，而 discipline 有成本：Specify 和 Clarify 会感觉慢，几十分钟都在 thinking，而 vibe coding 早已在屏幕上显示 code。要知道这个 gap 正是你做的 trade（beginner 往往在它感觉最糟时放弃，而那正是它马上要回本的时刻）。把它花在一行 fix 上是错的；在 payment system 上跳过它也是错的。关键 skill 是知道哪种是哪种。
| 该用 SDD 的时候… | 可以跳过（just vibe）的时候… |
|---|---|
| 工作触碰多个 files、modules 或 data | 它是一次性 script 或 tiny tweak |
| 其他人（或未来的你）会维护它 | 今天就会把结果丢掉 |
| 做错代价很高（money、data、trust） | 猜错的成本只是「press undo」 |
| Requirements fuzzy，需要钉清楚 | Task 完全可以用一句话说清 |
| 多个人需要 agree "done" 的含义 | 你还在探索，想 learn 自己到底要什么 |
把 "make this button blue" 跑完整个 constitution-to-implement process 很荒唐。但任务一旦涉及 state、permissions、data models、money，或任何他人的 expectations，结构就开始回本；东西活得越久，它回本越多。
阈值故意放得很低：tiny throwaway work 在左边，但大多数你真正会保留的 work 都落在右边，spec 会回本。
除了第一次做对，SDD 还有第二个 payoff：它让你 unstuck。Anthropic 的 session data 里，当 build 走偏时，经验最少的 users 会以高得多的比例放弃 troubled sessions；经验主要买来的是把 agent steer 回正轨的能力。你已经达成一致的 spec 就是 steering wheel：出问题时，你有一个 fixed point 可 debug，而不是一段含糊的记忆。Recovery move 很具体：当 agent mid-build 偏离 spec 时，把它忽略的具体 requirement（FR）贴回去，把任务缩小到那一件事，然后指回 acceptance criteria。
让 spec 保持 alive（大家最容易忘的部分）。 只有 spec 保持真实，它才是 source of truth。Behaviour 改变时（新 rule、移除 feature、修了 edge case），先改 spec，再 re-derive code。这是把 Spec-First 变成 Spec-Anchored 的动作，也是 spec 随时间越来越有价值和一个月后变成 repo 里的谎言之间的差别。
Spec drift 的样子很普通：有人直接在 code 里改了 digest email 的 subject line 并上线。Spec 还描述旧 subject。三周后，新 teammate 读 spec，把 code "fix" 回去，于是悄悄破坏了已经工作的东西。没人撒谎；spec 只是停止真实，并且用一个 bug 才被发现。Fix 便宜而无聊：每次变更都把 spec.md 和 code 放在同一个 commit 里。
当你有很多 specs 时会变什么。 一份 spec 是 document；几十份放在 specs/ folder 里，就是 system。Live question 不再是「这份 spec 清楚吗？」，而是「这些 specs 是否仍然 agree？」Features 会互相作用，因此一个 spec 的 change 会 ripple 到 others；当两个 specs 指向 conflicting choices 时，constitution 才是解决它的东西。随着整个 specs 集合长大，保持它们 consistent，才是真正从「我会 spec 一个 feature」跳到「我用 SDD 运行一个 repo」。
Practice
阅读 SDD 不等于学会 SDD。只有你在真实东西上跑完整 loop，并感受到 Clarify phase 抓住一个本来会 ship 的 mistake，discipline 才会变成你的。按顺序做。每个练习都提高 stakes，而且都刻意越过 "just vibe it" 那条线，让结构必须证明它值得。
每个 project 都产出同样四个 artifacts（constitution、spec.md、plan.md、tasks.md）加 working result。唯一成功测试就是 Concept 2 的测试：陌生人能否只靠你的 spec build 正确的东西，而不用问你一个问题？
Warm-up：感受 interview（claude.ai，约 30 分钟）。 挑一个你一直想做的最小真实东西：study planner、CSV-to-summary tool、habit tracker。建 Project，粘贴三行 constitution，跑全部四个 phases。唯一规则：不要跳过 Concept 7。 让 Claude 在任何 code 前 interview 你。数一数浮出水面的 decisions 有多少个是你从没想过要声明的。那个数字就是 SDD 存在的原因。
Project 1：有真实 rules 的 feature（claude.ai，约 1 小时）。 为 Smart Notes（worked example 里的 app）spec 并 build 一个 "tag and filter" feature：用户给 notes 添加 tags，并按 tags filter。听起来很简单，直到你开始 spec；这正是练习目的。强迫自己在 spec 中钉清 edge cases：没有 tags 怎么办？Duplicate tags？Filter 没有任何 match？大小写敏感吗？正在使用的 tag 被 rename 怎么办？Done when：你在写一行 implementation 前，spec 已经回答全部五个问题。
Project 2：把它移入 repo（Claude Code 或 OpenCode，约 2 小时）。
把 Project 1 从 chat window 带到 coding agent。把 constitution 放进 CLAUDE.md / AGENTS.md，把 spec.md、plan.md 和 tasks.md 作为 repo files 保存，并用 plan mode 当作 specify/clarify gate。一次 implement 一个 task，每个 task 后 commit。 Done when：git log 显示每个 task 一个 clean commit，spec 也在 version control 中，紧挨着它生成的 code。
Project 3：保持 spec alive（难的一个，约 1 小时）。
现在改变主意。给 Project 2 加一个新 requirement：例如 tags can be colour-coded，或 filtering supports "any of" and "all of" modes。忍住直接叫 agent 添加它的冲动。相反：先编辑 spec.md，对 changed section 重新跑 Clarify，update plan 和 tasks，再 implement。Done when：spec.md 的 diff 和 code 的 diff 讲的是同一个故事。这是把 Spec-First 变成 Spec-Anchored 的动作，也是多数人从不练的动作。
Project 4：在你没写过的 code 里工作（Claude Code 或 OpenCode，约 2 小时）。 一个全新项目是容易情况。Clone 一个你没见过的小 open-source project，或接手别人的 repo，用 SDD 加一个 modest feature。这次 Phase 1 承担重量：在你 spec 任何东西之前，让 agent research 现有 code 如何组织、你的 feature 要插到哪里、必须尊重哪些 conventions；用 subagents，让每个 mapping 一个 area 并汇报。你的 spec 必须包含 "fits the existing system" section，点名你匹配的 patterns。Done when：feature 读起来像本来就是 codebase 的一部分，而不是外挂的，并且 spec 解释了 why it fits。
Project 5：完全没有 code 的 SDD（claude.ai，约 45 分钟）。 证明它是 thinking discipline，不是 coding discipline（Concept "not a programmer"）。选择一个可重复 process，不是 app：从 raw notes 组装 weekly status report、content-repurposing pipeline、inbox-triage routine、对 submissions 使用 grading rubric。跑完全相同的 loop（constitution、research、spec、clarify、build），只是 "build" 产出的是 process and its prompts，不是 source code。Done when：你或 teammate 可以从 spec 运行流程，并每次得到 consistent result，不需要 improvisation。
Project 6：真正的 stranger test（capstone，约 1.5 小时）。 前面的检查都由你自己完成，这是最弱的 reviewer；你知道自己想表达什么。所以把自己拿掉。为一个 feature 写 spec，然后交给一个 fresh, empty AI session（一个完全新 chat，没有你的 discussion memory）或 peer，让他们 zero questions allowed 地 build。只要他们 build 错，责任在 spec，不在他们：修 spec，不修 code，然后重试。Done when：一个 cold reader 第一次就 build 出你真正想要的东西。通过这一关，你才掌握了真正的 skill：把 intent 写得足够精确，让它离开你的脑袋后仍能存活。
Where this leads
你现在已经拥有完整 discipline：先 agree what，再 generate how；把 spec 保持为 source of truth；在适合当前时刻的三个工具之一中运行 constitution → Research → Specify → Clarify → Build loop。
这就是本书后面所有内容下面的 thinking layer。你已经在 Agentic Coding Crash Course 中见过运行这个 loop 的 coding tools：Claude Code 和 OpenCode；也在 Cowork Crash Course 中看过这个 discipline 的实际样子；需要 mechanics 时可以回看。从这里开始，Mode tracks 会把这个 loop 用到真实构建中：你学的每一门 build course，Python in the AI Era、Build AI Agents、AI Searchable Context 和 Building a Digital FTE，都只是同一个 loop，应用到越来越大的 systems。
记住整本书的 thesis：General Agents build Custom Agents. Spec-Driven Development 是你把 general agent 指向 hard problem，并拿回 reliable system，而不是一堆 guesses 的 how。
Flashcards Study Aid
Test Your Understanding
测试你学到的内容。每次 session 会显示 18 道新题，所以你重做时会看到不同问题。