规范驱动开发（SDD）团队实践指南
版本 ：v2.0
适用对象 ：有传统开发经验、接触过少量Vibe Coding的中高级工程师团队
配套示例：Taskify------团队任务管理平台
一、什么是SDD
1.1 一句话定义
SDD（Specification-Driven Development，规范驱动开发） 是一种将"结构化规范"作为全流程唯一真相源的软件开发方法论。规范成为可执行的工件，直接生成工作实现，而非仅仅作为指导性文档。
SDD的核心哲学是 "先定规范，后写代码" ------在让AI写任何一行代码之前，先把"做什么"和"为什么"定义清楚。
1.2 SDD vs. Vibe Coding
| 维度 | Vibe Coding | SDD |
|---|---|---|
| 起点 | "帮写一个XXX功能" | 先写规范文档，再让AI实现 |
| 真相源 | 代码本身 | 规范文档（Markdown） |
| 维护方式 | 改代码 | 改规范→重新生成代码 |
| 可追溯性 | 差，需求与代码脱节 | 好，每行代码都能追溯到规范 |
| 适用规模 | 原型、<1000行代码 | 生产级、中大型项目 |
| 团队协作 | 差，依赖个人与AI的"感觉" | 好，规范是团队共享的"语言" |
OpenSpec的哲学是 "fluid not rigid, iterative not waterfall" （流动而非僵化，迭代而非瀑布），强调SDD不是回归瀑布式开发，而是让规范成为AI辅助开发的稳定锚点。
1.3 SDD的三个认知层级
根据Thoughtworks分析师Birgitta Böckeler的划分，SDD存在三个递进层级：
- Level 1：自然语言规范 ------ 用Markdown写需求文档，AI据此生成代码
- Level 2：结构化规范 ------ 规范包含Gherkin场景、JSON Schema等机器可读元素
- Level 3：可执行规范 ------ 规范本身就是可执行的契约
本指南覆盖Level 1和Level 2，这是大多数团队落地SDD的起点。
二、主流SDD框架选型
目前社区最主流的两个开源SDD框架：
| 维度 | GitHub Spec Kit | OpenSpec |
|---|---|---|
| 出品方 | GitHub | Fission-AI |
| 核心理念 | 通过Constitution（项目宪法）编码跨领域规则 | 轻量迭代，无需事先写Constitution |
| 工作流 | Constitution → Specify → Clarify → Plan → Tasks → Implement | Propose → Apply → Archive |
| 适用场景 | 受监管行业、需要强制合规的团队 | 大多数AI辅助开发场景，开箱即用 |
| 上手难度 | 中等 | 低 |
| AI工具兼容 | 30+种AI编码助手 | 25+种 |
选型建议：
- 团队在金融、医疗等受监管行业，或需要强制执行跨领域规则（如"每个API必须有OpenAPI文档"）→ Spec Kit
- 希望快速上手、迭代灵活，或有大量遗留代码需要渐进式接入 → OpenSpec
本文以OpenSpec为流程参考，因为其更轻量，适合传统团队首次引入SDD。Spec Kit的流程类似，只是多了一个Constitution（项目宪法）前置步骤。
三、总体协作原则（四条铁律）
-
需求由人定义，AI辅助结构化 ：人是需求的唯一源头，AI负责格式化和查漏补缺，严禁AI自行假设业务规则。
-
规范即真相：规范是唯一的真相源，代码只是规范的表达。任何代码修改必须追溯到规范变更。
-
变更走闭环：需求变更走"规范→设计→任务→代码"的完整闭环，禁止绕过规范直接改代码。
-
多角色会审是最终防线：验证阶段需要测试、架构、运维、性能等多角色共同参与，识别AI可能产生的幻觉。
四、标准SDD工作流程（五阶段）
┌─────────────────────────────────────────────────────────────────────────────┐
│ SDD 五阶段工作流 │
├─────────────────────────────────────────────────────────────────────────────┤
│ Phase 0: 上下文初始化 → Phase 1: 规范撰写 → Phase 2: 技术方案规划 │
│ （人主导，AI辅助） （人主导，AI辅助） （人主导，AI出方案） │
│ ↓ ↓ ↓ │
│ 建立项目宪法与上下文 定义"做什么/为什么" 定义"怎么做" │
│ ↓ ↓ ↓ │
│ Phase 3: 任务拆解 → Phase 4: 代码实现 → Phase 5: 验证与归档 │
│ （人定优先级，AI拆解） （AI主导编码） （多角色人共同裁决） │
│ ↓ ↓ ↓ │
│ 拆解为可执行任务 TDD：测试→实现→重构 多角色审阅→归档 │
└─────────────────────────────────────────────────────────────────────────────┘"主导方"的含义 ：指在该阶段承担主要认知劳动和决策责任的一方 。所有阶段均由人的指令触发------这是SDD作为工作范式的本质，人是最终的责任主体。
Phase 0：上下文初始化（Context Initialization）
等价操作 ：Claude Code的
/init/ Spec Kit的/speckit.constitution/ OpenSpec的openspec init
| 维度 | 具体内容 |
|---|---|
| 主导方 | 人 |
| 辅助方 | AI |
| 人的职责 | ① 执行初始化命令（如/init、openspec init）；② 审核并修正 AI生成的context.md和constitution.md------确认技术栈清单、补充遗漏的架构约束、调整不合适的规则（如"测试覆盖率必须≥80%"是否适用）；③ 回答AI提出的待澄清问题。 |
| AI的职责 | ① 扫描项目结构、技术栈（检测package.json/pyproject.toml/go.mod等）；② 识别现有架构模式、关键依赖、部署配置；③ 生成context.md初稿，列出已识别信息和待澄清问题；④ 基于扫描结果草拟项目constitution.md（编码规范、测试要求、安全规则等）。 |
| 协作时序 | 人（触发）→ AI（扫描+生成）→ 人（审核修正）→ AI（根据反馈更新）→ 人（最终确认）。这是一个迭代环。 |
| 标准操作步骤 | ① 人在项目根目录执行/init（Claude Code）或openspec init（OpenSpec）或/speckit.constitution（Spec Kit）；② AI自动扫描并生成初稿；③ 人逐条审核，修正错误、补充遗漏；④ 人将确认后的文件提交到版本库；⑤ 后续功能开发不再重复此阶段，仅在技术栈发生重大变化时增量更新。 |
| 阶段出口标准 | 人确认context.md和constitution.md内容准确无误，已提交版本库。 |
Phase 1：规范撰写（Specification）
核心定位：人是需求的唯一发起者，AI是"结构化秘书"与"苛刻的检视者"。
| 维度 | 具体内容 |
|---|---|
| 主导方 | 人 |
| 辅助方 | AI |
| 人的职责 | ① 主动输入 ：无论手打需求、口述录音转文字，还是直接复制粘贴传统PRD文档 ，第一个动作必须由人完成；② 定义业务边界 ：明确用户故事、不可违背的约束；③ 做决策：针对AI提出的所有补问，给出确定性答复（是/否/具体数值）。 |
| AI的职责 | ① 被动接收与格式化 ：将人投喂的PRD/草稿转化为标准化的spec.md（含FR/NFR/Gherkin场景）；② 主动查漏（补问） ：AI不能修改人的意图，但必须扫描未定义的边界 （例如："PRD未提及密码错误次数限制，建议默认5次，请确认"）；③ 生成差异摘要：向人汇报"根据PRD提炼出了哪些核心需求"，供人确认是否有遗漏。 |
| 协作时序 | 人（复制/撰写初始草稿）→ AI（格式化+提出补问清单）→ 人（逐一回答补问）→ AI（更新spec）→ 人（最终签字确认）。人驱动、AI反馈，AI严禁自行假设业务规则。 |
| 规范模板 | 见第五节模板库 |
| 阶段出口标准 | 人在spec.md上明确标注 "业务需求已确认" 。未获此签注，AI不得进入Phase 2。 |
Phase 2：技术方案规划（Design）
核心转变：人不再直接指定技术选型，而是咨询AI获取方案建议后人做决策。
| 维度 | 具体内容 |
|---|---|
| 主导方 | 人 |
| 辅助方 | AI |
| 人的职责 | ① 审阅AI生成的多套方案对比 ；② 做出最终决策 ------选择方案（或组合方案），记录决策理由；③ 补充组织约束（如"公司已有Redis集群，优先使用"）；④ 调整API设计细节（如字段约束、错误码定义）；⑤ 确认数据模型。 |
| AI的职责 | ① 发现阶段 ：执行只读探测，扫描代码库中相关模块、现有API模式、数据访问层实现；② 生成多套方案 ：基于探测结果和spec，提出2-3套技术方案，每套包含：架构选型、API设计草案、数据模型草案、优缺点分析、与现有系统的兼容性评估；③ 标注风险 ：识别各方案中的技术风险；④ 生成design.md草案，包含AI建议的推荐方案及理由。 |
| 协作时序 | 人（触发/speckit.plan）→ AI（探测+出方案）→ 人（审阅+决策）→ AI（根据决策更新design.md）→ 人（最终确认）。AI先出方案，人后决策。 |
| 被否决方案记录 | 人的决策过程中，必须记录被否决的方案及理由 ------这是可审计追溯的重要实践。AI负责将这些记录格式化到design.md的"架构决策"章节。 |
| 阶段出口标准 | 人解决design.md中所有待决策项，确认技术选型、API设计、数据模型无误。 |
Phase 3：任务拆解（Tasks）
| 维度 | 具体内容 |
|---|---|
| 主导方 | 人 |
| 辅助方 | AI |
| 人的职责 | ① 调整优先级 ：根据团队资源和业务紧急度，重新排序任务；② 标注风险任务 ：标记需要特别关注的任务；③ 分配负责人 （可选）；④ 确认任务粒度：过大的任务要求AI进一步拆分，过小的任务可以合并。 |
| AI的职责 | ① 暴力拆解 ：将design.md中的模块拆解为原子级任务（粒度15-60分钟）；② 计算依赖拓扑 ：自动标注任务依赖关系；③ 生成并行建议 ：识别可并行执行的任务组；④ 生成tasks.md完整草案，每个任务包含：描述、验收标准、预估时间、依赖项。 |
| 协作时序 | AI（拆解）→ 人（调优排序）→ AI（根据反馈更新）→ 人（最终确认）。人是调优者 而非创建者。 |
| 阶段出口标准 | 人确认所有任务都关联了对应的FR-XXX需求编号，需求覆盖率100%。 |
Phase 4：代码实现（Implement）------ TDD模式
核心定位：结合SDD契约与TDD红-绿循环，对抗AI的"幻觉通过率"。
| 维度 | 具体内容 |
|---|---|
| 主导方 | AI |
| 辅助方 | 人 |
| AI的职责 | ① 测试先行（红灯） ：针对当前任务的GIVEN-WHEN-THEN验收标准，AI必须先编写可执行的单元/集成测试代码 ，运行后预期为失败（红灯）；② 最小实现（绿灯） ：AI编写恰好满足测试的代码，运行后测试通过（绿灯）；③ 重构与规范化：在测试全绿的情况下，AI对代码进行结构优化，人的职责是监控重构是否破坏了测试。 |
| 人的职责 | ① 审查测试质量 ：检查AI写的测试是否真的覆盖了Spec中的异常分支 （而非只测成功路径）；② 处理AI卡顿 ：若AI连续3次无法写出使测试通过的代码，人介入提供算法思路提示 （如"试试用递归代替循环"），但人依然不直接改实现代码；③ 拒绝过绿测试 ：如果AI写的测试本身就极弱（随便写点代码就能过），人有权退回要求AI补强测试用例 ；④ 安全与性能审查：检查AI是否引入安全漏洞（SQL注入、硬编码密钥）或性能陷阱。 |
| 协作时序 | 人（触发Implement）→ AI（写测试→跑失败）→ AI（写实现→跑通过）→ AI（重构）→ 人（审查测试覆盖率和实现逻辑）。 |
| 是否符合SDD | 高度符合 。SDD的GIVEN-WHEN-THEN验收标准本身就是测试用例的契约 。将TDD引入SDD，恰好将"规范验收"转化为"红-绿-重构"的可执行闭环。Spec Kit的/speckit.implement命令也强调在实现过程中持续对照规范。 |
| 关键规则 | 人发现代码不合格时，不得直接修改代码------必须回到Phase 1或Phase 2修改规范，然后重新触发AI生成。直接改代码=破坏SDD闭环。 |
| 阶段出口标准 | 所有任务完成，单元测试通过，人审查通过。 |
Phase 5：验证与归档（Verify & Archive）------ 多角色门控
核心定位：AI不是最终裁判，而是"门控执行者"和"报告聚合器"；人类多角色团队做最终裁决。
| 维度 | 具体内容 |
|---|---|
| 主导方 | 人（多角色团队） |
| 辅助方 | AI |
| AI的职责 | ① 硬性门控（Hard Gate） ：静态对照spec.md，检查API签名、错误码、数据结构是否完全一致。发现硬性偏离时，AI直接阻止合并（Reject） ，生成《规范偏离清单》；② 生成多维度报告（软性评估） ：AI无权对性能、可维护性做出"通过/不通过"判断，但它必须生成原始数据报告 （如："接口平均响应时间XXX ms"、"新增依赖包大小XXX KB"、"圈复杂度变化趋势"）；③ 标注可疑幻觉 ：主动标记出代码中引用了上下文里不存在的第三方库或未定义的常量，供人类排查。 |
| 人类多角色团队的职责 | 这不是一个人的战斗，而是多角色会审 ： • 测试工程师 ：审阅E2E测试报告，确认业务流全绿 • 架构师 ：审阅AI的《偏离清单》，判断是否允许"技术债偏离"（如为了性能暂时违反规范） • 运维工程师 ：审阅资源消耗报告、新增环境变量清单 • 性能分析师 ：审阅P95响应时间、数据库连接池水位 • 所有人协作识别幻觉：共同确认AI生成的代码是否存在"看起来很美但逻辑错误"的幻觉 |
| 归档动作 | 仅在人类团队全部署"批准"意见后 ，人点击确认，AI执行自动归档（将变更合并到主规范库）。 |
| 协作时序 | 人（发起验证）→ AI（生成门控报告+多维数据）→ 人类多角色团队（审阅报告）→ 人（裁决：通过/打回/有条件通过）→ （若通过）AI（自动归档）。 |
| 阶段出口标准 | 规范已归档，代码已提交，CI通过。 |
需求变更的闭环流程
当需求发生变化时（如"登录失败锁定时间从15分钟改为30分钟"）：
- 人 发起变更请求------人是唯一的变更触发器。
- AI 自动定位到
spec.md中的对应NFR，修改数值。 - AI 自动检查
design.md中的配置项是否需要联动修改，标注改动点。 - AI 根据新规范，自动修改涉及的代码（仅修改锁定时间变量，不动其他逻辑）。
- 人运行回归测试，确认修改生效。
- AI更新归档记录。
关键约束：AI只负责"执行规范修改"，绝不主动"优化"业务规则。
五、规范文档模板库
5.1 规范文档（spec.md）模板
markdown
# 功能规范：[功能名称]
## 元信息
- **作者**：
- **创建日期**：
- **版本**：
- **关联Issue/PR**：
## 用户故事
> 作为 [角色]，我希望能 [目标]，以便 [价值]。
## 功能需求
### FR-001：[需求名称]
- **描述**：
- **输入**：
- **输出**：
- **验收标准**：
- GIVEN [前置条件]
- WHEN [触发动作]
- THEN [预期结果]
- AND [附加条件]
## 非功能需求
- NFR-001：[性能/安全/可用性要求]
## 边界与异常
- [场景1] → [预期行为]
- [场景2] → [预期行为]
## 依赖
- 外部依赖：[列出]
- 内部依赖：[列出]5.2 设计文档（design.md）模板
markdown
# 技术设计：[功能名称]
## 架构决策
### [决策名称]
- **决策**：
- **理由**：
- **被否决方案**：[方案] → [否决原因]
## API 设计
### [METHOD] [路径]
- **请求**：
- **响应**：
- **错误码**：
## 数据模型
```[语言]
[模型定义]安全考虑
-
安全措施1
-
安全措施2
技术选型
-
组件\]：\[选择\] → \[理由
5.3 任务清单（tasks.md）模板
markdown# 实施任务：[功能名称] ## 任务清单 - [ ] **T00X**：[任务描述] - 验收：[验收标准] - 预估：[时间] - 依赖：[任务编号] - 负责人：[可选]
六、从Vibe Coding到SDD：团队过渡策略
6.1 常见阻力与应对
| 阻力 | 应对策略 |
|---|---|
| "写规范太慢了" | 前期投入换后期稳定。研究表明，详尽规范能带来一致、可维护的生产级代码 |
| "规范写得太细，AI没发挥空间" | 规范定义WHAT ，AI决定HOW。规范越清晰，AI输出越准确 |
| "规范改起来比改代码还麻烦" | SDD的维护单位就是规范------改规范比改代码更符合"意图驱动"的理念 |
| "AI不按规范走怎么办" | 使用Phase 5的门控机制强制校验 |
| "我们是敏捷团队，SDD是不是瀑布？" | SDD不等于瀑布。规范可迭代完善，每个Sprint可产出增量规范 |
6.2 分阶段引入路线图
第一阶段：试点（2-4周）
- 选一个新功能（而非重构旧代码）作为试点
- 由1-2名工程师完整走一遍五阶段流程
- 目标是"走通流程"，而非"完美规范"
第二阶段：建立模板（1-2周）
- 基于试点经验，定制团队自己的规范模板
- 建立规范文档的存放位置和命名规范
- 配置CI/CD，加入规范合规检查
第三阶段：推广（4-8周）
- 所有新功能强制走SDD流程
- 旧功能维护：Bug修复可简化流程，新功能必须完整走
- 每周做一次规范评审会（替代部分代码评审）
第四阶段：常态化（持续）
- "改代码必先改规范"成为团队习惯
- 规范成为新成员入职的第一手资料
- 定期复盘优化规范模板和流程
6.3 何时可以跳过部分阶段
- Bug修复：跳过Phase 1-2，直接从Phase 3开始（但仍需在规范中记录）
- UI微调：可简化规范，但必须在规范中记录变更
- 探索性原型：先用Vibe Coding验证想法，确认后再用SDD重构
底线：任何进入生产环境的代码，必须有对应的规范文档。
七、参考资源
主流SDD框架
- GitHub Spec Kit：https://github.com/github/spec-kit
- OpenSpec：https://github.com/Fission-AI/openspec
- SDD落地实践指南：https://github.com/zhangluka/SDD
示例项目（可用于学习）
- Spec Kit Demo（Taskify） ：Spec Kit官方文档中的完整示例
- OpenSpec电商示例：基于电商场景的完整SDD实践
- Spec-driven-development-quickstart：中文SDD快速入门教程
关键阅读
- Birgitta Böckeler, "Understanding Spec-Driven Development: Kiro, spec-kit, and Tessl", martinfowler.com, 2025
- Thoughtworks技术雷达Vol.34（2025年11月，SDD评估级别）
- "Spec-Driven Development in 2025: The Complete Guide"
八、快速检查清单
每次开始一个新功能开发前，对照此清单：
- 是否已完成上下文收集（Phase 0）？
- 规范文档（spec.md）是否包含：
- 用户故事
- 功能需求（带验收标准）
- 非功能需求
- 边界与异常处理
- 设计文档（design.md）是否包含：
- 架构决策及理由
- API设计
- 数据模型
- 安全考虑
- 任务清单（tasks.md）是否：
- 拆解到15-60分钟粒度
- 标注了依赖关系
- 每个任务有验收标准
- 规范是否经过团队评审？
- 是否使用验证机制（如
/opsx:verify）验证了实现与规范的一致性？ - 完成后是否归档了规范？
九、总结：角色职责速查表
| 阶段 | 名称 | 主导方 | 辅助方 | 人与AI的核心关系 |
|---|---|---|---|---|
| Phase 0 | 上下文初始化 | 人 | AI | 人触发扫描，AI生成初稿，人审核确认 |
| Phase 1 | 规范撰写 | 人 | AI | 人提供需求素材，AI结构化与查漏补问 |
| Phase 2 | 技术方案 | 人 | AI | AI出多套方案对比，人做最终选型决策 |
| Phase 3 | 任务拆解 | 人 | AI | AI暴力拆解任务，人调整优先级与资源分配 |
| Phase 4 | 代码实现（TDD） | AI | 人 | AI写测试→写实现→重构，人审查测试质量与代码安全 |
| Phase 5 | 验证与归档 | 人（多角色） | AI | AI生成门控报告与多维数据，人类多角色团队共同裁决 |
团队一句话记忆点：
需求由人发起，规范由人确认；AI负责格式化与查漏，决不负责任何业务假设。测试先行是规范的红绿灯；多角色会审是对抗AI幻觉的最终防线。