Spec Kit 使用手冊 | Step by Step 教學

什麼是 Spec Kit？
這是 GitHub 推出的工具，幫助你在使用 AI 開發前，先把需求、規格寫清楚，讓 AI 更準確理解你的需求，減少來回修改的時間。

安裝 Spec Kit

首先，在終端機中執行以下指令安裝 Spec Kit CLI 工具：

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

安裝完成後，執行以下指令驗證：

specify --help

系統需求：
需要先安裝 Python 3.11+、Git 和 uv 套件管理工具

初始化專案

在你的專案目錄中執行初始化指令：

# 在新專案中初始化
specify init my-project --ai claude

# 或在現有專案中初始化
cd your-project
specify init . --ai claude

初始化後會在專案中建立 .claude/commands/ 資料夾，裡面包含：

speckit.constitution - 專案憲章（開發原則）
speckit.specify - 需求規格文件
speckit.plan - 技術規劃
speckit.tasks - 任務清單

編寫憲章文件

開啟 .claude/commands/speckit.constitution，定義專案的開發原則與規範。

📋 範本 1：前端專案憲章

# 專案開發憲章

## 技術棧
- 框架：React 18+ with TypeScript
- 樣式：Tailwind CSS
- 狀態管理：Zustand
- 建構工具：Vite

## 編碼規範
- 使用函數式元件和 React Hooks
- 元件命名採用 PascalCase
- 檔案結構按功能分組（feature-based）
- 使用 ESLint + Prettier 自動格式化

## 安全原則
- 所有使用者輸入必須驗證與消毒
- 敏感資訊使用環境變數管理
- 防範 XSS 和 CSRF 攻擊

## 品質標準
- 單元測試覆蓋率 > 80%
- 可訪問性符合 WCAG 2.1 AA
- 效能：LCP < 2.5s, FID < 100ms

🔐 範本 2：資安工具憲章

# 資安工具開發憲章

## 安全原則
- 最小權限原則（Principle of Least Privilege）
- 縱深防禦（Defense in Depth）
- 所有資料加密儲存與傳輸
- 完整的審計日誌記錄

## 技術要求
- 輸入驗證與消毒
- 防範 OWASP Top 10 漏洞
- 安全的依賴套件管理（定期掃描 CVE）
- 使用參數化查詢防止 SQL Injection

## 合規性
- 遵循個資法 / GDPR 規範
- 敏感資訊不可硬編碼
- 實作完整的錯誤處理與日誌

## 程式碼審查
- 所有安全相關程式碼需雙人審查
- 使用靜態程式碼分析工具（SonarQube）
- 定期進行滲透測試

🤖 範本 3：自動化腳本憲章

# 自動化腳本開發憲章

## 設計原則
- 冪等性：重複執行結果一致
- 容錯性：優雅處理異常狀況
- 可觀測性：詳細日誌與進度回報
- 模組化：功能拆分便於重用

## 技術規範
- 語言：Python 3.11+ with type hints
- 錯誤處理：完整的 try-except-finally
- 參數驗證：使用 argparse
- 環境變數：敏感資訊不可硬編碼

## 執行標準
- 提供 --dry-run 模式（試運行）
- 支援斷點續傳機制
- 產生執行報告與摘要
- 記錄詳細的執行日誌

## 安全考量
- 限制檔案系統存取範圍
- 驗證所有外部輸入
- 不執行動態生成的程式碼

編寫需求規格

開啟 .claude/commands/speckit.specify，詳細描述功能需求。

📝 範本：功能需求規格

# 功能需求規格

## 專案目標
開發一個網路設備配置產生器，協助網路工程師快速產生標準化的設備配置檔。

## 使用者故事
作為一個網路工程師，我希望能夠：
- 透過網頁表單輸入設備基本資訊
- 選擇設備類型（FortiGate/Aruba/Cisco）
- 自動產生符合公司規範的配置檔
- 下載配置檔或複製到剪貼簿

## 核心功能

### 1. 設備資訊輸入
- 主機名稱（hostname）
- 管理 IP 位址
- VLAN 配置
- 介面設定

### 2. 配置產生
- 根據範本自動產生配置
- 驗證 IP 位址格式
- 檢查 VLAN ID 範圍（1-4094）
- 套用安全性最佳實踐

### 3. 輸出功能
- 即時預覽配置檔
- 語法高亮顯示
- 一鍵複製功能
- 下載為 .txt 檔案

## 驗收標準
- [ ] 所有輸入欄位都有格式驗證
- [ ] 產生的配置符合廠商語法規範
- [ ] 支援常見的設備型號（至少 3 種）
- [ ] 配置中不包含預設密碼
- [ ] 頁面載入時間 < 2 秒
- [ ] 支援手機瀏覽器

## 非功能需求
- 效能：1000 次配置產生 < 5 秒
- 安全：輸入驗證防止 XSS
- 可用性：簡潔直覺的操作介面
- 維護性：模組化設計便於擴展新設備

使用 AI 代理執行

設定好文件後，在 Claude Code 中執行以下指令：

/speckit.plan - 讓 AI 產生技術規劃
/speckit.tasks - 拆解成具體的開發任務
/speckit.implement - 開始執行開發任務

使用技巧：
在對話中直接輸入斜線指令（例如 /speckit.plan）， AI 會自動讀取你寫好的文件，並根據內容進行規劃與開發。

💬 範例對話流程

你：/speckit.plan
AI：[讀取憲章和需求文件，產生詳細的技術規劃]

你：看起來不錯，請繼續
你：/speckit.tasks
AI：[將技術方案拆解為可執行的任務清單]

你：請開始實作第一個任務
你：/speckit.implement
AI：[開始撰寫程式碼並執行測試]

迭代與維護

開發過程中，隨時更新文件以反映最新的需求變更：

發現新需求時，更新 speckit.specify
調整開發規範時，修改 speckit.constitution
重新執行 /speckit.plan 產生新的技術方案
將文件納入版本控制（Git），方便團隊協作

團隊協作建議：
將 .claude/commands/ 資料夾加入 Git，讓所有團隊成員共享相同的開發規範與需求文件。

常見問題

我的專案已經開發到一半，還能用 Spec Kit 嗎？

可以！在現有專案中執行 specify init . --ai claude，然後根據現有程式碼補寫憲章和需求文件。這有助於後續的功能開發和維護。

一定要寫完所有文件才能開始開發嗎？

不一定。對於簡單的功能，可以只寫憲章和需求文件，跳過規劃和任務拆解步驟。 Spec Kit 的精神是「先思考後實作」，但使用方式可以靈活調整。

除了 Claude Code，還能用哪些 AI 工具？

Spec Kit 支援多種 AI 代理，包括 GitHub Copilot、Gemini CLI、Cursor 等。使用時在初始化指令中指定 --ai copilot 或其他選項即可。

文件要寫多詳細？

原則是「讓 AI 能理解並正確實作」。憲章文件約 100-200 行，需求文件約 50-150 行。重點是清楚描述「為什麼」和「做什麼」，而不是「怎麼做」（那是 AI 的工作）。

如何確保 AI 產生的程式碼符合規範？

在憲章文件中明確定義編碼規範、安全要求和品質標準。 AI 會參考這些原則來產生程式碼。建議搭配自動化測試和 Code Review 確保品質。

💫 Spec Kit 使用手冊