Spec-Gatekeeper: 规范驱动开发工作流
当源代码编写被 spec-gatekeeper 阻塞时,或者当开始一个新特性、服务或重大重构时,请使用本技能。
规范驱动开发(SDD)通过在实现开始之前,要求达成一份经过共识的、结构化的架构契约,来确保清晰性并消除需求漂移。
工作流步骤
步骤 1: 执行4问题开发者访谈
在编写任何代码或创建存根文件之前,向开发者提出以下4个聚焦的问题(或从现有需求中提取答案并请求确认):
-
范围与安全:
- 此任务的核心目标和明确的非目标是什么?
- 涉及哪些架构组件或系统边界?
- 有哪些安全、权限、认证或沙箱约束?
-
数据契约:
- 准确的数据模式、API接口、类型和协议形态是什么?
- 精确的输入参数和预期的输出载荷是什么?
-
边界情况与韧性:
- 关键故障模式、网络/IO中断以及异常输入有哪些?
- 必须实施哪些错误处理、验证和回退机制?
-
验收标准:
- 哪些确定性的验证矩阵和测试用例定义了“完成”?
- 每个验收标准将如何被验证?
步骤 2: 草拟 SPEC.md
创建或更新位于项目根目录(<repo_root>/SPEC.md)下的 SPEC.md。
必需的结构
规范文件必须满足以下要求:
- 大小要求: 至少包含 300 字节 的实质性内容。
- 标准章节标题: 代码块外的一到三级 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: 开发者签署与实现
- 将草稿
SPEC.md提交给开发者审查并明确签署。 - 一旦
SPEC.md已提交且有效(>= 300 字节,包含所有4个部分),spec-gatekeeper钩子将自动允许编写实现源代码文件。