GitHub Spec Kit：讓規格文檔成為軟件的第一公民

作者：Ranger Ramblings
日期：2026年4月29日 上午8:15
來源：WeChat 原文

✦整理版優先睇

速讀 5 個重點 高亮

GitHub Spec Kit 將規格文檔變成軟件第一公民，透過七步結構化流程解決 AI 編程嘅意圖漂移同文檔脱節問題

整理版摘要

呢篇文章係關於 GitHub 官方開源嘅 Spec Kit 工具集，核心理念係規格驅動開發（SDD），即係將規格文檔當成軟件嘅第一公民，代碼只係規格嘅「輸出」。作者整理咗官方文檔同實際使用經驗，想幫開發者理解 SDD 點樣解決傳統 AI 輔助編程嘅問題，例如意圖漂移、規格同代碼脱節、變更成本高等等。整體結論係：SDD 適合需求頻繁變更嘅大型項目，透過 constitution → spec → plan → tasks → implement 嘅結構化流程，令 AI 喺「軌道」上執行；但佢唔係萬能，對小項目或探索性原型反而會增加文檔維護負擔。

Spec Kit 透過一個叫 specify 嘅 CLI 工具同埋 AI 編程助手嘅 Slash 命令嚟實現 SDD。工作流程分七步：初始化項目、建立治理原則（Constitution）、生成規格文檔（Spec）、澄清模糊點（Clarify）、制訂技術計劃（Plan）、拆解任務（Tasks）、執行實現（Implement）。每一步都有對應嘅 /speckit.* 命令，例如 /speckit.constitution 建立項目「憲法」，/speckit.specify 只描述做咩唔講點做，/speckit.plan 先引入技術棧。呢個流程確保需求可以追溯、變更可以重生成，但代價係要維護 spec、plan、tasks 同 code 四份資產，需求變更時要改 3-4 步。

文章仲…

  • SDD 將代碼維護成本轉換為規格維護成本，需求變更時需更新 spec、plan、tasks 三層文檔，再重新生成代碼。
  • 核心工作流程分七步：init → constitution → specify → clarify → plan → tasks → implement，每一步有對應 Slash 命令。
  • 與傳統 Vibe Coding 最大差異在於起點係寫規格而非直接 prompt，文檔始終係源頭，代碼可追溯。
  • SDD 適合需求頻繁變更嘅大型項目同多人協作團隊，但不適用於探索性原型、需求未定或極簡任務。
  • 實際使用時要注意文檔維護税、AI 理解偏差同流程剛性，建議小團隊從 TinySpec 或只保留 spec.md 開始。
值得記低
連結 github.github.io

Spec Kit 官方文檔站

包含完整嘅 SDD 方法論、CLI 參考同安裝指南。

開啟
連結 github.com

GitHub Spec Kit 倉庫

源碼同最新更新，MIT 開源授權，已獲得 91k+ Stars。

開啟
結構示例

內容片段

內容片段 text 
specify init → /speckit.constitution → /speckit.specify → /speckit.clarify                                                                    ↓                                            /speckit.plan → /speckit.analyze                                                                    ↓                                                        /speckit.tasks                                                                    ↓                                                        /speckit.implement
整理重點

傳統 Vibe Coding 嘅缺失同 SDD 嘅回應

傳統 AI 輔助編程（即係 Vibe Coding）存在幾個死症：AI 一次過生成代碼之後，實際實現同原始需求越走越遠，呢個叫 意圖漂移；PRD 寫完就掉喺一邊，代碼同文檔長期唔同步；需求一變就要人手改 code，冇系統化嘅再生成機制；AI 自己揀技術方案，搞出好多不必要嘅抽象同複雜度；最慘係揾唔返點解要咁設計，成條鏈斷曬。

Spec Kit 嘅解法係：喺 AI 開始寫 code 之前，用結構化流程強制生成 規格（Spec）、實現計劃（Plan）同 任務清單（Tasks），等 AI 喺「軌道」上執行，而唔係隨意發揮。呢套思路叫做規格驅動開發（SDD）。

整理重點

七步結構化工作流程

Spec Kit 提供一個叫 specify 嘅 CLI 工具，配合 AI 助手嘅 Slash 命令，實行完整嘅 SDD 流程。首先用 specify init 初始化項目，然後 AI 助手就會有多條 /speckit.* 命令可用。

  1. 1 /speckit.constitution：建立項目治理原則，即係「憲法」，規範 code quality、測試標準、UX 一致性等，後續所有步驟都要跟足。
  2. 2 /speckit.specify：從需求描述生成結構化規格文檔，淨係講「做咩」同「點解」，唔好提技術棧。
  3. 3 /speckit.clarify：AI 出問卷幫你釐清規格入面嘅模糊位，答案會寫入 spec 嘅 Clarifications 節，一定要喺 plan 之前做。
  4. 4 /speckit.plan：先引入技術棧，生成實現計劃、技術調研、數據模型、API 契約等文檔。
  5. 5 /speckit.tasks：將計劃拆解為可執行任務，包含依賴關係、並行標記同 TDD 結構。
  6. 6 /speckit.implement：按任務清單順序執行實現，遵守 TDD，前置條件全部驗證先開始寫 code。

成個流程嘅精髓係「先規格後技術」，用 /speckit.clarify 減少理解偏差，任務清單確保每一行 code 都有源頭。

整理重點

咩時候用、咩時候唔好用

最佳適用場景包括全新項目（Greenfield）、迭代功能開發（Brownfield）、企業合規項目、多人協作團隊、需要頻繁變更需求嘅項目，同埋想用同一規格對比唔同技術棧嘅探索。呢啲情況下，SDD 嘅追溯性同可重生成能力係好大優勢。

不過，對於一次性腳本、極簡任務、純探索性 Prototype、需求極穩定嘅項目或者單人小項目（<500行 code），SDD 就太重手，文檔可能仲多過 code。文章仲特別提到唔建議用 SDD 嘅情況：需求本身仲喺探索階段、技術方案極度不確定，或者團隊已經有完整 PRD + 設計文檔，再多一層 spec/plan/tasks 只係重複。

  • 全新項目：完整走七步，產出高質量 code 同文檔。
  • 探索性原型：可用 /speckit.clarify skip 跳過澄清，或直接用 TinySpec 擴展。
  • 需求極穩定：傳統開發更化算，SDD 嘅多層維護成本 > 收益。
  • 小專案：建議只保留 spec.md + implement，唔好硬行曬成個流程。
整理重點

侷限性與真正成本

再靚嘅工具都有盲點。文章誠實咁點出五個需要正視嘅問題：第一，文檔維護税——原本得 code 一份資產，而家變咗 spec、plan、tasks、code 四份，需求變更要改 3-4 步，唔係 1 步。第二，反過度工程嘅矛盾——Constitution 話要簡潔，但七步流程本身對簡單項目就係 over-engineering。

  1. 1 缺乏真實落地數據</highlight>——官方冇提供缺陷率、交付速度等量化指標，Star 數（91k+）有 GitHub 官方加成，唔等於生產驗證。
  2. 2 AI 對規格嘅理解偏差</highlight>——clarify 過程本身都係 AI 驅動，可能引入新嘅偏差。
  3. 3 流程剛性 vs 開發靈活性</highlight>——七步假設需求可以預先確定，但好多開發場景需要邊做邊發現，硬套 SDD 會變咗喺沙上建城堡。
整理重點

擴展生態同對比傳統 Vibe Coding

Spec Kit 支持擴展（Extensions）同預設（Presets）嚟高度定製。擴展用嚟添加新命令或工作流，例如 spec-kit-jira 自動同步任務到 Jira、spec-kit-sync 檢測規格同 code 嘅漂移。預設用嚟調整模板格式，例如適應 Agile 或 Kanban。優先級係：項目本地覆蓋 > Presets > Extensions > 核心默認。

對比傳統 Vibe Coding，SDD 嘅起點係先寫規格再生成 code，文檔始終係源頭，需求變更時只需更新規格然後重新生成，唔使人手改 code。可追溯性極高，每行 code 都可以溯源到具體需求。團隊協作方面，Constitution 統一標準，避免各自為戰。不過上手成本較高，要學 CLI 同七條 Slash 命令，對於簡單任務嚟講性價比唔高。

  • 起點：Vibe Coding 直接 prompt AI 寫 code；SDD 先寫規格，再生成 code。
  • 文檔：Vibe Coding 事後補寫易過時；SDD 規格即文檔，始終係源頭。
  • 需求變更：Vibe Coding 要人工改 code；SDD 更新規格 → 重新生成。
  • 可追溯性：Vibe Coding 幾乎冇；SDD 每行 code 溯源到具體需求。
  • 團隊協作：Vibe Coding 各自為戰；SDD 用 Constitution 統一標準。
  • 質量保障：Vibe Coding 依賴 review；SDD 內置 TDD 同驗收清單。
  • 文檔維護：Vibe Coding 得一份文檔（如果有的話）；SDD 要維護 spec + plan + tasks 三層。
  • 上手成本：Vibe Coding 低，一張嘴就得；SDD 高，要學 CLI 加七條命令。

 

項目簡介

Spec Kit 係由 GitHub 官方開源嘅一套 規格驅動開發（Spec-Driven Development，SDD）工具集，佢嘅核心諗法係：

令規格文件成為軟件嘅第一公民，代碼係規格嘅「輸出」而唔係目的本身。

佢透過一個叫 specify 嘅 CLI 工具 + 一套 AI 編程助手嘅 Slash 命令，幫開發者同 AI 協作寫嘢嗰陣，將需求 → 規格 → 計劃 → 任務 → 實現嘅成個流程結構化、可追溯、可重複。

解決啲咩問題？

傳統 AI 輔助寫程式（俗稱「Vibe Coding」）有好大嘅缺陷：

問題
表現
意圖飄移
AI 一次過生成代碼，但實際做出嚟同原本需求嘅偏差越嚟越大
規格即廢紙
PRD/需求文件寫完就掉低，代碼同文件長期唔同步
更改成本高
需求一變就要人手重寫代碼，冇系統化嘅再造機制
過度工程
AI 自己決定技術方案，帶嚟冇必要嘅抽象同複雜度
無法追溯
點解要咁設計？揾唔到由需求到代碼嘅完整鏈
協作混亂
團隊入面每個人用 AI 嘅方法唔同，出嚟嘅風格同質素參差

Spec Kit 嘅解法：喺 AI 寫程式之前，用結構化嘅流程強制生成 spec（規格）、plan（實現計劃）、tasks（任務清單），令 AI 喺「軌道」上面執行，而唔係隨意發揮。

核心諗法：規格驅動開發（SDD）

SDD 嘅核心權力倒置：

傳統開發：  需求文檔 → [寫代碼] → 代碼是真正的"產品"
SDD：       規格文檔 → [AI 生成代碼] → 規格才是真正的"產品"
  • • 規格（Spec） = 意圖嘅表達，描述「做啲咩」同「點解」
  • • 計劃（Plan） = 技術實現策略，描述「點樣做」
  • • 任務（Tasks） = 原子化嘅可執行步驟
  • • 代碼 = 以上三者嘅「編譯輸出」，可以重新生成

當需求變更嗰陣，只需要更新規格，重新生成計劃同任務，AI 再次實現。咁樣令需求變更由「噩夢」變成「例行公事」。

誠實一刻：SDD 將「代碼維護成本」轉換成「規格維護成本」——spec / plan / tasks 三層文件本身都係要持續維護嘅資產。改一個需求代表至少要改 3 個檔案，再行 2 次重新生成。對於需求穩定嘅細 project，呢套流程嘅維護 overhead 可能仲高過直接改代碼。呢個唔係否定 SDD，而係提醒：佢解決嘅問題（需求成日變嘅大型 project）同佢引入嘅成本（多層文件維護）需要放埋一齊衡量。

工作流程總覽

specify init → /speckit.constitution → /speckit.specify → /speckit.clarify
                                                                    ↓
                                            /speckit.plan → /speckit.analyze
                                                                    ↓
                                                        /speckit.tasks
                                                                    ↓
                                                        /speckit.implement

安裝同環境要求

前置條件

  • • 操作系統：Linux / macOS / Windows
  • • Python 3.11 或以上
  • • Git
  • • 套件管理工具：建議用 uv[1] 或者 pipx[2]
  • • AI 編程助手：支援超過 30 款，包括 Claude Code、GitHub Copilot、Gemini CLI、Cursor、Codex CLI 等

安裝 Specify CLI

方法一：永久安裝（建議）

# 安裝指定穩定版本（推薦，將 vX.Y.Z 替換為最新 tag）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

# 或安裝最新 main 分支（可能包含未發佈的變更）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 使用 pipx 也可以
pipx install git+https://github.com/github/spec-kit.git@vX.Y.Z

確認已安裝：

specify version

方法二：一次性執行（唔使安裝）

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

方法三：企業/離線環境

請參閲官方企業安裝指南[3]。

升級

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

點樣用：完整七步工作流程

第 0 步：初始化項目

# 新建項目
specify init <PROJECT_NAME>

# 或在現有項目目錄初始化
specify init . --integration copilot
# 也可以用 --here flag
specify init --here --integration copilot

# 強制在非空目錄初始化
specify init . --force --integration copilot

初始化之後，你嘅 AI 編程助手就會有以下 Slash 命令：

命令
功能
/speckit.constitution
建立/更新項目治理原則
/speckit.specify
由需求描述生成結構化規格文件
/speckit.clarify
釐清規格入面嘅模糊位（計劃前必做）
/speckit.plan
生成技術實現計劃
/speckit.analyze
跨文件一致性分析
/speckit.tasks
將計劃拆解成可執行任務
/speckit.implement
按任務清單執行實現
/speckit.checklist
生成品質檢查清單

第 1 步：建立項目治理原則（Constitution）

/speckit.constitution Create principles focused on code quality, testing standards,
user experience consistency, and performance requirements.

呢個會建立 .specify/memory/constitution.md，作為成個項目 AI 行為嘅「憲法」，之後嘅所有步驟都會跟呢份原則。

憲法嘅九大條款（內置預設值）：

  • • Article I：庫優先原則（每個功能先作為獨立庫實現）
  • • Article II：CLI 接口強制（所有庫必須有 CLI 接口）
  • • Article III：測試優先（唔寫測試就唔準實現）
  • • Articles VII & VIII：簡潔性 + 反對過度抽象
  • • Article IX：集成優先測試（用真實環境測試，唔用 Mock）

第 2 步：建立規格文件（Spec）

重點：描述「做啲咩」同「點解」，唔好涉及技術棧。

/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. Allow users to add descriptions and tags to albums.

執行之後會自動完成：

  • • 建立語義化分支（例如 001-photo-album-app）
  • • 生成 .specify/specs/001-photo-album-app/spec.md
  • • 包含用戶故事、功能需求、驗收標準

第 3 步：釐清規格（Clarify）

/speckit.clarify

AI 會提出針對性嘅問題（結構化問卷），幫你揾出規格入面嘅模糊點，然後將答案記錄喺規格文件嘅 Clarifications 節。

呢一步應該喺生成計劃之前做，避免之後返轉頭改。

第 4 步：生成技術實現計劃（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 JSON file.

執行後會生成：

.specify/specs/001-photo-album-app/
├── spec.md          # 功能規格
├── plan.md          # 實現計劃
├── research.md      # 技術調研
├── data-model.md    # 數據模型
├── quickstart.md    # 驗證場景
└── contracts/       # API 契約
    └── api-spec.json

第 5 步：生成任務清單（Tasks）

/speckit.tasks

自動生成 tasks.md，包括：

  • • 按用戶故事組織嘅任務列表
  • • 依賴關係管理
  • • 並行任務標記（[P]）
  • • 每個任務對應嘅檔案路徑
  • • TDD 結構（先寫測試，再寫實現）

第 6 步：執行實現（Implement）

/speckit.implement

AI 會：

  1. 1. 確認所有前置條件（constitution / spec / plan / tasks 都存在）
  2. 2. 按依賴順序執行任務
  3. 3. 遵守 TDD 原則
  4. 4. 提供進度回饋

使用場景

最適合嘅場景

場景
原因
全新項目（Greenfield）
由零開始，完整行一次 SDD 流程，產出高質素代碼
疊代功能開發（Brownfield）
喺已有代碼庫上面增量加入功能，保持文件同代碼同步
企業合規項目
透過 Constitution 強制執行組織標準同合規要求
多人協作團隊
統一 AI 寫程式行為，保證團隊產出風格一致
需要成日改需求嘅項目
規格改完之後可以快速重新生成計劃同任務
技術探索/對比實現
同一規格生成多個技術棧實現，橫向比較

可以視情況用嘅場景

場景
建議
一次性腳本 / 極簡任務
SDD 流程比較重，細任務可以直接用 AI 生成，或者用社區擴展 TinySpec
純探索性 Prototype
可在 /speckit.clarify 嗰陣要明確講明跳過，避免 AI 等緊釐清
需求極度穩定嘅項目
如果需求幾乎唔變，SDD 嘅多層文件維護成本 > 收益，傳統開發更適合
單人細項目（< 500 行代碼）
七步流程出嘅文件可能仲多過代碼，建議只保留 spec.md + implement

唔建議用嘅場景

場景
原因
需求本身仲喺度探索緊
SDD 要求先寫清規格先做，但係有啲需求只能邊做邊發現（例如算法實驗、體驗探索）
技術方案極度唔肯定
當連用邊種技術棧都要試過先知嗰陣，行 SDD 等於喺沙上面起樓
已經有完整 PRD + 設計文件嘅團隊
再加多一層 spec/plan/tasks 係重複造輪，揀一層做單一真相來源就得

完整範例：建立 Taskify 看板應用

場景描述

建立一個多用戶 Kanban 看板系統，支援拖放任務卡、留言等功能。

執行過程

# 1. 初始化
specify init taskify --integration copilot

# 進入 Claude Code 或 Copilot，執行以下命令：
# 2. 建立項目原則
/speckit.constitution Create principles focused on code quality, testing standards,
user experience consistency, and performance requirements.
# 3. 描述需求（只描述 WHAT，不涉及技術）
/speckit.specify Develop Taskify, a team productivity platform. Allow users to create
projects, add team members, assign tasks, comment and move tasks between boards in
Kanban style. Five predefined users: one PM and four engineers. No login required.
Kanban columns: To Do, In Progress, In Review, Done. Tasks can be dragged between
columns. Users can add unlimited comments, edit/delete own comments only.
# 4. 澄清模糊點
/speckit.clarify
# 5. 生成技術計劃（此時引入技術棧）
/speckit.plan Use .NET Aspire with Postgres as database. Frontend: Blazor Server
with drag-and-drop task boards, real-time updates. REST APIs: Projects API,
Tasks API, Notifications API.
# 6. 拆解任務
/speckit.tasks
# 7. 執行實現
/speckit.implement

產生嘅目錄結構

taskify/
├── CLAUDE.md
└── .specify/
    ├── memory/
    │   └── constitution.md
    ├── specs/
    │   └── 001-create-taskify/
    │       ├── spec.md
    │       ├── plan.md
    │       ├── research.md
    │       ├── data-model.md
    │       ├── quickstart.md
    │       ├── tasks.md
    │       └── contracts/
    │           ├── api-spec.json
    │           └── signalr-spec.md
    ├── scripts/
    └── templates/

限制同取捨

再好嘅工具都有盲點。以下係實際使用入面要正視嘅問題：

1. 文件維護税

SDD 將單一代碼資產變成 spec + plan + tasks + code 四份資產。需求變更嗰陣：

  • • 傳統開發：改需求 → 改代碼（1 步）
  • • SDD：改 spec → 重跑 plan → 重跑 tasks → 改代碼（3-4 步）

對於需求成日變嘅大型項目，呢筆税係抵俾嘅（變更可以追溯、可以驗證）。但係對於需求穩定或者規模細嘅項目，文件維護本身就係不必要嘅開支。

2. 「反過度工程」嘅自我矛盾

Constitution 強調簡潔性同反對過度抽象，但係七步 SDD 流程本身對簡單項目就係過度工程。Spec Kit 建議細任務用 TinySpec，本質上係承認咗呢個矛盾——但係將問題外判俾社區擴展，而唔係由設計層面解決。

3. 欠缺真實落地數據

截至 2026 年 4 月，Spec Kit 官方冇提供任何關於團隊採用後嘅量化數據：

  • • 缺陷率下降幾多？
  • • 交付速度嘅變化趨勢？
  • • 規格同代碼嘅實際飄移率？
  • • 每步嘅平均需時？

Star 數雖然高（91k+），但 GitHub 官方出品嘅流量加成唔可以忽視。Star 數唔等於生產驗證，揀技術嗰陣需要額外考察。

4. AI 對規格嘅理解偏差

規格文件本身都係自然語言，AI 對 spec 嘅理解可能同你原本嘅意思有出入。SDD 增加咗 /speckit.clarify 嚟緩和呢個問題，但係釐清過程本身都係由 AI 驅動，可能會引入新嘅偏差——AI 問嘅問題唔一定係你真正需要釐清嘅地方。

5. 流程剛性 vs 開發靈活性

七步流程假設需求可以喺編碼之前完全確定，但係好多開發場景（算法實驗、UX 探索、技術驗證）需要邊做邊發現。喺呢啲場景夾硬用 SDD，會變成喺沙上面起城堡。

一句講曬：SDD 係重型武器，打坦克好用，打蚊就浪費喇。揀唔揀佢，取決於你個 project 到底係坦克定係蚊。

擴展系統：Extensions & Presets

Spec Kit 支援透過擴展同預設進行高度自訂。

優先級覆蓋順序

優先級
類型
位置
⬆ 最高
項目本機覆蓋
.specify/templates/overrides/
2
Presets
.specify/presets/templates/
3
Extensions
.specify/extensions/templates/
⬇ 最低
核心預設
.specify/templates/

Extensions（擴展）：加入新能力

# 搜索可用擴展
specify extension search

# 安裝擴展
specify extension add <extension-name>

# 直接通過 URL 安裝
specify extension add myext --from https://github.com/org/ext/archive/refs/tags/v1.0.0.zip

# 列出已安裝擴展
specify extension list

精選社區擴展舉例：

擴展名
功能
spec-kit-jira
自動同步任務到 Jira
spec-kit-review
實現之後嘅代碼質素審查
spec-kit-verify
驗證實現係咪符合規格
spec-kit-sync
偵測並修復規格同代碼嘅飄移
spec-kit-ci-guard
CI/CD 中檢查規格合規性
spec-kit-pr-bridge
由規格自動生成 PR 描述
TinySpec
輕量單檔案工作流程，適合細任務

Presets（預設）：自訂現有工作流程

specify preset search
specify preset add <preset-name>

預設用嚟調整範本格式，例如配合 Agile / Kanban / Waterfall 等唔同方法論。

幾時揀邊種

目標
使用
加入全新命令或工作流程
Extension
自訂規格/計劃/任務嘅格式
Preset
整合外部工具（Jira、Confluence 等）
Extension
強制執行組織標準或合規要求
Preset

常見問題同解決方案

Q1：specify 命令揾唔到 / PATH 未設定

解決：

# 確認 uv tool 的 bin 目錄在 PATH 中
export PATH="$HOME/.local/bin:$PATH"

# 或重新安裝並確認
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
specify version

Q2：AI 助手中睇唔到 /speckit.* 命令

原因：specify init 未成功寫入 AI 助手嘅設定目錄。

解決：

# 檢查是否生成了必要文件
specify check

# 重新初始化，明確指定 integration
specify init . --integration copilot --force
# 或
specify init . --integration claude --force

Q3：AI 跳過咗釐清直接開始實現

原因：冇明確執行 /speckit.clarify，或者 AI 誤判需求已經夠清楚。

解決：在 /speckit.plan 之前，明確執行：

/speckit.clarify

如果要跳過釐清（例如探索性原型），清楚話俾 AI 知：

/speckit.clarify skip - this is an exploratory prototype, proceed without clarification.

Q4：AI 實現時加咗冇要求嘅功能

原因：規格描述太模糊，或者 AI 「好心」加咗延伸功能。

解決：

  1. 1. 喺規格入面清楚標明邊界：Out of Scope: ...
  2. 2. 喺 Constitution 入面加入簡潔性原則
  3. 3. 喺計劃審查階段（Step 5）清楚叫 AI 檢查過度工程：
Read the plan and identify any features or components that were NOT explicitly
requested in the spec. List them and ask for my approval before including them.

Q5：規格同代碼出現飄移（Spec Drift）

症狀：實現完成之後，規格文件同實際代碼行為唔一致。

解決：安裝 spec-kit-sync 擴展：

specify extension add spec-kit-sync

然後執行同步檢測：

/speckit.sync

Q6：Linux 上面 Git 認證問題

wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
sudo dpkg -i gcm-linux_amd64.2.6.1.deb
git config --global credential.helper manager
rm gcm-linux_amd64.2.6.1.deb

Q7：企業/離線環境冇辦法連 PyPI 或 GitHub

場景：公司網絡限制冇辦法直接連 PyPI、GitHub，或者安全政策要求所有依賴要嚟自內部鏡像。

解決：官方支援三種離線部署模式，詳情請睇企業離線安裝指南[3]：

方案
適合場景
關鍵步驟
本機磁碟安裝
完全斷線嘅單機
由有網絡嘅電腦下載 wheel 套件 → USB 手指抄過去 → pip install 本地路徑
私有 PyPI 鏡像
有內部 Nexus/Artifactory 嘅團隊
將 specify-cli 同佢嘅依賴同步到內部鏡像，修改 pip index-url
自訂 Catalog URL
需要管控擴展生態嘅企業
搭建內部 Catalog 服務，設定環境變數 SPECKIT_CATALOG_URL 指向內部地址
# 方案 3 示例：指向企業內部 Catalog
export SPECKIT_CATALOG_URL="https://artifacts.your-company.com/spec-kit/catalog.json"

揀方案建議：細團隊（< 10 人）優先方案 1；有 DevOps 基建嘅中大型團隊優先方案 2；需要審計同控制社區擴展嘅大企業揀方案 3。

同傳統 AI 編程嘅對比

維度
傳統 Vibe Coding
Spec Kit SDD
起點
直接 prompt AI 寫代碼
先寫規格，再生成代碼
文檔
事後先補寫，容易過時
規格就係文件，永遠係源頭
需求變更
人手改代碼
更新規格 → 重新生成
可追溯性
幾乎冇
每行代碼追溯到具體需求
團隊協作
各自為戰
Constitution 統一標準
質素保證
依賴 code review
TDD + 驗收清單內置強制
文件維護
一份文件（如果需要的話）
spec + plan + tasks 三層文件，需求變更時要同步維護
上手成本
低，把口直接講就得
高，要學 CLI + 7 條 Slash 命令 + Constitution 機制
複雜項目
容易失控
分階段驗證，系統可控

延伸資源

  • • 完整 SDD 方法論文檔[4]
  • • 官方文檔站[5]
  • • CLI 命令參考[3]
  • • 社區擴展瀏覽器[6]
  • • 社區 Presets[7]
  • • 影片示範[8]
  • • 提交 Issue / 拎支援[9]

文件係根據 github/spec-kit[10]（91k Stars，GitHub 官方出品）整理，結合實際使用場景補充擴展。MIT License 開源，可以自由使用。

引用連結

[1] uv: https://docs.astral.sh/uv/
[2] pipx: https://pypa.github.io/pipx/
[3] 企業安裝指南: https://github.github.io/spec-kit/reference/overview.html
[4] 完整 SDD 方法論文檔: https://github.com/github/spec-kit/blob/main/spec-driven.md
[5] 官方文檔站: https://github.github.io/spec-kit/
[6] 社區擴展瀏覽器: https://speckit-community.github.io/extensions/
[7] 社區 Presets: https://github.github.io/spec-kit/community/
[8] 影片示範: https://www.youtube.com/watch?v=a9eR1xsfvHg
[9] 提交 Issue / 拎支援: https://github.com/github/spec-kit/issues/new
[10] github/spec-kit: https://github.com/github/spec-kit

 

 

項目簡介

Spec Kit 是由 GitHub 官方開源的一套 規格驅動開發（Spec-Driven Development，SDD）工具集，其核心理念是：

讓規格文檔成為軟件的第一公民，代碼是規格的"輸出"而非目的本身。

它通過一個名為 specify 的 CLI 工具 + 一套 AI 編程助手的 Slash 命令，幫助開發者在與 AI 協作編程時，將需求 → 規格 → 計劃 → 任務 → 實現的全流程結構化、可追溯、可重複。

解決什麼問題？

傳統 AI 輔助編程（俗稱"Vibe Coding"）存在嚴重缺陷：

問題
表現
意圖漂移
AI 一次性生成代碼，但實際實現與原始需求偏差越來越大
規格即廢紙
PRD/需求文檔寫完即棄，代碼和文檔長期失步
變更成本高
需求變了就要人工重寫代碼，沒有體系化的再生成機制
過度工程
AI 自行決策技術方案，帶來不必要的抽象和複雜度
無法追溯
為什麼這樣設計？找不到從需求到代碼的完整鏈條
協作混亂
團隊裏每個人用 AI 的方式不同，產出風格和質量參差不齊

Spec Kit 的解法：在 AI 編程之前，用結構化的流程強制生成 spec（規格）、plan（實現計劃）、tasks（任務清單），讓 AI 在"軌道上"執行，而不是隨意發揮。

核心理念：規格驅動開發（SDD）

SDD 的核心權力倒置：

傳統開發：  需求文檔 → [寫代碼] → 代碼是真正的"產品"
SDD：       規格文檔 → [AI 生成代碼] → 規格才是真正的"產品"
  • • 規格（Spec） = 意圖的表達，描述"做什麼"和"為什麼"
  • • 計劃（Plan） = 技術實現策略，描述"怎麼做"
  • • 任務（Tasks） = 原子化的可執行步驟
  • • 代碼 = 以上三者的"編譯輸出"，可以重新生成

當需求變更時，只需更新規格，重新生成計劃和任務，AI 再次實現。這使得需求變更從"噩夢"變成"常規操作"。

誠實一刻：SDD 把"代碼維護成本"轉換成了"規格維護成本"——spec / plan / tasks 三層文檔本身也是需要持續維護的資產。變更一個需求意味着至少改 3 個文件，再跑 2 道重新生成。對於需求穩定的小項目，這套流程的維護 overhead 可能比直接改代碼還高。這不是否定 SDD，而是提醒：它解決的問題（需求頻繁變更的大項目）和它引入的成本（多層文檔維護）需要放在一起衡量。

工作流程總覽

specify init → /speckit.constitution → /speckit.specify → /speckit.clarify
                                                                    ↓
                                            /speckit.plan → /speckit.analyze
                                                                    ↓
                                                        /speckit.tasks
                                                                    ↓
                                                        /speckit.implement

安裝與環境要求

前置條件

  • • 操作系統：Linux / macOS / Windows
  • • Python 3.11+
  • • Git
  • • 包管理工具：推薦 uv[1] 或 pipx[2]
  • • AI 編程助手：支持 30+ 種，包括 Claude Code、GitHub Copilot、Gemini CLI、Cursor、Codex CLI 等

安裝 Specify CLI

方法一：持久安裝（推薦）

# 安裝指定穩定版本（推薦，將 vX.Y.Z 替換為最新 tag）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

# 或安裝最新 main 分支（可能包含未發佈的變更）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 使用 pipx 也可以
pipx install git+https://github.com/github/spec-kit.git@vX.Y.Z

驗證安裝：

specify version

方法二：一次性運行（無需安裝）

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

方法三：企業/離線環境

參見官方企業安裝指南[3]。

升級

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

如何使用：完整七步工作流

第 0 步：初始化項目

# 新建項目
specify init <PROJECT_NAME>

# 或在現有項目目錄初始化
specify init . --integration copilot
# 也可以用 --here flag
specify init --here --integration copilot

# 強制在非空目錄初始化
specify init . --force --integration copilot

初始化後，你的 AI 編程助手將獲得以下 Slash 命令：

命令
功能
/speckit.constitution
創建/更新項目治理原則
/speckit.specify
從需求描述生成結構化規格文檔
/speckit.clarify
澄清規格中的模糊點（計劃前必做）
/speckit.plan
生成技術實現計劃
/speckit.analyze
跨文檔一致性分析
/speckit.tasks
將計劃拆解為可執行任務
/speckit.implement
按任務清單執行實現
/speckit.checklist
生成質量檢查清單

第 1 步：建立項目治理原則（Constitution）

/speckit.constitution Create principles focused on code quality, testing standards,
user experience consistency, and performance requirements.

這會創建 .specify/memory/constitution.md，作為整個項目 AI 行為的"憲法"，後續所有步驟都會遵守這份原則。

憲法的九大條款（內置默認值）：

  • • Article I：庫優先原則（每個功能先作為獨立庫實現）
  • • Article II：CLI 接口強制（所有庫必須暴露 CLI 接口）
  • • Article III：測試優先（不寫測試不得實現）
  • • Articles VII & VIII：簡潔性 + 反過度抽象
  • • Article IX：集成優先測試（用真實環境測試，不用 Mock）

第 2 步：創建規格文檔（Spec）

重點：描述"做什麼"和"為什麼"，不要涉及技術棧。

/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. Allow users to add descriptions and tags to albums.

執行後自動完成：

  • • 創建語義化分支（如 001-photo-album-app）
  • • 生成 .specify/specs/001-photo-album-app/spec.md
  • • 包含用戶故事、功能需求、驗收標準

第 3 步：澄清規格（Clarify）

/speckit.clarify

AI 會提出針對性問題（結構化問卷），幫你找出規格中的模糊點，並將答案記錄到規格文檔的 Clarifications 節。

這一步應在生成計劃之前完成，避免後期返工。

第 4 步：生成技術實現計劃（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 JSON file.

執行後生成：

.specify/specs/001-photo-album-app/
├── spec.md          # 功能規格
├── plan.md          # 實現計劃
├── research.md      # 技術調研
├── data-model.md    # 數據模型
├── quickstart.md    # 驗證場景
└── contracts/       # API 契約
    └── api-spec.json

第 5 步：生成任務清單（Tasks）

/speckit.tasks

自動生成 tasks.md，包含：

  • • 按用戶故事組織的任務列表
  • • 依賴關係管理
  • • 並行任務標記（[P]）
  • • 每個任務對應的文件路徑
  • • TDD 結構（先寫測試，再寫實現）

第 6 步：執行實現（Implement）

/speckit.implement

AI 將：

  1. 1. 驗證所有前置條件（constitution / spec / plan / tasks 均存在）
  2. 2. 按依賴順序執行任務
  3. 3. 遵守 TDD 原則
  4. 4. 提供進度反饋

使用場景

最佳適用場景

場景
原因
全新項目（Greenfield）
從零開始，完整走一遍 SDD 流程，產出高質量代碼
迭代功能開發（Brownfield）
在已有代碼庫上增量添加功能，保持文檔與代碼同步
企業合規項目
通過 Constitution 強制執行組織標準和合規要求
多人協作團隊
統一 AI 編程行為，保證團隊產出風格一致
需要頻繁變更需求的項目
規格變更後可快速重新生成計劃和任務
技術探索/對比實現
同一規格生成多個技術棧實現，橫向比較

酌情使用的場景

場景
建議
一次性腳本 / 極簡任務
SDD 流程較重，小任務可直接用 AI 生成，或使用社區擴展 TinySpec
純探索性 Prototype
可在 /speckit.clarify 時明確說明跳過，避免 AI 等待澄清
需求極度穩定的項目
若需求幾乎不變，SDD 的多層文檔維護成本 > 收益，傳統開發更合適
單人小項目（< 500 行代碼）
七步流程產出的文檔可能比代碼還多，建議只保留 spec.md + implement

不建議使用的場景

場景
原因
需求本身還在探索中
SDD 要求先寫清規格再動手，但有些需求只能邊做邊發現（如算法實驗、體驗探索）
技術方案極度不確定
當連用什麼技術棧都要試了才知道時，先走 SDD 等於在沙子上蓋樓
已有完整 PRD + 設計文檔的團隊
再多一層 spec/plan/tasks 是重複造輪子，選一層做單一真相源即可

完整示例：構建 Taskify 看板應用

場景描述

構建一個多用戶 Kanban 看板系統，支持拖拽任務卡片、評論等功能。

執行過程

# 1. 初始化
specify init taskify --integration copilot

# 進入 Claude Code 或 Copilot，執行以下命令：
# 2. 建立項目原則
/speckit.constitution Create principles focused on code quality, testing standards,
user experience consistency, and performance requirements.
# 3. 描述需求（只描述 WHAT，不涉及技術）
/speckit.specify Develop Taskify, a team productivity platform. Allow users to create
projects, add team members, assign tasks, comment and move tasks between boards in
Kanban style. Five predefined users: one PM and four engineers. No login required.
Kanban columns: To Do, In Progress, In Review, Done. Tasks can be dragged between
columns. Users can add unlimited comments, edit/delete own comments only.
# 4. 澄清模糊點
/speckit.clarify
# 5. 生成技術計劃（此時引入技術棧）
/speckit.plan Use .NET Aspire with Postgres as database. Frontend: Blazor Server
with drag-and-drop task boards, real-time updates. REST APIs: Projects API,
Tasks API, Notifications API.
# 6. 拆解任務
/speckit.tasks
# 7. 執行實現
/speckit.implement

產出的目錄結構

taskify/
├── CLAUDE.md
└── .specify/
    ├── memory/
    │   └── constitution.md
    ├── specs/
    │   └── 001-create-taskify/
    │       ├── spec.md
    │       ├── plan.md
    │       ├── research.md
    │       ├── data-model.md
    │       ├── quickstart.md
    │       ├── tasks.md
    │       └── contracts/
    │           ├── api-spec.json
    │           └── signalr-spec.md
    ├── scripts/
    └── templates/

侷限性與權衡

再好的工具也有盲區。以下是在實際使用中需要正視的問題：

1. 文檔維護税

SDD 把單一代碼資產變成了 spec + plan + tasks + code 四份資產。需求變更時：

  • • 傳統開發：改需求 → 改代碼（1 步）
  • • SDD：改 spec → 重跑 plan → 重跑 tasks → 改代碼（3-4 步）

對於需求頻繁變更的大型項目，這筆税是划算的（變更可追溯、可驗證）。但對於需求穩定或體量小的項目，文檔維護本身就是不必要的開銷。

2. "反過度工程"的自我矛盾

Constitution 強調簡潔性和反過度抽象，但七步 SDD 流程本身對簡單項目就是過度工程。Spec Kit 建議小任務用 TinySpec，本質上是承認了這個矛盾——但把問題外包給社區擴展，而非從設計層面解決。

3. 缺乏真實落地數據

截至 2026 年 4 月，Spec Kit 官方未提供任何關於團隊採納後的量化數據：

  • • 缺陷率下降多少？
  • • 交付速度變化趨勢？
  • • 規格與代碼的實際漂移率？
  • • 某步驟的平均耗時？

Star 數雖高（91k+），但 GitHub 官方出品的流量加成不可忽視。Star 數 ≠ 生產驗證，選型時需要額外考察。

4. AI 對規格的理解偏差

規格文檔本身也是自然語言，AI 對 spec 的理解可能和你的本意有偏差。SDD 增加了 /speckit.clarify 來緩解這個問題，但澄清過程本身也是 AI 驅動的，可能引入新的偏差——AI 問的問題不一定是你真正需要澄清的點。

5. 流程剛性 vs 開發靈活性

七步流程假設需求可以在編碼前完全確定，但很多開發場景（算法實驗、UX 探索、技術驗證）需要邊做邊發現。在這些場景中強行套用 SDD，會變成在沙子上建城堡。

一句話總結：SDD 是重型武器，打坦克好用，打蚊子就浪費了。選不選它，取決於你的項目到底是坦克還是蚊子。

擴展系統：Extensions & Presets

Spec Kit 支持通過擴展和預設進行高度定製。

優先級覆蓋順序

優先級
類型
位置
⬆ 最高
項目本地覆蓋
.specify/templates/overrides/
2
Presets
.specify/presets/templates/
3
Extensions
.specify/extensions/templates/
⬇ 最低
核心默認
.specify/templates/

Extensions（擴展）：添加新能力

# 搜索可用擴展
specify extension search

# 安裝擴展
specify extension add <extension-name>

# 直接通過 URL 安裝
specify extension add myext --from https://github.com/org/ext/archive/refs/tags/v1.0.0.zip

# 列出已安裝擴展
specify extension list

精選社區擴展舉例：

擴展名
功能
spec-kit-jira
自動同步任務到 Jira
spec-kit-review
實現後的代碼質量審查
spec-kit-verify
驗證實現是否符合規格
spec-kit-sync
檢測並修復規格與代碼的漂移
spec-kit-ci-guard
CI/CD 中檢查規格合規性
spec-kit-pr-bridge
從規格自動生成 PR 描述
TinySpec
輕量單文件工作流，適合小任務

Presets（預設）：定製現有工作流

specify preset search
specify preset add <preset-name>

預設用於調整模板格式，例如適配 Agile / Kanban / Waterfall 等不同方法論。

何時選擇哪種

目標
使用
添加全新命令或工作流
Extension
定製規格/計劃/任務的格式
Preset
集成外部工具（Jira、Confluence 等）
Extension
強制執行組織標準或合規要求
Preset

常見問題與解決方案

Q1：specify 命令找不到 / PATH 未配置

解決：

# 確認 uv tool 的 bin 目錄在 PATH 中
export PATH="$HOME/.local/bin:$PATH"

# 或重新安裝並確認
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
specify version

Q2：AI 助手中看不到 /speckit.* 命令

原因：specify init 未成功寫入 AI 助手的配置目錄。

解決：

# 檢查是否生成了必要文件
specify check

# 重新初始化，明確指定 integration
specify init . --integration copilot --force
# 或
specify init . --integration claude --force

Q3：AI 跳過了澄清直接開始實現

原因：沒有明確運行 /speckit.clarify，或 AI 誤判需求已足夠清晰。

解決：在 /speckit.plan 之前，明確執行：

/speckit.clarify

如果要跳過澄清（如探索性原型），明確告知 AI：

/speckit.clarify skip - this is an exploratory prototype, proceed without clarification.

Q4：AI 實現時加入了沒有要求的功能

原因：規格描述過於模糊，或 AI "好心"添加擴展。

解決：

  1. 1. 在規格中明確標註邊界：Out of Scope: ...
  2. 2. 在 Constitution 中添加簡潔性原則
  3. 3. 在計劃審查階段（Step 5）明確提示 AI 檢查過度工程：
Read the plan and identify any features or components that were NOT explicitly
requested in the spec. List them and ask for my approval before including them.

Q5：規格與代碼出現漂移（Spec Drift）

症狀：實現完成後，規格文檔與實際代碼行為不一致。

解決：安裝 spec-kit-sync 擴展：

specify extension add spec-kit-sync

然後執行同步檢測：

/speckit.sync

Q6：Linux 上 Git 認證問題

wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
sudo dpkg -i gcm-linux_amd64.2.6.1.deb
git config --global credential.helper manager
rm gcm-linux_amd64.2.6.1.deb

Q7：企業/離線環境無法訪問 PyPI 或 GitHub

場景：公司網絡限制無法直接訪問 PyPI、GitHub，或安全策略要求所有依賴來自內部鏡像。

解決：官方支持三種離線部署模式，詳見企業離線安裝指南[3]：

方案
適用場景
關鍵步驟
本地磁盤安裝
完全斷網的單機
從有網的機器下載 wheel 包 → U 盤拷貝 → pip install 本地路徑
私有 PyPI 鏡像
有內部 Nexus/Artifactory 的團隊
將 specify-cli 及其依賴同步到內部鏡像，修改 pip index-url
自定義 Catalog URL
需要管控擴展生態的企業
搭建內部 Catalog 服務，設置環境變量 SPECKIT_CATALOG_URL 指向內部地址
# 方案 3 示例：指向企業內部 Catalog
export SPECKIT_CATALOG_URL="https://artifacts.your-company.com/spec-kit/catalog.json"

選型建議：小團隊（< 10 人）優先方案 1；有 DevOps 基礎設施的中大型團隊優先方案 2；需要審計和控制社區擴展的大企業選方案 3。

與傳統 AI 編程對比

維度
傳統 Vibe Coding
Spec Kit SDD
起點
直接 prompt AI 寫代碼
先寫規格，再生成代碼
文檔
事後補寫，易過時
規格即文檔，始終是源頭
需求變更
人工改代碼
更新規格 → 重新生成
可追溯性
幾乎沒有
每行代碼溯源到具體需求
團隊協作
各自為戰
Constitution 統一標準
質量保障
依賴 review
TDD + 驗收清單內置強制
文檔維護
一份文檔（如果需要的話）
spec + plan + tasks 三層文檔，需求變更時需同步維護
上手成本
低，一張嘴直接說
高，需學習 CLI + 7 條 Slash 命令 + Constitution 機制
複雜項目
容易失控
分階段驗證，系統可控

延伸資源

  • • 完整 SDD 方法論文檔[4]
  • • 官方文檔站[5]
  • • CLI 命令參考[3]
  • • 社區擴展瀏覽器[6]
  • • 社區 Presets[7]
  • • 視頻演示[8]
  • • 提交 Issue / 獲取支持[9]

文檔基於 github/spec-kit[10]（91k Stars，GitHub 官方出品）整理，結合實際使用場景補充擴展。MIT License 開源，可自由使用。

引用連結

[1] uv: https://docs.astral.sh/uv/
[2] pipx: https://pypa.github.io/pipx/
[3] 企業安裝指南: https://github.github.io/spec-kit/reference/overview.html
[4] 完整 SDD 方法論文檔: https://github.com/github/spec-kit/blob/main/spec-driven.md
[5] 官方文檔站: https://github.github.io/spec-kit/
[6] 社區擴展瀏覽器: https://speckit-community.github.io/extensions/
[7] 社區 Presets: https://github.github.io/spec-kit/community/
[8] 視頻演示: https://www.youtube.com/watch?v=a9eR1xsfvHg
[9] 提交 Issue / 獲取支持: https://github.com/github/spec-kit/issues/new
[10] github/spec-kit: https://github.com/github/spec-kit