檢視 GitHub Spec Kit 的工作流程與可選指令

  • 8 分鐘

GitHub Spec Kit 是一個開源工具包，透過整合規格與 AI 編碼助理，實現規格驅動開發（SDD）。 在探索進階功能之前，讓我們先回顧一下基礎概念。

檢視 GitHub Spec Kit 基礎

GitHub Spec Kit 解決了 AI 輔助開發中的一項根本挑戰：如何在與編碼助理多次互動時維持上下文與一致性。 它提供三項基本功能：

  • 持久性工件：規格、計畫和任務會以標記檔案形式儲存在你的儲存庫中。
  • 標準化工作流程：明確的流程引導你完成四個 SDD 階段：規格化、規劃、任務分解與執行。
  • 可重複使用的指令：內建的斜線指令封裝了最佳的提示模式。

核心元件

GitHub Spec Kit 實作了以下核心元件：

元件 目標
specify CLI（命令列介面） 初始化並管理以規格為驅動的專案。
Markdown 成品檔案 constitution.md， spec.md， plan.md， 推動 tasks.md 開發。
斜線命令 /speckit.specify， /speckit.plan， ， /speckit.tasks， /speckit.implement 調用 GitHub Spec Kit 工作流程。

智能代理

GitHub Spec Kit 支援以下 AI 代理：GitHub Copilot、Claude Code、Cursor、Windsurf、Amazon Q Developer 等。 每個 Agent 都會收到依其特定提示格式所排版的範本，同時使用相同的底層成品檔案。

特徵追蹤的環境變數

GitHub Spec Kit 利用環境變數追蹤你目前正在開發的功能。 變數代表 SPECIFY_FEATURE 活躍功能目錄。

在基於 Git 的工作流程中，GitHub Spec Kit 會根據你的分支名稱推斷出這個功能。 如果你在分支 feature/document-upload，GitHub Spec Kit 會自動配合 features/document-upload/ 目錄運作。

對於非 Git 工作流程或手動功能規格，請明確設定環境變數：

$env:SPECIFY_FEATURE = "001-document-upload"

此設定會指示 GitHub Spec Kit 無論 Git 分支為何，都在 features/001-document-upload/ 目錄中讀取與寫入成品。

此功能追蹤確保當您呼叫 /speckit.plan時，AI 會讀取您目前功能的正確 spec.md 檔案，而非混淆不同功能的規格。

將 GitHub Spec Kit 與 Git 工作流程整合

GitHub Spec Kit 透過多種機制整合進你現有的開發實務中。

版本控制整合

所有 GitHub Spec Kit 的產物都是儲存在 Git 倉庫中的普通 markdown 檔案。 此方法提供多項優點：

  • 變更追蹤：每一次對規格、計畫或工作的修改，都會建立一筆 Git 提交。 你可以檢視需求變更的歷史，了解決策的原因，並回退有問題的變更。

  • 基於分支的開發：建立包含規範產物與實作程式碼的功能分支。 這種方法能讓需求與實作同步，讓程式碼審查變得全面——審查者同時看到你正在建構什麼（規格）和你如何建置（程式碼）。

  • 拉取請求工作流程：當你提交功能拉取請求時，請將 spec.md、plan.md 和 tasks.md 與程式碼變更一併加入。 審查者會驗證實作是否符合規範，且規範是否與專案目標相符。

例如，如果你正在實作一項新功能，你的功能分支包含：

  • spec.md 定義上傳要求。
  • plan.md 描述 Azure Blob 儲存架構。
  • tasks.md 列出實施步驟。
  • 實作此功能的原始碼。
  • 測試以驗證規範合規性。

這樣的完整圖景使得全面審查成為可能。 如果審查者質疑為何檔案限制在 50 MB，他們可以參考 spec.md，看到這項要求是利害關係人討論中產生的。

AI 助理整合情境 - GitHub Copilot

GitHub Spec Kit 透過 Visual Studio Code 的聊天介面與 GitHub Copilot 協同運作。 執行 specify init --ai copilot後，工具包會設定你的工作區來辨識 /speckit.* 指令。

當你打開 GitHub Copilot Chat 並輸入 /speckit.specify，GitHub Copilot 會從目錄中存取預設的範本 .github/prompts/ 。 這些範本有助於結構化 AI 輸出，包含所有必要的規格章節：使用者故事、驗收標準、功能需求、非功能需求及邊緣案例。

整合非常順暢——你不需要手動管理範本。 GitHub Spec Kit 會自動處理範本載入和上下文注入。 你的工作是提供功能描述並回答釐清問題。 GitHub Copilot 負責規範格式與完整性。

專案結構慣例

GitHub Spec Kit 以一致的目錄結構組織工件：

my-project/
├── .github/
│   ├── agents/
│   └── prompts/
├── .specify/
│   ├── memory/
│   │   └── constitution.md
│   ├── scripts/
│   └── templates/
├── SourceCode/ 
│   └── ...
├── specs/
│   └── 001-document-upload-feature/
│       ├── plan.md
│       ├── spec.md
│       └── tasks.md

此結構將規範產物與實作程式碼分離，同時保持它們在同一儲存庫中。 功能以順序編號（001、002、003）來追蹤開發順序。

對於同時處理多個功能的團隊來說，每個功能都有自己的目錄，包含完整的規格、計畫和任務。 這種隔離避免了混淆，並允許平行工作而無衝突。

持續工作流程支援

GitHub Spec Kit 支援透過指令鏈進行迭代開發。 產生初始規格後，你可以逐步精煉：

  1. 產生初始規格： /speckit.specify。
  2. 找出漏洞： /speckit.clarify。
  3. 根據答案更新規格。
  4. 制定實施計畫： /speckit.plan。
  5. 驗證一致性： /speckit.analyze。
  6. 產生任務： /speckit.tasks。
  7. 逐步實施： /speckit.implement。

只要需求改變，隨時可以回到早期階段，更新產物，並重新生成下游產物。 如果利害關係人在你產生任務後改變了對檔案大小限制的看法，你就會更新 spec.md，重新建立 plan.md 以反映架構影響，再用更新的驗證步驟重新生成 tasks.md，然後更新實作程式碼。

這種彈性支持需求演變的實際開發。 以規範為先的方法確保變更能系統性地傳播，而非在不更新文件前直接補丁進程式碼。

善用 GitHub Spec Kit 的可選增強指令

除了核心工作流程指令外，GitHub Spec Kit 還提供可選指令，以提升規格品質與一致性。

使用 /speckit.clarify 進行間隙分析

指令 /speckit.clarify 會分析你的規格，找出模糊不清、缺失細節及未明確指出的邊緣案例。 產生初始規格後，呼叫此指令讓 AI 提出澄清問題。

AI 會審查你的規格並產生以下問題：

  • 「規範提到檔案上傳，但沒規定最多同時上傳次數。 應該有個限制嗎？」
  • 「網路故障的錯誤處理未被指定。 如果上傳連線中斷，該怎麼辦？」
  • 「規範要求檔案驗證，但沒有說明驗證失敗訊息。 用戶應該看到什麼？」

對於每個問題，AI 通常會提供多項選擇選項來彌補差距。 你選擇選項或提供自訂答案，AI 會相應更新規格。

這種互動式的精煉能在實施開始前發現問題。 這就像有經驗的分析師審查你的規格，指出你漏掉的地方。

使用 /speckit.analyze 進行一致性驗證

此 /speckit.analyze 指令執行跨工件一致性檢查。 它驗證你的計畫是否實現所有規範要求、任務涵蓋所有計畫元素，且一切符合章程。

在產生 plan.md 和 tasks.md 後，但開始實作前執行此指令。 AI 會辨識不一致之處：

  • 「計畫建議使用 PostgreSQL，但架構需要 Azure SQL 資料庫。」
  • 「規範要求審計日誌，但計畫中並未描述日誌的實作。」
  • 「任務清單中省略了計畫中提到的資料庫遷移腳本。」

每一個發現的不一致，都是在實作或程式碼審查時會浮現的問題。 在分析階段即時發現它們可以避免重做。

使用 /speckit.checklist 進行品質驗證

這個 /speckit.checklist 指令會根據你的規格產生自訂的品質檢查清單。 這些檢查清單有助於驗證需求的完整性、清晰度與一致性——就像「英文散文的單元測驗」。

AI 會分析你的規格，並產生一份驗證問題清單：

  • 「每個用戶故事都有相應的接受標準嗎？」
  • 「所有錯誤情境都有附帶具體錯誤訊息嗎？」
  • 「非功能性需求是否包含可衡量的成功標準？」
  • 「所有外部依賴都有明確列出嗎？」

你依照清單逐一回答。 任何「不」的答案都表示規格上有缺口，需要補足。

此自我審查過程在與利害關係人分享或實施前，提升規格品質。

將 GitHub Spec Kit 應用於不同的開發場景

GitHub Spec Kit 支援多種開發場景，不僅限於從零開始建構新功能。

綠地開發

對於從零開始的新專案，GitHub Spec Kit 擅長將高層次的產品願景轉化為具體的實作。 你先 /speckit.constitution 建立專案原則，然後在迭代建置應用程式時，針對每個功能使用 /speckit.specify 。

這個情境是 GitHub Spec Kit 的主要使用情境——工作流程設計為 0 對 1 開發，也就是你要創造尚未存在的東西。

棕地強化

對於現有應用程式，你可以使用 GitHub Spec Kit 加入新功能，同時保持與現有程式碼庫的一致性。 你的憲法記錄了現有的建築模式和限制。 新的功能規範參考了這些既定模式。

當你在現有員工入口網站新增文件上傳功能時，你的規格會承認現有的 React 前端、.NET 後端以及 Azure 基礎架構。 計畫展示了新功能如何與現有架構整合，而非提出獨立實作方案。

重構與現代化

GitHub Spec Kit 可以透過將期望的最終狀態視為規格來引導重構工作。 你要記錄重構後的程式碼應該達成什麼（功能相同但結構更佳）、制定重構計畫，並產生漸進式變更的任務。

這種結構化的重構方法可避免常見的問題，也就是在重構過程中途迷失方向，留下僅部分可運作的程式碼。

探索性發展

如果你在探索多種潛在方法，可以使用 GitHub Spec Kit 從同一規格產生多個計畫。 穩定規格代表你想要達成的目標，而不同計畫則探索不同的技術方法。

你可以用 Azure Blob 儲存體 生成一個計畫，另一個用 Azure 檔案儲存體 建立，兩者都來自相同的上傳規範。 兩者都實作，比較結果，並根據實際經驗而非假設選擇更好的方法。

總結

GitHub Spec Kit 是一個強大的工具包，透過整合結構化工作流程、持久產物與可重複使用的 AI 指令模式，實現以規格驅動的開發。 它透過系統化的方式，將規格轉化為實際實作，徹底改變了你使用 AI 編碼助理（如 GitHub Copilot）的方式。 透過使用 GitHub Spec Kit，您可以確保需求與程式碼的一致性，維持決策的可追溯性，並促進開發團隊間的協作。