進階用法與最佳實務

專案 Constitution 設計

Constitution（憲章）是整個 Spec Kit 工作流的核心基礎文件，位於 .specify/memory/constitution.md。它不僅定義技術架構與選型，更明確陳述專案的設計原則、命名慣例、測試策略與 AI 協作邊界。一份優質的 Constitution 能讓所有 AI 代理在執行任務時有一致的判斷依據，大幅減少需要人工介入糾正的次數。

使用 /speckit.constitution 指令可互動式產生或更新 Constitution，系統會自動將異動同步至所有依賴此文件的模板，確保一致性。

Constitution 如何約束 AI 決策

AI 代理在執行 speckit.implement 或 speckit.plan 時，會優先讀取 Constitution 中的約束條款。例如，若 Constitution 宣告「禁止使用 any 型別」，AI 就不會在生成的程式碼中引入該型別；若宣告「所有 API 端點須附單元測試」，任務清單便會自動包含對應的測試任務。這種設計讓規格約束從人工 review 提升為系統層級的強制執行。

Constitution 應視為「活文件」，隨專案演進定期修訂。建議在每個里程碑結束後執行 /speckit.constitution 回顧，確認現有原則仍然適用。

多功能並行開發的規格管理

大型專案往往需要多條功能線並行推進。Spec Kit 透過獨立的功能資料夾結構支援此場景：每個功能在 .specify/features/<feature-id>/ 下維護各自的 spec.md、plan.md 與 tasks.md，互不干擾。Constitution 則作為共享基礎，所有功能共同遵守。

.specify/
├── memory/
│   └── constitution.md          # 全域憲章
├── features/
│   ├── auth-module/
│   │   ├── spec.md
│   │   ├── plan.md
│   │   └── tasks.md
│   └── payment-flow/
│       ├── spec.md
│       ├── plan.md
│       └── tasks.md
└── templates/                   # 共用模板

並行開發時最常見的問題是功能之間的介面衝突。建議在各功能的 spec.md 中明確宣告對外暴露的 API 契約，並在 Constitution 中維護一份全域介面清單，讓 speckit.analyze 能跨功能偵測衝突。

規格版本控制：Git 與 Spec 協作

所有 .specify/ 目錄下的文件都應納入 Git 版本控制。這讓規格的演進歷程可追溯，也讓 Code Review 流程同時涵蓋「程式碼變更」與「規格變更」兩個維度。

每次新增功能，先提交 spec.md 的 PR，獲得審查後再開始實作
任務完成後同步更新 tasks.md 的狀態標記
里程碑結束後為 Constitution 打上 Git tag，例如 spec-v1.2
使用 branch 隔離實驗性規格，避免污染主線
在 CI 中執行 speckit.analyze，讓規格一致性成為合併門檻

將規格文件與程式碼放在同一個 commit 中，可讓未來的開發者（或 AI）透過 git log --follow 清楚理解每一行程式碼背後的設計意圖。

團隊 SDD 協作規範

規格驅動開發（SDD）在團隊環境中需要明確的角色分工與交接協議。以下是一套經過實戰驗證的協作規範：

角色職責建議：產品負責人撰寫初稿需求，技術負責人執行 speckit.clarify 補充細節，全員審查 spec.md 後再由 AI 生成 plan.md 與 tasks.md。實作由開發者或 AI 代理執行，QA 依 checklist 驗收。

每次執行 speckit.implement 前，應確認任務的「完成定義」（Definition of Done）已在 tasks.md 中明確記載，包含預期輸出、測試涵蓋率目標與效能基準。

speckit.analyze 深度使用

speckit.analyze 是一個非破壞性的跨文件一致性分析工具。它會比對 spec.md、plan.md、tasks.md 三者之間的邏輯關係，找出遺漏、衝突或過時的內容，並輸出結構化的分析報告。

# 分析單一功能
/speckit.analyze

# 分析輸出範例
[WARN] tasks.md 中的「建立快取層」任務在 plan.md 未見對應設計章節
[ERROR] spec.md 宣告支援 OAuth2，但 plan.md 僅設計 JWT 流程
[INFO] 所有 spec 驗收條件均有對應 task 覆蓋

建議將 speckit.analyze 整合進 Git pre-merge hook，讓每次合併前自動執行分析，確保主線上的規格文件始終保持一致。若報告出現 [ERROR] 等級警告，則阻止合併直到修正為止。

自訂 Checklist

speckit.checklist 指令可依據當前功能的規格內容，自動產生針對性的驗收清單。預設清單涵蓋功能正確性、邊界條件、安全性與效能四大面向，但你可以透過修改 .specify/templates/checklist-template.md 來客製化輸出格式。

在模板中使用 {{feature.name}} 插入功能名稱
使用 {{spec.acceptance_criteria}} 自動展開驗收條件
加入團隊特有的安全稽核項目，例如 OWASP Top 10 對照
針對不同類型任務（API、UI、DB migration）設計不同子模板

GitHub Issues 整合

speckit.taskstoissues 能將 tasks.md 中的任務一鍵轉換為 GitHub Issues，並自動設定標籤、里程碑與任務相依關係。這讓 Spec Kit 的規格管理與團隊的 Issue Tracker 無縫接軌。

# 執行前設定
GITHUB_TOKEN=your_token
GITHUB_REPO=owner/repo

# 執行指令
/speckit.taskstoissues

# 自動建立的 Issue 範例
Title: [Task] 建立使用者認證 API
Labels: spec-kit, backend, auth
Milestone: v1.0
Body: (自動附上 spec.md 中的相關驗收條件)

轉換後的 Issues 會保留與 tasks.md 任務 ID 的雙向連結，讓規格文件與 Issue 狀態保持同步，避免「規格說一套、Issue 做另一套」的落差。

大型專案規格層次設計

當專案規模成長至數十個功能模組時，單層的功能規格結構會變得難以管理。建議採用三層規格架構：系統層（Constitution）、領域層（Domain Spec）與功能層（Feature Spec）。

三層架構示意：Constitution 定義全域原則 → Domain Spec 定義各業務領域的架構決策（如「訂單領域使用事件驅動」）→ Feature Spec 定義單一功能的實作細節。每一層只對上一層負責， AI 代理在產生計畫時會從最具體的層次向上查找約束。

導入層次設計後，speckit.analyze 會自動偵測下層規格是否違反上層約束，並在分析報告中標示違規的規格章節與建議修正方向，讓大型團隊也能維持規格庫的整體一致性與可追溯性。