Spec-Kit實戰：AI編程全流程落地

黃桂釗，擁有十多年的架構設計和程序開發經驗，曾作為核心技術骨幹、管理人員在中興通訊等公司任職，主導過多款大型產品的架構設計；現任某科技公司的AI架構師，專註於AI工程化落地應用實踐。《Cursor與MCP快速入門：零基礎開發智能體應用》作者，公眾號“AI趨勢洞察家”主理人。

茹炳晟，騰訊TechLead，騰訊研究院特約研究員，騰訊集團技術委員會委員，中國計算機學會（CCF）TF研發效能SIG主席，“軟件研發效能度量規範”團體標準核心編寫專家，中國商業聯合會互聯網應用技術委員會智庫專家，中國通信標準化協會TC608雲計算標準和開源推進委員會雲上軟件工程工作組副組長，國內外各大技術峰會的聯席主席、出品人和主題演講嘉賓，公眾號“茹炳晟聊軟件研發”主理人。著有技術暢銷書《測試工程師全棧技術進階與實踐》和《現代軟件測試技術之美》等，譯有《現代軟件工程》和《DevOps實踐指南（第2版）》等。

第 一部分 規範驅動開發的基礎理論與工具準備

第 1章 AI編程的範式轉移 …………………………………………… 2

1.1 氛圍編程的局限與挑戰 …………………………………………… 2

1.1.1.局限一：代碼質量如沙上建塔………………………………… 3

1.1.2.局限二：可維護性被嚴重透支………………………………… 3

1.1.3.局限三：團隊協作淪為“各自即興”………………………… 4

1.1.4.局限四：結果不確定性………………………………………… 5

1.2 SDD：新一代軟件工程方法論 …………………………………… 5

1.2.1.SDD的定義……………………………………………………… 6

1.2.2.SDD的三根支柱………………………………………………… 7

1.2.3.為什麼現在需要 SDD——AI時代的必然選擇………………… 8

1.2.4.SDD的適用場景與邊界………………………………………… 9

1.3 SDD核心價值：確定性、可維護性與團隊協作……………… 10

第 2章深入理解 Spec-Kit ………………………………………… 11

2.1 Spec-Kit的定位 ………………………………………………… 11

2.1.1.腳手架：零摩擦的項目啟動………………………………… 11

2.1.2.工作流引擎：從憲法到實現的可執行流程………………… 12

2.1.3.工具包：技術棧中立與 AI可選性 ………………………… 14

2.2 核心概念：憲法、規範、計劃與任務 ………………………… 14

2.2.1.憲法…………………………………………………………… 15

2.2.2.規範…………………………………………………………… 16

2.2.3.計劃…………………………………………………………… 16

2.2.4.任務…………………………………………………………… 17

2.2.5.四者的關系…………………………………………………… 18

第3章環境配置與 AI編程代理 ………………………………… 20

3.1 安裝與配置 Spec-Kit …………………………………………… 20

3.1.1.安裝 specify…………………………………………………… 20

3.1.2.驗證系統依賴項是否完善…………………………………… 22

3.2 認識與安裝 CodeBuddy ………………………………………… 23

3.2.1.CodeBuddy是什麼…………………………………………… 23

3.2.2.安裝 CodeBuddy.CLI ………………………………………… 24

3.3 其他 AI編程代理………………………………………………… 25

第二部分規範驅動開發實戰進階

第4章【基礎】組件驅動開發：用戶名片組件 ………………… 28

4.1 項目初始化及憲法確立 ………………………………………… 28

4.1.1.初始化項目…………………………………………………… 28

4.1.2.首次啟動 CodeBuddy………………………………………… 30

4.1.3.確立項目憲法………………………………………………… 31

4.2 編寫組件規範 …………………………………………………… 34

4.2.1.輸入需求……………………………………………………… 34

4.2.2.審視需求是否被準確理解…………………………………… 35

4.3 制定技術方案 …………………………………………………… 37

4.3.1 輸入技術方案………………………………………………… 37

4.3.2 生成技術方案相關文件……………………………………… 37

4.4 生成高質量 Vue組件 …………………………………………… 40

4.4.1.拆解任務清單………………………………………………… 40

4.4.2.執行實現……………………………………………………… 43

4.4.3.驗證項目效果………………………………………………… 45

4.5 小結 ……………………………………………………………… 46

第5章【進階】狀態管理：任務看板 …………………………… 48

5.1 項目初始化及憲法確立 ………………………………………… 48

5.2 編寫任務看板規範 ……………………………………………… 51

5.3 制定技術方案 …………………………………………………… 53

5.4 任務拆解與實現：從列表到看板 ……………………………… 55

5.4.1.拆解任務……………………………………………………… 55

5.4.2.執行實現……………………………………………………… 57

5.4.3.在瀏覽器中驗證……………………………………………… 58

第6章【基礎】構建後端 API與前後端聯調 …………………… 61

6.1 項目初始化及憲法確立 ………………………………………… 61

6.1.1.初始化後端 API服務項目…………………………………… 61

6.1.2.編寫後端 API服務項目憲法………………………………… 62

6.2 定義後端 API契約 ……………………………………………… 64

6.2.1.後端 API契約：核心作用與價值解析……………………… 64

6.2.2.對齊契約與前端數據模型…………………………………… 66

6.2.3.輸入 API契約描述…………………………………………… 66

6.2.4.審視契約：前後端一致性檢查……………………………… 68

6.2.5.確認契約並停止操作………………………………………… 70

6.3 規劃技術方案 …………………………………………………… 71

6.4 拆解與實現任務 ………………………………………………… 72

6.4.1.拆解任務……………………………………………………… 72

6.4.2.執行實現……………………………………………………… 74

6.4.3.驗證後端 API服務…………………………………………… 75

6.4.4.驗證通過並終止操作………………………………………… 77

6.5 前後端聯調：替換前端數據層 ………………………………… 77

6.5.1.理解數據層替換……………………………………………… 77

6.5.2.配置前端開發代理…………………………………………… 78

6.5.3.閱讀 API契約——了解後端接口…………………………… 79

6.5.4.創建 api.ts替換 storage.ts…………………………………… 80

6.5.5.適配 BoardContext的異步調用……………………………… 82

6.5.6.前後端聯調驗證……………………………………………… 83

第7章【進階】安全加固與前後端聯調 ………………………… 85

7.1 更新憲法：增加安全原則 ……………………………………… 85

7.1.1.更新後端 API服務項目憲法………………………………… 85

7.1.2.更新前端任務看板項目憲法………………………………… 86

7.1.3.確認憲法並停止操作………………………………………… 87

7.2 擴充規範：認證與權限 ………………………………………… 88

7.2.1.理解安全加固對規範的影響………………………………… 88

7.2.2.更新後端 API服務項目規範………………………………… 89

7.2.3.更新前端任務看板項目規範………………………………… 90

7.2.4.確認規範並停止……………………………………………… 92

7.3 更新方案：安全模塊的設計 …………………………………… 92

7.3.1.理解安全模塊的技術選型…………………………………… 92

7.3.2.更新後端 API服務項目計劃文件…………………………… 93

7.3.3.更新前端任務看板項目計劃文件…………………………… 94

7.3.4.確認計劃並停止……………………………………………… 95

7.4 前後端功能拆解與實現 ………………………………………… 96

7.4.1.後端 API服務項目：拆解任務……………………………… 96

7.4.2.後端 API服務項目：實現任務……………………………… 97

7.4.3.後端 API服務項目：驗證認證接口………………………… 98

7.4.4.同步後端 API契約到前端…………………………………… 100

7.4.5.前端項目：拆解任務………………………………………… 101

7.4.6.前端項目：實現安全任務…………………………………… 102

7.4.7.前端項目：驗證安全認證功能……………………………… 102

第三部分存量系統改造與未來展望

第8章 存量系統 Spec-Kit開發實踐：存量系統設計知識和代碼理解 …………………………………………… 106

8.1 存量系統面臨的獨特挑戰 ……………………………………… 106

8.1.1.文檔缺失、代碼錯誤的困境………………………………… 106

8.1.2.隱含業務邏輯與“神秘代碼”現象………………………… 107

8.1.3.系統脆弱，開發者不敢輕易重構…………………………… 107

8.1.4.SDD對存量系統的價值再審視 ……………………………… 108

8.2存量系統理解：從代碼到知識 ………………………………… 108

8.2.1.靜態分析：模塊結構、調用鏈、數據流…………………… 109

8.2.2.動態分析：運行時行為捕獲………………………………… 109

8.2.3.架構與集成分析……………………………………………… 110

8.2.4.數據模型理解………………………………………………… 111

8.3 從存量系統中提取規範：逆向工程實踐 ……………………… 112

8.3.1.API規範提取 ………………………………………………… 112

8.3.2.業務規則與行為規範提取…………………………………… 113

8.3.3.數據契約與領域模型規範…………………………………… 114

8.3.4.流程規範提取（工作流提取）……………………………… 115

8.4 規範驗證：確保規範與現有系統一致 ………………………… 116

8.4.1.規範與實現的一致性測試…………………………………… 116

8.4.2.構建回歸測試基線…………………………………………… 117

8.4.3.處理歧義與非確定性行為…………………………………… 117

8.5 在存量系統中增量落地 Spec-Kit ……………………………… 117

8.5.1.選擇首個子域………………………………………………… 118

8.5.2.建立規範基線，固定系統基準行為………………………… 118

8.5.3.雙軌工作流…………………………………………………… 118

8.5.4.漸進式重構：用規範驅動安全替換舊模塊………………… 119

8.5.5.組織與協作建議……………………………………………… 119

8.6綜合案例：為某電商訂單系統引入 SDD……………………… 120

8.6.1.系統背景與痛點……………………………………………… 120

8.6.2.規範提取過程演示…………………………………………… 121

8.6.3.驗證與問題發現……………………………………………… 122

8.6.4.新需求開發：使用 Spec-Kit流程新增“訂單拆分”功能… 123

8.6.5.成果與經驗總結……………………………………………… 124

8.7常見陷阱與應對策略 …………………………………………… 124

8.7.1.過度提取：規範膨脹癥……………………………………… 125

8.7.2.忽略外部依賴的行為變化…………………………………… 125

8.7.3.團隊成員的抵觸（“寫規範不如改代碼”）………………… 127

8.7.4.規範與代碼長期失步………………………………………… 128

8.8 小結 ……………………………………………………………… 129

第 9章從氛圍編程到 SDD，必由之路與未來圖景 ……………… 131

9.1 氛圍編程的局限性：繁榮表象下的暗流 ……………………… 131

9.2 SDD：系統性突破每一個局限 ………………………………… 134

9.3 展望：SDD的下一站 …………………………………………… 136

9.4 啟程建議：如何從你的下一個 PR開始擁抱 SDD …………… 138

結語秩序不是創造力的敵人，而是規模化的朋友…… 140