Spec Kit：AI 軟件開發 Spec-Driven Development

AI 智能體（AI Agent）開發工具的出現，如 OpenAI Codex、Anthropic 的 Claude Code、Google 的 Gemini CLI 及阿里的 Qwen Code，無疑為開發效率帶來了革命性的提升。 然而，這些工具有時會表現得缺乏紀律的。我們拋出一個模糊的想法，期望得到完美的代碼，結果卻是反覆的修正與溝通，開發者往往是憑感覺去開發。

為了解決這個問題，GitHub 推出 Spec Kit 的開源工具箱，旨在將傳統軟件工程中行之有效的「規格驅動開發」（Spec-Driven Development, SDD）方法，引入到與 AI 協作的工作流程中。 Spec Kit 作為一個框架，提供一套結構化的流程與指令，確保從概念發想到代碼實現的每一步都有清晰的定義與依據。 這使得 AI 智能體能在一個有良好規範的環境下工作，產出更穩定、更高品質且更符合預期的代碼。

本文將深入探討 Spec Kit 的核心理念，從初始化項目開始，詳細介紹其提供的核心指令（Slash Commands），並分析其優缺點。

為何需要 Spec Kit？從混亂到有序

直接向 AI 智能體下達指令雖然快捷，但當項目變得複雜時，問題便會浮現：

• 需求模糊：口語化的描述容易產生歧義，AI 可能會誤解你的真實意圖。
• 缺乏一致性：如果沒有明確的規範，AI 在不同時間點生成的代碼風格、架構決策可能會不一致。
• 難以追蹤與管理：開發過程缺乏文檔記錄，後續的維護與交接變得困難重重。
• 迭代困難：當需求變更時，需要重新向 AI 解釋上下文，耗費大量時間進行調整與修復。

Spec Kit 正是為了解決這些痛點而生。它將開發流程制度化，強調在編寫任何代碼之前，必須先有明確的規格（Specification）。 這種方法論的核心思想是，一份好的規格文件本身就是一份「合約」，它精確定義了軟件應該如何運作，成為開發者與 AI 智能體之間溝通的共同語言和真理的唯一來源。 通過這種方式，Spec Kit 將混亂的「憑感覺開發」轉變為一個可預測、可重複且系統化的工程流程。

Spec Kit 工作流程

要開始使用 Spec Kit，首先需要初始化項目，並了解其與 Git 的整合。

Step 1: 項目初始化 (specify init)

開始一個新項目時，第一步是使用 Spec Kit 的命令行工具（CLI）進行初始化。你需要先安裝 specify-cli 工具。

# 推薦使用 uv 進行安裝 (一次性安裝)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 初始化一個名為 'my-project' 的新項目，並選擇 claude 作為 AI 智能體
specify init my-project --ai claude

這個指令會創建項目文件夾，並在其中生成模板、腳本和命令。 這些文件是 Spec Kit 工作流程的基礎，為後續的指令提供了支援。在初始化過程中，你可以選擇使用不同的 AI 智能體，例如 copilot、claude 或 gemini。

與 Git 的整合：為每個功能建立分支

Spec Kit 與 Git 深度整合，使用 /speckit.specify 指令來定義一個新功能時，Spec Kit 會自動為你創建一個新的 Git feature branch。

這個設計遵循了業界標準的開發實踐，確保了：

• 功能隔離：每個新功能都在獨立的分支上開發，不會影響主分支的穩定性。
• 清晰的歷史記錄：每一次的功能開發都有對應的分支和提交記錄，方便代碼審查（Code Review）和版本追蹤。
• 協作順暢：團隊成員可以清楚地看到正在開發的功能，並在完成後通過 Pull Request 的方式合併回主分支。

Spec Kit 核心工作流程概覽

下圖清晰地展示了使用 Spec Kit 進行開發的完整流程，從項目初始化到最終的代碼實現，每一步都有對應的指令來驅動。

3、4、5、6 步為新增功能的循環。即當要新增一新功能時，3至6要反覆執行。

核心概念：掌握 Spec Kit 的 Slash Commands

初始化項目後，你將主要在你的 AI 智能體（如 VS Code 中的 GitHub Copilot Chat 或 Claude Code）的介面中，使用 Slash commands 來驅動整個開發流程。

Step 2: /speckit.constitution：定立項目最高原則

這是整個項目的基石。 /speckit.constitution 指令用於創建或更新項目的「憲法」（Constitution）。這份文件定義了項目的最高原則與規範，是 AI 在後續所有工作中都必須遵守的指導方針。

這份「憲法」通常包括：

• 技術棧：使用的編程語言、框架和主要庫。
• 編碼風格：命名約定、代碼格式化規則等。
• 架構原則：例如，項目是採用微服務架構還是單體架構。
• 測試標準：單元測試的覆蓋率要求、端到端測試的策略等。
• 非功能性需求：如性能要求、安全性標準等。

範例 (Example): You can use this command to define the project's basic tech stack and rules: /speckit.constitution Please create the constitution file. This project is a personal blog developed with Next.js and TypeScript. All code must adhere to ESLint and Prettier rules, and unit tests should be written for critical business logic.

Step 3: /speckit.specify：定義具體功能

當你確立了項目憲法後，就可以開始定義具體要開發的功能。/speckit.specify 指令的重點是描述「做什麼」和「為什麼做」，而不是「如何做」。

在這個階段，你應該提供：

• 用戶故事 (User Stories)：從用戶的角度描述功能需求。
• 驗收標準 (Acceptance Criteria)：明確定義功能完成的標準。
• 業務目標：解釋這個功能要解決什麼問題，帶來什麼價值。

注意：執行 specify 命令後，它會自動創建新的 Git 功能分支，從這步至 implement，所有工作都在新分支上完成。

範例 (Example): Describe a specific user requirement: /speckit.specify Please create the spec for this project. I want to add an article search feature to the blog. Users should be able to enter keywords into a search box on the homepage, and the system should return a list of all articles whose title or content contains those keywords.

執行此指令後，Spec Kit 會生成一份詳細的規格文件（spec.md），並如前所述，創建一個新的 Git 分支。

Step 4: /speckit.plan：制定技術實施計劃

有了明確的規格後，下一步是將其轉化為技術上的實施方案。/speckit.plan 指令用於創建技術計劃，這個計劃會基於先前定義的「憲法」和功能規格。

AI 智能體會在這個階段思考：

• 架構設計：需要創建哪些新的組件或模塊？
• 數據模型：需要什麼樣的數據結構或數據庫模式？
• API 設計：如果涉及後端，API 的端點和數據格式是怎樣的？
• 第三方服務：是否需要集成外部的庫或 API？

範例 (Example): Create a technical plan based on the specification: /speckit.plan Please generate the plan. The plan is to use a React frontend component to handle user input and display results. The backend will create an API endpoint /api/search that accepts a query parameter and performs a search in the database.

Step 5: /speckit.tasks：將計劃分解為可執行的任務

計劃制定好之後，/speckit.tasks 指令會將宏觀的計劃分解成一系列具體的、可操作的開發任務。 每個任務都應該是小而具體的，小到足以讓 AI 智能體一次性完成並進行測試。

這一步驟將一個複雜的功能分解為一個清晰的任務清單，例如：

1. 創建 SearchInput.tsx React 組件。
2. 實現前端組件的狀態管理和 API 請求邏輯。
3. 在 Next.js 中創建 /api/search API 路由。
4. 實現後端數據庫查詢邏輯。
5. 為後端 API 編寫單元測試。

範例 (Example): Convert the technical plan into a task list: /speckit.tasks Please breakdown the plan into tasks.

Step 6: /speckit.implement：執行任務，生成代碼

最後，/speckit.implement 指令會指示 AI 智能體按照任務列表，逐一完成代碼的編寫工作。 你可以讓 AI 實現所有任務，或是一次只實現幾個任務，這提供了很好的靈活性。

由於之前的步驟已經提供了充足的上下文（原則、規格、計劃、任務），AI 在這個階段生成的代碼將會更精準且符合項目規範。 從 specify 起到 implement 為止，所有工作都在新的 Git 功能分支上，完成後應合併到 master / main 分支。

若有新的功能，可以再次執行 specify，即執行 STEP 3 到 STEP 6 的循環。屆時，它會再創建另一新的 Git 功能分支。

Spec Kit 的優勢與挑戰

優勢

• 結構化與可預測性：它為 AI 驅動的開發帶來了紀律，將其從隨機的探索變為嚴謹的工程實踐。
• AI 智能體無關性：Spec Kit 的設計是通用的，支持多種主流的 AI 編碼助手，讓你不會被鎖定在單一平台上。
• 質量提升：通過前置的規格定義和計劃，極大地減少了因需求理解不清而導致的錯誤和返工，提升了代碼質量。
• 文檔即代碼：規格、計劃和任務本身就是項目的活文檔，它們與代碼同步演進，降低了維護成本。
• 無縫的 Git 流程：自動化的分支管理使得 AI 協作能與現代化的 DevOps 流程完美融合。

挑戰

• 前期投入較大：對於非常簡單或一次性的任務，遵循完整的 Spec Kit 流程可能會顯得有些繁瑣。
• 學習曲線：開發者需要時間來適應這種規格先行（spec-first）的思維模式和相關指令。
• 對規格質量的依賴：最終的產出質量仍然高度依賴於開發者所提供規格的清晰度和準確度。所謂「Garbage in, garbage out」，Spec Kit 只是提供了一個更好的結構來組織你的輸入。

結論

Spec Kit 代表了 AI 輔助軟件開發領域的一次重要範式轉移。它通過提供一個強大的框架，來增強開發者的管控能力，演著一個項目經理和架構師的角色，確保 AI 智能體可以有條理地完成工作。

📚 參考資料

• Spec Kit GitHub Repository