《SDD 实战》配套资源
《SDD 实战：规范驱动开发之道》· 人民邮电出版社 · 异步图书
这一页收录本书的配套资源，以及成书之后的演进与补充。
实操长文
七篇实操长文，每一篇都能跟着跑通。从手写第一份 spec 开始， 到 OpenSpec、BMAD、Superpowers 的协同实操。
这一组是把概念落到能跑通的具体动作上：Specify、Clarify、Implement 的三段闭环， 两层 Spec（项目愿景加任务变更）的结构， 以及它们在真实工程里怎么和 Memory、Sub-Agents、Skills 协同。 配套代码在 sdd-in-action。
-
第 1 篇
SDD 本质：手写第一份 spec
不装任何工具，只用 Claude Code / OpenCode，手写一份能跑的 spec。从 Vibe 路径和 SDD 闭环的双路对比开始，看清规范驱动开发到底解决什么问题。
-
第 2 篇
Memory 工程：AGENTS.md 的 SDD 化重写
把项目级 Memory 文件 AGENTS.md 当作 spec 来重写。用 Specify、Clarify、Implement 三阶段，把零散的项目说明变成可验收的规范。
-
第 3 篇
Sub-Agents 角色分工：三 Agent 协作规格
用 SDD 给三个 Sub-Agent 写协作规格：每个 Agent 的输入、输出、边界、失败模式。一份规格就是一次明确的角色对话契约。
-
第 4 篇
SDD 两层 Spec 的完整故事：从灰度开始讲
Spec 不是一份文档，而是两层结构：项目级愿景加任务级变更。从灰度发布这个真实需求切入，把两层 Spec 的演化过程讲清楚。
-
第 5 篇
OpenSpec 实操指南
OpenSpec 是 SDD 思想落地的开源工具。完整实操：怎么装、怎么跑、怎么和 Claude Code / OpenCode 协同，附完整命令清单与踩坑记录。
-
第 6 篇
BMAD + OpenSpec 协同实操：add-metrics-collector
用一个真实需求——给项目加一个指标采集器——把 BMAD 方法论和 OpenSpec 工具串起来。从需求到 spec 到代码到验收，端到端走一遍。
-
第 7 篇
Superpowers 详解 + 实操指南
Superpowers 是 SDD 体系下的一类高阶能力封装。把它的设计哲学、调用方式，以及与 Skills、Sub-Agents 的边界讲透。
配套代码仓库
本书配套代码在 GitHub 仓库
huangjia2019/sdd-in-action。
其中 book-code/ 是章节锚定的配套实战项目——智能日报生成器，贯穿全书第 4 至第 8 章。
| 章节 | 配套内容 | SDD 阶段 |
|---|---|---|
| 第 1 章 | book-code/examples/ch01-vibe-coding-audit/ | 问题诊断 |
| 第 3 章 | book-code/examples/ch03-framework-comparison/ | 工具链对比 |
| 第 4 章 | book-code/specs/proposal.md | 需求规范 |
| 第 5 章 | book-code/specs/design.md + contracts/ + adrs/ | 架构设计 + ADR |
| 第 6 章 | book-code/specs/tasks.md | 任务拆解 |
| 第 7 章 | book-code/src/ + tests/ | 执行验证 |
| 第 8 章 | Agent 自动化流水线 | 模式应用 |
同一仓库里还有 SDD 行动营四周的公开实操材料（week1/ 至 week4/），
可作为第 3 章工具链全景与第 7、8 章实战路径的延伸演练。
跟着实操材料动手时，代码在哪
实操文档是流水账，里面的代码块给的是命令与关键片段，不是完整源码。 完整可运行代码一律以仓库为准。第三周还有一个单独的完成态分支。
| 你要找的 | 在仓库的哪里 |
|---|---|
| 动手的起点 | master 分支。第三周的 week3/code/ 是基线，7 个 Agent 已就位，没有 metrics 相关代码 |
| 第三周的参考答案 | feature/add-metrics-collector-local 分支，含 workflows/metrics_collector.py、openspec/changes/add-metrics-collector/ 四件套、_bmad-output/ 里 BMAD 产出的 PRD 与架构文档 |
| 第二周的 change 产物 | week2/code/openspec/changes/archive/2026-04-20-add-analyzer-retry-policy/。走完 /opsx:archive 之后 change 目录会搬进 archive/，这是 OpenSpec 的正常生命周期，不是文件丢了 |
| 第二周的 retry 实现 | week2/code/pipeline/model_client.py 的 with_retry() 装饰器 |
工具演进说明
开源工具的迭代节奏比图书快。以下是成书之后发生的变化，跟随实操时请以此处为准。
Matt Pocock 的 skills 集合（2026 年 7 月核实）
| 项目 | 成书时 | 当前 |
|---|---|---|
| 拆任务票的 skill | to-issues | 已更名为 to-tickets |
| 写 skill 的 skill | write-a-skill | 已移除，由 writing-great-skills（写好 skill 的参考文档）取代 |
| 安装方式 | npx skills@latest add mattpocock/skills/<skill> -a <agent> | npx skills@latest add mattpocock/skills（交互式），并需运行一次 /setup-matt-pocock-skills |
| 任务票产出路径 | specs/issues/*.md | .scratch/<feature>/issues/<NN>-<slug>.md（tracker 可配置） |
| 依赖字段 | depends_on | Blocked by |
| 验收字段 | acceptance | Acceptance criteria（勾选框） |
grill-me | — | 名称未变，仍可用 |
to-tickets 产出的是任务票，不产出 JSON Schema 文件。
任务票里的验收标准是自然语言；把验收里的数据契约固化成可执行的 JSON Schema，是独立的一步。
只有当你事先用 prototype 做过原型、把 schema 片段内联进票时，票里才会出现 schema。
本页会随工具变化持续更新。以各工具仓库的 README 为最终依据。
勘误
以下条目均已核对原稿确认，将在第二次印刷中改正。
| 位置 | 印刷版 | 应为 | 状态 |
|---|---|---|---|
| 第 163 页 图 8-11 路由规则 |
加一个 Jira 数据源 → scheduler 改成每天 9 点生成 → collector |
加一个 Jira 数据源 → collector 改成每天 9 点生成 → scheduler |
第一印错 第二印改 |
图中四条路由规则，第一条与第四条的目标模块在绘图环节被对调了。
正确的对应关系是：新增数据源属于数据采集，归 collector；
修改生成时间属于定时调度，归 scheduler。
这正是该图想说明的那句话——design.md 的模块边界就是路由器的分类规则。
感谢读者指出。
如果你在阅读中发现错误，欢迎通过异步社区本书页面提交勘误， 或在配套代码仓库 提 issue。 经确认的条目会补充到这里。
内容补充
按章节整理的延伸材料，供需要展开的读者参考。
| 章节 | 主题 | 内容 |
|---|---|---|
| 第 3 章 | Superpowers：TDD 强制的纪律工具 | 作为独立框架展开：六个核心 Skill、设计哲学、与其他三家的组合关系 |
| 第 3 章 | 五大 SDD 框架对比 | 在书中三大框架的基础上补齐 Superpowers 与 Kiro |
| 第 3 章 | 工具组合决策树 | 按团队规模、项目类型、当前瓶颈三问定位初始组合 |
| 第 4 章 | 四种工具如何写同一份 proposal | 同一个 retry 需求在四种工具下的写法与切入点差异 |
| 第 7 章 | 工具层如何强制“测试先于代码” | 方法论落到工具约束的样本，以及它的边界 |
| 第 8 章 | 5 种 Agent 模式在 4 种工具中的落地 | 模式 × 工具映射矩阵，以及四个落地示例 |
| 第 10 章 | 工具会消失，方法论是稳定的 | 三次规范驱动复兴史，以及它对当下的推论 |
Superpowers：TDD 强制的纪律工具
书中第 3 章把 Superpowers 归在“四层工具生态”的第一层。 这里把它作为一个独立框架展开，与 OpenSpec、Spec-Kit、BMAD 并列讨论。
Superpowers 是 Jesse Vincent（GitHub 上的 obra）在 Claude Code 之上构建的插件式 Skills 框架， 核心心法可概括为：纪律先于灵感——每一次代码改动都从一个失败的测试开始。
与前三家不同，它不试图重新定义“规范怎么写”，而是把注意力放在“规范怎么落地”： 用一组原子化的 Skill 把工作流拆成可强制执行的步骤，通过框架本身的约束让规范无法被绕过。
六个核心 Skill
- brainstorm：模糊需求阶段。用结构化追问把模糊点钉死，在写 proposal 之前先理清边界。
- design：把澄清后的需求转成结构化设计，等价于 SDD 的 design.md 阶段。
- test-driven-development：整套体系的强制核心。没有失败的测试存在，就不允许进入代码生成阶段。
- debugging：结构化定位 bug。先复现、再二分定位、再形成最小修复假设，最后写测试验证。
- refactor：安全重构。任何重构必须保持测试绿色，不能借重构夹带行为变更。
- document：把决策与权衡固化为文档，把 ADR、CHANGELOG 纳入流水线的一部分。
设计哲学
OpenSpec 关心“规范怎么写”，Spec-Kit 关心“规范怎么治理”，BMAD 关心“角色如何协作”， Superpowers 关心的是“规范如何被强制执行”。 前三家解决的是“先写规范”的问题——规范应该长什么样、谁写、放哪。 Superpowers 解决的是更靠下游的一层：已经写了规范，有没有真的按规范执行。 具体到六阶段工作流，它通过 test-driven-development 强制第五阶段“代码生成”—— 没有覆盖需求的测试，代码不能生成。
与其他三家的关系
Superpowers 与 OpenSpec、Spec-Kit、BMAD 不互斥，而是补位关系。 你可以用 OpenSpec 写 proposal.md，再让代码在 Superpowers 的 TDD 强制下生成。 与 BMAD 也不冲突：BMAD 通过角色边界保证“写代码的 Agent 不能改规范”， Superpowers 通过测试前置保证“写代码的 Agent 不能跳过验证”。前者管空间隔离，后者管时间顺序。
五大 SDD 框架对比
在书中表 3-1 三大开源框架的基础上，补上 Superpowers 与 Kiro 两行。
| 框架 | 核心哲学 | 切入角度 | 执行强度 | 学习成本 | 适合场景 |
|---|---|---|---|---|---|
| OpenSpec | 轻量迭代，工具无关 | 变更箱（change-based） | 弱（规范可被忽略） | 低 | 个人 / 小团队 / 单仓项目 |
| Spec-Kit | 规范即主工件，治理优先 | CLI + 斜杠命令 + constitution | 中（constitution 强约束） | 中 | 已用 GitHub 全家桶的团队 |
| BMAD | 多 AI 角色模拟真实产品团队 | 多智能体编排 | 中（角色边界约束） | 中高 | 老项目 brownfield / 多角色协作 |
| Superpowers | 纪律先于灵感，TDD 强制 | Skill 组合 + 强制前置测试 | 强（无失败测试不让写码） | 低 | 个人 / 小团队 / 严格 TDD 派 |
| Kiro | IDE 原生，Spec 到代码端到端 | IDE 内置 spec 流水线 | 取决于 IDE 配置 | 高（需换 IDE） | 中大型企业级落地 |
这五者不是一个连续光谱，而是五种不同的定位。 选型时要问的不是“哪个最先进”，而是“我团队当前的瓶颈在哪一层”。
工具组合决策树
书中 3.5 节以文字论述工具选型。这里给出一份可以在五分钟内定位初始组合的速查路径。
问题一：团队规模
- 1-3 人：OpenSpec（轻量起步）+ Superpowers（强制 TDD）。两者学习成本都低，合起来覆盖“写规范”和“执行规范”两端。
- 3-10 人：团队是 GitHub-native 则 Spec-Kit + Superpowers；否则 OpenSpec + Superpowers + 团队 wiki。
- 10 人以上：Spec-Kit + BMAD，前者管治理，后者管角色协作；或直接用 Kiro 把流程内置到 IDE。
问题二：greenfield 还是 brownfield
- 全新项目：优先 Spec-Kit，从一开始建立 constitution 治理基线。
- 存量改造：优先 BMAD（多角色防止改坏老代码）+ Superpowers（强制 TDD 保护既有行为）。
问题三：当前最痛的工程缺陷
- 测试覆盖低 → Superpowers
- 规范不清晰 → OpenSpec 或 Spec-Kit
- 角色责任混乱 → BMAD
- IDE 体验割裂 → Kiro
三问三答得到的是初始版本，不是最终版本。 SDD 实践会随团队成熟度演化，工具组合也会随之调整。
四种工具如何写同一份 proposal
书中第 4 章展示了一份 proposal.md 模板。这里补一个横向对照： 同样是“给智能日报生成器加一个 retry 机制”这个需求，在四种工具下的写法差异。
OpenSpec（轻量、Markdown）：
在 openspec/changes/add-retry/proposal.md 写自由格式 Markdown——
目标、背景、范围、成功标准、技术约束。强调“人能读懂、AI 能执行”。
Spec-Kit（结构化、CLI）：
调用 /speckit.specify，按内置模板填写。
必含字段：Title / Why / What / Acceptance / Non-Goals / Constraints。
如果有模糊之处，/speckit.clarify 会自动追问。
BMAD（角色分工）： 由 Product Manager Agent 撰写 PRD，由 Architect Agent 审阅技术可行性。 强调“谁写谁担责”——proposal 不再是一个人脑里的全部假设，而是多个 AI 角色协作的产物。
Superpowers（TDD 锚定）： 先用 brainstorm 把需求的模糊点钉死——哪些异常要重试？max_attempts 是多少？ 429 状态码怎么处理？输出一份“需求理解纪要”，每一条都对应后续一个测试用例。
工具层如何强制“测试先于代码”
第 7 章讲规范驱动的测试策略，讲的是方法论层面“测试应该从规范派生”。 这里补一个工具层的落地样本。
在 Superpowers 框架下，想生成代码，必须先有一个对应需求的失败测试存在。 没有失败测试，代码生成阶段不启动。 方法论说“测试先于代码”，工具层把这句话写进 Skill 的前置条件—— 规范没有被绕过的可能性，而不是依赖人的自律。
5 种 Agent 模式在 4 种工具中的落地
第 8 章把 SDD 与五种 Agent 设计模式的对应关系讲到概念层。 实际工程中还有一个更具体的问题：我手上这个工具，操作层面怎么实现“护栏三明治”“层级委托”？
| Agent 模式 | OpenSpec | Spec-Kit | BMAD | Superpowers |
|---|---|---|---|---|
| 规划与执行 | propose + apply | plan + tasks | Architect → Dev | design → TDD |
| 生成-评审 | 手动 review | analyze + clarify | QA Agent | refactor skill |
| 层级委托 | 单一 Agent | 单一 Agent | 多 Agent（天然契合） | Skill 切换 |
| 护栏三明治 | spec 前置 + 手动后验 | constitution（强约束） | 角色边界 | test-first（强约束） |
| 条件路由 | change-based 分发 | clarify 分支 | 角色路由 | brainstorm 分支 |
示例一 · 护栏三明治 in Spec-Kit：
核心是 constitution.md，它被 Spec-Kit 视为项目级不可变约束。
前置护栏是在其中写入项目级约束（例如“禁止直接调用第三方 API，必须经过 adapter 层”），每一轮生成规范时都会读它；
中间执行时生成计划会自检是否违反 constitution，违反则拒绝生成；
后置护栏由 analyze 命令做跨文档一致性检查，验证代码确实落实了约束。
示例二 · 层级委托 in BMAD： BMAD 的多角色架构本身就是层级委托的实现。 Architect Agent 读完 proposal，把任务拆成子任务，分别委派给前端、后端、QA、DevOps 各 Agent。 每个子 Agent 在自己的上下文里工作，互不污染；主 Agent 只看汇总结果。 优势是上下文隔离自然——每个子 Agent 的 prompt 只包含自己的职责范围。
示例三 · 生成-评审 in Superpowers： 生成阶段由 test-driven-development 产出“能通过测试但未必优雅”的最小实现； 评审阶段由 refactor skill 进入“评审者”角色，审视命名清晰度、模块边界、可测试性、是否过度抽象， 并且必须在测试保持绿色的前提下才能应用建议。 两个 Skill 用同一个进程，但通过不同的 system prompt 扮演两个独立角色。
示例四 · 条件路由 in OpenSpec： OpenSpec 的 change-based 架构原生支持条件路由。 每个 change 是一个独立目录，有自己的 proposal/design/tasks，多个 change 可以并行存在。 “change 即路由单元”的设计，让它在多场景分支需求（企业版与个人版、Web 与移动端）下有天然的分发能力。
工具会消失，方法论是稳定的
这一节回应读者最常问的一个问题：我现在学的这些工具，18 个月后还有用吗？ 答案是：具体工具大概率会消失或被取代，但方法论会稳定下来。 过去三十多年，“规范驱动”这个思想已经历过三次工业复兴，每一次的规律都相同。
第一次复兴在 1988 年。 Bertrand Meyer 提出契约式设计，核心是“模块之间的接口必须有明确的契约，违反契约的代码不能编译”。 当时的载体是 Eiffel 语言。Eiffel 后来退出主流市场，但契约式设计被吸收进 Java 的 assert、 Python 的 typing、Rust 的所有权系统。工具消失了，方法论留下来了。
第二次复兴在 2015 年。 OpenAPI 推动 API-First Design 成为微服务时代的工程纪律。 具体工具在十年里换过几代，但“先写 API spec，再写代码”这个方法论从未动摇。
第三次复兴是当下。 OpenSpec、Spec-Kit、BMAD、Superpowers、Kiro 几乎同时出现， 回应的是同一个工业现实——AI 写代码的成本越来越低，真正稀缺的是清晰、可执行、可验证的意图。
把前两次的规律套用到这一次：具体工具会更迭，但“规范是第一手工件，代码是规范的衍生物” 这个核心命题会稳定下来。工具可能换名字、换接口、换实现， 而三层规范、六阶段工作流、五大核心原则会作为方法论留下来。
本页最近更新：2026 年 7 月