Community生產力與協作github.com

spec-gatekeeper

在編寫原始碼之前,先進行一個由 4 個問題組成的開發者訪談,並草擬一份確定性的 4 章節 SPEC.md(範圍與安全性、資料契約、邊緣案例、驗收標準)。

spec-gatekeeper 是什麼?

Spec-Gatekeeper 是一種規範驅動開發(SDD)技能,確保在開始實作任何功能、服務或重大重構之前,先建立並同意一份結構化的架構合約。它透過一個簡短的 4 問題開發者訪談來引導開發者定義範圍與安全性、資料契約、邊緣案例與恢復能力,以及驗收標準。訪談結束後,技能會自動草擬或更新專案根目錄下的 SPEC.md 檔案,要求至少 300 位元組的實質內容,並包含符合規範的章節目錄。這份規格書隨後會提交給開發者審核與簽核,只有當 SPEC.md 通過驗證(包含所有 4 個章節且大小符合)時,才會允許開始撰寫實作原始碼。此技能適用於任何需要確保實作與規格一致、降低溝通落差與技術債的開發環境,例如 Claude Code、Cursor 或 Codex 等 AI 輔助工具。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/dansierrasam79/spec-gatekeeper/tree/main/skills/spec-gatekeeper

Installed? Explore more 生產力與協作 skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Spec-Gatekeeper:規範驅動開發工作流程

當原始碼撰寫被 spec-gatekeeper 阻擋,或是要開始一個新功能、服務或重大重構時,請使用此技能。

規範驅動開發(SDD)確保在開始實作之前,先建立並同意一份結構化的架構合約,以釐清需求並消除規格偏移。


工作流程步驟

步驟 1:進行 4 問題開發者訪談

在撰寫任何程式碼或建立樁檔案之前,向開發者提出以下 4 個重點問題(或從既有需求中擷取答案並請求確認):

  1. 範圍與安全性:

    • 此任務的核心目標與明確的非目標是什麼?
    • 涉及哪些架構元件或系統邊界?
    • 有哪些安全性、權限、驗證或沙箱限制?
  2. 資料契約:

    • 確切的綱要、API 介面、型別與通訊協定格式是什麼?
    • 精確的輸入參數與預期的輸出酬載是什麼?
  3. 邊緣案例與恢復能力:

    • 主要的失敗模式、網路/I/O 中斷以及格式錯誤的輸入有哪些?
    • 必須包含哪些錯誤處理、驗證與備用機制?
  4. 驗收標準:

    • 定義「完成」的確定性驗證矩陣與測試案例是什麼?
    • 每個驗收標準將如何被驗證?

步驟 2:草擬 SPEC.md

在已解析的專案根目錄(<repo_root>/SPEC.md)中建立或更新 SPEC.md。

必要結構

規格檔案必須滿足以下條件:

  1. 大小要求: 至少 300 UTF-8 位元組 的實質內容。
  2. 標準章節標題: 程式碼區塊外的一級至三級 Markdown 標題,需與 4 個必要章節相符:
    • 範圍與安全性: 包含 範圍、安全性、架構、概覽、邊界、威脅模型 或 權限 等詞的標題。
    • 資料契約: 包含 資料契約、資料合約、綱要、綱要、介面、介面、API、型別、酬載 或 通訊協定 等詞的標題。
    • 邊緣案例: 包含 邊緣案例、邊界案例、錯誤處理、失敗模式、失敗模式、恢復能力、限制 或 備用方案 等詞的標題。
    • 驗收標準: 包含 驗收標準、驗收測試、測試矩陣、驗證、測試、完成定義 或 核可 等詞的標題。

範本

# 規格:<功能或服務名稱>

## 1. 範圍與安全性
### 目標與架構邊界
- 詳細的範圍描述...
### 安全性與威脅模型
- 權限檢查與安全性邊界...

## 2. 資料契約
### 綱要與介面
- 型別、API 簽章、請求/回應格式...

## 3. 邊緣案例與恢復能力
### 錯誤處理與備用方案
- 邊界條件、輸入驗證、失敗模式...

## 4. 驗收標準
### 驗證與測試矩陣
- AT-01:...
- AT-02:...

步驟 3:開發者簽核與實作

  1. 將 SPEC.md 草稿提交給開發者審查並進行明確簽核。
  2. 一旦 SPEC.md 被提交且通過驗證(>= 300 位元組且包含所有 4 個章節),spec-gatekeeper 鉤子將自動允許撰寫實作原始碼。

相關技能