跳至主要内容

Spec Kit + Claude Code 使用指南

Spec-Driven Development (SDD) — 在寫任何程式碼之前，先定義軟體應該做什麼。 規格文件成為「唯一真相來源」，人和 AI 都依據它來產生程式碼。

目錄​

  1. 什麼是 Spec Kit？
  2. 為什麼需要 SDD？
  3. 安裝與環境設定
  4. 專案初始化
  5. 核心工作流程（六階段）
  6. 輔助命令
  7. 檔案結構說明
  8. 實戰範例
  9. 最佳實踐
  10. 何時該用 / 不該用
  11. 常見陷阱與解法
  12. 進階技巧
  13. 參考資源

1. 什麼是 Spec Kit？​

Spec Kit 是 GitHub 開源的 Spec-Driven Development 工具包，提供結構化流程讓 AI coding agent（如 Claude Code、GitHub Copilot、Gemini CLI）依據明確規格產出程式碼。

核心理念：規格 (Specification) 不只是文件，而是可執行的開發指令。

兩個組成部分：

組件說明
Specify CLI命令列工具，用來初始化專案、下載模板
Templates + Slash Commands定義規格格式、技術計畫結構、任務拆解方式的模板與 Claude Code 指令

2. 為什麼需要 SDD？​

直接用 AI 寫程式碼的問題​

問題說明
Context 遺失對話越長，AI 越容易忘記前面的約定
假設不一致AI 會根據自己的理解做決定，不一定符合你的架構
程式碼偏移沒有明確規格時，AI 容易加入不需要的功能或偏離設計
難以協作多人用 AI 開發時，每個人給的 prompt 不一樣，產出不一致

SDD 解決方式​

  • Constitution（憲法） 確保每次 AI 互動都參照同一套原則
  • Specification（規格） 消除模糊需求，給 AI 明確指示
  • Plan（計畫） 嵌入架構約束，避免 AI 偏離設計
  • Tasks（任務） 將大問題拆成小塊，降低 AI 出錯率
  • 每個階段都有檢查點，讓你在 AI 執行前確認方向

3. 安裝與環境設定​

前置需求​

  • Python 3.11+
  • uv（Astral 的 Python 套件管理器）
  • Git
  • Claude Code（已安裝並可執行）

安裝 uv（如果還沒裝）​

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

安裝 Specify CLI（推薦持久安裝）​

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

升級​

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

驗證安裝​

specify check

此命令會檢查 git、claude 等工具是否正確安裝。

4. 專案初始化​

在現有專案初始化​

cd your-project
specify init . --ai claude --force

建立新專案​

specify init my-project --ai claude

init 選項​

選項說明
--ai claude指定使用 Claude Code（也支援 copilot、gemini、cursor-agent 等）
--script ps使用 PowerShell 腳本（Windows 適用）
--force跳過非空目錄確認
--no-git不初始化 git repo

初始化後產生的結構​

your-project/
├── .claude/
│   └── commands/           # Claude Code slash commands
│       ├── speckit.constitution.md
│       ├── speckit.specify.md
│       ├── speckit.clarify.md
│       ├── speckit.plan.md
│       ├── speckit.tasks.md
│       ├── speckit.implement.md
│       ├── speckit.analyze.md
│       ├── speckit.checklist.md
│       └── speckit.taskstoissues.md
├── .specify/
│   ├── memory/
│   │   └── constitution.md  # 專案憲法（核心原則）
│   ├── templates/           # 各階段的模板
│   │   ├── constitution-template.md
│   │   ├── spec-template.md
│   │   ├── plan-template.md
│   │   ├── tasks-template.md
│   │   ├── checklist-template.md
│   │   └── agent-file-template.md
│   └── scripts/
│       └── powershell/      # 自動化腳本
│           ├── check-prerequisites.ps1
│           ├── common.ps1
│           ├── create-new-feature.ps1
│           ├── setup-plan.ps1
│           └── update-agent-context.ps1
└── specs/                   # 各功能的規格文件（執行後產生）

5. 核心工作流程（六階段）​

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ Constitution │───>│   Specify   │───>│   Clarify   │
│  (做一次)     │    │  (定義需求)  │    │  (釐清模糊)  │
└─────────────┘    └─────────────┘    └──────┬──────┘
                                             │ (可選)
                   ┌─────────────┐    ┌──────▼──────┐
                   │  Implement  │<───│    Plan     │
                   │  (執行實作)  │    │  (技術計畫)  │
                   └──────▲──────┘    └──────┬──────┘
                          │                  │
                   ┌──────┴──────┐    ┌──────▼──────┐
                   │   Analyze   │<───│    Tasks    │
                   │  (品質檢查)  │    │  (拆解任務)  │
                   └─────────────┘    └─────────────┘

完整流程順序​

/speckit.constitution  →  設定一次，所有功能共用
/speckit.specify       →  描述你要建什麼（聚焦 WHAT & WHY）
/speckit.clarify       →  [可選] AI 問你最多 5 個釐清問題
/speckit.plan          →  產出技術計畫（聚焦 HOW）
/speckit.tasks         →  拆解為可執行任務清單
/speckit.analyze       →  [可選] 跨文件一致性檢查
/speckit.implement     →  逐一執行任務，產出程式碼

Stage 1: Constitution（憲法）​

目的：定義專案不可妥協的開發原則。只需做一次，所有功能開發共用。

執行：

/speckit.constitution 原則內容描述...

輸入什麼：

  • 架構模式與約束
  • 技術棧要求
  • 命名慣例
  • 測試要求
  • 安全約束
  • 品質標準

範例：

/speckit.constitution
1. C# .NET Framework 4.8 + WinForms，不使用 WPF
2. 所有 Process 必須繼承 clsThreadProc，使用 EQRunCase 狀態機
3. 硬體操作必須有 timeout 和 alarm 機制
4. 多執行緒透過 boolean flag 協調，共享資源用 lock 保護
5. 遵循現有命名慣例：cls/enu/Proc 前綴
6. UI 更新必須透過 clsProjectInvoke 確保執行緒安全

產出：.specify/memory/constitution.md（填入具體原則，取代佔位符）

重點：

  • Constitution 品質直接影響後續所有階段的產出品質
  • 明確列出「禁止」的模式和「必須」的做法
  • 包含版本號和修訂日期，方便追蹤

Stage 2: Specify（規格定義）​

目的：描述你要建構什麼功能，聚焦在「做什麼」和「為什麼」。

執行：

/speckit.specify 功能描述...

輸入什麼：

  • 使用者故事（User Stories）
  • 功能需求（Functional Requirements）
  • 成功標準（Success Criteria）
  • 邊界情況（Edge Cases）

範例：

/speckit.specify 新增 FOUP Mapping 功能：
操作員在 LD 站載入 Cassette 後，系統自動偵測每個 Slot 是否有 Wafer，
產生 Mapping 結果顯示在 UI 上。支援 25 slot 標準 Cassette，
異常時（如感測器故障）發出 Alarm，Mapping 結果存入 Log。

產出：

  • specs/{N}-{feature-name}/spec.md — 完整規格文件
  • specs/{N}-{feature-name}/checklists/requirements.md — 規格品質檢查表
  • 自動建立 Git feature branch

spec.md 包含：

  • User Stories（帶優先級 P1/P2/P3）
  • Acceptance Scenarios（Given/When/Then 格式）
  • Functional Requirements（FR-001, FR-002...）
  • Key Entities
  • Success Criteria（可量測的成功指標）
  • Edge Cases

重點：

  • 不要寫技術實作細節（不提框架、API、程式結構）
  • 要從使用者角度描述功能
  • 最多 3 個 [NEEDS CLARIFICATION] 標記
  • 每個 User Story 必須可獨立測試

Stage 3: Clarify（釐清模糊）​

目的：在進入技術計畫前，由 AI 偵測規格中的模糊地帶，透過互動問答釐清。

執行：

/speckit.clarify

運作方式：

  1. AI 掃描 spec.md，針對 10 個分類做模糊度分析
  2. 產生最多 5 個釐清問題（按影響度排序）
  3. 一次問一題，提供推薦選項
  4. 你可以回覆選項代碼（如 "A"）、說 "yes" 接受推薦、或自行回答
  5. 每個答案立即寫回 spec.md 對應章節

分析分類：

  • 功能範圍與行為
  • 資料模型
  • 互動與 UX 流程
  • 非功能性需求（效能、安全、可靠性）
  • 外部整合與依賴
  • 邊界與例外處理
  • 術語一致性

何時使用：

  • 複雜功能 → 強烈建議執行
  • 簡單功能 → 可跳過，但 AI 會警告風險增加

Stage 4: Plan（技術計畫）​

目的：根據規格產出技術實作計畫，包含架構選擇、資料模型、專案結構。

執行：

/speckit.plan 技術棧與約束描述...

範例：

/speckit.plan 使用 C# .NET Framework 4.8，
繼承 clsThreadProc 狀態機模式，
EtherCAT motion control，
IO 透過 enuDi/enuDo enum 存取

執行階段：

階段產出說明
Phase 0research.md解決所有技術未知項，記錄決策與替代方案
Phase 1data-model.md實體、欄位、關聯、狀態轉移
Phase 1contracts/介面契約（API、CLI、通訊協議）
Phase 1quickstart.md整合情境與驗證步驟

plan.md 包含：

  • Technical Context（語言、依賴、儲存、測試、平台）
  • Constitution Check（比對原則，必須通過才能繼續）
  • Project Structure（具體目錄結構）
  • Complexity Tracking（違反原則的項目須說明理由）

重點：

  • Plan 階段可以請 AI 產出多個方案比較
  • Constitution Check 是品質閘門，違反原則會 ERROR
  • 所有 NEEDS CLARIFICATION 必須在 Phase 0 解決

Stage 5: Tasks（任務拆解）​

目的：將計畫拆解為可執行的任務清單，按 User Story 分組。

執行：

/speckit.tasks

產出：specs/{N}-{feature-name}/tasks.md

任務格式：

- [ ] T001 Create project structure per implementation plan
- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py
- [ ] T012 [P] [US1] Create User model in src/models/user.py
標記說明
- [ ]Markdown 核取方塊
T001任務編號（執行順序）
[P]可並行執行（不同檔案、無依賴）
[US1]對應 User Story 1
描述包含具體檔案路徑

Phase 結構：

Phase 1: Setup         — 專案初始化
Phase 2: Foundational  — 阻擋性前置工作（必須先完成）
Phase 3: User Story 1  — P1 最高優先（= MVP）
Phase 4: User Story 2  — P2
Phase N: Polish        — 跨功能整理

重點：

  • 每個 User Story 可獨立實作與測試
  • MVP = 只完成 Phase 1 + 2 + 3（User Story 1）即可交付
  • 標記 [P] 的任務可同時進行
  • 每個任務必須具體到 AI 不需要額外上下文就能執行

Stage 6: Implement（實作）​

目的：按任務清單逐一產出程式碼。

執行：

/speckit.implement

執行流程：

  1. 檢查 checklists 是否都通過（不通過會詢問是否繼續）
  2. 載入 tasks.md、plan.md、data-model.md 等上下文
  3. 驗證/建立 ignore 檔案（.gitignore 等）
  4. 按 Phase 順序逐一執行任務
  5. 完成的任務標記為 [X]
  6. 每個 Phase 完成後做驗證檢查點

重點：

  • 前 2-3 個任務要仔細檢查產出品質
  • 如果偏離規格，隨時可回到 /speckit.plan 或 /speckit.clarify 修正
  • [P] 標記的任務會嘗試並行執行
  • 失敗的任務會停下來報告，不會硬做

6. 輔助命令​

/speckit.analyze（一致性分析）​

目的：在 implement 之前做跨文件品質檢查（唯讀，不修改任何檔案）。

執行：在 /speckit.tasks 之後、/speckit.implement 之前。

檢查項目：

類別檢查內容
重複偵測近似重複的需求
模糊偵測缺乏量化標準的形容詞（fast、scalable、robust）
不足偵測有動詞但缺少對象或量化結果的需求
憲法對齊違反 MUST 原則的項目（自動標為 CRITICAL）
覆蓋缺口沒有對應任務的需求、沒有對應需求的任務
不一致性術語飄移、資料實體不同步、任務排序矛盾

嚴重度：CRITICAL > HIGH > MEDIUM > LOW

產出：結構化分析報告（Markdown 表格），包含修正建議。

/speckit.checklist（品質檢查表）​

目的：為特定領域產生「需求品質檢查表」，驗證需求本身是否寫好（不是驗證實作）。

範例：

/speckit.checklist 安全性需求檢查
/speckit.checklist UX 互動流程需求品質
/speckit.checklist 硬體通訊介面需求完整性

核心概念：Checklist 是「需求的單元測試」。

✅ 正確：「是否為所有互動元素定義了鍵盤導航需求？」[Coverage, Gap]
❌ 錯誤：「驗證按鈕點擊後正確導航」（這是測試實作，不是測試需求）

產出：specs/{feature}/checklists/{domain}.md

/speckit.taskstoissues（任務轉 GitHub Issues）​

目的：將 tasks.md 中的任務自動建立為 GitHub Issues。

前置條件：Git remote 必須是 GitHub URL。

7. 檔案結構說明​

specs/
└── 1-feature-name/          # 每個功能一個目錄
    ├── spec.md               # 功能規格（/speckit.specify 產生）
    ├── plan.md               # 技術計畫（/speckit.plan 產生）
    ├── research.md           # 技術調研（/speckit.plan Phase 0 產生）
    ├── data-model.md         # 資料模型（/speckit.plan Phase 1 產生）
    ├── quickstart.md         # 整合情境（/speckit.plan Phase 1 產生）
    ├── contracts/            # 介面契約（/speckit.plan Phase 1 產生）
    ├── tasks.md              # 任務清單（/speckit.tasks 產生）
    └── checklists/           # 品質檢查表
        ├── requirements.md   # 規格品質（/speckit.specify 自動產生）
        ├── security.md       # 安全需求品質（/speckit.checklist 產生）
        └── ux.md             # UX 需求品質（/speckit.checklist 產生）

.specify/
├── memory/
│   └── constitution.md       # 專案憲法（/speckit.constitution 產生）
├── templates/                # 各階段模板（不要手動修改）
└── scripts/                  # 自動化腳本

.claude/
└── commands/                 # Claude Code slash commands

8. 實戰範例​

情境：為 ENR_DUC 新增 FOUP Mapping 功能​

Step 1: 設定 Constitution（第一次做）​

/speckit.constitution
1. C# .NET Framework 4.8 + WinForms
2. 所有 Process 繼承 clsThreadProc，使用 EQRunCase 狀態機
3. EtherCAT motion control，IO 透過 enuDi/enuDo enum 存取
4. 硬體操作必須有 timeout，異常必須觸發 enuAlarm
5. 多執行緒用 boolean flag 協調，共享資源用 lock
6. 命名慣例：cls/enu/Proc 前綴，匈牙利命名法
7. UI 更新透過 clsProjectInvoke 確保執行緒安全
8. 新 Process 必須加入 clsEditRunThread 靜態屬性
9. Log 透過 clsLog.Log(enuLogType_Extend.XXX, message)

Step 2: 定義功能規格​

/speckit.specify 新增 FOUP Mapping 功能：
操作員在 LD 站載入 Cassette 後，系統使用感測器自動偵測每個 Slot（1-25）
是否有 Wafer，產生 Mapping 結果。結果即時顯示在 UI 的 Cassette 圖示上
（有 Wafer = 綠色, 無 = 灰色, 異常 = 紅色）。
Mapping 完成後結果存入 Recipe Log。
感測器故障或讀取異常時觸發 Alarm。
支援 Bypass Mapping 選項（測試模式下跳過）。

Step 3: 釐清（可選）​

/speckit.clarify

AI 可能問：

  • Q1: Mapping 感測器使用 DI 還是 AI（類比/數位）？
  • Q2: 是否需要支援非標準 Cassette（非 25 slot）？
  • Q3: Bypass Mapping 的權限等級？

Step 4: 技術計畫​

/speckit.plan 使用現有 clsThreadProc 狀態機模式，
DI 感測器透過 EtherCAT GetDI 讀取，
UI 用 WinForms UserControl，
新增 ProcLD_Mapping Process

Step 5: 任務拆解​

/speckit.tasks

Step 6: 一致性檢查（可選但推薦）​

/speckit.analyze

Step 7: 執行實作​

/speckit.implement

9. 最佳實踐​

Constitution 是關鍵​

做法說明
越具體越好「使用 clsThreadProc」比「使用狀態機」好
列出禁止項「禁止直接設定 iStepIndex，必須用 EQRunCase.GoCase()」
包含命名規則減少 AI 自創命名的機會
定期更新架構決策改變時同步更新

Specify 聚焦使用者視角​

  • 描述「操作員會做什麼」而非「系統怎麼實作」
  • 包含邊界情況（感測器故障、通訊斷線）
  • 每個 User Story 帶優先級
  • 初始 prompt 越詳細，後續修正越少

Plan 要符合現有架構​

  • 明確指定要修改或新增的具體檔案
  • 引用現有的 class 和 pattern
  • 標示與現有系統的整合點

Tasks 要夠具體​

  • 每個任務指定具體檔案路徑
  • 任務之間的依賴關係要清楚
  • MVP 策略：先完成 User Story 1 即可交付

Implement 要有監督​

  • 前 2-3 個任務仔細 review
  • 發現偏離時立即修正（回到 plan 或 clarify）
  • 每個 Phase 完成後做人工檢查

10. 何時該用 / 不該用​

適合使用的情境​

情境原因
新功能模組開發需要完整的設計到實作流程
複雜功能（涉及多檔案）AI 容易在大範圍修改中失控
多人協作同一功能共享同一份規格，產出一致
重構子系統需要先釐清現有行為再動手
對接新硬體/通訊協議需要嚴謹的介面定義

不適合使用的情境​

情境替代方式
Bug 修復直接描述 bug，讓 Claude 修
參數調整直接改
單一檔案小修改直接 prompt Claude
探索性原型先 vibe coding，確定方向後再用 SDD
緊急 hotfix流程太重，直接修

判斷原則​

如果你的修改涉及 3 個以上檔案、需要新增 class、或影響多個子系統 → 考慮用 Spec Kit

如果 10 分鐘內可以手動完成 → 直接做

11. 常見陷阱與解法​

陷阱解法
Constitution 太模糊用具體的 class 名、pattern 名，而非泛泛形容詞
Specify 寫了技術細節聚焦「使用者做什麼」「系統應該怎樣」，不寫「用什麼技術」
跳過 Clarify 直接 Plan複雜功能建議執行，可減少後續返工
AI 無視 Constitution在後續 prompt 中明確引用 constitution 原則
任務描述太籠統加入具體檔案路徑、function 名、依賴關係
一次 implement 太多先只做 MVP（User Story 1），驗證後再繼續
規格與程式碼脫節需求變更時先更新 spec，再跑後續流程
Context window 耗盡每個 stage 完成後考慮 /compact 或 /clear
AI 自建元件不用現有程式庫Constitution 中明確列出「必須使用 xxx 而非自己實作」

12. 進階技巧​

多方案比較​

在 Plan 階段可以請 AI 產出多個方案：

/speckit.plan 請產出兩個方案比較：
方案 A: 在現有 ProcWorker_LD 中加入 Mapping 子流程
方案 B: 獨立新建 ProcWorker_Mapping Worker

漸進式交付​

Phase 1-2: Setup + Foundation  → 基礎就緒
Phase 3:   User Story 1 (P1)  → MVP 交付、測試
Phase 4:   User Story 2 (P2)  → 第二次交付
Phase N:   Polish              → 最終整理

每個 checkpoint 都可以暫停、review、修正方向。

Constitution 與 CLAUDE.md 共存​

  • CLAUDE.md：全局偏好（build commands、架構概覽、開發慣例）
  • Constitution：特定功能開發的不可妥協原則

兩者互補，不衝突。CLAUDE.md 管日常開發，Constitution 管 SDD 流程。

處理大型功能​

如果功能太大，拆成多個獨立的 spec：

/speckit.specify FOUP Mapping — 感測器讀取與資料模型
/speckit.specify FOUP Mapping — UI 顯示與操作介面
/speckit.specify FOUP Mapping — Log 記錄與報表

環境變數​

# 非 Git 環境下指定 feature 目錄
export SPECIFY_FEATURE=1-foup-mapping

13. 參考資源​

官方資源​

社群教學​

深度分析​

快速參考卡​

命令                          何時用              產出
─────────────────────────────────────────────────────────
/speckit.constitution         專案初始化（一次）   .specify/memory/constitution.md
/speckit.specify <描述>       每個新功能          specs/{N}-{name}/spec.md
/speckit.clarify              specify 後（可選）   更新 spec.md
/speckit.plan <技術棧>        clarify 後          plan.md, research.md, data-model.md
/speckit.tasks                plan 後             tasks.md
/speckit.analyze              tasks 後（可選）     分析報告（不修改檔案）
/speckit.checklist <領域>     任何時候（可選）     checklists/{domain}.md
/speckit.implement            tasks/analyze 後    實際程式碼
/speckit.taskstoissues        tasks 後（可選）     GitHub Issues

本文件最後更新：2026-03-09 基於 GitHub Spec Kit v0.1.4 + spec-kit-template-claude