檢視 GitHub Spec Kit 的開發環境

  • 7 分鐘

GitHub Spec Kit 需要適當配置的開發環境，才能支援以規格驅動的開發工作流程。 正確配置的環境包含 Specify CLI、AI 編碼助理、程式碼編輯器及版本控制系統。 了解組成 GitHub Spec Kit 開發環境的元件、支援的配置，以及安裝與初始化的概念非常重要。

開發環境元件

GitHub Spec Kit 開發環境由幾個關鍵元件組成，協同運作以支援以規格驅動的開發流程：

  • 指定 CLI：命令列介面工具，用於初始化專案、建立範本結構，並管理規格驅動的工作流程。 Specified CLI 是基於 Python，需要 Python 3.11 或更新版本，並且是建立 GitHub Spec Kit 專案的基礎。

  • UV 套件管理器：安裝與管理 Specify CLI 的推薦工具。 該 uv 工具提供持續安裝、版本管理及升級功能，適用於指定 CLI。

  • 具備 AI 整合的程式碼編輯器：GitHub Spec Kit 設計用於支援透過聊天介面與斜擊指令支援 AI 編碼助理的程式碼編輯器。 Visual Studio Code 搭配 GitHub Copilot 是主要支援的配置，雖然工具包也支援其他 AI 代理。

  • 版本控制系統：GitHub Spec Kit 的產物（規格、計畫、任務及架構檔案）以 markdown 檔案形式儲存在版本控制的倉庫中。 Git 是標準版本控制系統，支援 GitHub、GitHub Enterprise Server 及 Azure Repos。

  • AI 編碼助理：規格驅動的工作流程依賴 AI 模型來解讀規格並生成實施計畫與程式碼。 GitHub Copilot 是此訓練的推薦 AI 助理，雖然 GitHub Spec Kit 支援多個 AI 代理。

  • 程式設計執行時（依情境而定）：雖然 GitHub Spec Kit 本身不要求特定的程式執行時，但你需要相應的執行時來實作基於你所選技術堆疊的功能（例如 .NET SDK、Node.js或 Python）。

支援的 AI 代理與模型

GitHub Spec Kit 設計用於支援多種 AI 編碼助理，而這些助理支援聊天介面及自訂斜線指令。 了解支援的選項有助於你為開發工作流程選擇合適的配置：

  • GitHub Copilot：GitHub Spec Kit 支援的主要 AI 助理，可透過 Visual Studio Code 的 GitHub Copilot Chat 擴充功能使用。 GitHub Copilot 提供整合的聊天體驗、內嵌程式碼建議，以及支援觸發 GitHub Spec Kit 工作流程的自訂斜線指令。

  • 廣泛的 AI 代理支援：GitHub Spec Kit 支援超過 15 種 AI 編碼助理，包括 Claude Code、Cursor、Windsurf、Gemini CLI、Qwen Code、Kilo Code、Auggie CLI、CodeBuddy CLI、Roo Code、Codex CLI 及 Amp。 每個代理程式透過類似模式與 GitHub Spec Kit 整合——聊天介面能辨識 /speckit.* 斜杠指令並能讀取專案產物以指導實作。

  • 代理專屬限制：大多數代理程式完全支援 GitHub Spec Kit，但有些代理存在限制。 例如，Amazon Q Developer CLI 不支援斜杠指令的自訂參數，這可能會影響某些工作流程的自訂。

  • 模型需求：GitHub Spec Kit 工作流程依賴能理解複雜規格、維持多個產物上下文並產生結構化輸出的 AI 模型。 現代大型語言模型擁有廣泛的上下文視窗，最適合解釋規格並產生完整的實作計畫。

技術堆疊與語言支援

GitHub Spec Kit 的核心原則之一是技術獨立性——以規格為導向的方法適用於各種技術堆疊、程式語言與框架：

  • 語言無關：規範描述的是要建什麼，而不是怎麼建。 你可以用 .NET、Node.js、Python、Java 或其他語言實作相同的規範。 技術堆疊的選擇是在規劃階段進行，而非規格說明階段。

  • 框架彈性：GitHub Spec Kit 支援任何適合你專案的框架或函式庫。 無論是使用 React、Angular 或 Blazor 建置網頁應用程式，使用 Express 或 ASP.NET Core 開發後端服務，或是使用 .NET MAUI 或 React Native 的行動應用程式，規格驅動的流程始終保持一致。

  • 雲端平台中立性：雖然規範可能包含架構限制（如「使用 Azure 服務」或「部署至 AWS」），但 GitHub Spec Kit 並不強制執行特定雲端供應商。 組織架構文件中定義的標準指引雲端平台的選擇。

  • 多重同時實作：進階 GitHub Spec Kit 工作流程支援使用不同技術堆疊建立同一規範的多個平行實作，允許在最終方案前探索多元解決方案。

平台與作業系統支援

GitHub Spec Kit 支援跨主要作業系統，確保開發團隊能使用他們偏好的平台：

  • Windows 支援：完整支援 Windows 10 及更新版本，支援 PowerShell 與命令提示字元。 Specified CLI 包含 Windows 專用的初始化與設定腳本。

  • macOS 與 Linux 支援：原生支援 macOS 與 Linux 發行版，並支援 bash 與 zsh shell。 安裝依照標準 Unix 慣例使用套件管理器與 PIP 進行。

  • 跨平台一致性：GitHub Spec Kit 的產物（Markdown 檔案、提示範本與設定）採用平台無關格式，確保規格與計畫在不同作業系統間運作一致。

企業環境考量

組織通常有特定的需求、政策及影響開發環境配置的基礎架構：

  • 企業網路限制：企業環境可能會使用代理伺服器、自訂憑證授權中心或防火牆規則，影響套件安裝與 Git 操作。 開發環境必須透過代理設定與憑證信任設定來考量這些限制。

  • 擴充功能與軟體審核：部分組織限制 Visual Studio Code 擴充套件安裝僅限於核准的市集，或要求安全審查。 了解這些政策有助於規劃環境設置的時間表。

  • 託管開發環境：許多組織提供預先設定的開發虛擬機、容器或雲端開發環境。 這些受管理環境通常預裝 Python、Git 和 Visual Studio Code，簡化設定並確保符合組織標準。

  • Azure DevOps 整合：對於使用 Azure DevOps 而非 GitHub 的團隊，GitHub Spec Kit artifacts 能無縫整合 Azure Repos。 任務可以連結到 Azure Boards 的工作項目，規格則作為 pull request 中的文件。

  • GitHub Enterprise Server：使用 GitHub Enterprise Server（自架 GitHub）的組織可使用 GitHub Spec Kit，具備企業專屬的認證、合規控制及組織政策。

安裝與初始化概念

了解如何安裝和初始化 GitHub Spec Kit，有助於你更懂得環境設定的過程。

主要的安裝與初始化概念包括：

  • Specify CLI 安裝：Specify CLI 可透過 uv 工具持久安裝，使 specify 指令在系統範圍內可用，或一次性使用 uvx 而無需安裝。 建議持續安裝以持續進行開發，並透過uv tool list、uv tool upgrade及uv tool uninstall指令提供更好的工具管理。

  • 環境驗證：指令用以 specify check 驗證所需工具是否已安裝並可存取，包括 Git 及所選 AI 編碼代理。 此驗證步驟有助於在開始開發前診斷環境問題。

  • 專案初始化：指令建立 specify init 專案結構以規範驅動開發。 此過程會產生提示範本目錄、工件範本檔案及設定，使 AI 助理能辨識並回應 /speckit.* 斜線指令。

  • 進階初始化選項：此 specify init 指令支援企業及專業場景的各種旗標，包括跳過 Git 初始化--no-git（）、使用現有目錄（--here、）、 --force企業環境指定 GitHub 標記（--github-token）、代理場景跳過 TLS 驗證（--skip-tls）、以及啟用詳細除錯輸出（--debug）。

  • AI 代理選擇：初始化時，你會選擇你使用的 AI 編碼助理（例如 GitHub Copilot、Claude 或其他軟體）。 此選擇決定了所設定的提示範本與整合腳本。

  • 版本控制整合：GitHub Spec Kit 預設初始化 Git 倉庫（除非明確停用），確保所有產物從一開始就被版本控制。 版本控制整合促進團隊共享規格並追蹤變更的協作工作流程。

初始化後的專案結構

初始化後，GitHub Spec Kit 會建立一個標準化的專案結構：

  • .github/prompts/ 目錄：包含提示範本檔案，引導 AI 助理完成規格驅動工作流程的每個階段。 檔案包括 constitution.prompt.md、 specify.prompt.md、 clarify.prompt.md、 plan.prompt.md、 tasks.prompt.mdimplement.prompt.mdanalyze.prompt.mdchecklist.prompt.md和 。

  • 工件範本檔案：GitHub Spec Kit 在專案根目錄中建立 constitution.md、spec.md、plan.md 和 tasks.md 的範本版本。 這些範本提供起始點，並附上在工作流程中填充的區段佔位符。

  • 設定檔：根據所選的 AI 代理，GitHub Spec Kit 可能會建立其他設定檔，與程式助理的環境整合。

  • 腳本變體：為跨平台支援，GitHub Spec Kit 能產生 bash/zsh 腳本（.sh 檔案）及 PowerShell 腳本（.ps1 檔案），確保與不同作業系統及 shell 相容。

斜線指令架構

AI 編碼助理中顯示的 /speckit.* 指令，是透過 GitHub Spec Kit 的提示範本架構來啟用的。

  • 指令辨識：當你在 AI 聊天介面輸入 /speckit 時，助理會根據 Prompt .github/prompts/範本辨識出自訂指令。

  • 核心工作流程指令：規格驅動開發工作流程的必備指令包括 /speckit.constitution （建立專案原則）、 /speckit.specify （定義需求）、 /speckit.plan （建立技術計畫）、 /speckit.tasks （產生任務清單）及 /speckit.implement （執行實作）。

  • 品質提升指令：其他指令支援迭代精煉與驗證，包括 /speckit.clarify （釐清未明確指定區域）、 /speckit.analyze （跨工件一致性分析）及 /speckit.checklist （產生品質驗證檢查清單）。

  • 模板驅動指引：每個斜線指令對應一個提示範本檔，指示 AI 如何生成或更新特定工件。 例如，引導 specify.prompt.md AI 建立結構化規格，包含摘要、需求、接受標準及邊緣案例等區塊。

  • 情境感知：提示範本會參考專案中的其他元素，使 AI 能維持一致性。 例如，在產生技術計畫時，/speckit.plan 會同時參考 constitution.md （作為約束條件）和 spec.md （作為需求）。

  • 客製化潛力：組織可自訂提示範本以強制執行特定文件標準、新增必要章節，或納入領域專屬術語。

環境驗證概念

妥善配置的環境能促進順暢且以規格為驅動的開發流程。

關鍵驗證點包括：

  • CLI 可及性：該 specify 指令應在終端機路徑中可用，表示 CLI 安裝成功。

  • Visual Studio Code 擴充功能啟用：應安裝、啟用並驗證 GitHub Copilot Chat 擴充功能，啟用用於斜線指令的聊天介面。

  • 專案識別：初始化後，在 Visual Studio Code 開啟專案時，應該會在 GitHub Copilot Chat 的自動完成功能中使/speckit.*指令可用。

  • 版本控制準備度：應配置 Git 並初始化儲存庫，允許工件提交與協作。

  • 環境變數：GitHub Spec Kit 支援透過環境變數進行設定。 例如，該 SPECIFY_FEATURE 變數可以覆寫非 Git 資料庫中的功能偵測，使得在未使用 Git 分支時，能對特定功能進行工作。

常見的環境考量

不同的開發情境帶來不同的環境挑戰：

  • 企業代理與防火牆：企業網路通常需要代理設定來安裝套件和 Git 操作。 憑證授權中心可能需要先設定，才能信任企業 HTTPS 攔截。

  • 擴充功能審核流程：有安全政策的組織可能需要在安裝 Visual Studio Code 擴充功能前取得批准，影響設定時間。

  • Python 版本管理：同一台機器上有多個 Python 版本，可能會導致路徑衝突。 了解是哪個 Python 直譯器在啟動，有助於排除安裝問題。

  • PATH 配置：透過 pip 或 uv 安裝的 CLI 工具需要在系統 PATH 中保留安裝目錄。 不同的作業系統和 shell 對 PATH 設定的處理方式不同。

  • 管理環境與自助服務環境：預先設定的開發虛擬機簡化設定，但客製化可能受限。 自助本地安裝提供彈性，但需要更多個別配置。

總結

GitHub Spec Kit 開發環境結合了 Specified CLI、AI 編碼助理、程式碼編輯器及版本控制系統等重要元件，以實現有效的規格驅動開發工作流程。 了解斜線指令架構、專案結構及環境驗證流程，能確保你能建立並維護一個高效的開發環境。 透過解決企業環境中常見的考量，你可以調整 GitHub Spec Kit 以符合組織需求，同時利用 AI 驅動的編碼協助，實現一致且可追蹤的實作。