Spec-Driven Development 真正有用的不是「寫更多」，而是把它當成合約＋證據
SDD 不是 Markdown 瀑布流。對 coding agents 來說，能降低不確定性的不是更長的規格，而是合約（API/schema/error policy）＋證據（tests/evals）＋乾淨的脈絡供應鏈（context engineering）。本文整理一套可落地的 SDD 工作流。
Spec-Driven Development（SDD）真正有用的不是「寫更多」，而是把它當成合約＋證據
我很懂那種畫面：
coding agent 很自信說「完成了 ✅」，你一跑測試，紅到像聖誕樹。
不是因為它不努力，是因為它在「腦補」。
很多時候我們以為問題是 spec 不夠長，於是開始把規格寫成教科書、寫成瀑布流 Markdown。
但真相更殘酷：你寫得再多，只要缺少邊界與驗證，agent 一樣會用錯的方式把事情做完。
所以我現在更願意把 SDD 理解成一句話：
SDD = contract + evidence（合約＋證據）
而不是文件堆疊。
## 1）SDD 做對的事：讓 agent 不用猜
站在 coding agent 的視角，最值錢的不是「長篇敘述」，而是幾種硬資訊：
-
共同語言：需求、邊界、non-goals 先寫清楚，少腦補。
-
約束與合約：API / schema / error policy / SLO，這些是邊界條。
-
可生成骨架：stubs / types / docs，讓它不用每次從 0 猜結構。
-
可追溯：需求 → spec → code → test，形成稽核鏈。
如果你做的是介面明確、邊界穩定的工作（SDK、API contract、資料 schema），SDD 的收益會非常高。
## 2）SDD 容易崩壞的地方：都跟「人類以為自己有控制力」有關
我看過 SDD 在實務上崩壞，通常不是因為概念錯，而是因為落地方式踩到這幾個坑：
-
規格維護稅（spec drift）
需求改了，改 code 很快；先更新 spec 再改 code 常常變流程負擔。
最後 spec/code/團隊腦內模型不同步，反而更危險。 -
規格永遠寫不完「為什麼」
spec 擅長 what，但真正決定行為的是 why：trade-off、不可動假設、暫時妥協。
沒寫進去就會意圖錯位。 -
過度規格＝假的安全感
文件越厚越像有控制力。
但沒有 tests / evals 的證據，agent 仍然可以把你帶到錯的地方。 -
Markdown 地獄 + Double Review
規格裡常包含 pseudo-code，你要先 review spec，再 review 真 code。
審查成本直接翻倍。
## 3）我後來的結論：重點是 Context Engineering，不是 Spec Engineering
很多 prompt 失敗，其實是 context 失敗。
Context engineering 更像系統設計：你要設計「資訊供應鏈」，讓 agent 每一步拿到此刻剛剛好的資料。
而不是把 repo / wiki / 規格整包塞進 context window。
那種 everything-bagel context，只會讓注意力互相打架。
所以我現在把 spec 放在 context 裡，但它只負責「最硬的那塊」：
-
合約（contract）
-
邊界（boundaries）
-
驗收標準（acceptance criteria）
剩下的，交給檢索、工具、測試去提供證據。
## 4）一個我覺得可行的 SDD 工作流（偏實作）
- 先寫最小 spec（只寫邊界）
-
問題 / 非目標（non-goals）
-
合約（API、資料結構、error policy）
-
驗收標準（acceptance criteria）
-
安全/依賴 allowlist
- 讓 agent 產 plan，但強制切小批次
- 每一步都要能在 5–20 分鐘內驗證
- 每個步驟都要有「證據」
-
unit / integration tests / 最小 eval
-
沒綠燈不算 done
-
不接受「手動測試說明」當驗證
- context 當作預算管理
-
只檢索此步驟需要的檔案
-
工具按需上架（不要全開）
-
清掉衝突指令，只留單一 source of truth
- 行為改了就更新 spec
- spec 不更新，後面只會誤導 agent
## 5）怎麼把 spec 當「合約」，讓跨部門 review 不變成 double review 地獄
我覺得很多團隊對 SDD 的痛，表面上是「文件很煩」。
底層其實是：你把 spec 當成故事在寫，所以每個人都得再花一次腦力把它翻譯成「可以驗收的東西」。
要避免 double review，我通常會做三個收斂：
### 收斂 1：把 spec 寫成「可驗收的合約條款」，不是描述文
一份好用的 spec，對跨部門來說應該像合約：
-
我們要交付什麼（scope）
-
我們不做什麼（non-goals）
-
什麼情況算失敗（error policy）
-
用什麼方式驗收（acceptance criteria）
只要驗收條款清楚，review 就會自然變短。
### 收斂 2：把「why / trade-off」集中放在一個區塊，避免散落成小說
跨部門 review 最浪費時間的，通常不是在看功能，而是在問：
-
為什麼要這樣設計？
-
為什麼不做另一種？
-
這個取捨背後的假設是什麼？
你不用寫長篇，但一定要有一個固定區塊，列出 3–5 條：
-
不可動假設
-
主要取捨
-
風險與替代方案
讓大家一次看完，不用在文件裡「找作者心情」。
### 收斂 3：把 review 切成兩段：合約 review（一次）＋證據 review（自動）
double review 會發生，是因為大家先 review spec，之後又要 review code。
比較省的方法是：
-
合約 review：跨部門只 review 邊界/驗收/風險（一次就結束）
-
證據 review：靠 CI 跑 tests/evals，變成可被信任的綠燈
然後你在 PR 裡只要求兩個輸出：
- 「合約是否被破壞」（diff 看 contract/spec 的關鍵段落）
- 「證據是否成立」（CI 綠燈）
當 spec 真的是合約、tests 真的是證據，review 就不會變成兩次相同的閱讀。
如果要用一句話收尾：
把 spec 寫成可驗收的合約，把對話變成可自動驗證的證據，你就能把跨部門 review 從「讀作文」拉回「確認條款」。
## 結尾
我不反對 spec。
我反對的是把 spec 當成「控制不確定性」的唯一手段。
對 coding agents 來說，能真正降不確定性的，通常是這三件事一起存在：
-
清楚的合約（spec）
-
乾淨的脈絡（context）
-
可驗證的證據（tests/evals）
你把 SDD 用在「合約＋證據」上，agent 會更可靠。
你把 SDD 用在「文件堆疊」上，你只會更晚發現錯誤。
#SDD #CodingAgents #ContextEngineering #Testing #軟體工程
