Github Spec Kit

Github Spec Kit - 更快速的打造高品質軟體

▋什麼是規格驅動開發？

以規格驅動的開發（Spec-Driven Development） 顛覆了傳統軟體開發的腳本。數十年來，程式碼一直是王者——規格只是我們在開始「真正的工作」撰寫程式碼之前搭建然後丟棄的鷹架。以規格驅動的開發改變了這一點： 規格變得可執行 ，直接產生可運行的實作，而不僅僅是作為指引。

開始使用

核心理念

規格驅動開發是一個強調以下事項的結構化流程：

以意圖驅動的開發 ：先由規格定義「 做什麼 」，再決定「 怎麼做 」
豐富的規格撰寫 ：使用護欄與組織原則
多步驟精化 ：而非從提示一次性生成程式碼
高度依賴先進的 AI 模型能力來解讀規格

開發階段

階段	重點	主要活動
從 0 到 1 的開發（「綠地專案」）	從頭產生	由高階需求開始產生規格說明規劃實作步驟建立可上線的生產應用程式
創意探索	平行實作	探索多元解決方案支援多種技術棧與架構實驗不同使用者體驗模式
逐步增強（「既有系統」）	棕地現代化	逐步新增功能現代化舊有系統調整流程

實驗目標

我們的研究與實驗重點包括：

技術獨立性

使用多樣化的技術棧建立應用程式
驗證「規格驅動開發」是一個不綁定於特定技術、程式語言或框架的流程

企業約束

展示關鍵任務應用程式開發
納入組織限制（雲端提供者、技術棧、工程實務）
支援企業設計系統與合規性需求

以使用者為中心的開發

為不同使用者族群與偏好建置應用程式
支援各種開發方法（從 vibe-coding 到 AI 原生開發）

創意與反覆流程

驗證平行實作探索的概念
提供健全的反覆功能開發工作流程
擴展流程以處理升級與現代化任務

▋安裝指南

先決條件

Linux/macOS（或 Windows；現在也支援不使用 WSL 的 PowerShell 腳本）
AI 程式碼代理：Claude Code、GitHub Copilot 或 Gemini CLI
用於套件管理的 uv
Python 3.11+
Git

安裝

初始化一個新專案

開始的最簡單方式是「初始化一個新專案」或「在目前目錄中初始化」：

uvx --from git+https://github.com/github/spec-kit.git specify init .
# or use the --here flag
uvx --from git+https://github.com/github/spec-kit.git specify init --here

指定 AI 代理

你可以在初始化時主動指定你的 AI 代理人：

uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai claude
uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai gemini
uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai copilot

指定指令腳本類型（Shell 或 PowerShell）

所有自動化腳本現在同時提供 Bash（.sh）與 PowerShell（.ps1）版本。

自動行為：

Windows 預設：ps
其他作業系統預設：sh
互動模式：預設會顯示提示，除非你傳入 --script

強制指定腳本類型：

uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --script sh
uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --script ps

忽略代理工具檢查

如果你想在不檢查所需工具的情況下取得範本：

uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai claude --ignore-agent-tools

驗證

初始化後，你應該會在你的 AI 代理中看到下列可用指令：

/speckit.specify - 建立規格
/speckit.plan - 產生實作計畫
/speckit.tasks - 拆解為可執行的任務

.specify/scripts 目錄將包含 .sh 和 .ps1 腳本。

疑難排解

Git 憑證管理程式在 Linux 上

如果你在 Linux 上遇到 Git 認證問題，可以安裝 Git 憑證管理程式：

#!/usr/bin/env bash
set -e
echo "Downloading Git Credential Manager v2.6.1..."
wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
echo "Installing Git Credential Manager..."
sudo dpkg -i gcm-linux_amd64.2.6.1.deb
echo "Configuring Git to use GCM..."
git config --global credential.helper manager
echo "Cleaning up..."
rm gcm-linux_amd64.2.6.1.deb

▋快速上手指南

本指南將協助你使用 Spec Kit 開始實作規格驅動開發（Spec-Driven Development）。

最新：所有自動化腳本現在同時提供 Bash（.sh）與 PowerShell（.ps1）版本。除非你使用 --script sh|ps 指定，否則 specify CLI 會根據作業系統自動選擇。

四步驟流程

1. 安裝 Specify

根據你使用的程式碼代理（coding agent）來初始化你的專案：

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

明確選擇腳本類型（可選）：

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME> --script ps  # Force PowerShell
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME> --script sh  # Force POSIX shell

2. 建立 Spec

使用 /speckit.specify 指令來描述你想要建立的內容。專注於 要做什麼 和 為什麼 ，而不是技術棧。

/speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.

3. 建立技術實作計畫

使用 /speckit.plan 指令來提供你的技術棧與架構選擇。

/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.

4. 拆分並實作

使用 /speckit.tasks 來建立可執行的任務清單，然後請你的代理人實作該功能。

詳細範例：構建 Taskify

這裡是一個建立團隊生產力平台的完整範例：

步驟 1：使用 `/speckit.specify` 定義需求

Develop Taskify, a team productivity platform. It should allow users to create projects, add team members,
assign tasks, comment and move tasks between boards in Kanban style. In this initial phase for this feature,
let's call it "Create Taskify," let's have multiple users but the users will be declared ahead of time, predefined.
I want five users in two different categories, one product manager and four engineers. Let's create three
different sample projects. Let's have the standard Kanban columns for the status of each task, such as "To Do,"
"In Progress," "In Review," and "Done." There will be no login for this application as this is just the very
first testing thing to ensure that our basic features are set up. For each task in the UI for a task card,
you should be able to change the current status of the task between the different columns in the Kanban work board.
You should be able to leave an unlimited number of comments for a particular card. You should be able to, from that task
card, assign one of the valid users. When you first launch Taskify, it's going to give you a list of the five users to pick
from. There will be no password required. When you click on a user, you go into the main view, which displays the list of
projects. When you click on a project, you open the Kanban board for that project. You're going to see the columns.
You'll be able to drag and drop cards back and forth between different columns. You will see any cards that are
assigned to you, the currently logged in user, in a different color from all the other ones, so you can quickly
see yours. You can edit any comments that you make, but you can't edit comments that other people made. You can
delete any comments that you made, but you can't delete comments anybody else made.

步驟 2：完善規格

在初始規格建立後，釐清任何遺漏的需求：

For each sample project or project that you create there should be a variable number of tasks between 5 and 15
tasks for each one randomly distributed into different states of completion. Make sure that there's at least
one task in each stage of completion.

也要驗證規格檢查清單：

Read the review and acceptance checklist, and check off each item in the checklist if the feature spec meets the criteria. Leave it empty if it does not.

步驟 3：使用 `/speckit.plan` 產生技術計畫

請具體說明您的技術棧與技術需求：

We are going to generate this using .NET Aspire, using Postgres as the database. The frontend should use
Blazor server with drag-and-drop task boards, real-time updates. There should be a REST API created with a projects API,
tasks API, and a notifications API.

步驟 4：驗證並實作

讓你的 AI 代理審核實作計畫：

Now I want you to go and audit the implementation plan and the implementation detail files.
Read through it with an eye on determining whether or not there is a sequence of tasks that you need
to be doing that are obvious from reading this. Because I don't know if there's enough here.

最後，實作解決方案：

implement specs/002-create-taskify/plan.md

關鍵原則

明確說明你正在建構的內容以及原因
在規格階段不要只專注於技術堆疊
在實作前反覆迭代並精煉你的規格
在開始編碼前驗證該計畫
讓 AI 代理處理實作細節

下一步

閱讀完整方法論以獲得深入指引
在此儲存庫中查看更多範例
在 GitHub 上瀏覽原始程式碼

本地開發指南

本指南示範如何在本機對 specify CLI 進行迭代，而不需先發佈版本或提交到 main。

腳本現在同時提供 Bash（.sh）與 PowerShell（.ps1）版本。CLI 會依作業系統自動選擇，除非你傳入 --script sh|ps。

1. Clone 並切換分支

git clone https://github.com/github/spec-kit.git
cd spec-kit
# Work on a feature branch
git checkout -b your-feature-branch

2. 直接執行 CLI（回饋最迅速）

你可以透過模組進入點執行 CLI，而不需要安裝任何東西：

# From repo root
python -m src.specify_cli --help
python -m src.specify_cli init demo-project --ai claude --ignore-agent-tools --script sh

如果你偏好以腳本檔案方式呼叫（使用 shebang）：

python src/specify_cli/__init__.py init demo-project --script ps

3. 使用可編輯安裝（隔離環境）

使用 uv 建立一個獨立環境，讓相依性解析與最終使用者所看到的一模一樣：

# Create & activate virtual env (uv auto-manages .venv)
uv venv
source .venv/bin/activate  # or on Windows PowerShell: .venv\Scripts\Activate.ps1

# Install project in editable mode
uv pip install -e .

# Now 'specify' entrypoint is available
specify --help

在可編輯模式下，程式碼修改後重新執行不需要重新安裝。

4. 直接從 Git（目前分支）以 uvx 呼叫

uvx 可以從本機路徑（或 Git 參考）執行，以模擬使用者流程：

uvx --from . specify init demo-uvx --ai copilot --ignore-agent-tools --script sh

你也可以將 uvx 指向特定分支而不進行合併：

# Push your working branch first
git push origin your-feature-branch
uvx --from git+https://github.com/github/spec-kit.git@your-feature-branch specify init demo-branch-test --script ps

4a. 絕對路徑 uvx（可從任何位置執行）

如果你位於其他目錄，請改用絕對路徑而不是 .：

uvx --from /mnt/c/GitHub/spec-kit specify --help
uvx --from /mnt/c/GitHub/spec-kit specify init demo-anywhere --ai copilot --ignore-agent-tools --script sh

為方便起見，設定一個環境變數：

export SPEC_KIT_SRC=/mnt/c/GitHub/spec-kit
uvx --from "$SPEC_KIT_SRC" specify init demo-env --ai copilot --ignore-agent-tools --script ps

(可選) 定義一個 shell 函式：

specify-dev() { uvx --from /mnt/c/GitHub/spec-kit specify "$@"; }
# Then
specify-dev --help

5. 測試腳本權限邏輯

在執行 init 之後，檢查在 POSIX 系統上 shell 腳本是否具有可執行權限：

ls -l scripts | grep .sh
# Expect owner execute bit (e.g. -rwxr-xr-x)

在 Windows 上則改用 .ps1 腳本（不需要 chmod）。

6. 執行 Lint / 基本檢查（可自行新增）

目前未附帶強制執行的 lint 設定，但你可以快速檢查是否可被匯入：

python -c "import specify_cli; print('Import OK')"

7. 在本機建置 Wheel（可選）

在發佈前驗證封裝：

uv build
ls dist/

如有需要，將已建置的產物安裝到全新的臨時環境中。

8. 使用暫存工作區

在髒亂的目錄中測試 init --here 時，建立一個臨時工作區：

mkdir /tmp/spec-test && cd /tmp/spec-test
python -m src.specify_cli init --here --ai claude --ignore-agent-tools --script sh  # if repo copied here

或者如果想要一個較輕量的沙盒，可以只複製已修改的 CLI 部分。

9. 偵錯網路 / TLS 跳過

如果在試驗過程中需要繞過 TLS 驗證：

specify check --skip-tls
specify init demo --skip-tls --ai gemini --ignore-agent-tools --script ps

（僅用於本地實驗。）

10. 快速編輯循環摘要

動作	指令
直接執行 CLI	`python -m src.specify_cli --help`
可編輯安裝	`uv pip install -e .` 然後 `specify ...`
本機 uvx 執行（倉庫根目錄）	`uvx --from . specify ...`
本機 uvx 執行（絕對路徑）	`uvx --from /mnt/c/GitHub/spec-kit specify ...`
Git 分支 uvx	`uvx --from git+URL@branch specify ...`
建立 wheel	`uv build`

11. 清理

快速移除建置產物 / 虛擬環境：

rm -rf .venv dist build *.egg-info

12. 常見問題

症狀	修復
`ModuleNotFoundError: typer`	執行 `uv pip install -e .`
腳本無法執行（Linux）	重新執行 init 或 `chmod +x scripts/*.sh`
已跳過 Git 步驟	您傳入了 `--no-git` 或系統未安裝 Git
下載了錯誤的腳本類型	請明確傳入 `--script sh` 或 `--script ps`
企業網路上的 TLS 錯誤	嘗試使用 `--skip-tls`（非生產環境用）

13. 下一步

更新文件，並使用你修改過的 CLI 跑一遍快速上手教程
在滿意時開立拉取請求（PR）
（可選）在變更合併到 main 後標記釋出版本

Github Spec Kit

BMAD