SDD 實戰：規範驅動開發之道

黃佳，筆名咖哥，新加坡科技研究局人工智能高級研究員，奇點智能研究院特聘專家，專註於AI Agent系統設計、大模型工程化與企業級AI應用研究。他提出了“雙軸Agent設計框架”（認知功能×執行拓撲）和“模式選擇卡”方法論，用於指導復雜Agent系統的設計、拆解與落地。

中文著作包括《Agent設計模式 圖解可復用智能體架構》《Claude Code實戰：Harness工程之道》《大模型應用開發 RAG實戰課》《大模型應用開發 動手做AI Agent》《GPT圖解 大模型是怎樣構建的》等；英文著作包括Manning出版社的Designing AI Agents、Packt出版社的RAG from First Principles和Building with Claude Code。

在極客時間開設了專欄《Agent設計模式之美》和《Claude Code工程化實戰》，並開設“大模型RAG進階實戰訓練營”。

第 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