•
規格驅動開發 (Spec-Driven Development) 與 AI 協作全流程實戰
45 分鐘閱讀 •
這份做來送給我的同事參考,希望他們都能把這套用起來!😀
其核心是將開發流程的重心從「撰寫程式碼」轉移到「定義規格」。 透過一個結構化的流程,將模糊的業務需求層層轉化為清晰的規格文件、技術藍圖與可執行的任務清單,再由 AI 代理執行具體的編碼工作。對資深工程師而言,這意味著角色的轉變:從主要的程式碼生產者,轉變為系統意圖的架構師、品質的把關者與複雜問題的解決者。本報告將深入剖析 SDD 的核心理念與工作流程,並透過與傳統開發及 Vibe Coding 的對比,闡明其在現代軟體工程中的獨特價值與實踐心法。
開發範式的演進:從傳統到 AI 世代
在深入 SDD 之前,我們必須先理解當前軟體開發領域並存的三種主要模式:傳統開發、Vibe Coding,以及作為兩者演化方向的 SDD。
傳統開發模式
傳統開發,無論是瀑布式(Waterfall)或敏捷式(Agile),都建立在嚴謹的流程之上12。工程師遵循明確的步驟,從需求分析、設計、編碼到測試,一步步建構軟體3。
- 優點:
- 缺點:
Vibe Coding:跟著感覺走的 AI 程式設計
隨著大型語言模型(LLM)的興起,一種全新的開發模式應運而生。由 OpenAI 共同創辦人 Andrej Karpathy 於 2025 年 2 月提出的「Vibe Coding」,指的是開發者主要透過自然語言提示(Prompt),引導 AI 快速生成程式碼,專注於「感覺」與「意圖」,而非程式碼的語法細節13141516。
- 優點:
- 缺點:
深入解析:規格驅動開發 (Spec-Driven Development, SDD)
SDD 並非一個全新的發明,而是將傳統軟體工程中「設計先行」的嚴謹思維,與 AI 的自動化能力相結合的現代實踐。它不是要你寫更多文件,而是要讓「規格」本身成為可執行、可驗證、並能驅動開發流程的「活資產」2612。
核心哲學:意圖即真理 (Intent is the Source of Truth)
傳統開發的真理來源是「程式碼」,而 Vibe Coding 則幾乎沒有真理來源。SDD 的核心轉變是將「規格」或更精確地說是「開發意圖」,確立為唯一的真理來源27232812。
這意味著,任何程式碼的產生、修改或測試,都必須源自於一份清晰、明確的規格。這份規格不再是開發完成後束之高閣的靜態文件,而是整個開發生命週期的起點與核心1011。當需求變更時,我們修改的不是程式碼,而是規格;規格的更新會自動觸發後續技術設計、任務清單乃至程式碼的連動變更2930。
SDD 通用工作流程
雖然不同工具有其特定實現,但一個典型的、工具無關的 SDD 流程包含以下幾個關鍵階段,每一階段都產出對應的 Markdown 文件作為交付物313233:
第一階段:規格定義 (Specify - The "What" & "Why") 這個階段的目標是回答「我們要做什麼?」以及「為什麼要做?」,完全不涉及技術實現3412。資深工程師需要與產品團隊協作,將模糊的商業需求轉化為結構化的規格文件(相當於
requirements.md
)。產出:一份包含使用者故事(User Stories)和驗收標準(Acceptance Criteria)的清晰文件。
心法:採用標準化語法來消除歧義。例如,EARS (Easy Approach to Requirements Syntax) 語法,透過「WHEN-THEN-SHALL」的格式,將每個需求都轉化為一個可測試的場景313532。
範例:
# 需求:增加亮色模式主題 ## 使用者故事 AS a user, I WANT to be able to switch between light and dark themes, SO THAT I can choose the most comfortable viewing experience. ## 驗收標準 (EARS 格式) WHEN a user visits the site for the first time, THEN the system SHALL display the page in the default dark theme. WHEN a user activates the theme toggle control, THEN the system SHALL switch the site's appearance to the light theme.
第二階段:技術規劃 (Plan - The "How") 當「做什麼」被明確定義後,才進入「如何做」的階段。此時,AI 代理會基於第一階段的規格文件,以及預先設定好的專案技術限制(如技術棧、架構模式、命名慣例等),生成一份詳細的技術藍圖(相當於
design.md
)3132。- 產出:包含技術架構決策、資料流程圖(如 Mermaid 圖)、API 端點定義、資料庫 Schema 變更、前端元件劃分等內容的設計文件31。
- 心法:這是資深工程師發揮最大價值的環節。你需要審核 AI 產生的設計方案,確保其符合專案的長期架構、具備良好的延展性與效能。你的角色是「把關者」,而不是「執行者」。
第三階段:任務拆解 (Tasks - The Work Breakdown) 一旦技術藍圖被確認,AI 會自動將其分解為一系列具體的、有依賴關係的、可獨立執行的開發任務(相當於
tasks.md
)3132。產出:一份精細的任務清單,每個任務都直接關聯到設計文件和原始需求,建立了清晰的可追溯鏈31。
範例:
# 任務清單 - [ ] T01: [DB] 在 `users` 資料表中新增 `theme_preference` 欄位。 - [ ] T02: [API] 建立 `PATCH /api/user/preferences` 端點以更新主題偏好。 - [ ] T03: [Frontend] 建立 `ThemeToggle` React 元件。 (依賴 T02) - [ ] T04: [Test] 為 `ThemeToggle` 元件撰寫單元測試。 (依賴 T03)
心法:確保每個任務的粒度足夠小,可以在 1-2 小時內完成,這有利於 AI 自動執行和人類進行審查36。
第四階段:實作與驗證 (Implement) AI 代理或開發者依照任務清單逐一完成編碼工作。與 Vibe Coding 的巨大程式碼傾倒不同,SDD 模式下的程式碼提交是小而聚焦的,每一次變更都直接對應一個具體任務12。
- 心法:程式碼審查(Code Review)的重點從「這段程式碼寫得好不好?」轉變為「這段程式碼是否忠實地實現了 T03 任務所描述的規格?」。審查變得有據可依,效率和品質都大幅提升。
資深工程師在 SDD 中的新角色
SDD 不會取代資深工程師,反而會放大你的價值。 你的工作將從繁瑣的編碼中解放出來,更專注於以下高價值活動:
- 意圖的架構師:你的核心職責是撰寫高品質的規格,清晰地表達業務意圖。
- 系統的治理者:定義專案的技術邊界與品質護欄,確保 AI 的產出符合團隊規範3236。
- AI 的導師:將 AI 視為一個能力極強但缺乏經驗的初級工程師,為其提供清晰的指令、上下文和指導3738。
- 複雜問題的攻堅者:專注於處理 AI 難以勝任的複雜架構設計、演算法優化和疑難問題排查3940。
三種開發模式的比較分析
為了更直觀地理解 SDD 的定位,下表從多個維度對三種開發模式進行了比較:
評估指標 | 傳統開發 (Traditional Development) | Vibe Coding | 規格驅動開發 (Spec-Driven Development) |
---|---|---|---|
核心理念 | 流程與紀律 | 速度與直覺 | 意圖與結構 |
開發速度 | 慢 | 極快 (僅限原型) | 快 (功能開發) |
程式碼品質 | 高 | 低 | 高 |
可維護性 | 中(文件易過時) | 極低 | 高(活文件) |
技術債 | 中 | 極高 | 低 |
文件 | 靜態,易與程式碼脫節 | 幾乎沒有 | 動態,與程式碼同步(活文件) |
開發者角色 | 實作者、工程師 | 提示者、實驗者 | 架構師、審查者、指揮者 |
適用場景 | 高度監管的行業、大型核心系統、遺留系統維護79 | 快速原型驗證 (MVP)、個人專案、創意探索171816 | 複雜功能開發、企業級應用、注重長期維護的新專案4135 |
從比較中可以看出,SDD 巧妙地在 Vibe Coding 的「速度」與傳統開發的「品質」之間取得了平衡3742。它吸收了 Vibe Coding 由自然語言驅動的優勢,同時透過引入結構化的軟體工程實踐,克服了其混亂和不可靠的致命缺陷。
擁抱 SDD 的心法:給資深工程師的轉型指南
要成功轉型到 SDD,不僅是學習新工具,更是一場思維模式的變革。
從「如何做」轉向「為何做」 在思考任何技術實現之前,先強迫自己清晰地闡述功能的商業價值、使用者場景和成功指標。練習撰寫高品质的
requirements.md
是第一步,也是最重要的一步3412。將 AI 視為你的「初級開發夥伴」 不要期待 AI 能讀懂你的心思。你需要像指導一位新進成員一樣,為它提供清晰的規格、完整的上下文(現有程式碼、架構約束)和明確的目標。你的經驗將體現在你提供給 AI 的「指導品質」上3738。
擁抱「活文件」生態系統 徹底拋棄「先寫程式碼,後補文件」的舊習慣。在 SDD 中,文件是驅動程式碼的引擎。要習慣於在
design.md
中規劃架構,在tasks.md
中追蹤進度。這些文件是專案知識傳承的核心,其價值甚至高於程式碼本身2612。從「編碼者」轉型為「指揮家」 你的價值不再由你寫了多少行程式碼來衡量,而是由你設計的系統有多麼健壯、可維護來決定。將你的時間和精力投入到更高層次的架構決策、設計方案審查和定義品質標準上3937。
採取漸進式導入策略 不要試圖一夜之間改變整個團隊的開發流程。從一個新的、相對獨立的功能模組開始試驗。為這個模組完整地走一遍 SDD 流程,並與團隊過去的開發方式進行對比。用實際成果(更高的品質、更少的返工、更清晰的文件)來證明 SDD 的價值,是推動變革最有效的方式1341。
總結而言,Spec-Driven Development 是 AI 時代下軟體工程嚴謹性的回歸與升級。對於資深工程師來說,這不是威脅,而是一個契機——一個將你從重複的編碼勞動中解放出來,讓你真正專注於架構、設計與品質,從而最大化自身經驗價值的歷史性機遇。
開發者首先在 VS Code 環境中,利用 GitHub Copilot 的上下文理解與程式碼生成能力,完成從需求定義、技術設計到任務拆解的規格文件(requirements.md
, design.md
, tasks.md
),並將其轉化為一個包含完整開發脈絡的 GitHub Issue。接著,開發流程的重心轉移至本地執行的 Codex CLI,此 AI 代理(Agent)被賦予讀取該 GitHub Issue 的能力,自主完成程式碼實作、建立 Pull Request,並在 PR 內生成詳盡的實作報告。最後,人類工程師的角色昇華為最終的品質把關者,負責審查、批准合併,或提出修改建議以驅動 AI 進行迭代修正。此工作流程不僅體現了 SDD 的核心精神——「意圖即為真理來源」,更透過 GitHub 平台與模型上下文協定(Model Context Protocol, MCP)將開發與維運(DevOps)無縫整合,實現了從規格到交付的高度自動化與可追溯性,為複雜軟體專案提供了一個兼具速度、品質與治理的先進開發範式。
本章使用到以下工具:
我選中了 GitHub Copilot Chat + Codex CLI 的組合,是因為這是一套可以選擇串接本地或雲端 LLM 的工具組合。且它們在本文提到的範圍中較不具有獨特性,使得這個工作流程可以套用在其它類似的工具組合上。
階段一:運用 GitHub Copilot 進行規格定義與任務規劃
此工作流程的起點是開發者的整合式開發環境(IDE),在此階段,人類的意圖與 AI 的輔助能力緊密結合,共同產出驅動後續開發的核心規格。
規格文件撰寫與版控
開發者在 Visual Studio Code 中,開啟專案的工作區(Workspace),並啟動 GitHub Copilot Chat43。此階段的目標是產出 SDD 的前三份核心文件:
- 需求規格 (
requirements.md
):開發者透過與 Copilot 的對話,將模糊的產品概念轉化為結構化的使用者故事與驗收標準。開發者可以提供初步想法,並要求 Copilot 依據標準格式(如 EARS 語法)進行精煉。 - 技術設計 (
design.md
):基於已確定的需求,開發者會要求 Copilot 規劃技術實現方案。透過提供專案的上下文(例如使用#filename
標籤或@workspace
引用關鍵的現有程式碼檔案),Copilot 能夠提出更貼近專案架構的建議,例如 API 端點設計、資料庫結構變更、前端元件劃分等4445。開發者的主要職責是審核與修正 AI 產生的設計,確保其符合長期的技術願景與品質標準。 - 任務拆解 (
tasks.md
):技術設計一經確認,開發者便會指示 Copilot 將設計藍圖分解為一系列具體、可執行的開發任務清單。
這個過程充分利用了 Copilot 作為「AI 配對程式設計師」的優勢,它擅長理解上下文、生成樣板程式碼以及輔助撰寫文件464748。完成後,這三份 Markdown 文件會被提交至 Git 儲存庫,成為整個功能開發週期的「單一真理來源」,確保所有後續工作都有據可依。
這裡不需要是「三份」文件,我更推薦撰寫詳細完整的 wiki,同時供 AI 和人類開發夥伴參考。並且要確實的進版控,和程式碼放在一起,確保開發時它們能夠隨時被 AI 查閱,或者方便帶入脈絡中。
建立可執行的 GitHub Issue
規格定義完成後,下一步是將其轉化為一個可供 AI 代理執行的正式任務。開發者繼續在 VS Code 中使用 GitHub Copilot Chat,執行以下操作:
- 生成 Issue 內容:開發者指示 Copilot 根據
tasks.md
的內容,草擬一份新的 GitHub Issue4950。 - 注入完整上下文:這份 Issue 的描述(Body)不僅僅是任務列表的簡單複製。開發者會引導 Copilot 將
requirements.md
的核心目標、design.md
的架構決策、相關的程式碼片段範例,以及必要的環境設定等資訊,全部整合進 Issue 的描述中5152。這一步驟至關重要,它將一個人類可讀的任務,轉化為一個機器(AI 代理)可讀、上下文豐富的「任務包」。 - 透過 MCP 建立 Issue:利用 GitHub 的模型上下文協定(Model Context Protocol, MCP),Copilot Chat 能夠直接在 VS Code 內呼叫 GitHub API,將草擬的內容建立成一個真正的 GitHub Issue,並為其設定標籤、指派人員等53。這實現了從 IDE 到 DevOps 平台的無縫銜接。
最終產出的 GitHub Issue,成為連接「規劃階段」與「執行階段」的關鍵橋樑。
我有一份專門用來產出高品質 GitHub Issue 的 GitHub Copilot prompt,在此提供給讀者參考
階段二:Codex CLI 的自主實作與迭代
當 GitHub Issue 建立完成後,開發流程進入下一個核心階段:由本地 AI 代理 Codex CLI 接手執行。人類的角色從「指導者」轉變為「監督者」。
讀取任務並自主開發
開發者在自己的本地終端機中,於已複製(Clone)的專案目錄下啟動 Codex CLI5455。
- 任務啟動:開發者向 Codex CLI 下達一個初始指令,要求它讀取並執行前一階段建立的 GitHub Issue。
雖然直接從 URL 讀取 Issue 內容的功能有時不穩定5657,但更可靠的做法是將 Issue 的完整內容複製貼上至終端機,或將其儲存為本地檔案後提供給 Codex CLI。不,透過 GitHub MCP 或是 GitHub CLI 讀取 Issue 內容的表現非常穩定,請直接這麼做。
- 自主執行:Codex CLI 作為一個本地運行的代理,被授權讀取本地檔案系統545859。它會解析 Issue 中的所有上下文,包括需求、設計、任務清單和程式碼範例。接著,它會以
auto-edit
或full-auto
模式開始工作,自主地修改程式碼、建立新檔案、安裝相依套件,並執行測試指令606162。所有操作都在一個安全的沙箱環境中進行,以防止意外的系統級變更6061。
自動化 PR 建立與報告生成
當 Codex CLI 判斷任務完成後(例如,所有測試都已通過),它會自動執行以下 Git 操作:
- 提交變更:將所有修改過的檔案執行
git commit
63。 - 建立 PR:自動將本地分支推送到遠端,並建立一個指向主分支的 Pull Request64。
- 生成實作報告:這是此流程的亮點之一。Codex CLI 會在 PR 的描述(Body)中,自動生成一份詳細的報告65。這份報告通常包含:
- 任務目標摘要。
- 具體的變更說明。
- 執行的關鍵指令與其輸出日誌。
- 引用其修改或參考過的檔案路徑與行號,提供完整的可驗證性與可追溯性63。
這是用來實作 Issue 並提交 PR 的 prompt
階段三:人類審查與修正循環
AI 完成了初步的實作與報告後,控制權再次交還給人類工程師,進行最終的品質驗證。
審查與合併
工程師打開該 PR,此時的審查重點不再是逐行檢查語法細節,而是更高層次的驗證:
- 意圖符合性:PR 的實現是否完全符合原始 GitHub Issue 中定義的需求與設計?
- 邏輯正確性:程式碼的邏輯是否健全?邊界條件是否處理得當?
- 架構一致性:變更是否遵循了專案既有的架構模式與編碼規範?
如果 PR 品質達標,工程師便可直接批准並合併,完成整個開發循環。
請求變更與 AI 迭代
如果審查發現問題,工程師無需親自修改程式碼。他們只需在 GitHub PR 的審查評論(Review Comments)中,用自然語言清晰地寫下需要修正的地方。
接著,開發者會啟動一個新的 Codex CLI 實例,並將這些審查評論作為新的指令輸入。AI 代理會讀取這些回饋,理解需要進行的修改,然後在同一個分支上提交新的修補程式碼,自動更新該 PR6667。這個「審查 -> 回饋 -> AI 修正 -> 再次審查」的循環可以重複進行,直到 PR 達到可合併的品質標準為止。
協作模型分析
這個工作流程清晰地劃分了人類與不同 AI 工具的職責,形成一個高效的協作體系。
參與者 | 核心角色 | 主要任務 | 關鍵能力/工具 |
---|---|---|---|
人類工程師 | 意圖定義者、品質把關者、最終決策者 | 提出初始需求、審核 AI 設計、建立 Issue、審查 PR、提出修改建議、合併程式碼 | 專業領域知識、架構判斷力、批判性思維 |
GitHub Copilot | 規劃助理、上下文整合者 | 輔助撰寫規格文件、將設計轉化為任務、整合上下文並建立 GitHub Issue | IDE 整合、上下文理解 (@workspace )、程式碼生成、文件撰寫、MCP 協定686953 |
Codex CLI | 自主執行者、實作代理 | 讀取 Issue、修改本地程式碼、執行測試、提交變更、建立 PR、生成實作報告、根據回饋修正 PR | 本地檔案存取、命令列執行、沙箱環境、Git 自動化、報告生成54585955 |
優勢與挑戰
- 優勢:
- 職責分離:明確區分了 Copilot 在 IDE 中的「規劃輔助」角色和 Codex CLI 在終端機的「自主執行」角色,避免了單一工具的權責不清。
- 高度可追溯:從規格文件到 GitHub Issue,再到 PR 的每一次提交,都建立了清晰的連結,極大地方便了後續的維護與審計。
- 提升開發者價值:將開發者從繁瑣的編碼工作中解放出來,使其能更專注於架構設計、需求分析和品質控制等高價值活動。
- 挑戰:
結論與未來展望
本報告所闡述的整合工作流程,不僅是 SDD 理論的一個具體實踐,更代表了 AI 驅動軟體開發走向成熟的一個重要里程碑。它成功地將 GitHub Copilot 的互動式輔助能力與 Codex CLI 的自主代理能力結合,在 DevOps 平台上形成了一個從意圖到交付的閉環自動化系統。
展望未來,隨著 AI 代理能力的進一步增強,特別是像 GPT-5-Codex 這樣專為程式碼任務優化的模型的出現,我們可以預見此工作流程將會更加流暢與整合747576。目前在 Copilot 和 Codex CLI 之間清晰的職責劃分可能會逐漸模糊,演化為一個更統一、更強大的「開發超級代理」。這個代理或許能夠在接收到一個高層次的 GitHub Issue 後,自主完成從規劃、設計、編碼、測試、報告到修正的全過程,而人類開發者的角色將徹底轉變為專案的「首席架構師」與「產品策略師」,專注於定義「做什麼」與「為何做」,而將「如何做」的絕大部分工作安心地委託給 AI。 Day 10 - AI-DLC Sprint × Spec-Driven Development - iT 邦幫忙 ↩ ↩2 Day 10 - AI-DLC Sprint × Spec-Driven Development - iT 邦幫忙 ↩ ↩2 Day 9 - Spec-Driven Development:讓 AI 真正理解你想要什麼 - iT 邦幫忙::一起幫忙解決難題,拯救 IT 人的一天 ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 Vibe Coding vs. Spec-Driven Development - Alt + E S V ↩ ↩2 ↩3 Spec-driven development with AI: Get started with a new open ... ↩ Spec-Driven Development (SDD) Is the Future of Software ... ↩ ↩2 ↩3 ↩4 Spec-Driven Development (SDD) Is the Future of Software ... ↩ ↩2 Does Copilot have whole codebase context? : r/GithubCopilot ↩ How to feed/provide documentations to Github Copilot for ... ↩ How to use GitHub Copilot for multiple files? - Stack Overflow ↩ Using GitHub Copilot in your IDE: Tips, tricks, and best practices ↩ OpenAI releases Codex CLI, an AI coding assistant built into ... ↩ ↩2 OpenAI Codex CLI: Build Faster Code Right From Your Terminal ↩ Codex: Automatically push to branch instead of creating a PR ↩ Anyone else find Codex CLI dissapointing? : r/OpenAI - Reddit ↩ Anyone else find Codex CLI dissapointing? : r/OpenAI - Reddit ↩ How do I troubleshoot errors or issues when using Codex CLI? ↩ How do I troubleshoot errors or issues when using Codex CLI? ↩