AI Coding Agent 變得越來越好用之後，團隊常遇到一個新問題：需求講得很快，AI 也做得很快，但最後做出來的東西，卻不一定符合原本想要的結果。
例如你只說：「做一個建立購物車模組的功能。」AI 可能真的開始改程式，但它可能會漏掉商品狀態、庫存檢查、金額計算、錯誤處理，或只寫到最順利的測試情境。
這不一定是 AI 不夠聰明，而是因為我們沒有把「系統到底應該怎麼運作」寫成可追蹤、可驗證的規格。這正是 SDD 和 OpenSpec 想解決的問題。
先講結論：SDD 是觀念，OpenSpec 是落地工具
SDD，全名是 Specification-Driven Development，也就是「規格驅動開發」。它的重點不是叫大家多寫文件，而是把規格變成開發流程的 Source of Truth。
OpenSpec 則是把這套概念落地成資料夾結構、artifact 和 AI slash commands，讓人類、AI Agent、程式碼、測試和 review 都能對齊同一份規格。
| 名詞 | 白話說法 | 解決的問題 |
|---|---|---|
| SDD | 先定義規格，再依規格開發 | 避免 AI 憑感覺寫 code |
| OpenSpec | 把規格、設計、任務變成固定結構 | 讓規格可追蹤、可 review、可驗證 |
| GitHub Copilot / Agent | 依規格執行實作的工具 | 提升開發速度，但需要清楚上下文 |
為什麼 AI 開發更需要 SDD？
傳統寫程式時，需求不清楚已經會造成返工。到了 AI Coding 時，這個問題會被放大，因為 AI 的速度很快，但它不一定每次都讀到完整上下文。
常見流程長這樣：
一句需求 → AI 直接改 code → 測試才發現不符 → 補 prompt 修正 → 規格散落在聊天紀錄裡這會帶來幾個痛點：
- 上下文不穩：AI 不一定每次都看到同一份需求。
- 需求與實作斷裂：需求留在聊天裡，最後 code 反而變成唯一真相。
- 重工成本高：改一段流程時，常漏掉資料庫、通知、測試或文件。
- Review 很難判斷：只能問「看起來對不對」，而不是對照規格驗證。
SDD 的價值，就是讓團隊和 AI 都有同一份「應該做什麼」的依據。
什麼是 SDD？
傳統 AI Coding 常見做法是：先丟 prompt，AI 直接改程式，人再慢慢補充。SDD 則反過來：先建立規格，再讓 AI 依規格產生設計、任務和實作。
規格不是最後補的文件，而是啟動 AI 開發與驗證的契約。
| 方法 | 起點 | 主要產物 | 驗證方式 | AI 適配性 |
|---|---|---|---|---|
| TDD | 測試案例 | Unit test | Test pass | 中 |
| BDD | 使用者行為 | Scenario / Story | Scenario match | 中 |
| SDD | 正式規格 | Spec / Design / Tasks | Spec + Scenario + Test | 高 |
| AI Vibe Coding | Prompt | Code diff | 人工判斷 | 快，但風險高 |
SDD 不是要取代 TDD 或 BDD，而是把「AI 要遵守什麼」放到更前面。
SDD 的基本循環
SDD 不是一次把所有文件寫滿，而是從人類意圖開始，逐步收斂成可驗證的實作。
- Intent：說清楚要解決什麼問題。
- Spec：寫成正式行為規格。
- Design：決定技術方案、限制與風險。
- Tasks：拆成可執行、可驗收的步驟。
- Implement：AI 依照任務實作。
- Verify：用 scenario、test 和 review 對照規格驗證。
如果驗證不符合，就回到 Spec 或 Design 修正，再重新實作。重點是每次變更都留下可追蹤的差異，而不是只在聊天中補一句「剛剛不是這樣」。
OpenSpec 是什麼？
OpenSpec 可以理解成「讓 SDD 可操作的專案結構」。它把規格、設計、任務與變更記錄放在固定位置，讓 AI Agent 不必每次從零猜上下文。
openspec/
config.yaml
specs/
payment-callback/spec.md
seller-order/spec.md
changes/
add-seller-order-scheduler/
proposal.md
design.md
tasks.md
specs/...這個結構的核心價值是：讓「為什麼改」、「怎麼改」、「要做哪些事」、「驗證什麼」形成同一條可追蹤鏈。
OpenSpec Workflow：選對入口
OpenSpec 的 slash commands 可以視為不同階段的操作入口。需求越模糊，越應該先 explore；需求越明確，才適合 propose 或 apply。
| 情境 | 建議入口 | 用途 |
|---|---|---|
| 需求還不清楚 | /opsx-explore | 先釐清邊界、未知點與風險 |
| 需求已經明確 | /opsx-propose | 建立 change，產生 proposal、spec、design、tasks |
| 準備開始做 | /opsx-apply | 讀取 tasks，開始實作並更新完成狀態 |
| 功能完成 | /opsx-archive | 封存 change，必要時同步回正式 specs |
Delta Specs：描述「這次規格怎麼變」
SDD 最重要的不是寫很多文件，而是清楚描述這次規格變更。OpenSpec 常用三種語意：
- ADDED：本來沒有，這次新增。
- MODIFIED：本來有，這次修改規則。
- REMOVED：本來有，這次刪除。
例如新增「建立購物車模組」時，可以這樣寫：
## ADDED Requirements
### Requirement: 支援購物車模組建立
#### Scenario: 使用者加入商品後可建立購物車項目
- GIVEN 商品可購買且庫存足夠
- WHEN 使用者將商品加入購物車
- THEN 系統建立或更新對應的購物車項目這樣 AI 在實作時，就不是只看一句「幫我做購物車」，而是有明確規則可以對照。
在 VS Code + GitHub Copilot 怎麼用？
在 VS Code 裡，OpenSpec 的 slash commands 是操作入口，instructions、prompts、skills 則是不同層級的治理方式。
| 機制 | 用途 | 適合放什麼 |
|---|---|---|
| Instructions | 長期影響 Copilot 回應 | 專案規範、路徑規則、測試要求 |
| Prompts | 可重複使用的任務模板 | /opsx-* 這類手動呼叫流程 |
| Skills | 封裝專門工作流程 | 部署、排查、匯入、報告產生 |
簡單說：OpenSpec 的 /opsx-* 是 prompt file 入口；團隊共通規則放 instructions；高度重複且有 SOP 的任務，才封裝成 skills。
進階指令怎麼記？
如果只記四個核心指令會不夠。OpenSpec 還有一些進階指令，適合大型需求或多人協作。
| 指令 | 用途 |
|---|---|
/opsx-new | 只建立變更資料夾與基本結構，適合大型需求先分段審查。 |
/opsx-continue | 每次只產生下一個 artifact，適合高風險需求逐步 review。 |
/opsx-ff | 需求已清楚時，一次補齊剩餘 artifacts。 |
/opsx-verify | 檢查 code、tasks、scenario、design 是否對齊。 |
/opsx-sync | 把 delta specs 合併回正式 specs。 |
/opsx-bulk-archive | 批次封存多個 changes，適合 release 前集中整理。 |
/opsx-onboard | 讓 Agent 掃描專案，協助團隊導入 OpenSpec。 |
記憶方式很簡單：new / continue / ff 管「規劃怎麼長出來」；verify / sync / archive 管「完成後如何收斂」。
規範到底要放哪裡？
很多團隊導入 AI 開發時，會把所有規則都塞進同一份文件，最後變得又長又難維護。比較好的做法是依照用途分類。
openspec/specs/：正式系統行為規格，例如付款狀態轉移、callback 驗證失敗處理。openspec/config.yaml：OpenSpec artifact 生成共識，例如 design 必須包含回滾策略。.github/copilot-instructions.md：全專案 AI 開發規則。.github/instructions/*.md：依路徑套用的模組規則。skills/：特定任務的專門流程。
低 Token 策略：不要讓 Agent 全量讀 specs
規格優先，不代表每次都把所有規格塞進上下文。這樣不只浪費 token，也容易讓 Agent 讀到不相關內容。
- 先讀
openspec/specs/README.md找索引。 - 定位相關 capability，例如
payment-callback。 - 只讀相關
spec.md。 - 再讀本次 change 的
proposal.md、design.md、tasks.md和 delta specs。 - 必要時才手動補
#file或#folder。
低 token 原則：先定位，再讀取；先索引，再展開。
複雜需求怎麼餵給 OpenSpec？
不要把需求貼成一大包流水帳。更好的方式是先整理成四段，讓 AI 先看懂問題邊界。
| 段落 | 要回答的問題 |
|---|---|
| 目標 | 這次要解決什麼問題？ |
| 範圍 | 包含哪些流程？不包含什麼？ |
| 已知規則 | 哪些業務條件、資料表、限制已確定？ |
| 待確認事項 | 哪些風險、未知點或選項還沒定案？ |
例如建立購物車模組，可以先這樣整理：
目標：使用者將可購買商品加入購物車時，系統自動建立或更新購物車項目，並即時計算金額。
範圍：選擇商品 → 檢查商品狀態與庫存 → 建立或更新購物車項目 → 計算小計與總額 → 回傳購物車狀態。
已知規則：商品已上架、庫存足夠、購買數量合法、會員或訪客識別存在；同一商品重複加入時需合併數量。
待確認：購物車明細是否新增或更新、金額計算是否正確、庫存變動處理、重試與冪等機制、購物車有效期限。
這種需求建議先用 /opsx-explore 釐清未知點，再用 /opsx-propose 建立正式 change。
團隊導入路線圖
| 階段 | 重點 | 建議做法 |
|---|---|---|
| 第 1 週 | 試點 | 選一個小功能，建立 specs README，跑一次 explore / propose / apply。 |
| 第 2–3 週 | 標準化 | 補 copilot instructions、模組 instructions、config rules。 |
| 第 4 週 | 擴大使用 | PR review 對照 scenario，檢查 tasks 完成度。 |
| 持續 | 收斂 | 整理 pitfalls，把重複流程沉澱成 skills，定期清理 specs。 |
參考資源
- OpenSpec Docs
- OpenSpec config.yaml
- VS Code Copilot Custom Instructions
- VS Code Copilot Agent Skills
- Spec-Driven Development overview（Martin Fowler）
最後總結
SDD 的重點不是文件變多，而是讓規格成為團隊和 AI 共同遵守的契約。OpenSpec 則把這份契約變成可操作、可追蹤、可驗證的工作流程。
當 AI Coding Agent 越來越快，真正拉開差距的不是誰的 prompt 寫得更長，而是誰能把需求、規格、設計、任務和驗證串成一條穩定的鏈。
