我的知識庫

Spec-Driven Development：規格先行

閱讀時間約 8 分鐘

沒有 spec 就直接寫程式，是在猜測。Spec-Driven Development（SDD）的核心主張只有一句：在寫任何程式之前，先把「我們在建什麼、為什麼、完成的樣子是什麼」寫成文件。這份文件不是事後補的說明，而是事前達成的共識——spec 的價值發生在寫 spec 的過程，不是在讀它的時候。

Thoughtworks 在 2025 年將 SDD 列為「AI 輔助工程的關鍵新實踐」；Microsoft 稱之為 AI-native engineering 的規格先行方法（spec-first approach）。在 AI agent 可以根據 spec 自動生成程式碼的時代，一份清楚的 spec 同時是人類的共識文件，也是 AI 的執行 prompt。

四階段閘門工作流程

SDD 把開發拆成四個有人工審核閘門的階段。不通過上一個閘門，不進入下一個階段：

SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
   │          │        │          │
   ▼          ▼        ▼          ▼
 人工         人工      人工        人工
 審核         審核      審核        審核

SPECIFY：把需求淬煉成一份結構化 spec 文件（六大核心，見下節）。此階段的主要工作是把假設浮上來——越早把假設寫明，越少機會讓它悄悄成為「事實」。

PLAN：根據 spec 產生技術實作計畫：識別主要元件與依賴關係、確認建置順序（先做什麼才能做後面的）、標出風險、識別可並行 vs. 必須循序的工作。

TASKS：把計畫拆成獨立、可執行的任務，每個任務有明確的驗收標準和驗證步驟。每個任務應在一次專注工作中完成，更改不超過約五個檔案。

IMPLEMENT：逐一執行任務。這個階段才碰程式碼——前三個階段都是書面工作。

Spec 寫什麼：六大核心

一份完整的 spec 涵蓋六個面向：

1. Objective（目標）：我們在建什麼？為誰建？成功的樣子是什麼？用具體、可測試的驗收標準表達，而非模糊的願景。

❌ 「讓用戶更容易登入」
✅ 「已驗證用戶從點擊「登入」到進入首頁的步驟數 ≤ 2，
     且找回密碼流程在 15 秒內完成（4G 網路）」

2. Commands（指令）：完整可執行的 build、test、lint、dev 指令，含所有 flag，不只是工具名稱。

3. Project Structure（專案結構）：源碼、測試、文件各自的位置；新增程式碼該放在哪。

4. Code Style（程式風格）：用一個真實程式碼片段展示風格，勝過三段文字描述。包含命名慣例、格式規則。

5. Testing Strategy（測試策略）：用什麼框架、測試放在哪、覆蓋率期望、各測試層級各管哪些事。

6. Boundaries（邊界）：三層清單：

  • Always do（永遠做）：提交前跑測試、遵守命名慣例、驗證用戶輸入
  • Ask first（先問再做）：資料庫 schema 變更、新增外部依賴、改 CI 設定
  • Never do（絕對不做）：把 secret commit 進 repo、修改 vendor 目錄、刪除失敗測試

Spec 的假設浮現機制

Spec 最大的價值不在「記錄決定」，而在「強迫把假設寫出來」。一個實用的做法是在 spec 草稿開頭，先列出你在做這份 spec 時正在假設的事：

## 我正在假設
1. 這是 Web App，不是原生 mobile
2. 認證使用 session-based cookie，不是 JWT
3. 資料庫是 PostgreSQL（基於現有 Prisma schema）
→ 如果有誤，現在更正，否則我依此繼續

這個機制的作用是：在寫程式之前，讓所有相關人看到假設清單，給他們一個指正的機會。假設沉默到實作階段才被發現，是大多數「做完才發現做錯了」事故的來源。

把模糊需求重構成可測試的驗收標準

接到模糊需求時，先把它翻譯成可測試條件再寫進 spec：

模糊需求重構後的驗收標準
「讓 dashboard 更快」Dashboard LCP < 2.5s（4G），初始資料載入 < 500ms
「提升用戶滿意度」新手引導完成率 > 60%，Day 7 留存率 > 25%
「讓 API 更穩定」錯誤率 < 0.1%，P99 latency < 200ms，自動重試 3 次

這個翻譯步驟有時比 spec 本身花更多時間——但一旦做了，後續所有爭議（「到底算完成沒？」「這算 bug 嗎？」）都有一個清楚的基準可以對照。

Spec vs. 直接動手：對比

直接動手Spec 先行
快速開始，但方向可能從一開始就錯前 15–30 分鐘慢，後續大量省去方向修正成本
假設隱藏在程式碼裡，讀不出來假設顯性化，可被指正
需求在實作中邊做邊猜需求衝突在實作前被發現
完成的定義模糊，驗收靠感覺完成的定義是具體驗收標準
AI agent 無從判斷方向是否正確Spec 成為 AI agent 的執行 prompt

Spec 是活的文件

Spec 寫完不是束之高閣。它應該隨決策演進：

  • 資料模型有變動：先更新 spec，再實作
  • Scope 增減：反映進 spec
  • Spec 應 commit 進版本庫，與程式碼並存
  • PR description 應回頭引用 spec 裡的對應章節

常見藉口對照表

藉口現實
「這個需求很簡單，不需要 spec」簡單的任務不需要長 spec，但仍需要驗收標準。兩行 spec 完全可以。
「我會在做完之後補 spec」那是文件，不是規格。Spec 的價值在於它發生在寫程式之前。
「寫 spec 很慢」15 分鐘的 spec 能阻止幾小時的重工。慢是錯覺，返工才慢。
「需求反正會變，何必寫」正因為需求會變，才需要一個活文件追蹤「現在決定的是什麼」。
「大家都知道要做什麼」每個人「都知道」的事往往略有不同。寫下來才會發現差異。

延伸

關係圖譜

反向連結