2026 Spec Kit 完整使用教程：從安裝配置到 AI 程式實戰，Windows、macOS、Linux 規範驅動開發

GitHub 維護的 Spec Kit 把規範驅動開發收成可安裝的命令列和一組 Agent 技能。PyPI 上的包名是 specify-cli，原始碼倉庫是 github/spec-kit。它不替換 Cursor、Claude Code、GitHub Copilot 或 Codex，只規定這些 Agent 先寫清行為，再寫技術選型，最後才改倉庫。2026 年 11 月，Windows 可以直接走 PowerShell 指令碼，不必先裝 WSL。這篇只講安裝、目錄和命令順序。規格為什麼必須先於程式碼，見 規範驅動開發完全指南。技能檔案怎麼放，見 Agent Skills 使用指南。

為什麼一句「幫我做個看板」已經不夠

舊方式和新方式的衝突很具體。舊方式是會話優先：把目標、技術棧、目錄結構一次塞進聊天，Agent 邊猜邊改檔案，換一臺機器或換一個人，上下文就斷了。新方式是製品優先：原則寫進 .specify/memory/constitution.md，行為和原因寫進 specs/<feature>/spec.md，技術棧留到 plan.md，可執行的順序留到 tasks.md。當前功能看 .specify/feature.json，不看你記得的上一輪對話。

這件事在 2026 年變成安裝問題，而不是態度問題，有三個原因。第一，技能的呼叫拼法按 Agent 分叉：Cursor、Claude Code 和 Copilot 預設技能模式用 /speckit-specify，Codex 用 $speckit-specify，文件裡的點號寫法只是參考記法。第二，uv 和 pipx 各裝一次會留下兩個 specify，PATH 裡的舊二進位制會讓 --integration 直接失敗。第三，可選的 git 擴充套件會建編號分支，但 git checkout 本身不會切換當前功能。三件事都發生在寫第一行業務程式碼之前。

規範驅動開發在 Spec Kit 裡分成哪幾層

不要把九個斜槓命令當成同一層的清單。它們落在三種製品上，而且只有兩條合法路徑。

原則層一個倉庫做一次。/speckit-constitution 寫程式碼質量、測試、許可權和體驗上的硬約束，給後面每一步當尺子。功能層每個功能一份。/speckit-specify 只回答使用者能觀察到什麼、為什麼要做；/speckit-clarify 把含糊的地方問清楚並寫回規格。實現層才允許出現框架和目錄。/speckit-plan 產出計劃、調研、資料模型和契約；/speckit-tasks 把計劃拆成有依賴順序的任務，可並行的標 [P]；/speckit-implement 按任務改檔案；/speckit-converge 拿程式碼和製品對賬，缺什麼就補任務，直到它報告 Converged。

中間還有兩道質量門，不要和「程式碼寫完了」混為一談。/speckit-checklist 生成的是審閱者手裡的需求質量清單，勾選表示這條要求寫清楚了，不表示功能已經實現。/speckit-analyze 只讀，報告 spec.md、plan.md、tasks.md 之間的衝突，不改檔案。內建的 checklists/requirements.md 由 specify 和 clarify 維護；自定義清單歸審閱者，implement 只會在未勾選時停下來問你，不會替你打勾。

短路徑適合邊界已經清楚的小功能：specify、plan、tasks、implement、converge。完整路徑適合要上線的功能：constitution（專案裡做一次）之後走 specify、clarify、plan、checklist、tasks、analyze、implement、converge。修缺陷走官方的 bug-fixing 快速入門，判斷點子值不值得做走 idea assessment。兩條都不是這條 SDD 路徑的前置步驟。

Windows、macOS、Linux 分別怎麼安裝

共同前提是 Python 3.11 或更高、Git 可選（只有啟用 git 擴充套件時才需要）、以及你真正會用來寫程式碼的那個 Agent。推薦用 uv 做持久安裝。終端裡只跑 CLI；斜槓技能在 Agent 聊天裡呼叫。

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv tool install specify-cli
specify version
specify self check
specify init deskboard --integration cursor-agent --script ps

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install specify-cli
specify version
specify self check
specify init deskboard --integration cursor-agent --script sh

裝完先看兩件事。specify version 只證明這條命令能跑、並列印版本，不能證明它來自 PyPI 還是 GitHub。specify self check 只讀，告訴你有沒有更新，不會改安裝。文件裡的示例標籤寫成 v0.12.11 這種帶 v 的釋出號；要從原始碼釘死某一版，用 uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z，v 不要去掉。PyPI 釘版則是 uv tool install specify-cli==X.Y.Z。升級必須用當初那一個工具：uv tool install --force specify-cli、pipx install --force specify-cli 或 pip install --upgrade specify-cli。

已經有程式碼的倉庫不要在髒工作區上初始化。先提交或備份，再執行 specify init --here --force --non-interactive --integration claude。--force 只表示你知道模板會並進現有檔案。沒有鍵盤的 CI 要加 --non-interactive，否則初始化會停在方向鍵選單；Agent 裝在另一臺機器上時再加 --ignore-agent-tools，跳過本機的可執行檔案檢查。非互動預設整合是 Copilot，除非你寫明別的 --integration。

整合鍵不要猜。Cursor 是 cursor-agent，不是 cursor。常見還有 claude、copilot、gemini、pi、omp、codebuddy。互動終端不傳 --integration 時會讓你選；指令碼和管道必須顯式傳入。

九步命令：入口、能改什麼、留給誰

下面這張表用同一套列。真正的差異在入口和執行邊界，不在模型名字。

按場景選短路徑還是完整路徑

實操用一個只在本機跑的便籤看板，不上傳、第一期不做密碼。三位預設成員，專案下四列：待辦、進行中、待確認、完成。拖拽改列。評論只能改自己寫的。specify 階段只說這些行為和原因。plan 階段再寫「本地 SQLite，前端不用遠端介面」。把資料庫寫進 specify，等於讓第一份技術直覺變成不可挑戰的需求。

推薦組合：Agent、指令碼型別、隔離環境

如果你已經在 Cursor 裡寫這個倉庫，就用 cursor-agent 加本機系統的指令碼型別：Windows 用 ps，macOS 和 Linux 用 sh。初始化之後在聊天裡按短路徑或完整路徑逐條呼叫，每條看完製品再下一條。不要把九個命令粘成一條提示詞。

如果你主要用 Claude Code，整合鍵用 claude。技能很多、描述擠佔上下文時，初始化加上 --integration-options="--no-model-invocation"，核心命令只在你輸入 /speckit-specify 時跑。Copilot 使用者保持預設技能佈局即可；只有要舊的 agent 檔案時才加 --commands。

implement 會改檔案並執行命令。第一輪不要在存著生產金鑰的筆記本上做。把倉庫放到遠端 Mac，看清 diff 再合回。節點怎麼訂，見 Mac mini 租用；預算見 套餐定價。規格里如果包含 macOS 構建或簽名，把那一段任務放到真機節點，並用 OpenClaw 雲端自動化 把構建和日常筆記本分開。安裝失敗先查 幫助中心 裡的連線和系統要求，再懷疑 Spec Kit 本身。

五條會讓後續全部返工的誤區

1. 在 specify 裡寫框架和資料庫。 技術棧屬於 plan。規格里出現「必須用某某庫」，後面的 clarify 和 analyze 都在替這個選擇圓場。
2. 在終端輸入 /speckit-specify。 斜槓技能只存在於 Agent 聊天。終端只跑 specify 本身。
3. 把文件點號命令貼進 Cursor。 Cursor 裡的技能是 /speckit-specify。點號形式是參考記法。
4. uv 和 pipx 各裝一份。 舊的 0.1.x 會報 No such option: --integration，或在 --ai 上報 No matching release asset found。先 which specify，再決定刪哪一份。
5. 用 git checkout 當功能切換器。 要改 .specify/feature.json，或設定 SPECIFY_FEATURE_DIRECTORY。只換分支，命令仍會改上一份規格的目錄。

七步落地

1. 安裝 uv 和 specify-cli，跑 specify version 與 specify self check，確認 PATH 上只有一個二進位制。
2. 按系統選 --script，按正在用的 Agent 選 --integration，執行 specify init。已有倉庫先提交，再加 --here --force。
3. 在 Agent 聊天裡執行一次 /speckit-constitution。只寫原則：輸入要校驗、評論只能改作者本人、第一期不上傳。
4. 用 /speckit-specify 寫便籤看板的行為和原因。要上線就接著 /speckit-clarify，把拖拽、許可權和空專案這三處問完。
5. 規格穩定後再 /speckit-plan。然後 checklist、tasks、analyze。analyze 報衝突就改源頭，不要在 implement 裡打補丁。
6. 在隔離的 Mac 或乾淨目錄執行 /speckit-implement。任務多就按階段，不要一次吞掉整個 tasks.md。
7. 跑 /speckit-converge，直到報告 Converged。然後看 diff：有沒有越出規格的檔案，有沒有把金鑰寫進倉庫。

常見問題

Spec Kit 和直接在 Cursor 裡聊天有什麼區別？

聊天記錄留在會話裡，換人、換機器就丟。Spec Kit 把原則、規格、計劃、任務寫成倉庫裡的 Markdown。當前功能由 .specify/feature.json 指向，不靠你記得上一次聊了什麼。

命令到底是 /speckit-specify 還是 /speckit.specify？

Cursor、Claude Code 和 GitHub Copilot 預設技能模式用連字元，在 Agent 聊天裡呼叫，不是在終端裡輸入。Codex 技能模式用 $speckit-specify。文件裡的點號寫法是參考記法，不要照抄進 Cursor。

Windows 必須先裝 WSL 嗎？

不必。2026 年的 Spec Kit 在 Windows 上預設使用 PowerShell。初始化時加 --script ps。macOS 和 Linux 預設是 bash，對應 --script sh。

uv 和 pipx 可以各裝一次嗎？

不要。兩套工具會留下兩個 specify。PATH 裡排在前面的舊版會讓 --integration 報錯，或出現 No matching release asset found。升級時用當初那一個工具加 --force 或 --upgrade。

git checkout 會切換當前功能嗎？

不會。當前功能看 .specify/feature.json，也可以用 SPECIFY_FEATURE_DIRECTORY 覆蓋。可選的 git 擴充套件會建編號分支，但只切換分支並不會改這份狀態。

先把命令裝對，再讓 Agent 改倉庫

Spec Kit 的價值不在多一個斜槓，而在把「先規格、再計劃、最後改檔案」寫成倉庫裡能複查的檔案。Windows 用 PowerShell，macOS 和 Linux 用 bash，Cursor 用 cursor-agent 和連字元技能。小功能走短路徑，要上線走完整路徑，implement 放在隔離節點上。下一步不是再收集提示詞，而是用 specify version 確認你面前這個二進位制就是你剛裝的那一個。

延伸閱讀

• 規範驅動開發完整指南：方法怎麼落地 →
• Agent Skills 怎麼裝、該裝哪些 →
• OpenClaw 雲端自動化與遠端 Mac →