规范驱动开发 (SDD) 技能

引导用户使用 GitHub 的 Spec-Kit 进行规范驱动开发——这是一种将传统软件开发流程倒置的方法论，通过使规范可执行并直接生成可用的实现来工作。

核心理念

规范驱动开发强调：

意图驱动开发：先定义“做什么”，再考虑“怎么做”
丰富的规范创建：使用护栏和组织原则
多步细化：非一次性代码生成
原生 AI：高度依赖先进的 AI 能力

请记住：这是原生 AI 开发。规范不仅仅是文档——它们是可直接驱动实现的可执行人工制品。AI 代理使用它们生成与规范中定义的意图相匹配的工作代码。

验收标准：Gherkin 格式（必需）

每个 spec.md（或 specify.md）中的用户故事，除了其文字描述外，必须包含 Gherkin 风格的验收标准。 这适用于绿地开发和棕地开发，适用于每个用户故事，无论该人工制品是由 /speckit.specify 生成的，还是为不使用 CLI 生成模板的仓库手动编写的。文字描述说明故事内容；Gherkin 场景则精确说明如何验证——这正是使规范可执行而非描述性的关键。

格式——在每个用户故事下方直接使用围栏 gherkin 代码块，包含 1-4 个场景：首先是快乐路径，然后是针对该故事的重要边界/负面情况（而非规范中的所有边界情况——那些应属于规范自己的“边界情况”部分；仅包含与本故事相关的）。

Scenario: <简短、具体的名称——不要使用“快乐路径”>
  Given <前提条件 / 起始状态>
  When <参与者执行的单个操作>
  Then <可观察、可测试的结果>
  And <额外的结果，如果需要>

Scenario: <本故事的边界/负面情况>
  Given <前提条件>
  When <操作>
  Then <结果——“不应该发生什么”也是一个有效的 Then>

编写规则：

每个场景只包含一个 When。 多个操作意味着多个场景——这确保每个场景对应一个测试。
Then 必须是可观察的，而不是内部状态：使用“用户看到确认提示”，而不是“状态正确更新”。如果你说不出如何检查它，那它就没准备好。
重用规范自身的词汇。 Given/When/Then 步骤应使用与用户故事和功能需求相同的名词（资产名称、交易类型、字段名称），而不是意译。
不要将功能需求重新表述为 Gherkin。 验收标准验证故事；FRs 被单独追踪。重叠是可以的，但将每个 FR 都作为场景复制则不可以。
当一个故事有多个场景时，为场景编号以便追踪：Scenario: AC-1 — ...，Scenario: AC-2 — ...（对于单场景故事可选）。

总结时（10 点模板，“生成的内容”），需报告场景数量以及用户故事/成功标准数量，例如：“5 个用户故事（11 个 Gherkin 场景），8 个成功标准。”如果用户故事缺少验收标准，在移至 /speckit.plan 之前，需在“🔍 重要待审事项”下标记。基于没有验收标准的故事制定的计划往往会低估测试需求。

行为性 ACs：仅适用于 LLM 参与循环的故事

Gherkin 假设一次运行就能决定通过/失败。当模型输出决定结果时，这就不适用了：非确定性故事的一次成功运行几乎证明不了什么。对于这些故事，需在 Gherkin 块下添加一个行为性 ACs 块。

仅当故事的可观察结果依赖于模型输出时才生成它。 示例：提示词、系统提示词、任务、技能文件或工具描述发生变化；模型选择操作、判断或裁决某事，或编写面向用户的文本；模型或其参数发生变化。不要生成 对于确定性代码、已存储数据的 UI 渲染、管道，或故事中包含模型调用但其输出未被断言的情况。如有疑问，请先提一个问题；不要投机性地添加该块。没有 LLM 参与循环的故事的规范不应包含任何行为性 ACs，也不应包含空占位符。

格式：每个符合条件的故事一个块，直接放在其 Gherkin 块之后。

**行为性 ACs** (LLM 参与循环：<模型决定的内容>)
- **案例：** <N> 个案例，位于 `<案例集路径>`，来自 <真实失败 / 追踪 / 转录>；仅使用合成输入填补空白，绝不使用合成预期输出
- **运行次数：** k = <k> 每个案例（≈ 3 / 预期失败率；未知时为 20–30）
- **通过标准：** <指标> ≥ <阈值> 在 k 次运行中，优于基线的幅度超过噪声（与当前版本进行配对比较）
- **评分器：** 代码检查 | LLM 裁判（二元，每个失败模式一个）| 人类；裁判还需说明其验证：TPR/TNR ≥ 0.9（最低 0.8）基于保留的人类标签，或清楚标明“未验证”
- **命令：** `<运行该命令并打印通过率、成本和延迟的单个命令>`

规则：

只有真正的模型运行才算数。 模拟、关键字仿真或预测分数都不是结果。如果无法运行（成本、密钥），则说明故事为未评估。不要伪造数字。
优先使用代码评分器。 仅对代码无法检查的内容使用裁判。
Gherkin 仍然适用。 Gherkin 场景涵盖确定性外壳（创建了工件、保持了护栏）。行为性 ACs 则涵盖模型的行为。
plan.md 包含评估信息： 案例集位置、运行命令、每次运行的成本以及运行时机（每个 PR 运行，或者如果成本高昂则在合并前运行）。

总结时，需分别计数，例如：“5 个用户故事（11 个 Gherkin 场景，其中 2 个包含行为性 ACs）”。在“重要待审事项”下标记任何缺少该块的 LLM 参与循环故事，以及任何标记为“未验证”的裁判。

快速决策树

这是新项目吗（绿地开发）？

→ 请参阅绿地开发工作流，了解完整的 6 步流程

这是现有代码库吗（棕地开发）？

→ 请参阅棕地开发工作流，了解逆向工程和集成指南

需要安装帮助？

→ 请参阅安装指南，了解设置和故障排除

安装快速开始

推荐（持久化安装）：

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（可执行的任务分解）
  - 棕地工作流的分析报告
读取并总结
- 读取相关工件
- 提取关键信息：
  - 对于 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% | 已完成：5 个功能中的 1 个 | 依赖关系：database-setup ✅

**您的选项：** [A] 继续规划 [B] 修改需求 [C] 解释 JWT 选择 [D] 显示完整状态

何时跳过总结

仅在以下情况下跳过总结步骤：

用户明确要求“跳过总结”或“自动运行所有步骤”
重新运行命令且没有工件变更
命令失败或产生错误（此时应进行故障排除）

此工作流的好处

消除“黑箱”感：清晰解释生成的内容及其原因
实现早期反馈：在执行前发现误解
保持敏捷性：使用结构化格式快速审查，而非冗长的审批流程
建立信任：用户可以看到 AI 的推理和决策及其理由
提供上下文：功能状态让用户始终了解项目的整体进展

功能状态追踪

混合方法

在每个 SDD 命令之后，在总结中包含一个简短的功能状态行。根据请求通过 /speckit.status 提供详细状态。

简短状态行格式

在每个总结末尾包含以下内容：

📊 **功能状态：** [当前功能名称]（[阶段]）→ 下一步：[下一个功能名称]
   进度：[●●●○○] [X]% | 已完成：[N] 个中的 [总计] 个功能 | 依赖关系：[Dep] ✅/⏸️

阶段值：

指定中（完成 20%）
规划中（完成 40%）
任务分解中（完成 60%）
进行中（完成 80%）
已完成（完成 100%）

进度指示器：

使用实心圆 (●) 表示已完成的阶段
使用空心圆 (○) 表示待完成的阶段
根据阶段计算百分比

详细状态仪表板

当用户请求完整状态（选项 D）或运行 /speckit.status 时，显示以下内容：

📊 项目功能状态仪表板

🎯 当前功能
├─ [功能名称]（[阶段] - [X]% 完成）
│  ├─ ✅ 需求已指定
│  ├─ 🔄 实现计划进行中
│  ├─ ⏸️ 任务未开始
│  └─ ⏸️ 实现未开始
│  阻塞项：[无 | 描述]
│  依赖关系：[功能名称] ✅

✅ 已完成功能（[N] 个）
├─ [功能 1]（100% 完成）
└─ [功能 2]（100% 完成）

📋 即将推出的功能（[N] 个）
├─ [功能 3]（依赖：[当前功能]）
└─ [功能 4]（依赖：[功能 3]）

⚠️ 被阻塞的功能

…

[为翻译而截断]

工作流参考

由于文件空间限制，此技能参考以下工作流文件以获取详细的步骤指令：

绿地开发工作流：新项目的完整 6 步流程
棕地开发工作流：针对现有代码库的逆向工程和集成指南
安装指南：详细的安装、故障排除和环境变量配置

这些工作流文件包含开发人员成功使用此技能所需的逐步骤说明。

Spec-Driven Development (SDD) 技能