spec-driven-development

面向 AI 软件工厂的规范驱动开发

一种软件构建方法：规范是 AI 代码生成流水线的可执行输入。工厂模式：规范是蓝图，AI Agent 是装配线，验证是质量控制，而各道关卡会在缺陷累积前将其拦截。

流水线概览

INCEPTION → [SPECIFY] → REVIEW → [DECOMPOSE] → REVIEW → [IMPLEMENT] → REVIEW → [VERIFY] → DELIVER
                 ↑         ↑          ↑            ↑           ↑           ↑          ↑         ↓
            Phase 1    Gate 1    Phase 2       Gate 2    Phase 3      Gate 3    Phase 4   Gate 4

每个阶段都必须通过一道关卡，才能开始下一阶段。在关卡 1 发现的缺陷只需几分钟即可修复；同样的缺陷若到关卡 4 才被发现，则需要数小时才能修复。

如果现有且已批准的 PRD、架构文档或问题集满足 references/factory-review-lanes.md 中规定的最低交接要求，请将其用作规范。 在整个工作流中，SPEC.md 指的就是这份权威规范；它不必是新建的文件，也不应成为与现有文档相冲突的副本。请验证内容等效性和可追溯性。 仅当格式专用脚本的预期输入格式适用时才运行；否则，请记录等效的内容检查结果以及任何缺失信息。

SDD 核心原则

1. 明确重要意图。 让规范易于阅读和测试。Agent 可以请求澄清；尚未解决的重要选项必须指定负责人，并且在到达其决策边界前，依赖该选项的工作必须暂停。
2. 完整性优先于简洁。 每一条缺失的验收标准都意味着一个缺失的功能。提前明确一个边界情况只需几分钟；等到生产环境中才发现，则可能需要数小时甚至数天。
3. 可测试性优先于描述性。 如果某条 AC 无法得出明确的通过或失败结论，那它就不是 AC——只是一个愿望。
4. 尽早通过关卡发现缺陷。 修复关卡 1（规范评审）中发现的缺陷只需几分钟。修复关卡 4（验收评审）中发现的缺陷则需要数小时——可能必须丢弃整个实现。
5. 规范是唯一事实来源。 每一项下游产物都应能追溯到规范。除非明确记录，否则任何偏差都是缺陷。
6. 规范为测试判定依据提供指导。 Gherkin 风格的 AC 可以转化为可执行用例，但仍需进行实现、覆盖率和判定依据评审。独立且保留未公开的场景有助于发现可见示例中的缺口。

加载指南

参考资料	加载时机	文件
SDD 概述与理念	需要理解“为什么”——软件工厂的比喻、SDD 与传统需求的区别，以及核心原则：规格是可执行输入，而非沟通产物	references/sdd-overview.md
AI 工厂流水线	需要了解完整的 5 阶段流水线，包括各阶段的输入、输出和转换规则；或者要从头设计一条新流水线	references/ai-factory-pipeline.md
工厂评审通道	需要将行为验收与可维护性分开，或调整现有规划产物	references/factory-review-lanes.md
规格质量关卡	已编写 SPEC.md，需要在 Gate 1 之前进行验证——了解区分优秀规格与含糊规格的 7 道关卡	references/spec-quality-gates.md
评审记录与假设	需要将评审结论绑定到候选版本、跟踪暂定选择，或关闭延期处理的发现项	references/review-records.md
阶段关卡方法论	正在运行评审关卡（4 种中的任意一种），需要决策标准、结论格式和升级路径	references/phase-gate-methodology.md
方法论选择矩阵	需要决定哪种规格方法论（BDD、Formal、DbC、OpenAPI、ADR）适合当前情况——了解各自的适用场景及 AI 就绪度评级	references/methodology-matrix.md
AI 规格中的 NFR 编码	需要以机器可读格式表达非功能需求（性能、安全性、可观测性）	references/nfr-encoding.md
格式转换	需要在不同规格格式之间映射——Gherkin ↔ OpenAPI ↔ SPEC.md ↔ JSON Schema——或将人工编写的 PRD 转换为适用于 AI 的规格	references/format-translation.md
批评与权衡	需要决定“何时不”使用 SDD——了解坦诚的局限性：规格瓶颈、垃圾进垃圾出、偏移、规格过度或不足，以及形式化方法的成本	references/critiques-and-tradeoffs.md
完整示例——完整的 SPEC.md	想查看一份完整实现的规格，以校准输出的详尽程度——示例展示了规范的 AC 格式、边缘情况枚举、NFR 阈值、数据契约，以及密码重置功能的假设	references/example-spec.md

方法论快速选择

不确定哪种规格方法论适合你的情况？使用此快速参考表（加载 references/methodology-matrix.md 查看完整内容）：

关注点	选择	AI 就绪度	生成格式
REST API 契约	OpenAPI	非常高	YAML/JSON 规格
事件/消息架构（Kafka、RabbitMQ）	AsyncAPI	高	YAML/JSON 通道规格
行为需求（系统的行为）	BDD / Gherkin	高	包含 Given/When/Then 的 .feature 文件
接口正确性（前置条件/后置条件/不变量）	契约式设计	非常高	代码中的断言
分布式系统正确性（一致性、协议）	TLA+ / Alloy	非常高（范围较窄）	数学模型
架构决策（选择 X 的原因）	ADR	中	结构化 Markdown
系统结构（方框与连线）	C4 Model	中高	PlantUML / 结构化文本
原始利益相关者意图	用户故事	低（需要细化）	“作为……我想要……”

组合方法： 大多数系统需要组合使用其中 3–4 种方法。REST API 使用 OpenAPI，事件流使用 AsyncAPI，关键行为使用 Gherkin 场景，跨团队接口边界使用 DbC 断言。

模板

模板	流水线阶段	文件
SPEC.md	阶段 1 — 规范编写（SPECIFY）。首先编写此文件：问题、范围、用户故事、验收条件、边缘情况、非功能性需求、数据契约	templates/SPEC.md
FACTORY-REVIEW.md	任务集成与发布验收——针对同一候选版本分别给出行为和工程方面的结论	templates/FACTORY-REVIEW.md
REVIEW.md	关卡 1-4 — 阶段关卡评审。在每次关卡转换时使用：规范评审、计划评审、实现评审、验收评审	templates/REVIEW.md
TASK-PLAN.md	阶段 2 — 工作分解（DECOMPOSE）。从已批准的规范中提取：任务组、依赖关系图、每项任务的验收条件、实现指令	templates/TASK-PLAN.md
VERIFICATION.md	阶段 4 — 验证（VERIFY）。实现完成后填写：验收条件通过/失败矩阵、合规性评分、包含修复方案的失败档案	templates/VERIFICATION.md

脚本

脚本	运行时机	文件
spec-quality-check.sh	编写或编辑 SPEC.md 后——验证所有必需章节是否存在（问题陈述、范围、验收条件、边缘情况、非功能性需求、假设）	scripts/spec-quality-check.sh
spec-to-tasks.sh	编写 TASK-PLAN.md 后——验证每项规范验收条件是否都有对应的任务引用	scripts/spec-to-tasks.sh

触发条件

在以下情况加载此技能：

• 你正在构建软件工厂——一种 AI Agent 通过带关卡的流水线，根据结构化规范生成代码的系统
• 你正在设计或优化由规范驱动实现的 AI 代码生成流水线
• 你需要编写供 AI Agent（而不仅是人类）使用的规范
• 你正在为项目评估规范方法（BDD、形式化方法、OpenAPI 优先）
• 你需要 SPEC.md、TASK-PLAN.md、REVIEW.md 或 VERIFICATION.md 的模板
• 你正在依据规范评审或验证 AI 生成的代码

快速参考：流水线步骤

步骤	操作	加载此参考资料	产出
1	复用已批准的等效规范，或编写 SPEC.md；补齐缺失的交接内容	references/spec-quality-gates.md（第 1 关前进行验证）	SPEC.md
2	对其支持的格式运行 spec-quality-check.sh；否则记录等效的内容检查	—	验证报告
3	第 1 关 — 根据质量关卡评审规范，并生成 REVIEW.md	references/spec-quality-gates.md、references/phase-gate-methodology.md	REVIEW.md（APPROVED/CONDITIONS/REJECTED）
4	将已批准的规范分解为 TASK-PLAN.md——每项任务都能追溯到规范章节	references/ai-factory-pipeline.md（分解阶段）	TASK-PLAN.md
5	第 2 关 — 评审任务计划的依赖关系是否属实、规范覆盖是否完整	references/phase-gate-methodology.md	REVIEW.md
6	实现每项任务——每个 Agent 会话处理一项任务	—	代码/PR
7	第 3 关 — 验证规范合规性；集成前记录独立的工程评审意见	references/phase-gate-methodology.md	REVIEW.md
8	根据所有验收条件运行验证，并生成 VERIFICATION.md	—	VERIFICATION.md
9	第 4 关 — 评审验证报告；仅在没有 BLOCKING 失败时交付	references/phase-gate-methodology.md	最终批准

如需深入了解方法论，请加载 references/sdd-overview.md（理念）或 references/ai-factory-pipeline.md（包含并行执行的完整流水线详情）。

流水线模式与入口点

从何处进入流水线

你不必总是从 SPECIFY 开始。根据你已有的内容，进入相应阶段：

你已有的内容	从此阶段进入	从以下内容开始
一个模糊的想法、一段对话或一份 PRD	阶段 1 — SPECIFY	templates/SPEC.md + references/format-translation.md
已获批准的产品范围及交互约定	阶段 1 — SPECIFY	product-design-and-ux 交接内容 + templates/SPEC.md
清晰且已批准的规格说明，或等效的规划文档	阶段 2 — DECOMPOSE	templates/TASK-PLAN.md + references/ai-factory-pipeline.md
规格说明 + 已批准的任务计划	阶段 3 — IMPLEMENT	带有各任务专属指令的任务卡
需要验证的现有代码	阶段 4 — VERIFY	templates/VERIFICATION.md

选择要使用的流水线模式

并非每项变更都需要通过全部 4 道关卡。请选择适合的模式：

模式	适用情况	要运行的关卡	规格说明深度
Full	从零开发的功能、多 Agent 协作、高风险变更、复杂接口	全部 4 道关卡	完整的 SPEC.md，包含 AC、NFR、数据约定和边界情况
Lightweight	简单的错误修复、已充分理解的变更、单文件编辑	关卡 1（轻量）→ 实现 → 关卡 4（轻量）	单个用户故事、1–3 个 AC、精简的 NFR
Minimal	原型、试验、探索、一次性代码	无 — 跳过正式关卡	迷你规格说明：1 段内容 + 3 个 AC。不需要 NFR 表或约定

经验法则： 如果你能在 60 秒内确定修复方案，且只涉及一个文件，就使用 Lightweight 模式。如果你不确定正确的解决方案是什么，就使用 Full 模式 — 关卡会尽早发现问题。

评审有效性与决策

使用 templates/REVIEW.md 记录候选项／约定的身份和已执行的证据； 使用 templates/SPEC.md 中的假设台账，并将其中的 ID 沿用到任务中。 相关变更会取代受影响的批准／证据。对后续影响重大的未决选择，必须在合并／发布前解决；低风险且可逆的选择，则可在现有授权范围内批量处理。稳定的发现项 ID 可保留后续跟进责任和已验证的关闭状态，而不会把每条建议都变成工单。 在这些交接节点阅读 references/review-records.md。BMad 负责待办事项／授权路由；harness engineering 负责运行时状态完整性和强制执行。

关卡恢复与修订

如果关卡拒绝了你的文档，会发生什么？流水线不会停止 — 它会继续迭代。

修订循环

Artifact submitted → Gate review → REJECTED or CONDITIONS
                                         ↓
                              Return to current phase
                                         ↓
                              Patch specific findings
                                         ↓
                              Resubmit for re-review
                                         ↓
                              APPROVED → next phase

如何修补，而非重写

每条发现都指出了一个范围明确、可修复的缺陷。请在发现所在位置进行修补：

发现严重程度	操作	示例
BLOCKING	立即修复 — 未解决前无法通过关卡	重写无法测试的 AC，改为明确的 PASS/FAIL 条件
CRITICAL	必须修复。如果发现项不超过 2 条，可记录例外后通过关卡	在用户故事部分补充缺失的边界情况
MINOR	如果可行，在进入下一阶段前修复。也可通过关卡，但需制定整改计划	在数据约定中添加请求／响应架构
INFO	记录为未来改进建议。通过关卡无需采取行动	建议采用其他字段命名方式

重新评审范围

修补后，由评审者确定评审范围：

• 完整重新评审： 判定为 REJECTED 时必须进行。重新评估整个文档，而不只是修补过的部分。
• 定向重新评审： 判定为 CONDITIONS 时可以进行。只评审受影响的发现项及其上下文。

局部修复的风险： 只修复 BLOCKING 发现项而忽略 CRITICAL 发现项，必然会在同一关卡再次被拒绝。在关卡 1 只需几分钟就能修复的 CRITICAL 发现项，如果到关卡 4 才被发现，就要花上数小时才能修复。

常见修订模式

失败模式	修复策略	预防措施
AC 不可测试（使用“应该处理”“应该高效”等模糊措辞）	为每条 AC 重新编写明确的 Given/When/Then 和二元结果	提交前执行 Gate 1 检查
缺少边界情况	为每个用户故事列出边界情况——每个故事至少 3 个	使用 spec-quality-gates 中的“五件可能出错的事”测试
NFR 模糊（“应该很快”“应该安全”）	替换为具体阈值和验证方法	使用 nfr-encoding 参考中的“我能为此编写测试吗？”测试
契约不完整（列出了端点，但没有架构）	为每个端点添加完整的请求/响应架构	提交前检查 Gate 5
范围蔓延（范围内项目含义不明确）	收紧范围说明并扩展范围外内容	使用“有人会纳入超出预期的内容吗？”测试

何时不使用

• 目标明确的单个小改动——跳过规格流程，直接实现； 首先对工作进行分类（参见 bmad）。
• 你需要围绕流程的控制平面协议——由谁负责确定意图、如何对工作进行分类、 何时自主执行是安全的、失败如何在不同层之间流转：使用 bmad 来处理意图契约、工作分类、自主执行门控和失败路由。SDD 提供规格格式 和门控机制；bmad 提供驱动整个工作的协议。
• 问题本身尚未验证——先转交给 product-discovery， 再基于未经审视的想法编写规格。

与工具无关的设计

此技能描述的是方法论，而不是特定工具。此流程适用于：

• Claude Code — 使用 CLAUDE.md 作为规格上下文，采用先规划后实现模式
• Cursor — 使用 Plan Mode + .cursorrules 提供规格上下文，使用 Agent Mode 实现
• Hermes Agent — 原生 SDD 流程（编写 → 审查 → 分解 → 验证）
• Devin / OpenHands — 根据规格生成的任务计划进行基于任务的实现
• GitHub Copilot Workspace — 以问题为驱动，将规格作为结构化的问题正文
• droid (Factory) — 根据规格分解生成任务卡片

这些模板与格式无关（markdown）。请根据所用工具调整交接机制（CLAUDE.md、.cursorrules、AGENTS.md）。

可执行的业务策略规格

将业务条款转化为可重复的资格判定或路由决策时，请阅读业务策略指南，并使用发布契约。保留策略所有者的权威性、独立的翻译保真度证据，以及明确的审查流程。从此技能目录运行 python3 scripts/business_policy.py --input evals/loan-request.json，进行只读的合成演示（Python 3.10+，标准库）；运行 python3 -m pytest scripts/test_business_policy.py 执行其契约测试（需要 pytest）。确定性执行并不能证明生成的解释正确。

对于业务规则，不要编造权威条款或所有者审批。必须要求完整且有效的事实（包括区分 false/zero）、经所有者审查的优先级、独立的源文档推导测试样例，以及依据权威事件日期/范围选定的唯一适用已发布版本。调用方提供的版本覆盖不得绕过适用性判定。事实缺失或解释未解决时，应转交审查。要求正数天数的策略必须拒绝零天。除非存在执行证据，否则应将测试报告为未运行；测试通过并不能保证翻译正确或实现 100% 合规。