Spec Kit 安裝教學:正確安裝 specify-cli 與 /speckit-* 指令變化

Spec Kit 是 GitHub 開源的規格驅動開發（Spec-Driven Development）工具包：先寫規格，再產出計畫和任務，最後讓 AI 程式設計助理依任務實作。它的命令列叫 specify，由 specify-cli 套件提供。

網路上很多教學還在用舊的安裝指令、--ai 參數和 /speckit.specify 這類指令名稱，照抄經常出錯。本文依官方文件整理目前的正確做法，並列出哪些東西變過。

核對時間

內容對照 Spec Kit 官方文件整理，核對日期 2026-10-26。這個專案版本更新很快，指令以你本機 specify --help 和官方文件為準。

適合誰

想在現有 AI 程式設計助理（Claude Code、GitHub Copilot、Gemini CLI、CodeBuddy CLI、Pi、Oh My Pi 等）裡試用規格驅動流程的人。
之前依舊教學裝過 Spec Kit，現在指令出錯或找不到的人。

前置條件

項目	要求
系統	Linux、macOS 或 Windows（PowerShell 腳本可用，不需要 WSL）
Python	3.11 或更高
套件管理器	uv（建議）或 pipx
AI 程式設計助理	任意一個受支援的助理，官方文件列出數十個整合
Git	選用，只有啟用 git 擴充功能時才需要

Spec Kit 本身不依賴 Node.js。如果你的助理是透過 npm 安裝的，請先看 AI Agent CLI 安裝。

安裝 specify-cli

方式一：從 PyPI 安裝（最短）

# 建議：uv
uv tool install specify-cli

# 或 pipx
pipx install specify-cli

# 或 pip
pip install specify-cli

固定版本：uv tool install specify-cli==0.12.11（把版本號換成發布頁上的版本）。

方式二：從 GitHub 發布標籤安裝

官方文件把它列為建議的可重現方式，需要先裝好 uv：

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

vX.Y.Z 換成 Releases 裡的標籤，開頭的 v 不能省，例如 v0.12.11。

驗證安裝

specify version
specify self check

specify version 確認指令可用並顯示版本；specify self check 為唯讀，會告訴你有沒有更新的發布版本。

初始化專案

specify init my-project --integration claude
cd my-project

--integration 用來選擇你的 AI 助理，常用值有 claude、copilot、gemini、codebuddy、pi、omp。幾個常用選項：

--script sh|ps|py：選擇腳本類型。Windows 預設 ps，其他系統預設 sh。
--here --force：在已有的非空目錄裡初始化。--force 表示你已知悉合併警告，請先提交或備份本機變更。
--non-interactive：用於 CI。不傳 --integration 時預設選 GitHub Copilot，別被這個預設值坑到。

指令名稱：`/speckit-*`

初始化後，在 AI 助理的聊天框裡依序執行這些指令，不是在終端機裡：

步驟	指令	作用
1	`/speckit-constitution`	撰寫專案原則，後續步驟會據此檢查，每個專案一次
2	`/speckit-specify`	用自然語言描述要做的功能，產生 `spec.md`
3	`/speckit-clarify`	針對規格裡的空白提問，並把答案補回規格
4	`/speckit-plan`	依你的技術堆疊產生 `plan.md` 等設計產物
5	`/speckit-checklist`	產生需求品質檢查清單
6	`/speckit-tasks`	產生依相依關係排序的 `tasks.md`
7	`/speckit-analyze`	唯讀，檢查 `spec.md`、`plan.md`、`tasks.md` 之間的衝突和遺漏
8	`/speckit-implement`	依 `tasks.md` 逐項實作
9	`/speckit-converge`	對照規格檢查程式碼，缺口會追加成新任務；重複 implement 與 converge，直到回報 `Converged`

最短路徑是 specify → plan → tasks → implement → converge，完整路徑才包含 constitution、clarify、checklist 和 analyze。

你的助理裡可能叫法不同

官方快速開始裡的名稱是帶連字號的 /speckit-*（GitHub Copilot 的預設技能模式）。較早的教學和升級文件裡還能看到 /speckit.specify 這種點號寫法。不同助理、不同模式的呼叫格式不一樣，請以初始化後助理指令清單中實際出現的名稱為準。

和舊教學相比，變了什麼

舊教學裡常見的做法	現在
只能 `uv tool install ... --from git+https://...`	新增了 PyPI 的 `specify-cli`，uv、pipx、pip 都能裝；GitHub 標籤安裝仍受支援
`specify init --ai claude`	官方文件全部使用 `--integration claude`
`/speckit.specify`、`/speckit.plan`	快速開始使用 `/speckit-specify`、`/speckit-plan`，並新增 `/speckit-converge`
`/constitution` 會同步修改範本和指令檔	現在只更新 `.specify/memory/constitution.md`；要恢復舊的同步行為，執行 `specify preset add constitution-sync`
git 功能預設開啟	現在是選用擴充功能，需要時執行 `specify extension add git`
依 Git 分支判斷目前功能	現在用 `.specify/feature.json` 記錄目前功能目錄

升級

升級命令列本身：

specify self check                 # 唯讀，檢查有沒有新版
specify self upgrade --dry-run     # 預覽，不真正升級
specify self upgrade               # 升級到最新穩定版
specify self upgrade --tag vX.Y.Z  # 固定到某個標籤

升級既有專案裡的檔案，請在專案目錄內執行：

specify integration status         # 查看已安裝的整合和被改動過的檔案
specify integration upgrade <key>  # 每個已安裝的整合各執行一次
specify extension update           # 更新所有擴充功能

只有在指令提示有本機改動的受管理檔案，且你確認過差異之後，才對 specify integration upgrade 加上 --force。

常見問題

command not found: uv：先安裝 uv，再重新執行安裝指令。
No such option: --integration：你的機器上還有一份很舊的 specify（例如 0.1.6），排在 PATH 前面。用安裝時的同一個工具重新安裝，例如 uv tool install --force specify-cli，再用 specify version 確認。
裝了兩份：uv、pipx、pip 各裝一次會留下多個副本。用同一個工具升級，不要混用。
PyPI 安裝不會自動升級：裝好後版本就固定了，需要用上面的升級指令更新。
在既有目錄裡初始化被拒絕：確認目錄已提交或備份後，加上 --here --force。