第 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
