安裝與設定｜Spec Kit 教學

前置需求

在安裝 Specify CLI 之前，請確認本機環境已符合以下所有條件。Specify CLI 以 Python 編寫，並以 uv 作為推薦的套件管理與執行工具。

Python 3.11 以上版本（建議使用 3.12）
uv 0.4.0 以上版本
Git（用於從 GitHub 安裝或更新）
網路可連線至 github.com（離線環境請見下方企業內網章節）

確認 Python 版本：

python3 --version
# 期望輸出：Python 3.12.x

安裝 uv

uv 是由 Astral 開發的新世代 Python 套件管理工具，比傳統 pip 快上數十倍，並內建虛擬環境與工具隔離機制。推薦以官方腳本一鍵安裝：

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows（PowerShell）
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

安裝完成後，重新載入終端機 Shell，再執行以下命令確認版本：

uv --version
# 期望輸出：uv 0.4.x (或更新版本)

提示：若使用 Homebrew，也可執行 brew install uv 完成安裝，但建議優先使用官方腳本以取得最新版本。

uv 持久安裝詳解

「持久安裝」是指將 Specify CLI 安裝為系統層級的可執行工具，安裝後可在任意目錄直接呼叫 specify 命令，無需每次指定完整路徑或重新下載。

uv tool install specify-cli \
  --from "git+https://github.com/github/spec-kit.git@v1.2.0"

uv tool install 會在隔離的虛擬環境中安裝套件，並將可執行檔連結至 uv 的工具目錄（通常為 ~/.local/bin）。請確認該路徑已加入系統 $PATH。

注意：@v1.2.0 為版本標籤，務必替換為團隊決定採用的實際版本號。不指定版本標籤將拉取最新 commit，可能在團隊間產生不一致的行為。

安裝成功後，執行以下命令驗證可執行檔是否已正確加入路徑：

which specify
# 期望輸出：/Users/yourname/.local/bin/specify

specify --version
# 期望輸出：specify-cli 1.2.0

uvx 一次性使用場景

uvx 是 uv 提供的臨時執行機制。執行時自動建立隔離環境、安裝套件、執行命令，結束後不留下任何全域安裝痕跡。適合以下場景：

CI/CD 管線中每次都需要乾淨環境的情境
只想試用 Specify CLI 而不想污染全域環境
在不同專案中需要使用不同版本的情境
無管理員權限的受限環境

# 初始化新專案（一次性）
uvx --from "git+https://github.com/github/spec-kit.git@v1.2.0" \
  specify init . --ai claude

# 驗證安裝（一次性）
uvx --from "git+https://github.com/github/spec-kit.git@v1.2.0" \
  specify check

CI/CD 推薦：在 GitHub Actions 或 GitLab CI 中，建議永遠使用 uvx 並固定版本標籤，避免因隱式升級導致管線行為改變。

版本鎖定的重要性

Specify CLI 的命令模板、腳本與輸出格式會隨版本演進而變動。若團隊成員使用不同版本，將造成以下問題：

生成的 .specify/ 目錄結構不一致，導致 Git merge 衝突
AI Agent 讀取的 prompt 模板不同，輸出品質參差不齊
CI/CD 管線執行與本地開發結果不同，難以重現問題

建議在專案根目錄建立 .specify-version 或在 README.md 中記錄採用的版本號，並在 onboarding 文件中明確要求所有成員使用相同版本。

最佳實踐：將版本號寫入 Makefile 或 CI 設定檔的環境變數中，例如 SPECIFY_VERSION=v1.2.0，統一由此變數控制所有安裝與執行指令。

specify init 詳解

specify init 是安裝後的第一道命令，用於在專案目錄中建立 Spec Kit 所需的完整目錄結構與初始模板檔案。

specify init . --ai claude

執行後會在當前目錄生成以下結構：

.specify/
├── init-options.json          # 記錄初始化參數（AI 提供者等）
├── memory/
│   └── constitution.md        # 專案 AI 行為守則（可自訂）
├── scripts/
│   ├── powershell/            # Windows PowerShell 腳本
│   │   ├── common.ps1
│   │   ├── create-new-feature.ps1
│   │   └── setup-plan.ps1
│   └── bash/                  # macOS / Linux Bash 腳本
│       ├── common.sh
│       ├── create-new-feature.sh
│       └── setup-plan.sh
└── templates/
    ├── spec-template.md        # Spec 撰寫模板
    ├── plan-template.md        # 實作規劃模板
    ├── tasks-template.md       # 任務清單模板
    └── checklist-template.md  # 驗收檢查清單模板

--ai claude 參數指定使用 Claude 作為 AI 提供者，模板內容將針對 Claude 的 prompt 格式最佳化。目前支援的值包括 claude、cursor、copilot。

重要：初始化完成後，建議立即將 .specify/ 目錄提交至 Git，讓整個團隊共享相同的模板與設定基準。

升級方式（--force）

當有新版本發布，或需要切換至特定版本時，使用 --force 旗標強制覆蓋現有安裝：

uv tool install specify-cli --force \
  --from "git+https://github.com/github/spec-kit.git@v1.3.0"

升級後務必驗證版本：

specify --version

注意：升級 CLI 本身不會自動更新專案目錄內的模板檔案。若模板也需同步更新，請接著執行下方的「更新既有專案模板」步驟。

更新既有專案模板（--here --force）

當 Specify CLI 升級後，新版本可能帶來改良的 AI prompt 模板或腳本。使用以下命令將現有專案的 .specify/ 目錄更新至新版模板：

specify init --here --force --ai claude

--here：在當前目錄執行，不建立子目錄
--force：強制覆寫現有的模板與腳本檔案
你的 specs/ 目錄及所有 Spec 內容不會被覆蓋
constitution.md 等自訂記憶檔案亦不受影響

建議流程：每次升級 CLI 版本後，都應執行此命令並將更新後的模板檔案一併提交至 Git，確保團隊所有成員取得一致的新版模板。

企業內網離線安裝步驟

若所在環境無法直接連線至 github.com（如金融、政府或高安全性企業內網），可採用以下離線安裝流程：

步驟一：在可連網機器下載 wheel 套件

# 在可連網機器上執行
pip download specify-cli \
  --no-deps \
  --dest ./offline-packages \
  --index-url https://pypi.org/simple/

# 或從 GitHub 下載 release tarball
curl -L https://github.com/github/spec-kit/archive/refs/tags/v1.2.0.tar.gz \
  -o specify-cli-v1.2.0.tar.gz

步驟二：將套件傳入內網（使用 USB、SCP 或內部檔案伺服器）

步驟三：在內網機器上安裝

# 從本地 tarball 安裝
uv tool install specify-cli \
  --from "./specify-cli-v1.2.0.tar.gz"

# 或從本地目錄安裝
uv tool install specify-cli \
  --from "./offline-packages/specify_cli-1.2.0-py3-none-any.whl"

企業 Proxy：若環境使用 HTTP Proxy，可設定環境變數 HTTPS_PROXY=http://proxy.corp.example.com:8080 後再執行安裝命令，uv 會自動遵循此設定。

驗證安裝成功（specify check 輸出說明）

安裝完成後，在任意已初始化的專案目錄中執行：

specify check

成功時的輸出範例如下：

✔ specify-cli v1.2.0 installed
✔ Python 3.12.3 detected
✔ .specify/ directory found
✔ constitution.md present
✔ All templates up to date
✔ Scripts executable (bash + powershell)

Ready. Run `specify --help` to see available commands.

各行輸出的含義：

specify-cli vX.Y.Z installed：CLI 可執行檔版本確認
Python 3.x.x detected：確認 Python 版本符合最低需求
.specify/ directory found：當前目錄已完成 init
All templates up to date：模板版本與 CLI 版本相符
Scripts executable：腳本檔案具備執行權限

若出現警告：輸出中以 ⚠ 開頭的行表示可選項目未設定；以 ✘ 開頭的行表示必要項目缺失，需立即修復後方可正常使用。

常見問題

Q1：執行 specify 時出現「command not found」

這是因為 uv 的工具目錄尚未加入 $PATH。請將以下行加入 ~/.bashrc 或 ~/.zshrc：

export PATH="$HOME/.local/bin:$PATH"

儲存後執行 source ~/.zshrc（或重新開啟終端機）再試一次。

Q2：安裝後 specify --version 顯示舊版本

Shell 可能快取了舊路徑。執行以下命令清除快取後重試：

hash -r        # bash
rehash         # zsh

若仍顯示舊版本，確認 which specify 指向的路徑是否為 uv 管理的工具目錄，而非其他來源安裝的舊版本。

Q3：升級後執行 specify check 出現「templates out of date」警告

升級 CLI 後未同步更新專案模板。執行以下命令即可解決：

specify init --here --force --ai claude

Q4：Windows 上 PowerShell 腳本無法執行

Windows 預設的執行原則（Execution Policy）可能阻擋未簽署的腳本。以系統管理員身份開啟 PowerShell，執行：

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

說明：RemoteSigned 允許執行本機建立的腳本，僅對從網路下載的腳本要求簽署，是企業環境中較為安全的設定。

Q5：在 CI/CD 中使用 uvx 時，每次都重新下載很慢

可利用 CI 平台的快取機制，快取 uv 的工具快取目錄：

# GitHub Actions 範例
- uses: actions/cache@v4
  with:
    path: ~/.cache/uv
    key: uv-${{ runner.os }}-specify-v1.2.0

快取建立後，後續管線執行時 uvx 會直接使用快取的套件，大幅縮短安裝時間。