SDD实战：规范驱动开发之道

前言

先撰写规范，再编写代码。

SDD 不是什么新发明。

SDD 本质上就是 Covey 的这一洞察在 AI 辅助编程时代的具体实现。

这本书讲什么

一个正在达成的共识

本书适合谁阅读

第1章 空中楼阁：Vibe Coding的甜蜜与陷阱 ……………………1

1.1 什么是Vibe Coding ………………………………………………4

1.2 甜蜜的陷阱：5个致命问题 ………………………………………6

1.2.1 问题一，需求蒸发 ………………………………………………6

1.2.2 问题二，上下文漂移 ……………………………………………6

1.2.3 问题三，不可审查 ………………………………………………7

1.2.4 问题四，不可复现 ………………………………………………8

1.2.5 问题五，不可维护 ………………………………………………8

1.3 案例：一个“AI写的项目”为何没人敢改 ……………………10

1.4 三次范式迁移：从瀑布模型、敏捷开发到SDD模式 ………12

1.4.1 第一代，瀑布模型—有规范，无迭代 ……………………12

1.4.2 第二代，敏捷开发—有迭代，轻规范 ……………………13

1.4.3 第三代，SDD模式—有迭代，有规范 …………………14

本章小结 ………………………………………………………………17

思考题 …………………………………………………………………18

第2章 按图索骥：SDD的核心思想 ……………………………20

2.1 一句话定义SDD …………………………………………………21

2.2 SDD的历史渊源：三次复兴 ……………………………………23

2.2.1 第一春，契约式设计（1988年） ……………………………24

2.2.2 第二春，API-First开发（2015年） …………………………25

2.2.3 第三春，AI时代的SDD（2025年） ………………………26

2.3 SDD的五大核心原则 ……………………………………………27

2.3.1 原则一，规范先行 ……………………………………………28

2.3.2 原则二，规范即文档 …………………………………………29

2.3.3 原则三，规范可执行 …………………………………………30

2.3.4 原则四，规范可版本控制 ……………………………………31

2.3.5 原则五，代码服务规范 ………………………………………33

2.4 SDD工作流：6个阶段 …………………………………………34

2.4.1 阶段一，需求定义→proposal.md …………………………34

2.4.2 阶段二，架构设计→design.md ……………………………36

2.4.3 阶段三，接口契约→api-spec.yaml/data-models.md ………37

2.4.4 阶段四，任务拆解→tasks.md ………………………………38

2.4.5 阶段五，代码生成 ……………………………………………39

2.4.6 阶段六，验证与交付 …………………………………………39

2.5 SDD不是什么：边界与误区 ……………………………………39

本章小结 ………………………………………………………………41

思考题 …………………………………………………………………42

第3章 欲善其事：SDD工具链全景 ……………………………43

3.1 三大SDD开源框架 ……………………………………………44

3.1.1 OpenSpec：文档驱动的规范框架 ……………………………44

3.1.2 Spec-Kit：GitHub的规范工具包 ……………………………46

3.1.3 BMAD：角色驱动的多智能体编排 …………………………47

3.1.4 四层工具生态：从技能到方法论 ……………………………50

3.2 AI辅助编程工具与SDD的结合 ………………………………51

3.2.1 Claude Code：SDD的天然载体 ……………………………52

3.2.2 Cursor：规则驱动的上下文管理 ……………………………55

3.2.3 GitHub Copilot：从Issue到代码的规划能力 ………………56

3.2.4 Kiro：把Spec流程内置进IDE ……………………………58

3.3 规范的载体选择：Markdown、YAML与JSON Schema ………58

3.3.1 Markdown：SDD第三春的主力 ……………………………59

3.3.2 YAML：结构化的中间地带 …………………………………60

3.3.3 JSON Schema：形式化的极端 ………………………………61

3.4 版本控制与协作：Git中的规范管理 ……………………………61

3.4.1 目录结构约定 …………………………………………………62

3.4.2 规范审查：规范审查先于代码审查 …………………………63

3.4.3 分支策略：规范探索 …………………………………………64

3.5 如何选择适合自己的工具组合 …………………………………64

本章小结 ………………………………………………………………66

思考题 …………………………………………………………………67

第4章 条分缕析：需求分析与规范撰写 ………………………68

4.1 从模糊意图到结构化规范 ………………………………………69

4.2 规范的三层结构 …………………………………………………71

4.3 实战：智能日报生成器的proposal.md ………………………72

4.4 常见陷阱：过度规范与规范不足 ………………………………75

4.5 用Claude Code辅助编写规范 …………………………………77

4.6 规范质量检查清单 ………………………………………………79

本章小结 ………………………………………………………………79

思考题 …………………………………………………………………80

第5章 运筹帷幄：架构设计与技术决策 ………………………82

5.1 从proposal.md到design.md：关键的一步跨越 ……………83

5.2 系统架构：先画地图，再行军 …………………………………84

5.2.1 为什么架构设计如此重要 ……………………………………84

5.2.2 智能日报生成器的架构设计 …………………………………86

5.2.3 模块职责定义 …………………………………………………88

5.3 技术选型：ADR的艺术 …………………………………………90

5.3.1 为什么需要记录技术决策 ……………………………………90

5.3.2 ADR的格式 …………………………………………………91

5.3.3 智能日报生成器的ADR示例 ………………………………92

5.4 接口契约：模块之间的“握手协议” …………………………94

5.4.1 为什么接口比实现更重要 ……………………………………94

5.4.2 数据模型定义 …………………………………………………95

5.4.3 模块接口定义 …………………………………………………96

5.5 非功能性约束：那些“看不见的需求” ………………………98

5.5.1 非功能性需求为什么容易被忽略 ……………………………98

5.5.2 智能日报生成器的非功能性约束 ……………………………98

5.6 实战：用Claude Code生成架构设计 …………………………100

5.6.1 工作流 …………………………………………………………100

5.6.2 生成过程中的关键注意点 ……………………………………101

5.7 design.md完整示例 ……………………………………………102

本章小结 ………………………………………………………………103

思考题 …………………………………………………………………104

第6章 化整为零：任务拆解与执行编排 ……………………106

6.1 从design.md到tasks.md：SDD的第三份规范 ……………107

6.1.1 三份规范的递进关系 …………………………………………107

6.1.2 tasks.md的基本结构 …………………………………………108

6.2 任务粒度：不大不小的艺术 ……………………………………109

6.2.1 粒度的两个极端 ………………………………………………109

6.2.2 黄金法则：一个任务=一个可验证的交付物 ………………110

6.3 任务依赖与执行顺序：DAG思维 ………………………………110

6.3.1 不是所有任务都要排队 ………………………………………110

6.3.2 智能日报生成器的任务依赖图 ………………………………111

6.4 验收标准：每个任务的“完成”定义 …………………………112

6.4.1 没有验收标准的任务等于没有终点 …………………………112

6.4.2 优秀的验收标准长什么样 ……………………………………113

6.5 完整的tasks.md示例 …………………………………………114

6.6 实战：用Claude Code逐任务执行 ……………………………120

6.6.1 执行工作流 ……………………………………………………120

6.6.2 给AI的上下文 ………………………………………………121

6.6.3 验证与迭代 ……………………………………………………123

6.7 实战：用子智能体并行执行 ……………………………………123

6.7.1 为什么要并行执行 ……………………………………………123

6.7.2 并行执行的安全边界 …………………………………………123

6.7.3 并行执行的工作流 ……………………………………………124

本章小结 ………………………………………………………………126

思考题 …………………………………………………………………127

第7章 千锤百炼：验证、迭代与演进 ………………………128

7.1 规范驱动的测试策略 ……………………………………………129

7.1.1 从验收标准到测试用例 ………………………………………129

7.1.2 让AI从规范生成测试 ………………………………………130

7.1.3 测试金字塔在SDD中的应用 ………………………………131

7.2 回归验证：代码变了，规范怎么跟着变 ………………………133

7.2.1 变更的4种类型 ………………………………………………133

7.2.2 变更流程：自上而下的涟漪 …………………………………133

7.2.3 逆向回溯：从代码bug发现规范缺陷 ………………………135

7.3 规范的版本演进 …………………………………………………137

7.3.1 规范的版本控制 ………………………………………………137

7.3.2 增量式规范迭代 ………………………………………………138

7.4 Brownfield场景：为存量系统补写规范 ………………………139

7.4.1 存量系统的困境 ………………………………………………139

7.4.2 逐步收编策略 …………………………………………………139

7.4.3 存量系统的规范补写流程 ……………………………………141

7.5 实战：完整的SDD迭代循环 …………………………………142

7.5.1 场景回顾 ………………………………………………………142

7.5.2 Step 1，更新proposal.md ……………………………………142

7.5.3 Step 2，更新design.md ………………………………………142

7.5.4 Step 3，更新tasks.md ………………………………………143

7.5.5 Step 4，执行与验证 …………………………………………144

7.5.6 Step 5，全量回归测试 ………………………………………145

7.5.7 完整迭代循环图 ………………………………………………145

本章小结 ………………………………………………………………147

思考题 …………………………………………………………………148

第8章 登堂入室：SDD与Agent设计模式 …………………150

8.1 规划与执行模式：SDD的天然搭档 ……………………………151

8.1.1 模式简介 ………………………………………………………151

8.1.2 SDD和规划与执行模式的结构映射 ………………………152

8.1.3 CLAUDE.md作为规划上下文 ………………………………153

8.2 生成—评审模式：规范审查的自动化 …………………………154

8.2.1 模式简介 ………………………………………………………154

8.2.2 SDD为评审提供客观标准 …………………………………155

8.2.3 生成—评审模式的实践应用 …………………………………156

8.3 层级委托模式：规范驱动的多智能体协作 ……………………157

8.3.1 模式简介 ………………………………………………………157

8.3.2 SDD与层级委托模式的结合 ………………………………157

8.4 护栏三明治模式：规范作为安全护栏 …………………………159

8.4.1 模式简介 ………………………………………………………159

8.4.2 SDD规范作为护栏的素材 …………………………………160

8.4.3 在Claude Code中实现护栏 …………………………………160

8.5 条件路由模式：规范定义的任务分发 …………………………162

8.5.1 模式简介 ………………………………………………………162

8.5.2 SDD为路由提供分发规则 …………………………………163

8.6 实战：用Agent模式落地SDD自动化 ………………………164

8.6.1 生成—评审模式：一条指令启动自我审查循环 ……………164

8.6.2 层级委托模式：用子智能体并行执行独立任务 ……………165

8.6.3 护栏三明治模式：用Hooks实现自动化规范检查 …………166

8.6.4 4种模式之间的组合 …………………………………………169

8.7 5种模式组合构建SDD半自动化流水线 ……………………169

8.7.1 从手动到半自动 ………………………………………………169

8.7.2 人类的角色变迁 ………………………………………………169

8.7.3 不是完全自动化 ………………………………………………171

8.8 从Agent设计模式到Harness Engineering …………………172

本章小结 ………………………………………………………………173

思考题 …………………………………………………………………175

第9章 众人拾柴：团队中的SDD实践 ………………………176

9.1 从个人到团队：三个阶段 ………………………………………177

9.1.1 为什么不能一步到位 …………………………………………177

9.1.2 第一阶段的关键：选对试点人和试点项目 …………………177

9.2 规范的协作模式：谁撰写、谁审核、谁执行 …………………179

9.2.1 三种角色 ………………………………………………………179

9.2.2 规范审查的PR流程 …………………………………………180

9.3 规范模板的团队标准化 …………………………………………181

9.3.1 为什么需要统一模板 …………………………………………181

9.3.2 模板的弹性 ……………………………………………………181

9.4 与现有开发流程的融合 …………………………………………183

9.4.1 SDD+Scrum …………………………………………………183

9.4.2 SDD+CI/CD …………………………………………………184

9.5 度量与改进：如何衡量SDD的效果 …………………………186

9.5.1 为什么要度量 …………………………………………………186

9.5.2 SDD效果的度量指标 ………………………………………186

9.6 CI/CD 中的规范守护：让机器帮你盯规范 ……………………188

9.6.1 规范审查不能只靠人 …………………………………………188

9.6.2 三个层次的自动化规范检查 …………………………………188

9.6.3 实战：一个最小的规范CI工作流 …………………………189

本章小结 ………………………………………………………………191

思考题 …………………………………………………………………192

第10章 大道至简：SDD的未来与思考 ………………………194

10.1 SDD的边界：什么场景适合，什么场景不适合 ……………194

10.1.1 SDD的甜蜜区 ………………………………………………194

10.1.2 不适合SDD的场景 …………………………………………195

10.1.3 行业验证：SDD绝非一家之言 ……………………………196

10.2 SDD与其他方法论的融合 ……………………………………197

10.2.1 方法论不是金科玉律 ………………………………………197

10.2.2 SDD与主流方法论的关系 …………………………………197

10.3 AI辅助编程方法论的演进方向 ………………………………198

10.3.1 从辅助到协作，再到自治 …………………………………198

10.3.2 规范形态的演进 ……………………………………………200

10.4 规范即代码的终极愿景 ………………………………………201

10.4.1 当规范足够精确时 …………………………………………201

10.4.2 我们离终极愿景还有多远 …………………………………201

10.5 写给开发者的话：在AI时代，工程素养重于编码能力 ……202

10.5.1 能力矩阵的迁移 ……………………………………………202

10.5.2 工程素养的回归 ……………………………………………203

10.6 从Vibe Coding毕业 …………………………………………203

本章小结 ………………………………………………………………205

思考题 …………………………………………………………………206

后记 百川入海，殊途同归………………………………………207

......(更多)