Community生产力与协作github.com

spec-gatekeeper

在编写源代码之前,通过一个简洁的4问题开发者访谈,草拟一份确定的4部分SPEC.md(范围与安全、数据契约、边界情况、验收标准),从而确保开发流程的清晰性并消除需求漂移。

spec-gatekeeper 是什么?

spec-gatekeeper 是一个面向开发者与AI编码助手的技能,旨在推行“规范驱动开发”(SDD)工作流。它会引导开发者完成一个4个问题的访谈,分别覆盖范围与安全、数据契约、边界情况与韧性、验收标准,然后自动生成一份结构化的SPEC.md文件,确保在执行代码编写前,所有利益相关方对架构契约达成一致理解。该技能主要适用于Claude Code、Cursor、Codex等AI编码工具,帮助它们在开始实现之前获取完整的规范。通过强制要求SPEC.md至少包含300字节的有效内容、并使用特定的标题来涵盖四个必须的章节,spec-gatekeeper能够防止过早编写代码,减少后期重构成本,并提升最终交付质量。最终,开发者需审查并签署SPEC.md,随后系统会解除写代码的阻塞。

兼容平台~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. 边界情况与韧性:

    • 关键故障模式、网络/IO中断以及异常输入有哪些?
    • 必须实施哪些错误处理、验证和回退机制?
  4. 验收标准:

    • 哪些确定性的验证矩阵和测试用例定义了“完成”?
    • 每个验收标准将如何被验证?

步骤 2: 草拟 SPEC.md

创建或更新位于项目根目录(<repo_root>/SPEC.md)下的 SPEC.md。

必需的结构

规范文件必须满足以下要求:

  1. 大小要求: 至少包含 300 字节 的实质性内容。
  2. 标准章节标题: 代码块外的一到三级 Markdown 标题,必须分别匹配以下4个必需部分:
    • 范围与安全: 包含 Scope、Security、Architecture、Overview、Boundaries、Threat Model 或 Permissions 的标题。
    • 数据契约: 包含 Data Contract、Data Contracts、Schema、Schemas、Interface、Interfaces、API、Types、Payload 或 Protocol 的标题。
    • 边界情况: 包含 Edge Case、Edge Cases、Error Handling、Failure Mode、Failure Modes、Resilience、Constraints 或 Fallbacks 的标题。
    • 验收标准: 包含 Acceptance Criteria、Acceptance Test、Test Matrix、Verification、Testing、Definition of Done 或 Validation 的标题。

模板

# 规范: <特性或服务名称>

## 1. 范围与安全
### 目标与架构边界
- 详细的范围描述...
### 安全与威胁模型
- 权限检查和安全边界...

## 2. 数据契约
### 模式与接口
- 类型、API签名、请求/响应格式...

## 3. 边界情况与韧性
### 错误处理与回退
- 边界条件、输入验证、故障模式...

## 4. 验收标准
### 验证与测试矩阵
- AT-01: ...
- AT-02: ...

步骤 3: 开发者签署与实现

  1. 将草稿 SPEC.md 提交给开发者审查并明确签署。
  2. 一旦 SPEC.md 已提交且有效(>= 300 字节,包含所有4个部分),spec-gatekeeper 钩子将自动允许编写实现源代码文件。

相关技能