【工具】Spec驱动开发（Specification Driven Development, SDD）解析

为什么需要 SDD

传统“代码先行、文档事后”的开发方式在大模型时代的问题被放大：AI 易误解意图、输出不稳、改动不可追溯，返工成本高。

SDD目前尚无严格定义，但它的核心思想可以概括为：

1
“让规范（specification）成为开发过程中的中心实体，使人和 AI 都以此为唯一事实源（single source of truth）。”

简言之，SDD 并非全新的方法论，而是对“生成式 AI 参与软件开发”这一趋势的系统化回应。它探讨的问题是：当 AI 能够读懂并据此生成代码时，我们是否应当以规范为起点重新组织开发流程？

规范驱动开发（Specification-Driven Development, SDD） 要求先写清楚要做什么和验收标准，再让人和 AI 严格按规范实现，把文档提升为一等公民。

背景脉络与提出者

  • “Specification-Driven Development” 没有单一权威定义，它继承了“先定义契约/接口再实现”的工程传统，与 API First、契约测试、TDD/BDD 等理念一脉相承。
  • 大模型编码兴起让“规范先行”成为显性需求。
  • GitHub 的 Spec-Kit、Fission AI 的 OpenSpec，以及多代理框架 BMAD 等项目强化了 SDD 的术语和流程，使其从“工程常识”演化为可复用的工作流。
  • 核心主张：规范是输入和审查基线；接口/契约先于实现；验收标准前置；让 AI 严格受规范约束。

SDD 是什么：一套“先约定、后实现、可验证”的工作方式

  1. 文档即契约：规范写清 What/Why/约束，成为设计、实现和评审的共同基线。
  2. 接口优先：先定义 API/模块接口、输入输出、边界条件，再编码，便于并行开发和松耦合。
  3. 渐进细化：从目标 → 澄清 → 方案 → 任务 → 验收 → 实现，避免陷入技术细节前就做决策。
  4. 验收前置：规范中直接写验收场景，测试从规范派生，形成闭环。
  5. 可追溯性：规范、任务、实现、测试之间可映射，利于审计和复盘。

SDD三个层次

根据 Martin Fowler 团队的观察，当前关于 SDD 的实践大致可分为三个层次，分别体现出规范在开发生命周期中的不同角色：

  • Spec-first（规范先行）在这一层次上，开发流程以撰写规范为起点。开发者首先以结构化方式描述系统需求、接口和行为，然后再由人工或 AI 编写代码。此时，规范主要用于“指导实现”，其地位类似于传统的软件需求规格说明书（SRS），但通常更加可执行化。
  • Spec-anchored（规范锚定）该层次的特点是：规范不仅在初始阶段使用，而且在后续维护与扩展过程中持续存在。代码与规范之间保持双向关联，任何修改都需要在两者之间保持一致。这一模式强调演进过程中的一致性管理。
  • Spec-as-source（规范即源）这是最激进的一种形态。在此模式下，开发者直接编辑规范，而代码由生成式 AI 自动生成并更新。代码文件通常包含提示信息（如 // GENERATED FROM SPEC - DO NOT EDIT），明确指出源文件来自规范而非人工撰写。此时，“源代码”的地位实际上被“规范”取代，开发的本质变成了规范工程（spec engineering）。

三层AI参与度和自动化程度也逐层提升。

与 TDD、BDD 的关系

  • TDD 用代码层测试断言描述行为，SDD 在更高层写文档+接口定义，适合组合使用。
  • BDD 更偏用户视角场景，SDD 可嵌入 BDD 场景格式，但更全面覆盖需求到实现。

快速流程示意（30 分钟上手）

  1. 写目标与接口草稿、边界/约束；
  2. 补疑点与非目标；
  3. 拆出任务，附验收条件；
  4. 实施与对齐；
  5. 回写规范，归档成正式文档。

SDD 的适用与限制场景

✅ 适用：

  • 多团队并行协作、大型系统；
  • 跨模块改造、大功能开发；
  • API/平台型项目（需提前 Mock/定义）；
  • 从零构建时需要骨架/共识的场景；
  • 需要审计/知识沉淀/可回溯过程的系统。

🚫 不适用或可简化：

  • 脚本、小改动、快速验证原型；
  • 模糊探索期（只记录关键约束即可）。

当前SDD面临术语不统一、AI服从性不足等挑战，但“先定规范再开发”已能提升代码一致性与效率，未来需解决规范语义统一、AI规范服从性、自动一致性验证以推动普及。

三种代表性工具与用法

快速对比表

工具 定位/擅长 节奏与粒度 适用场景
BMAD 多角色 AI 模拟敏捷团队，产出需求/架构/任务/实现 重、全周期，偏大版本 0→1、重构、架构升级
OpenSpec 轻量变更驱动，每次变更都有提案/任务/归档 轻、线性，小步快跑 维护、接口新增
Spec-Kit 结构化七步流程，产出规范与任务库 中等偏重，强调一致性 新项目规划、大功能设计

BMAD（多代理敏捷团队模拟）

定位：用多角色 AI（Analyst/PM/Architect/Dev/QA）模拟团队，从需求到交付。

典型步骤：

1) /analyst 需求分析（生成项目简报/目标）；
2) /pm 编写 PRD、划分 Epic/优先级；
3) /architect 设计架构/接口/数据；
4) /sm 生成用户故事与任务、验收标准；
5) /dev 实现与测试；循环迭代。

优点：流程完整、角色分明、能输出较完整的需求/架构/任务包、适合大版本启动；
限制：流程重，偏好从零开始的大版本，不适合高频迭代、小改小修；需上下文长期维护，增量小改动时显得“过度工程”。

什么时候用：新产品、跨团队大版本、需要完整需求-架构-实现链条时优先。

简单示例：

1
2
3
4
5
6
7
8
9
# 安装（一次性）
npx bmad-method install

# 触发一次完整迭代
/analyst 目标：做一个支持扫码点餐的小程序，核心是菜单浏览与下单
/pm 输出 PRD，列出必做/可选功能和优先级
/architect 选择技术栈（UniApp + Node + MongoDB），设计主要接口
/sm 给出下一轮 Sprint 的用户故事与任务
/dev 实现任务并附单元/集成测试

OpenSpec（轻量规范驱动）

定位：维护期每次功能/接口变更都走 Proposal → Tasks → Apply → Archive 流程,让每次变更都有提案、任务和归档，保持“规范即现状”。

目录结构：

  • openspec/specs/ 当前生效规范
  • openspec/changes/ 变更中提案（proposal.md、tasks.md 等）

典型步骤：

1) Proposal：/openspec:proposal 或 CLI 生成变更目录与 proposal.md（Why/What/Impact）；
2) Review & Align：补充/澄清约束，用 MUST/SHOULD 固化；
3) Plan & Tasks：自动生成 tasks.md（含测试任务），必要时添加 design.md；
4) Apply：/openspec:apply 按任务顺序实现并勾选；
5) Archive：迁移变更目录到 archive，并把新增/修改的 spec 合并进 specs/。

优点：流程轻、贴合增量迭代；接口友好、Mock 与测试自动生成；归档让规范与代码同步；
限制：不含架构设计、不负责 0→1 全局设计，复杂决策需人工介入或需配合 Spec-Kit/BMAD 立骨架；提案粒度过大时质量易下降。

什么时候用：小步快跑的功能迭代、接口新增、线上缺陷修复后的补规范。

示例（现有项目新增导出报表接口）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 初始化（一次性）
npm install -g @fission-ai/openspec@latest
openspec init

# 创建提案
/openspec:proposal 新增 GET /reports/export 接口，支持店铺ID和时间范围，导出 CSV

# 补充约束（在 proposal/design 中）
- MUST 时间范围不超过 7 天
- MUST Content-Type: text/csv，流式输出避免 OOM

# 生成任务
/openspec:tasks

# 实施
/openspec:apply   # AI 按 tasks 逐项实现并勾选

# 归档并合并规范
/openspec:archive

Spec-Kit（结构化规范生成器）

定位：为 0→1 项目或大功能提供结构化七步，明确项目目标、接口、方案与任务，产出可执行的规范与任务库，强调前后一致性。

七步（斜杠命令）：/constitution（原则）→ /specify（需求）→ /clarify（澄清疑点）→ /plan（技术方案）→ /tasks（任务拆解）→ /analyze（一致性检查）→ /implement（按任务实现与测试）。

  • 优势：阶段清晰、可做跨文档一致性检查；AI/技术栈无关，可基于同一规范尝试多方案；形成可传承的知识库。
  • 局限：文档量大、上手成本高；小项目或快节奏需求可能不划算；需统一运行环境（如 Python/依赖）。
  • 什么时候用：新项目规划、跨模块大功能、需要规范沉淀和一致性检查的团队。

示例（新建“照片管理”项目）： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 安装 CLI
pip install spec-kit

# 初始化
specify init photo-manager --ai cursor

# 依次运行七步
/constitution 关注性能、易用性、可维护性，函数不超 50 行，单测覆盖率 80%
/specify 构建照片管理应用，支持拖拽整理、日期分组、平铺预览
/clarify （让 AI 提问并补充：导入方式、批量操作、删除策略等）
/plan 采用 Vite + vanilla JS，SQLite 存元数据，本地存储图片
/tasks （生成任务清单）
/analyze （检查 Spec/Plan/Tasks 一致性）
/implement （按任务顺序实现并带测试）

工具协同建议

  • “Spec-Kit 立骨架 + OpenSpec 管迭代”：前期用 Spec-Kit 输出 Constitution/Spec/Plan/Tasks，后续需求变更用 OpenSpec 的 Proposal → Tasks → Apply → Archive 保持规范常新。
  • “BMAD 做大版本 + OpenSpec 做小步”：大版本或架构升级用 BMAD 规划与设计，日常维护/小需求用 OpenSpec 快速交付。
  • 借鉴而不堆叠：已用 BMAD 可吸收 Spec-Kit 的 Clarify/Analyze；已用 Spec-Kit 可用 OpenSpec 的归档保持规范-代码同步。

实战案例摘选

1) API 平台新增导出能力（OpenSpec）

  • 背景：已有交易报表系统，需要新增 CSV 导出，前端和后端由不同团队负责。
  • 做法：用 /openspec:proposal 固化需求与约束（时间范围 ≤7 天、Content-Type: text/csv、流式输出防 OOM），生成 tasks.md。
  • 成果：后端先按规范提供 Mock，前端并行开发；上线后按 tasks.md 勾选并归档，规范与实现同步。

2) 数据标注工具重构（BMAD → OpenSpec）

  • 背景：旧版前端性能差，需重构并分期上线。
  • 做法：先用 BMAD 产出完整 PRD、架构、数据流设计和验收标准；每个迭代用 OpenSpec 拆变更（提案→任务→归档）。
  • 成果：大方向与接口在 BMAD 阶段一次对齐，后续小步交付；避免“边重构边改需求”带来的返工。

3) 0→1 设备管理系统（Spec-Kit）

  • 背景：要做 IoT 设备管理，接口多、边界复杂，团队需要统一原则和一致性检查。
  • 做法：用 Spec-Kit 跑七步，明确非目标（不做 OTA）、性能约束（1 万设备秒级查询），并在 /analyze 阶段校验 Spec/Plan/Tasks 一致。
  • 成果：上线前发现两处接口与约束不一致（分页规则、告警阈值），提前修正；规范文档直接变成培训材料。

典型落地误区

  1. 规范写成“备忘录”，缺少验收场景
  • 现象：只有需求陈述，没有 BDD 场景，测试无法对齐。
  • 纠正：每条需求至少列 1 个“WHEN/THEN”场景，覆盖主流程与关键边界。
  1. 粒度失衡：要么太大要么太碎
  • 现象：一个提案覆盖多个子系统，导致任务不可验证；或拆得过碎，审阅成本高。
  • 纠正：以“可独立验收的接口/用户旅程”作为粒度；大版本先用 BMAD/Spec-Kit 定骨架，再用 OpenSpec 小步落地。
  1. 规范与代码不同步
  • 现象：上线后不回填，规范失真，AI/新人拿到旧信息。
  • 纠正：把“归档/更新 spec”作为发布前的必做检查，可在 CI 或 PR 模板中加入核对项。
  1. 只写需求不写约束/非目标
  • 现象：AI 按默认假设补充实现，导致超范围或性能踩坑。
  • 纠正：显式写“非目标”“已知风险/约束”（比如 SLA、限流、数据上限），避免隐含假设。
  1. 工具堆叠、流程过重
  • 现象：同时跑 BMAD + Spec-Kit + OpenSpec，重复产出，团队疲劳。
  • 纠正：按阶段选 1-2 个核心工具，明确交接点；重在“规范可执行、可验证”，而非工具数量。

落地建议

  • 选痛点切入：维护质量痛点先试 OpenSpec，需求对齐痛点试 Spec-Kit，大版本规划试 BMAD，先小范围试点再推广。
  • 流程本地化：约定哪些文档必审、哪些可简化；把 Proposal/Tasks 接入现有评审或 PR 模板。
  • 规范先行习惯：提交代码前更新规范；新增功能必须补接口定义与验收场景；测试用例对齐规范。
  • 规范实时性：设定归档/合并规则，CI 或合并检查规范是否更新，避免“文档滞后”。
  • 人机协同：AI 负责生成/执行，人工把关架构与风险；关键决策、验收与测试需人工确认。
  • 持续复盘：记录使用成本与收益，跟进工具版本/最佳实践，按团队节奏调整流程深度。

结语

规范先行，是让 AI 真正可信的关键。SDD 提倡“先对齐、再实现”，让文档成为共识入口，也让自动化从规范出发，带来更可靠的交付、更少的返工。

延伸资料