Spec-Driven Development：AI Coding Agent 指南

官方 Spec Kit 快速入門把完整流程列為 9 個階段，由原則、規格、澄清、設計、任務一路走到實作與收斂；這說明真正有效的 Spec-Driven Development AI Coding Agent 流程，不是寫一份很長的 Prompt，而是把意圖逐級轉成約束、設計、可獨立執行的任務與驗收證據。官方流程說明

這篇適合三類讀者：經常需要反覆糾正 AI Coding Agent 的個人開發者、準備把 AI 程式開發引入團隊流程的技術負責人，以及需要為 Agent 生成程式碼建立審計與驗收依據的工程團隊。

先固定邊界，再讓 Agent 開始工作

Spec-Driven Development 如何開始？第一個產物不應是功能 Prompt，而是「專案約束」。這份約束可以是一個簡短的工程章程，亦可以分散在專案文件中，但必須讓後續每一輪任務都能引用，避免開發者重複提醒相同規則。

建議先記錄以下內容：

• 使用中的語言、框架、套件管理方式與測試工具。
• 目錄用途、檔案命名、模組依賴方向及 API 邊界。
• 不可修改的資料庫結構、設定檔、部署腳本或既有介面。
• 個人資料、金鑰、權限、日誌及外部服務的安全限制。
• 完成定義，包括必須通過的測試、靜態檢查、手動操作與文件更新。
• Agent 可以自行決定的範圍，以及必須先詢問人員的決策。

這一步處理的是三個常見隱性成本。第一，沒有固定邊界時，Agent 可能為了完成單一功能而更換依賴或重寫既有結構。第二，權限與秘密資料若未明確禁止，測試階段可能把敏感值帶入程式碼或輸出。第三，沒有完成定義時，開發者只能以「看起來差不多」驗收，後續爭議自然會轉成再次修改。

提醒：「不要修改既有 API」不是可驗收的規格。較好的寫法是列出介面路徑、輸入欄位、錯誤格式，以及哪些測試必須維持通過。

若使用官方 Spec Kit 類型的工作流，章程或治理原則會先成為後續規格、設計與任務的共同依據；其官方文件亦將這類原則放在規格產生之前。查看官方命令與階段說明

第二步：把需求改寫成可判定的 Specification

Specification 要寫到什麼程度 AI 才能執行？關鍵不在篇幅，而在每一條要求是否能被測試、檢查或人工確認。

一條可執行的 Specification 至少應包含：

1. 行為目標：使用者做甚麼，系統應產生甚麼結果。
2. 輸入條件：必填欄位、格式、長度、權限與前置狀態。
3. 輸出結果：成功回應、畫面變化、資料寫入或事件觸發。
4. 異常行為：輸入錯誤、重複請求、逾時、無權限及依賴失敗時如何處理。
5. 非功能要求：安全、可觀測性、相容性、可維護性與部署限制。
6. 驗收證據：測試命令、API 範例、畫面操作、日誌內容或人工檢查項目。

例如，模糊需求是：「加入一個可管理任務的頁面。」可判定版本則應寫成：

• 已登入使用者可以建立任務，標題為必填。
• 任務必須具有待處理、進行中及已完成三種狀態。
• 未填標題時，畫面顯示錯誤並且不建立資料。
• 無權限使用者不能修改其他專案的任務。
• 建立、修改狀態及刪除操作都必須留下可追蹤記錄。
• 驗收時需通過新增、錯誤輸入、無權限及狀態轉換測試。

這裡沒有加入無法核實的效能數字，但已經給 Agent 足夠的行為邊界。官方工作流也建議在進入技術設計前，先處理規格中的模糊部分；澄清階段的價值，是避免在錯誤假設上繼續產生設計與任務。官方快速入門中的澄清階段

Specification 與一般需求文件有甚麼不同？一般需求文件可以保留大量背景描述，但 Specification 必須把背景轉成可觀察結果，並且指明「完成」與「不完成」的分界。若一句話無法對應測試、檢查或人工操作，通常仍停留在願望，而不是可執行規格。

讓規格、設計與任務形成時間軸

完成 Specification 後，不應立即要求 Agent 修改程式碼。較穩定的做法，是讓它先產生設計方案，再將方案拆成能獨立實作與驗證的任務。

一個清楚的產物流如下：

• constitution：專案原則、禁止事項與工程標準。
• specification：功能行為、輸入輸出、例外及驗收條件。
• plan：資料流、模組邊界、介面、依賴影響與技術選擇。
• tasks：按依賴排序的實作任務、涉及檔案與驗證方式。
• implementation：依任務修改程式碼，並回報差異與結果。
• verification：把測試、靜態檢查及人工驗收映射回原始規格。

AI Coding Agent 如何按規格拆分任務？可要求 Agent 為每個任務回答四件事：修改哪些檔案、前置依賴是甚麼、完成後執行哪個命令、失敗時回到哪一層處理。

任務粒度需要控制在「一個清晰目的、一組相關檔案、一組可重複驗證」的範圍。例如，先建立資料模型與遷移，再建立服務層，再加入 API，最後處理介面與端到端測試。若一個任務同時更改資料庫、權限、前端狀態與部署流程，任何測試失敗都很難判斷責任屬於哪個部分。

官方文件把 plan、tasks 與 implement 分成不同階段，並提供跨文件分析命令，用於檢查規格、設計與任務之間的衝突、缺口及歧義。官方任務與分析流程

第三步：以小任務驅動程式碼修改

每一輪對 Agent 提供的上下文，應只包含當前任務真正需要的內容：

• 對應的 Specification 段落及驗收條件。
• 相關目錄、介面、測試檔案與設定檔。
• 不可修改的檔案清單。
• 預期執行的測試或檢查命令。
• 前一個任務留下的介面或資料格式。

修改前要求 Agent 先輸出計劃，至少包括預計修改檔案、保留的邊界、可能風險及驗證命令。修改後則要求它提供：

• 實際變更的檔案清單。
• 每個變更如何對應 Specification。
• 測試、靜態檢查或手動驗收的結果。
• 尚未處理的假設、警告及後續任務。

這個節奏能降低上下文漂移，因為 Agent 不需要每輪重新理解整個專案，也不容易把上一個任務的臨時決策帶入新功能。對個人開發者而言，這比要求 Agent「完成整個功能」更容易回退；對團隊而言，差異檔與驗證結果則能成為審查依據。

程式碼應放在獨立分支或可重置的工作目錄中。分支的價值不是增加流程，而是把功能變更與主線隔離；官方版本控制文件說明，切換分支可以回到不同提交的工作狀態，合併前亦能獨立測試與處理衝突。版本控制分支與合併說明

用這份清單判斷一輪任務是否可以結束

以下清單可直接放進每個功能分支的審查流程：

• [ ] 已指定本輪唯一任務，沒有把未相關的重構混入其中。
• [ ] Agent 已列出會修改的檔案及不會修改的區域。
• [ ] 每項變更都能對應到一條 Specification。
• [ ] 輸入、成功輸出、錯誤輸出及權限行為均有驗證方式。
• [ ] 自動測試已執行，失敗訊息已保留，而不是只回報「測試通過」。
• [ ] 靜態檢查、格式檢查及型別檢查已按專案規則執行。
• [ ] 手動驗收只檢查規格要求，不以額外偏好要求 Agent 擴大修改。
• [ ] 差異檔沒有包含秘密值、無關重構或未經批准的依賴更新。
• [ ] 任務狀態、規格連結及已知限制已提交到版本控制。
• [ ] 若未通過，已指出應回退到任務層、設計層或 Specification 層。

測試工具不需要複雜才有價值。以 Python 專案為例，pytest 官方文件示範以一般 assert 驗證預期結果，並會在失敗時提供中間值與差異資訊；這類輸出很適合作為 Agent 回報中的驗收證據。pytest 官方測試說明

第四步：把驗收結果映射回原始規格

驗收不應只看程式碼能否執行，而要逐條回答：「原始 Specification 是否已被滿足？」

可把驗收分為四層：

• 行為測試：驗證正常輸入、邊界輸入及錯誤輸入。
• 介面檢查：驗證 API 欄位、狀態碼、錯誤格式或畫面流程。
• 工程檢查：驗證型別、格式、靜態分析、依賴及安全規則。
• 人工驗收：只處理自動化難以表達的內容，例如操作順序、文字清晰度或跨角色流程。

每項結果都應回寫到規格或任務文件，例如：

REQ-03：無權限使用者不能修改任務
驗證：test_task_permission_denied
結果：通過
提交：a1b2c3d

若規格要求的測試失敗，不應立刻新增一段臨時提示，要求 Agent「再修好一點」。應先判斷失敗位於哪一層：

• Specification 不清楚：先補充條件與例外。
• 設計不完整：修正資料流、模組邊界或介面契約。
• 任務拆分錯誤：拆出缺失的前置任務。
• 實作錯誤：只回到對應任務重新修改。

對團隊流程而言，可將測試、建置或掃描結果設為合併前的必要狀態檢查；官方文件指出，受保護分支可以要求狀態檢查通過後才允許合併。官方狀態檢查說明

經驗：驗收證據不是為了讓文件變長，而是為了讓下一位開發者能在不重新閱讀全部對話的情況下，重現「為何這次修改可以合併」。

規格變更後，先做影響分析再更新程式碼

規格變更後如何避免程式碼失控？核心規則是「先改規格，再改任務，最後改程式碼」，而不是把新需求直接追加到原有 Prompt。

建議每次變更都留下：

1. 原規格版本與新規格版本。
2. 變更原因及提出者。
3. 受影響的模組、介面、資料結構與測試。
4. 需要新增、刪除或重新排序的任務。
5. 不相容變更及回退方案。
6. 重新驗收的範圍。

如果只是修改文字標籤，影響可能只在介面與測試；如果改變資料欄位或權限規則，則可能需要同步更新資料遷移、API、前端、測試與文件。Agent 必須先列出影響範圍，並等待人員確認高風險變更，而不是自行擴大修改。

官方文件亦提醒，工具升級時應更新已安裝的整合檔案與範本，但規格目錄、實作計劃與原始碼屬於需要保護的專案內容；這種「工具腳手架可更新、專案產物不可被任意覆寫」的邊界，正是長期維護時應保留的原則。官方升級與檔案保護說明

規格、設計、任務、測試與程式碼應處於同一版本控制流程。當需求進入下一個版本，先提交規格及影響分析，再讓 Agent 產生新的任務清單；若新舊規格不能同時成立，必須明確標記相容策略，而不是讓 Agent 以猜測方式維持兩套行為。

最後把開發環境也納入完成定義

Spec-Driven Development 能否穩定運作，不只取決於規格寫得好不好，亦取決於 AI Coding Agent 是否有一個可重置、可測試及可審查的執行環境。至少應確認版本控制、依賴安裝、測試工具、環境變數管理、資料庫重建方式及日誌收集方式都已固定。

如果目前的開發方式依賴個人電腦上的手動設定，常見缺點是環境差異難以重現、測試資料會殘留、Agent 修改後不容易快速回退；若改用一般雲端主機，又可能遇到權限配置、長時間保留成本、連線品質及圖形化測試支援不足等問題。對需要暫時建立測試環境、驗證 Apple 平台流程或讓團隊共享一致工作狀態的情況，租用 Zutcloud 的 Mac 環境通常比臨時購置硬體更容易控制週期與回收風險。可先參考 Zutcloud Mac 租用方案 及 Zutcloud 價格資訊，再按測試工具與團隊權限需求確認是否適合。

不過，長期固定重負載、必須接駁特定實體設備，或需要完全掌控硬體與儲存政策的團隊，仍應評估自購 Mac；若只是短期驗證、分支測試或建立可重置的 AI Coding Agent 工作區，租用方案通常能避開硬體折舊、環境重建與多人共用同一部電腦的限制。開始前亦可查看 Zutcloud 幫助中心，先確認連線方式、帳戶權限及使用流程是否符合專案的完成定義。

延伸閱讀

• 建立可持續的專案記憶與開發上下文，讓 AI Coding Agent 遵循專案約束
• 多個 AI Agent 平行協作：從任務拆分到完整開發工作流程
• 平行 AI Coding 實戰：打造協作式開發流程