SDD 工程實戰：用OpenSpec從零構建真實項目

李海武，20餘年軟件開發從業經驗，先後在多家大型外企和互聯網公司擔任工程師、架構師、技術專家、研發經理等職務，擁有若幹項第一作者發明專利，近期轉向SDD並在實際項目開發中積攢了豐富的實戰經驗，期望能夠為普及AI編程工程化落地略盡綿薄之力

第一篇 SDD初探
第1章 為什麼你的軟件項目總是延期 2
1．1 軟件項目的三大頑疾 3
頑疾一：需求漂移 3
頑疾二：實現偏差 4
頑疾三：溝通成本 5
1．2 傳統開發流程的困境 5
瀑布模型：完美的計劃，殘酷的現實 5
敏捷開發：解決了流程，沒解決規格 6
產品需求文檔的根本問題 7
1．3 AI編程時代的範式轉變 7
AI不是銀彈 7
範式轉變：從“怎麼寫”到“寫什麼” 8
1．4 SDD是什麼 9
SDD的核心原則 9
3個遞進層次 10
SDD的工作方式 11
一個Spec長什麼樣 11
1．5 本書學習路線圖 12
你將構建的系統 12
本書各章對應的功能實現 13
如何使用本書 14
第2章 認識OpenSpec――你的AI編程規範搭檔 15
2．1 OpenSpec的設計哲學 15
Fluid not Rigid（靈活不僵化） 15
Iterative not Waterfall（疊代而非瀑布） 16
Simple not Complex（簡單不覆雜） 16
Brownfield-first（存量優先） 17
2．2 核心概念速覽 17
Spec――系統的“行為真相源” 17
Change――“我想改什麼” 18
Delta Spec――“和現在的有什麼不同” 18
Artifact――Change的組成部分 18
2．3 OpenSpec項目的目錄結構 19
2．4 兩種工作流模式 20
默認：Core Profile（5個命令） 21
可選：Expanded Workflow（11個命令） 21
選擇指南 22
2．5 OpenSpec的能力邊界 22
擅長的事 22
不擅長的事 22
2．6 OpenSpec與Spec-Kit的對比 23
概況對比 23
設計哲學對比 23
命令體系對比 24
Artifact機制對比 24
選型建議 24
2．7 環境準備 25
安裝Node．js 25
安裝Claude Code 25
安裝Codex CLI 26
本章小結 27
第3章 快速上手――安裝、配置與實現第一個Change 29
3．1 環境確認 29
3．2 安裝OpenSpec 30
3．3 初始化項目 30
3．4 編寫項目配置 32
這個配置如何工作 32
幾個配置技巧 33
讓OpenSpec用中文撰寫內容 33
3．5 實現你的第一個Change 34
執行命令 34
AI做了什麼 35
看看AI生成了什麼 36
3．6 CLI常用命令速查 38
3．7 動手：OpenSpec基本操作 41
本章小結 42
第二篇 OpenSpec基礎
第4章 從需求到規格――編寫高質量Spec 44
4．1 需求≠規格 44
需求的本質是“願望” 44
規格的本質是“契約” 45
一個“血的教訓” 45
4．2 Spec文件結構解剖 46
Purpose――一句話定義模塊邊界 47
Requirement――系統必須做到的事 48
Scenario――可驗證的實例 49
4．3 GIVEN、WHEN、THEN編寫指南 50
3層覆蓋原則 50
5個常見錯誤及修正 52
Scenario質量自檢表 54
4．4 Delta Spec詳解 55
為什麼需要Delta Spec 55
ADDED――追加需求 55
MODIFIED――替換現有需求 56
REMOVED――刪除需求 57
Delta Spec的歸檔合並過程 58
動手：創建add-dark-mode（練習MODIFIED操作） 58
4．5 Lite Spec與Full Spec：漸進式嚴謹 61
Lite Spec――日常功能開發 62
Full Spec――高風險變更 62
選擇決策樹 63
4．6 動手：為Team KB創建用戶認證功能Spec 64
環境確認 64
第一步：創建Change 65
第二步：創建Proposal 65
第三步：手動創建Spec（核心步驟） 66
第四步：檢查你的Spec 69
第五步：驗證 69
第六步：實施 70
4．7 寫好Spec的7個習慣 71
習慣一：先寫Scenario，再歸納Requirement 71
習慣二：把Scenario當作6個月後的測試用例 71
習慣三：異常路徑至少占Scenario總數的30% 71
習慣四：用具體的值，拒絕籠統的描述 72
習慣五：Spec是活文檔，實現中隨時更新 72
習慣六：給覆雜功能畫狀態機 72
習慣七：Spec審查勝過Spec編寫 73
4．8 常見問題與排查 73
Q：應該為一個功能寫多少Scenario 73
Q：Spec應該多詳細 73
Q：發現Spec寫錯了怎麼辦 73
本章小結 74
第5章 設計決策與任務拆解 75
5．1 何時需要Design 75
決策框架 75
不寫Design時 76
5．2 Design的結構與要素 77
Context――背景 77
Goals/Non-Goals――目標與非目標 77
Decisions――技術決策 78
Data Flow――數據流 80
Risks/Trade-offs――風險與權衡 81
5．3 編寫可執行清單 81
好的任務長什麼樣 81
任務排序原則 82
完整的任務示例 83
5．4 Fast-Forward模式與Continue模式的選擇 85
深入理解兩種模式 85
選擇的實戰準則 85
5．5 動手：為Team KB設計文章CRUD功能 86
第一步：創建Change（用Fast-Forward模式） 86
第二步：審查並完善Design 90
第三步：審查並完善Tasks 91
第四步：驗證 91
第五步：實施 91
5．6 Design的常見反模式 94
反模式一：Design變成了“操作手冊” 94
反模式二：過度設計 94
反模式三：沒有寫“為什麼” 95
5．7 實戰技巧：Artifact疊代的節奏 95
“三輪疊代”模式 95
何時該更新Artifact 95
本章小結 96
第6章 讓AI寫出符合規格的代碼 97
6．1 /opsx：apply的工作原理 97
完整的執行流程 97
3種狀態的處理 98
AI如何理解代碼庫 99
6．2 Claude Code apply實戰 99
先應用前置Change 99
創建add-search Change 100
前置準備 102
啟動實現 103
啟用SQLite FTS5全文搜索擴展 105
實現搜索API 106
前端搜索組件 108
實現完成的總結 110
6．3 Codex apply實戰對比 110
命令格式的差異 110
執行流程一致 111
實際對比 111
核心結論 112
6．4 實現中的疊代修正 112
場景一：設計時發現不可行 112
正確的處理方式 113
場景二：Spec遺漏了場景 113
6．5 並行工作與中斷恢覆 114
場景：因緊急Bug打斷開發 114
tasks．md作為進度標記的原理 115
6．6 動手：實現Team KB的搜索功能 116
第一步：確保Change就緒 116
第二步：啟動實現 116
第三步：觀察並參與 116
第四步：實現過程中的決策 116
第五步：驗證實現 116
常見問題排查 117
6．7 apply過程中的常見問題 117
Q：AI生成的代碼不符合我的代碼風格怎麼辦 117
Q： 一個任務太大，AI在中途暫停了嗎 118
Q：我能在apply過程中手動修改代碼嗎 118
Q：AI實現的功能和Spec不一致怎麼辦 118
本章小結 118
第7章 驗證、同步與歸檔――完成一次完整疊代 120
7．1 為什麼需要驗證 120
3個真實的風險 120
/opsx：verify就是為這3個風險設計的 121
7．2 /opsx：verify三維檢查詳解 121
啟動驗證 121
解讀驗證結果 123
7．3 修覆驗證時發現的問題 124
路徑A：修正代碼（當Spec正確時） 124
路徑B：修正Spec（當Spec不合理時） 124
關鍵原則 125
7．4 /opsx：sync――將Delta Spec合並進主Spec 125
同步的3個行為 125
4種需要單獨執行/opsx：sync的場景 126
7．5 /opsx：archive――完成閉環 126
第一步：將Delta Spec合並進主Spec中 126
第二步：移動到歸檔目錄 126
第三步：保留完整上下文 127
歸檔的價值 127
7．6 完整的疊代閉環演示 127
完整的時間線 127
完整的閉環圖 128
7．7 以CLI方式歸檔 128
7．8 動手：完成用戶認證的完整閉環 129
第一步：確認add-user-auth的Artifact完整 129
第二步：實現 129
第三步：驗證 129
第四步：根據驗證結果行動 129
第五步：歸檔 130
第六步：確認歸檔結果 130
本章小結 130
第8章 探索模式與漸進式開發 132
8．1 需求模糊是常態 132
面對現實 132
不要過早進入Spec 133
8．2 /opsx：explore探索模式詳解 133
探索模式是什麼 133
啟動探索 134
探索模式下的AI行為 134
探索模式的立場 136
8．3 從探索到變更的無縫轉換 136
轉換過程 137
探索結論如何影響Artifact質量 137
8．4 增量式構建：MVP優先，逐步疊代 138
從“大而全”到“小而精” 138
增量式開發與大爆炸式開發的對比 138
8．5 動手：探索並實現Team KB的權限系統 139
第一步：啟動探索 139
第二步：觀察AI的探索過程 139
第三步：從探索到創建Change 140
第四步：創建並實現 140
完成後的Team KB全貌 142
8．6 探索模式的哲學 143
本章小結 144
第三篇 OpenSpec進階
第9章 團隊協作與工作流定制 146
9．1 自定義Schema工作流 146
為什麼需要自定義Schema 146
覆刻現有Schema 147
覆刻Artifact詳解 147
編輯Schema：添加review．md 151
創建新Artifact的模板 152
從零創建Schema 152
驗證、設置和使用 153
9．2 Config深度定制 153
context是AI的項目認知窗口 153
rules按Artifact生效 154
驗證配置是否生效 154
9．3 多工具協作 155
安裝多工具支持 155
多工具命令格式對照 155
團隊協作場景 156
9．4 團隊Change管理最佳實踐 157
Change的粒度 157
命名規範 157
歸檔紀律 157
9．5 跨角色應用――產品經理、測試工程師、設計師、技術負責人如何用好
OpenSpec 158
產品經理的OpenSpec用法 158
測試工程師的OpenSpec用法 159
設計師的OpenSpec用法 161
技術負責人的OpenSpec用法 162
跨角色協作全景 163
9．6 動手：為Team KB創建自定義工作流 163
本章小結 164
第10章 源碼透視――OpenSpec核心命令與Skill架構解析 165
10．1 架構總覽 165
10．2 依賴圖引擎 166
Schema中的依賴聲明 166
拓撲排序與狀態判定 167
三態狀態機 167
openspec status的JSON解讀 167
10．3 Skill指令機制 168
以propose為例 168
為什麼Skill用Markdown而不是硬編碼 168
指令註入機制 169
10．4 Skill與Command的雙軌制 169
10．5 3個核心Skill的執行邏輯對比 170
propose――基於DAG的增量創建 170
apply――有狀態的逐任務循環 172
explore――沒有固定步驟的思考夥伴 173
三者對比 173
10．6 從Legacy到OPSX的演進 174
10．7 源碼文件系統布局 174
本章小結 177
第11章 最佳實踐、常見陷阱與未來展望 178
11．1 OpenSpec的10個最佳實踐 178
11．2 7個常見陷阱 180
陷阱一：把Spec寫成了實現指南 180
陷阱二：MODIFIED只寫了變化的部分 180
陷阱三：任務粒度過粗或過細 180
陷阱四：Spec只有正常路徑 180
陷阱五：忘記同步、直接歸檔 181
陷阱六：context太長或太短 181
陷阱七：在多個並行Change中修改同一個Spec 181
11．3 Team KB項目的完整回顧 181
系統演進全景 181
最終的openspec/目錄 182
關鍵數字 182
11．4 版本演進路線 183
已發布版本 183
社區現狀 183
未來版本路線圖 184
11．5 OpenSpec的生態與未來 184
當前能力 184
社區Schema 184
CI/CD集成方向 185
11．6 你的下一步 185
剛學完本書 185
在團隊中推廣 185
持續學習 185
本章小結 186
附錄A OpenSpec CLI命令速查 187
附錄B Slash Command速查 189
附錄C Team KB Change索引 191
附錄D 術語表 192
附錄E 實踐案例――智能書城 193