Spec-Gatekeeper:規範驅動開發工作流程
當原始碼撰寫被 spec-gatekeeper 阻擋,或是要開始一個新功能、服務或重大重構時,請使用此技能。
規範驅動開發(SDD)確保在開始實作之前,先建立並同意一份結構化的架構合約,以釐清需求並消除規格偏移。
工作流程步驟
步驟 1:進行 4 問題開發者訪談
在撰寫任何程式碼或建立樁檔案之前,向開發者提出以下 4 個重點問題(或從既有需求中擷取答案並請求確認):
-
範圍與安全性:
- 此任務的核心目標與明確的非目標是什麼?
- 涉及哪些架構元件或系統邊界?
- 有哪些安全性、權限、驗證或沙箱限制?
-
資料契約:
- 確切的綱要、API 介面、型別與通訊協定格式是什麼?
- 精確的輸入參數與預期的輸出酬載是什麼?
-
邊緣案例與恢復能力:
- 主要的失敗模式、網路/I/O 中斷以及格式錯誤的輸入有哪些?
- 必須包含哪些錯誤處理、驗證與備用機制?
-
驗收標準:
- 定義「完成」的確定性驗證矩陣與測試案例是什麼?
- 每個驗收標準將如何被驗證?
步驟 2:草擬 SPEC.md
在已解析的專案根目錄(<repo_root>/SPEC.md)中建立或更新 SPEC.md。
必要結構
規格檔案必須滿足以下條件:
- 大小要求: 至少 300 UTF-8 位元組 的實質內容。
- 標準章節標題: 程式碼區塊外的一級至三級 Markdown 標題,需與 4 個必要章節相符:
- 範圍與安全性: 包含
範圍、安全性、架構、概覽、邊界、威脅模型或權限等詞的標題。 - 資料契約: 包含
資料契約、資料合約、綱要、綱要、介面、介面、API、型別、酬載或通訊協定等詞的標題。 - 邊緣案例: 包含
邊緣案例、邊界案例、錯誤處理、失敗模式、失敗模式、恢復能力、限制或備用方案等詞的標題。 - 驗收標準: 包含
驗收標準、驗收測試、測試矩陣、驗證、測試、完成定義或核可等詞的標題。
- 範圍與安全性: 包含
範本
# 規格:<功能或服務名稱>
## 1. 範圍與安全性
### 目標與架構邊界
- 詳細的範圍描述...
### 安全性與威脅模型
- 權限檢查與安全性邊界...
## 2. 資料契約
### 綱要與介面
- 型別、API 簽章、請求/回應格式...
## 3. 邊緣案例與恢復能力
### 錯誤處理與備用方案
- 邊界條件、輸入驗證、失敗模式...
## 4. 驗收標準
### 驗證與測試矩陣
- AT-01:...
- AT-02:...
步驟 3:開發者簽核與實作
- 將
SPEC.md草稿提交給開發者審查並進行明確簽核。 - 一旦
SPEC.md被提交且通過驗證(>= 300 位元組且包含所有 4 個章節),spec-gatekeeper鉤子將自動允許撰寫實作原始碼。