Specification-Driven Development (SDD) 规范驱动开发 · 面向 AI 辅助编程时代的软件工程实践 · 从需求到运维的全流程指南
本仓库是 SDD（Specification-Driven Development，规范驱动开发） 的落地实践指南，面向 AI 辅助编程、敏捷开发、多团队协作 场景。内容涵盖：需求规格化、契约先行、机器可读规范、与现有 BA/设计/开发流程的衔接，以及从试点到推广的落地步骤。
关键词：SDD 规范驱动开发 Specification-Driven Development 需求规格 AI 编程 软件工程 契约先行 需求分析 验收标准 多团队协作
- 一、SDD 设计理解摘要
- 二、落地要解决什么问题
- 三、规范形态：可执行、可验证的契约
- 四、当前组织上下文：多团队 + 传统开发模式
- 五、在多团队 + 传统模式下的落地思路
- 六、工具与自动化（可选、分步）
- 工具选型建议（Spec-Kit / OpenSpec / Speck / SpecPulse 对比与落地能力）
- 七、分阶段推进建议
- 八、与现有交付物的关系
- 九、如何判断落地成功
- 十、小结
SDD 不是传统 SDLC（Software Development Life Cycle ）里的某一个孤立阶段，而是一套覆盖从需求到运维全流程的软件工程范式，面向 AI 辅助编程时代。其核心起点在「需求分析收尾之后、编码开始之前」，并以结构化、可验证、机器可读的规范作为全流程唯一真相源，用于解决：
- 需求歧义
- 生成质量不稳定
- 代码与需求脱节
| 阶段 | 核心作用 |
|---|---|
| Specify 规格定义 | 把模糊需求转化为无歧义、可验证的功能规格；只定义「做什么/为什么/验收标准」，不涉及「怎么做」。 |
| Plan 方案规划 | 把业务规格转化为技术蓝图，定义技术约束与实现框架，衔接业务与 AI 代码生成。 |
| Tasks 任务拆解 | 拆解为可执行、可验证、可并行的最小任务单元，为 AI 和开发者提供明确执行路径。 |
| Implement 实现与验证 | AI 完成重复性代码生成，开发者聚焦验证与核心逻辑；以规格为准绳校验实现。 |
| Deliver 交付与集成 | 以规格为唯一依据完成验收、集成、上线，确保交付物符合业务规格。 |
| Iterate 迭代与运维 | 任何变更、修 bug、重构都先更新规格并评审，再基于新规格执行开发，实现「规格领先于代码，代码对齐规格」。 |
- 规范 = 全流程唯一真相源：业务需求、技术实现、测试验收、运维迭代均以规范为法定依据，消除多源信息割裂。
- 契约先行：先完整定义「做什么/不做什么、成功/失败标准、边界与异常、验收标准」，全角色评审通过后再进入设计与编码。
- 规范可执行、可验证、机器可读：结构化、可被机器解析、可自动化校验，避免模糊描述。
- 全角色协同共识：规范的定义与评审覆盖产品、开发、测试、运维、安全等，各角色从自身视角补充边界与验收标准。
- 风险左移：在规格阶段解决歧义与缺陷，降低编码与上线后的返工成本。
- 规范是核心资产，代码是衍生物：可复用、可迭代的是规范体系；规范稳定则可随技术栈/人员/AI 工具再生实现。
- 全生命周期闭环：任何修改都先更新规范、评审，再改代码/测试/文档，保证规范与实现永远同步。
将 SDD 从理念落到实际项目，需要回答：
- 规范长什么样：用什么格式、存在哪里、谁维护。
- 流程怎么跑：每个阶段谁在何时写/改规范、谁评审、如何与任务/代码挂钩。
- 如何「机器可读」：规范如何被工具和 AI 直接消费与校验。
- 如何可持续：团队愿意用、形成「改代码必先改规范」的习惯。
- 采用按功能/模块的规格文件（如 Markdown 固定结构或 YAML/JSON），存放在与代码同源的仓库（如
specs/或docs/sdd/），随代码做版本管理。 - 每个规格包含：功能 ID、名称、业务目标、范围（做/不做）、输入输出、成功/失败/边界/异常、可验收的条目。
- 每条验收写成「给定 X，系统应 Y，可观测/可验证为 Z」。
- 可检验方式包括：接口契约（请求/响应）、状态/数据可观测、可自动化断言（单元/集成/E2E）。
- 规范与测试用例可一一对应，甚至从规范生成测试骨架或用例描述。
- 规格中只写：输入、输出、规则、约束、验收条件。
- 不写：技术选型、类名、表结构、算法细节；这些放在 Plan 阶段的方案/设计文档中，并引用规格 ID。
- 需求：BA 提供 Word 版本需求说明书，通过会议与开发团队进行需求澄清。
- 设计：开发人员根据需求澄清结果完成软件开发总体设计与详细设计，并与 BA、测试人员进行评审。
- 开发与交付：编码 → 测试 → 交付 → 结项。
| 当前环节 | 对应 SDD 阶段 | 主要差距 |
|---|---|---|
| BA Word 需求 + 会议澄清 | Specify | 需求是「文档+口口相传」，未结构化、难机器读；澄清结果常只在会议纪要里。 |
| 总体设计 + 详细设计 + 评审 | Plan + 部分 Tasks | 设计与需求是两套东西，需求变更后设计/文档易不同步。 |
| 编码 | Implement | 开发依据的是设计文档和记忆，不是单一可追溯的规范。 |
| 测试、交付、结项 | Deliver / Iterate | 验收标准多在测试脑中或分散在 Word/Excel，与需求/设计没有强绑定。 |
核心问题：需求（Word）、设计（另一份文档）、代码、测试用例是多源、易脱节的；多团队时更容易出现各团队对同一需求理解不一致。
- 不推倒重来：不立刻废除 Word，也不要求一步到位上全套工具。
- 先立「规范」这一源：在现有流程中插入或强化「结构化规格」环节，使其逐步成为 BA、开发、测试、交付共同依据的唯一真相源。
- 规范从现有产出物里「长出来」：由 Word 需求 + 澄清结果 + 设计中的「做什么/验收标准」收敛成一份结构化规格。
- 保留 BA Word 需求，增加「规格产出」出口
- 需求澄清会议结束时，出口不仅是「会议纪要」，而是本迭代/本需求的结构化规格。
- 规格由 BA 主导起草，开发、测试在澄清阶段就参与补充（边界、异常、验收方式），澄清结果直接沉淀到规格中。
- 总体设计/详细设计与规格的关系
- 规格：只写「做什么、边界、验收标准」，不写技术实现。
- 设计文档：写「怎么做」，但必须显式引用规格（如「本设计实现规格 SPEC-xxx」）。
- 流程上：先有规格并评审通过，再写/评设计；设计评审时检查「是否覆盖规格、是否有未覆盖的验收条件」。
- 多团队协同
- 每个需求/特性有唯一规格 ID（如
SPEC-2025-xxx），跨团队共享。 - 若一个规格由多团队实现（如前端 + 后端），在规格中用「验收条件」按模块/接口拆清（如 AC-1 后端接口、AC-2 前端展示），各团队的设计与任务都引用同一份规格及对应 AC。
阶段 A：统一模板 + 固定位置（先做到「结构化」）
- 规格使用 Markdown 或 Word 固定模板，存放在统一位置（如 Git 仓库的
specs/或与项目同源的文档库），与代码同版本管理。 - 模板强制包含：
- 规格 ID、需求名称、业务目标
- 范围：做什么 / 不做什么
- 输入/输出/规则（列表或表格，避免大段散文）
- 成功/失败/边界/异常（逐条）
- 验收条件：每条为「给定 X，系统应 Y，可验证方式 Z」
- 评审要求：每条验收条件无歧义、可测试；开发与测试共同认可。
阶段 B：机器可读（在阶段 A 稳定后）
- 将模板固化为 YAML/JSON 结构 或带固定标题的 Markdown，由脚本解析。
- 用简单脚本：从规格生成「验收清单」、与任务/用例关联；CI 或门禁检查「改动是否关联规格」等。
- 起草：BA 基于 Word 与澄清结果写初版规格；开发、测试在需求澄清阶段即参与，将边界、异常、验收方式写入规格。
- 评审：规格评审 = BA + 开发（各团队接口人）+ 测试 + 必要时运维/安全；评审通过 = 规格冻结，作为本迭代「法定依据」。
- 变更：任何需求/范围变更，先改规格并再评审，再更新设计、任务、代码；多团队场景下，规格变更需通知到所有实现该规格的团队。
- 设计文档：仍由开发编写总体/详细设计，但必须在文档中写明「实现 SPEC-xxx」，并在设计评审时做「规格覆盖度」检查。
- 规格归属与拆分：按需求/特性建规格，不按团队建；一个需求一个 SPEC-ID。跨团队时在规格内用验收条件或模块拆成子项，明确对应团队或接口。
- 共享与可见性：规格存放在所有相关团队可访问的仓库或文档库，变更走评审与变更记录（如 Git 历史或变更日志）。
- 接口与契约：跨团队接口（API、事件、数据）在规格中以「契约」形式写清（输入输出、错误码、关键约束）；设计阶段再细化为技术协议。
- 会议节奏：保留「需求澄清会」，增加规格评审会（可在澄清后同迭代内）；设计评审增加「与规格一致性」检查；多团队时规格评审拉齐各团队代表。
- 规范即文件、即数据：统一结构（如 YAML/JSON schema 或约定好的 Markdown 结构），便于脚本解析；可从规范提取验收条件，生成测试清单或用例模板。
- 规范与代码/任务绑定：在 MR/PR 或任务单中强制关联规格 ID；CI 或门禁检查：若改动涉及某模块，则检查是否存在对应规格及近期评审记录。
- AI 使用方式：将「当前任务的规格片段 + 验收条件」作为上下文给 AI，减少歧义；代码审查以「是否符合规格 + 是否覆盖所列验收条件」为检查要点。
- 轻量工具：规范仓库 + 简单 CLI（如
sdd validate specs/校验格式，sdd trace SPEC-001列出关联 task/PR），不必先上重量级平台。
工具选型：对 OpenSpec、Spec-Kit、Speck、SpecPulse 等工具的对比分析及各自落地能力陈述，见 工具选型建议。结论：以本指南为基准在实际项目中落地时，优先采用 Spec-Kit（主用 Claude Code 时可选 Speck）；需要强契约与可执行验收时可结合 OpenSpec 作为补充。
- 选择需求边界清晰、周期可控的一个项目或一条业务线。
- 在「BA Word + 需求澄清」之后，增加「规格编写 + 规格评审」：用固定模板将澄清结果写成规格，BA + 开发 + 测试一起评审。
- 设计与开发阶段要求：设计文档、任务单写明「实现 SPEC-xxx」；测试用例能对应到规格中的 AC。
- 目标：验证「先有规格再设计/开发」是否减少返工、是否让多角色理解一致。
- 设计评审增加「是否覆盖规格全部 AC」的检查；在 MR/PR 或任务单中要求填写规格 ID（可先人工，再考虑脚本）。
- 试点稳定后，将「规格模板 + 评审出口标准」写成内部操作说明，推广到更多团队。
- 用户验收、结项检查时，以规格及其验收条件为验收清单，而非仅以 Word 或口头约定为准。
- 迭代/结项后的变更：要求先更新规格并评审，再排期开发，在多团队范围内形成习惯。
- 在 2～3 个团队都按规格开发后，再考虑规格的结构化格式、从规格生成验收清单、与任务/用例的关联、简单门禁等，避免一开始工具过重影响采纳。
| 现有交付物 | 建议关系 |
|---|---|
| Word 需求说明书 | 保留为 BA 的输入与背景，但法定依据逐步从 Word 转为「结构化规格」。 |
| 总体/详细设计 | 保留，但必须引用规格 ID，且先有规格再设计；设计描述「怎么做」，规格描述「做什么/验什么」。 |
| 会议与澄清 | 保留，但澄清的输出从「会议纪要」升级为「更新后的规格」。 |
| 测试与交付 | 验收清单与规格中的 AC 对齐；结项以规格为基准，便于多团队、多迭代的可追溯。 |
可从以下维度观察：
- 规范覆盖：核心功能是否有对应规格，规格是否有评审记录。
- 变更纪律：需求/bug/重构是否先改规格再开发（可通过 PR/需求单抽样检查）。
- 可追溯性：从规格能追溯到任务与代码，从代码能追溯到规格。
- 质量与返工：同类需求在采用 SDD 前后，返工率、线上缺陷是否下降。
- AI 使用效果（若已引入）：以规范为输入的生成任务，一次通过率或可用率是否提升。
- 规范：用「结构化 + 可验收」的规格文件（含清晰验收条件）作为唯一真相源，与代码同库、同版本。
- 流程：约定各阶段谁写/谁审、出口标准，并强制「先改规范再改代码」。
- 工具：规范即数据、可解析；与任务/PR 关联；用简单脚本或门禁保证规范不被绕过。
- 推进：从「Specify → Implement」小闭环试点开始，再叠加 Plan/Tasks，再固化交付与迭代规则，最后推广到多团队。
在「多团队 + BA Word + 传统设计/开发/测试」的现状下，不推翻现有流程，而是在现有流程中插入「结构化规格」这一层，并使其逐步成为全流程唯一依据，即可实现 SDD 的平稳落地与持续迭代。
- 产品 / BA：希望需求可追溯、少歧义、与开发/测试对齐
- 开发 / 架构：希望设计有据可依、与 AI 协作时输入更清晰
- 测试 / QA：希望验收标准明确、可自动化校验
- 项目经理 / 敏捷教练：希望引入规范驱动、契约先行的流程改进