Spec-Driven Development 工作流詳解

症狀：需求一句話就交給 AI Coding Agent，最後卻出現範圍膨脹、測試缺漏，沒有人說得清楚哪個決定造成問題。 最快解法：採用雙軌的 Spec-Driven Development 工作流，由規格軌管理需求、約束與驗收標準，由程式碼軌按可驗證任務產生變更，再用版本、任務編號和測試結果把兩軌連起來。

這篇文章適合準備在真實 Git 儲存庫導入 Spec-Driven Development 的團隊，也適合需要多人審查 AI 生成程式碼的研發負責人。若你希望讓遠端 Coding Agent 長時間執行工作，同時保留清楚的交接、復原與審查紀錄，以下流程比一次生成整套程式碼更容易管理。

先建立兩條互相牽制的工作軌

規格軌不是文件展示區，程式碼軌也不是讓 Agent 自由發揮的執行區。兩者應該各自負責不同問題：

• 規格軌：記錄需求目標、使用者行為、資料規則、介面契約、例外情況、技術限制與驗收條件。
• 程式碼軌：記錄影響檔案、依賴變更、遷移方式、測試命令、任務順序、程式碼差異與未解決項目。
• 交接關係：每項程式碼任務都要指向 Specification 條目；每項驗收結果都要能回指需求；每次範圍變更都要先更新規格，再重新產生實施任務。

GitHub Spec Kit 的官方流程把 specify、plan、tasks 與 implement 分成不同階段，並提供 clarify、checklist、analyze 和 converge 等品質閘門。這種設計正好說明，規格確認與程式碼執行不應被壓縮成單一提示詞。 GitHub Spec Kit 快速開始文件 (github.com)

需求評審：先把模糊目標變成可判定範圍

在需求評審階段，先不要急著選框架、資料庫或 API 形式。你要先判斷這項需求是否已經足以進入 Specification。

每一項需求至少應整理出以下內容：

• 目標使用者是誰，以及他在什麼情況下觸發行為。
• 使用者可完成的核心行為與預期結果。
• 明確不處理的內容，例如本次不包含登入、付款、批次匯入或舊資料兼容。
• 風險約束，例如權限、個人資料、相容性、效能門檻或不可中斷的既有流程。
• 可觀察的驗收結果，例如回應內容、畫面狀態、資料狀態或測試通過條件。
• 尚未確認的問題，並標示由產品、架構師或資安負責人決定。

需求不能只寫「加入團隊協作功能」，而應改成「具有團隊成員權限的使用者，可以邀請成員加入指定專案；被邀請者接受後才能檢視專案內容；未授權使用者不可取得專案資料」。後者才有機會轉換成可測試的 Specification。

注意：如果需求仍然只能用「更快」、「更友善」、「支援更多情境」描述，就先停在評審階段。讓 AI Coding Agent 進入下一步，只會把未決策的問題轉化成程式碼，而不會替團隊承擔產品決策。

Specification 與技術設計應該怎樣分工？

Specification 的單一事實來源，應該描述「系統要呈現什麼可驗證行為」，而不是提早把實作方案寫死。建議把內容分成三類，避免業務事實、技術決定和未決問題混在一起：

• 業務事實：使用者角色、狀態轉換、資料規則、成功結果、失敗結果。
• 技術約束：既有 API 必須保留、資料庫不可直接刪欄位、某些模組只能由指定服務存取。
• 待確認項：尚未決定的驗證方式、遷移窗口、錯誤訊息格式或第三方服務選擇。

換句話說，Specification 回答「要做到什麼、什麼情況算完成」；技術計劃回答「在現有程式庫內，準備用哪些元件、檔案和測試方式完成」。兩者可以互相引用，但不要把實作選擇偽裝成產品需求。

以檔案產物來看，GitHub Spec Kit 常見的功能資料會包括 spec.md、plan.md 與 tasks.md。其中 spec.md 應維持需求與驗收語意，plan.md 承擔技術影響分析，tasks.md 則轉換成可執行工作。 Spec Kit 的核心概念與參考文件 (github.com)

交接條件應該明確寫出來：

• 需求評審完成：每個核心行為都有結果、範圍和驗收方式。
• Specification 完成：待確認項已清零，或已獲得明確負責人與期限。
• 技術計劃完成：已列出受影響的元件、依賴、遷移和測試策略。
• 任務可執行：每個任務都能單獨說明修改範圍與驗證方式。

寫程式前如何檢查現有儲存庫的影響範圍？

把 Specification 直接交給 Agent 寫程式，最大的風險不是語法錯誤，而是它沒有掌握現有儲存庫的邊界。因此技術規劃階段應先做影響盤點，再決定是否允許拆分任務。

至少要檢查：

• 哪些元件會新增、修改或移除。
• 哪些 API、資料模型、環境變數和部署設定會受到影響。
• 是否需要資料庫遷移、回填、向後兼容或回滾方案。
• 現有單元測試、整合測試、端對端測試是否能覆蓋新增行為。
• 是否存在權限、祕密管理、外部服務或跨團隊依賴。
• 失敗時能否只回復這項功能，而不破壞同一分支上的其他變更。

高風險變更應設成人工批准點。例如會改動公開 API、身份驗證、付款流程、資料庫結構或共用核心模組時，先由人員審核 plan.md，確認遷移與回滾方案後，才讓 Agent 產生 tasks.md。

如果你使用 Spec Kit，初始化既有儲存庫時可透過 specify init . 或 specify init --here 將結構放入目前專案；官方核心參考也列出 --integration、--script 和 --force 等參數。對既有團隊而言，重點不是照抄目錄，而是先確認初始化不會覆寫現有 Agent 指令或團隊規則。 Spec Kit 核心命令參考 (github.com)

優點與限制要同時看

採用規格與程式碼雙軌後，你會得到較好的追蹤性、較清楚的審查責任，以及較容易復原的 Agent 任務；代價則是前期需要投入需求評審、文件維護和人工批准時間。

它不適合以下情況：

• 只是一次性的極小修正，建立完整規格的成本高於修改本身。
• 團隊沒有指定誰負責確認需求和接受驗收結果。
• 儲存庫沒有可重複執行的測試或檢查命令。
• 任務內容經常被口頭改動，卻不更新 Specification。

它較適合以下情況：

• 多人會接手同一功能，且需要在數週後仍能理解決策依據。
• AI Coding Agent 會在無人值守時執行較長工作。
• 需求存在多條例外路徑，單看畫面或主流程不足以判斷完成度。
• 團隊希望把程式碼審查從「看起來能跑」提升到「符合已批准的行為」。

Agent 執行如何切成可恢復的小批量任務？

每個任務都應該具備四個欄位：對應的 Specification 條目、目標檔案或模組、驗證命令、退出條件。缺少其中任何一項，Agent 失敗後都會難以判斷應該重試、修正還是回復。

可執行的任務通常具有以下特徵：

• 修改範圍集中，不同功能不要綁在同一任務。
• 完成後可以執行明確測試、靜態檢查或建置命令。
• 不需要同時做需求決策與技術實作。
• 失敗時能保留差異、命令輸出和錯誤原因。
• 下一個任務可以根據上一個任務的產物開始，而不是重新猜測背景。

例如，不要交給 Agent「完成整個成員邀請系統」，而是拆成「建立邀請資料模型並完成遷移」、「加入建立邀請的服務方法」、「加入權限檢查」、「補上接受與失效情況測試」。每一批變更都應該有可驗證的終點。

對長時間執行的遠端 Agent，建議在任務之間保存檢查點：

• 先保存規格與技術計劃的版本。
• 完成一個可測試任務後保存程式碼差異與測試輸出。
• 失敗時從最近一次通過驗證的檢查點恢復，而不是直接覆蓋整個工作目錄。
• 交接給另一位開發者時，同時提供任務狀態、未解決項目和下一個建議命令。

當功能過大、單一上下文難以維持時，可以採用「規格的規格」方式，把大型功能拆成互相獨立的子功能；每個子功能再各自走 Specification、技術計劃、任務和實作流程。 Spec Kit 的 Spec of Specs 說明 (github.com)

代碼審查應該同時檢查實作與規格

程式碼審查不能只看 diff 是否整齊、測試是否通過。審查者還要回到 Specification，檢查 Agent 是否漏掉例外情況，或在沒有批准的情況下擴大了功能範圍。

建議把審查分成兩層：

• 實作層：命名、模組邊界、錯誤處理、測試品質、資安風險、相容性與維護成本。
• 規格一致性層：每個需求條目是否有對應變更；每個驗收標準是否有測試或檢查；未授權、失敗、重試和空資料等路徑是否被處理；是否出現規格未批准的額外功能。

Agent 交付時，至少應附上：

• 差異摘要：修改了哪些檔案，原因是什麼。
• 規格對應：每項變更對應哪個需求或任務編號。
• 測試結果：執行了哪些命令，哪些通過，哪些未執行。
• 未解決項：已知限制、待確認問題和建議後續工作。

這種交付格式能讓遠端執行不再等同於「把整個工作目錄交給下一個人」。若團隊需要在隔離環境中進行檔案、權限與連線管理，可先參考 kvmboot 的支援中心，再按內部資安要求配置審查者的登入權限。

如何把雙軌流程接入現有 Git 與持續交付？

不要把 Specification 放在 Git 之外，也不要只在 Pull Request 描述中貼一段摘要。較穩妥的做法是讓規格、計劃、任務、測試與程式碼差異都能隨同一項變更被檢查。

你可以按以下步驟落地：

1. 在現有儲存庫建立規格文件位置，並先定義命名、需求編號與審查責任。
2. 為一項真實功能完成需求評審，記錄目標行為、不做範圍、風險和驗收條件。
3. 產生 Specification，再由產品或技術負責人確認業務事實、技術限制和待確認項。
4. 盤點儲存庫影響範圍，建立技術計劃、遷移方案和測試策略。
5. 經人工批准後，產生依賴有序的任務，為每項任務指定目標檔案、驗證命令與退出條件。
6. 讓 AI Coding Agent 逐批執行，保存差異、測試輸出和檢查點。
7. 在 Pull Request 中同時審查程式碼與 Specification，拒絕沒有規格依據的範圍擴張。
8. 合併前確認需求編號、任務狀態、測試結果與程式碼版本一致。
9. 上線後若出現缺陷或需求變化，先回寫 Specification，再建立新的實施任務。

若你採用不同的 AI Coding Agent，應先核對整合方式與目前版本，而不要假設所有工具都使用相同的指令格式。Spec Kit 的整合文件列出不同 Agent 的安裝位置、命令形式和切換方式；例如部分工具使用技能目錄，部分工具則使用專案內的命令檔。 Spec Kit 整合參考 (github.com)

決策時可以直接套用以下分支：

• 若需求已有可判定的驗收結果，就進入 Specification；否則回到需求評審，不要讓 Agent 先寫程式。
• 若變更只涉及單一模組且可獨立測試，可拆成較短任務；否則先補上影響分析和檢查點。
• 若會改動公開介面、權限、資料庫或共用元件，先要求人工批准技術計劃；否則才進入任務拆分。
• 若遠端環境能保留隔離工作區、命令輸出和快照，才適合交給 Agent 長時間執行；否則回退到有人監督的短任務模式。
• 若規格、任務、測試和程式碼版本無法互相對應，不要合併，先補齊追蹤鏈。

在真實團隊中，這套流程的成本不只是文件撰寫，還包括遠端執行環境的隔離、日誌保留、快照恢復與審查者安全接入。若你目前使用的是個人電腦或臨時雲端主機，常見問題是環境狀態不一致、工作目錄難以復原、權限配置分散，以及長任務中斷後缺乏完整交接資料。當你需要的是短期測試、臨時 Agent 執行環境或可交接的遠端工作區時，租用 kvmboot 的 Mac 環境通常比臨時拼裝本地設備更容易快速驗證；你可以先從 kvmboot 的服務介紹 了解方案，再判斷是否符合你的倉庫隔離、日誌保存和審查流程。