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 管「完成後如何收斂」。
規範到底要放哪裡？
如果把所有規則塞進同一份文件，內容會愈來愈長，也難以維護。可依用途分開存放。
openspec/specs/：正式系統行為規格，例如付款狀態轉移、callback 驗證失敗處理。openspec/config.yaml：OpenSpec artifact 產生共識，例如 design 必須包含回滾策略。.github/copilot-instructions.md：全專案 AI 開發規則。.github/instructions/*.md：依路徑套用的模組規則。skills/：特定任務的專門流程。
低 Token 策略：不要讓 Agent 全量讀 specs
規格優先不等於每次都把全部規格放進上下文。全量讀取會浪費 token，也可能混入無關內容。
- 先讀
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 的速度愈快，需求、規格、設計、任務與驗證之間的連結就愈重要。
