規格驅動開發 (SDD) 技能
引導使用者使用 GitHub 的 Spec-Kit 進行規格驅動開發——這是一種翻轉傳統軟體開發的方法論，讓規格成為可執行的產出物，並直接產生可運作的實作。
核心哲學
規格驅動開發強調：
- 意圖驅動開發：先定義「做什麼」再談「怎麼做」
- 豐富的規格建立：使用防護措施與組織原則
- 多步驟精煉：非一次性程式碼生成
- AI 原生：高度依賴先進的 AI 能力
切記：這是 AI 原生開發。規格不只是文件——它們是直接驅動實作的可執行產出物。AI 代理會根據規格中所定義的意圖，產生符合需求的運作程式碼。
驗收條件：Gherkin 格式（必要）
每個 spec.md（或 specify.md）中的使用者故事都必須附帶 Gherkin 風格的驗收條件，以及其散文敘述。這適用於 Greenfield 與 Brownfield 專案，適用於每個使用者故事，無論該產出物是由 /speckit.specify 產生，還是為不使用 CLI 產生模板的儲存庫手動撰寫。散文說明故事的內容；Gherkin 情境則精確說明如何驗證——這就是讓規格「可執行」而非「描述性」的關鍵。
格式——在每個使用者故事下方，使用圍籬代碼塊 gherkin，包含 1 到 4 個情境：先放快樂路徑，然後是對該故事重要的邊界/負面案例（非規格中所有邊界案例——那些屬於規格自身的「邊界案例」段落；這裡只放與該故事相關的）。
Scenario: <簡短、具體的名稱——請勿使用「happy path」>
Given <前提條件/起始狀態>
When <行動者採取的單一行動>
Then <可觀察、可測試的結果>
And <額外結果，如有需要>
Scenario: <該故事的邊界/負面案例>
Given <前提條件>
When <行動>
Then <結果——「不應該發生什麼」也是有效的 Then>
撰寫規則：
- 每個情境一個
When。多個行動代表多個情境——這讓每個情境對應一個測試。 Then必須是可觀察的，而非內部狀態：「使用者看到確認通知」，而非「狀態正確更新」。如果你無法說明某個人如何檢查它，代表尚未準備好。- 重複使用規格本身的詞彙。 Given/When/Then 步驟應使用與使用者故事和功能需求相同的名詞（資產名稱、合約類型、欄位名稱）——而非改寫。
- 不要將功能需求直接重寫為 Gherkin。 驗收條件是驗證 故事；FR 則分開追溯。重疊沒問題，但將每個 FR 都複製成一個情境則不恰當。
- 當一個故事有多個情境時，為情境編號以便追蹤：
Scenario: AC-1 — ...、Scenario: AC-2 — ...（單一情境的故事可選擇性使用）。
進行摘要時（使用 10 點模板，「產生了什麼」），請回報情境數量，與使用者故事/成功條件數量並列，例如 「5 個使用者故事（11 個 Gherkin 情境），8 個成功條件。」 如果某個使用者故事缺少驗收條件，請在「🔍 重要待審項目」中標記，然後再移動到 /speckit.plan——基於缺乏驗收條件的故事所制定的計畫，通常會導致測試規格不足。
行為 AC：僅適用於 LLM 參與的故事
Gherkin 假設一次執行就能決定通過/失敗。但當模型的輸出決定結果時，這就不適用了：一個非確定性故事的一次綠色執行幾乎無法證明任何事。對於這類故事，請在 Gherkin 區塊下方新增一個行為 AC（Behavioural ACs） 區塊。
僅當故事的觀察結果取決於模型的輸出時才產生它。 範例：提示詞、系統提示詞、任務、技能檔案或工具描述變更；模型選擇動作、判斷或決定某件事，或撰寫使用者面對的文字；模型或其參數變更。請勿對確定性程式碼、已儲存資料的 UI 呈現、基礎設施，或故事中包含模型呼叫但其輸出未被斷言的情況，產生此區塊。 有疑問時，先問一個問題；不要投機性地新增區塊。一個完全沒有 LLM 參與故事的規格，就不會有任何行為 AC，也不要有空的佔位符。
格式：每個符合資格的故事一個區塊，直接放在其 Gherkin 之後。
**行為 AC**（LLM 參與：<模型決定的內容>）
- **案例：** <案例數量>，來自 `<案例集的路徑>`，取自 <真實失敗 / 軌跡 / 逐字稿>；僅在需要填補缺口時使用合成輸入，絕不使用合成預期輸出
- **執行次數：** k = <每次案例的執行次數>（≈ 3 / 預期失敗率；未知時為 20–30）
- **通過門檻：** <指標> ≥ <閾值> 在 k 次執行中，超越基線且差距大於雜訊（與目前版本進行配對比較）
- **評分者：** 程式碼檢查 | LLM 評審（二元，每個失敗模式一個）| 人類；評審也需說明其驗證方式：在保留的人類標籤上 TPR/TNR ≥ 0.9（最低 0.8），或直接標明「未驗證（UNVALIDATED）」
- **指令：** `<一個可執行並輸出通過率、成本和延遲的指令>`
規則：
- 只有真實的模型執行才算數。 Mock、關鍵字模擬或預測分數都不是結果。如果無法執行（成本、金鑰問題），請標明該故事為「未評估（UNEVALUATED）」。不要偽造數字。
- 優先使用程式碼評分者。 只有在程式碼無法檢查的情況下，才使用 LLM 評審。
- Gherkin 仍然適用。 Gherkin 情境涵蓋確定性的外殼（產出的成品、守住的護欄）。行為 AC 則涵蓋模型的行為。
plan.md承載評估設定： 案例集位置、執行指令、每次執行成本，以及執行時機（每次 PR 執行，或僅在合併前執行，如果成本高昂）。
進行摘要時，請分開計算，例如 「5 個使用者故事（11 個 Gherkin 情境，其中 2 個包含行為 AC）」。在「重要待審項目」下標記任何缺少行為 AC 區塊的 LLM 參與故事，以及任何標記為 UNVALIDATED 的評審。
快速決策樹
這是新專案（Greenfield）嗎？
→ 請參閱 Greenfield 工作流程 了解完整的 6 步驟流程
這是現有程式碼庫（Brownfield）嗎？
→ 請參閱 Brownfield 工作流程 了解逆向工程與整合指引
需要安裝說明嗎？
→ 請參閱 安裝指南 了解設定與疑難排解
快速安裝
推薦（永久安裝）：
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
一次性使用：
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
驗證：
specify check
如需詳細安裝選項、疑難排解與環境變數，請參閱安裝指南。
支援的 AI 代理
適用於：
- ✅ Claude Code
- ✅ GitHub Copilot
- ✅ Gemini CLI
- ✅ Cursor
- ✅ Qwen Code
- ✅ opencode
- ✅ Windsurf
- ✅ Kilo Code
- ✅ Auggie CLI
- ✅ CodeBuddy CLI
- ✅ Roo Code
- ✅ Codex CLI
- ✅ Amp
- ⚠️ Amazon Q Developer CLI（不支援斜線指令的自訂引數）
產出物摘要與回饋循環
關鍵工作流程：在任何 SDD 指令產生或修改產出物之後，自動遵循此回饋循環，以保持使用者參與：
每個指令完成後
-
偵測產出物變更
- 識別哪些產出物被建立或修改：
constitution.md（專案原則）spec.md（需求規格）plan.md（技術實作計畫）tasks.md（可執行任務分解）- Brownfield 工作流程的分析報告
- 識別哪些產出物被建立或修改：
-
讀取並摘要
- 讀取相關產出物
- 提取關鍵資訊：
- 針對 constitution.md：核心原則、編碼標準、限制條件
- 針對 spec.md：主要需求、使用者故事（及其 Gherkin 驗收條件）、成功條件
- 針對 plan.md：技術棧選擇、架構決策、里程碑
- 針對 tasks.md：任務數量、主要任務類別、相依性
- 針對分析報告：當前模式、技術債、整合點
-
呈現結構化摘要（使用下方的 10 點模板）
- 展示產生了什麼以及原因
- 用理由突出最重要的決策
- 包含品質指標與注意事項
- 保持摘要重點明確且可行
- 每個部分使用清晰標題
-
包含功能狀態（混合方式）
- 每個摘要中包含簡短狀態行
- 使用
/speckit.status按需提供詳細狀態 - 請參閱下方的「功能狀態追蹤」章節
-
提供回饋選項
- 選項 A：「看起來不錯，繼續下一步」
- 選項 B：「我想修改 [特定章節]」
- 選項 C：「套用這些變更重新產生：[使用者輸入]」
- 選項 D：「解釋為什麼做出 [特定決策]」
10 點摘要模板
在任何 SDD 指令完成後，使用此結構化格式：
## ✅ [指令名稱] 已完成 - 以下是剛剛發生的事
### 🎯 主要決策（前 3 項）
1. [決策] - **理由：** [為何選擇此項]
2. [決策] - **理由：** [為何選擇此項]
3. [決策] - **理由：** [為何選擇此項]
### 📋 產生了什麼
- [產出物 1]：[內容簡短說明]
- [產出物 2]：[內容簡短說明]
### 🔍 重要待審項目（前 3 項）
1. [需要檢查的關鍵項目及其重要性]
2. [需要驗證的重要細節及其潛在影響]
3. [需要考慮的邊界案例及其對設計的影響]
### ⚠️ 注意事項（前 2 項）
- [潛在問題或陷阱] - **如何避免：** [指引]
- [常見錯誤] - **如何避免：** [指引]
### 🔄 這讓下一步可以做什麼（2 個選項）
- **選項 1：** [下一步] - 最適合：[條件]
- **選項 2：** [替代步驟] - 最適合：[條件]
📊 **功能狀態：** [當前功能名稱]（[階段]）→ 下一步：[下一個功能]
進度：[●●●○○] [X]% | 已完成：[N] / [總數] 功能 | 相依性：[狀態]
**您的選項：** [A] 繼續 [B] 修改 [C] 進一步解釋 [D] 顯示完整狀態
範例：增強型摘要（/speckit.specify 之後）
## ✅ Specify 已完成 - 以下是剛剛發生的事
### 🎯 主要決策
1. **認證方式：JWT 令牌** - 理由：無狀態架構、水平擴展性佳、業界標準
2. **密碼要求：12 個字元以上且具複雜性** - 理由：在安全性（NIST 指南）與可用性之間取得平衡
3. **工作階段逾時：24 小時** - 理由：Web 應用程式的標準，在安全性與使用者便利性之間取得平衡
### 📋 產生了什麼
- `.speckit/features/user-auth/specify.md`：完整需求，包含 5 個使用者故事（12 個 Gherkin 驗收條件情境）、8 個成功條件、3 個邊界案例
### 🔍 重要待審項目
1. **密碼重設流程** - 驗證電子郵件需求是否與您的基礎設施相符（SMTP 伺服器、範本）
2. **多因子驗證** - 目前標記為「未來增強」；可能需要納入 MVP
3. **速率限制** - 設定為每 15 分鐘 5 次登入嘗試；考慮是否符合您的安全政策
### ⚠️ 注意事項
- **未指定電子郵件服務相依性** - 如何避免：將電子郵件服務加入 plan.md 的相依性中
- **使用者資料的 GDPR 合規** - 如何避免：檢視資料保留與使用者刪除需求
### 🔄 這讓下一步可以做什麼
- **選項 1：** 執行 `/speckit.plan` 來設計技術實作 - 最適合：需求看起來沒問題
- **選項 2：** 修改 specify.md - 最適合：您需要調整需求或新增功能
📊 **功能狀態：** user-authentication（已規格化）→ 下一步：profile-management
進度：[●●○○○] 40% | 已完成：1 / 5 功能 | 相依性：database-setup ✅
**您的選項：** [A] 繼續進行規劃 [B] 修改需求 [C] 解釋 JWT 的選擇 [D] 顯示完整狀態
何時跳過摘要
僅在以下情況跳過摘要步驟：
- 使用者明確要求「跳過摘要」或「自動執行所有步驟」
- 重新執行指令但產出物無變更
- 指令失敗或產生錯誤（此時應進行疑難排解）
此工作流程的好處
- 消除「黑箱」感：清楚說明產生了什麼以及原因
- 實現早期回饋：在實作前就發現誤解
- 保持敏捷性：快速審查，使用結構化格式，無需冗長的核准流程
- 建立信任：使用者看到 AI 的推理過程與決策理由
- 提供脈絡：功能狀態讓使用者了解專案整體進度
功能狀態追蹤
混合方式
每次執行 SDD 指令後，在摘要中包含簡短的功能狀態行。使用 /speckit.status 按需提供詳細狀態。
簡短狀態行格式
在每個摘要結尾包含以下內容：
📊 **功能狀態：** [當前功能名稱]（[階段]）→ 下一步：[下一個功能名稱]
進度：[●●●○○] [X]% | 已完成：[N] / [總數] 功能 | 相依性：[相依項目] ✅/⏸️
階段值：
規格化中（Specifying，20% 完成）規劃中（Planning，40% 完成）任務分解中（Tasking，60% 完成）實作中（In Progress，80% 完成）已完成（Complete，100% 完成）
進度指示符：
- 已完成階段使用實心圓（●）
- 待完成階段使用空心圓（○）
- 根據階段計算百分比
詳細狀態儀表板
當使用者要求完整狀態（選項 D）或執行 /speckit.status 時，顯示：
📊 專案功能狀態儀表板
🎯 當前功能
├─ [功能名稱]（[階段] - [X]% 完成）
│ ├─ ✅ 需求已規格化
│ ├─ 🔄 實作計畫進行中
│ ├─ ⏸️ 任務尚未開始
│ └─ ⏸️ 實作尚未開始
│ 阻礙：[無 | 說明]
│ 相依性：[功能名稱] ✅
✅ 已完成功能（[數量]）
├─ [功能 1]（100% 完成）
└─ [功能 2]（100% 完成）
📋 即將進行功能（[數量]）
├─ [功能 3]（相依於：[當前功能]）
└─ [功能 4]（相依於：[功能 3]）
⚠️ 受阻功能
…
[為簡潔起見已截斷]