SDD 规范驱动开发 + Spec Kit 实战全解

一、为什么需要 SDD

AI 编程目前的主流方式是 Vibe Coding（氛围编程）——给 AI 一段提示词，AI 直接生成代码。这种方式看起来快，但实际上存在根本性问题：

问题	表现
起点模糊	需求藏在脑子里，AI 拿到的是"大概意思"而非精确描述
过程黑箱	AI 一次性生成，无法干预中间方向
结果不可预测	返工频繁，代码与预期常常偏离
迭代成本高	需求变了基本靠重写
不可追溯	为什么这么写？不知道

SDD 的诞生，就是为了解决这些问题。

二、SDD 是什么

SDD（Spec-Driven Development，规范驱动开发）——先定义清楚要做什么（What）、为什么做（Why），再让 AI 基于结构化规范去生成代码，而不是直接丢一段提示词给 AI。

2.1 与其他开发范式的关系

范式	全称	核心关注	回答的问题
DDD	领域驱动开发	业务建模与系统边界	业务是什么？
BDD	行为驱动开发	业务验收与共同理解	如何验证？
TDD	测试驱动开发	代码正确性	如何保证质量？
SDD	规范驱动开发	人定义意图，AI 执行	如何控制 AI？

这四种范式是层级递进关系，不是替代关系。SDD 站在最顶端，负责把 DDD 的业务模型、BDD 的行为验收整理成 AI 可以精确执行的结构化规范。

2.2 SDD 的哲学

意图是唯一的真理。

规范不是代码的附属品，而是驱动一切实现的源头。

过去	现在（SDD）
文档 = 代码的附属品	代码 = 规范的产物
技术文档 = 参考	规范文档 = 产出代码的精准定义
代码是核心	规范是核心

三、SDD 的 8 步核心流程

① Constitution          ② Specify          ③ Clarify（可选）
 定团队原则              编写功能规范          澄清模糊需求

④ Plan                ⑤ Checklist（可选）   ⑥ Tasks
 制定技术计划            生成验收清单           分解任务列表

⑦ Analyze（可选）        ⑧ Implement
 一致性分析               执行实现

人类负责：掌舵（定义 What & Why）
AI 负责：划桨（基于规范执行 How）

第一步：Constitution — 团队宪法

做什么：建立项目核心价值观、不可违反的原则、标准、质量门槛。

原则核心：只写可执行的约束，不写模糊的理想。

❌ 模糊理想 → ✅ 可执行约束

模糊理想	可执行约束
写高质量代码	所有函数必须有 JSDoc 注释；所有 API 必须有输入校验 schema
注重性能	列表组件数据超过 100 条时，必须使用虚拟滚动
保证安全	所有 SQL 查询必须使用参数化查询，禁止字符串拼接
代码要可维护	每个函数不超过 50 行，禁止嵌套超过 3 层

产物：.specify/memory/constitution.md
审核重点：原则是否可验证、可执行；AI 后续行为是否足够可控。

第二步：Specify — 编写功能规范

做什么：定义 What（做什么）和 Why（为什么做），专注需求本身，完全不解耦技术实现。

产物：specs/001-功能名/spec.md

规范文档标准结构：

项目概述
用户故事
功能需求
非功能需求（性能、安全、可扩展性）
验收标准（每个标准必须可验证）
约束条件

审核重点（第二个检查点）：

功能是否完整无遗漏？
优先级是否清晰（MVP vs 后期迭代）？
边界条件和异常情况是否被考虑？
验收标准是否足够清晰可验证？

第三步：Clarify — 澄清需求（可选但强烈推荐）

做什么：让 AI 审视 spec.md 中模糊或未定义的地方，以 Q&A 形式向用户确认。

价值：

在写代码之前就把模糊需求全部确定
强迫开发者在动手前深度思考需求
大幅减少实现阶段的返工

典型 Q&A 场景：

"这个功能的并发用户量级是多少？100 还是 10,000？"
"如果 AI 生成的内容为空，系统的降级策略是什么？"
"移动端的交互和 PC 端是否完全一致？"

第四步：Plan — 制定技术计划

做什么：定义 How（怎么做），提供高层技术方向，不提供具体实现细节。

关键：Plan 阶段才涉及技术选型，Specify 阶段完全不要考虑技术问题。

产物：specs/001-功能名/plan.md
包含：架构总览、目录结构、数据模型、API 契约、模块划分等

审核重点（技术决策关键节点）：

目录结构是否合理、符合团队习惯？
数据库表设计是否合理、外键关系是否正确？
API 端点是否完整、风格是否一致？
组件拆分粒度是否合适？
技术方案是否有不必要的复杂度？

第五步：Tasks — 分解任务

做什么：将技术计划转换为 AI 可逐个执行的原子化工作项。

产物：specs/001-功能名/tasks.md

结构：

Phase 1
  [P] T001 - 可并行任务
  [P] T002 - 可并行任务
  T003 - 依赖 T001 完成
Phase 2
  ...

标记 [P] 的任务 = 可并行执行，这是 Spec Kit 提升开发速度的核心机制。

审核重点：

依赖关系是否合理，有无循环依赖？
任务粒度是否足够小，能否在单次 AI 交互中完成？
需求映射是否完整，每个任务能否追溯到具体需求？
Phase 划分是否合理？

第六步：Analyze — 一致性分析（可选但推荐）

做什么：对比 spec.md、plan.md、tasks.md 三者之间的一致性，找出潜在遗漏或矛盾点。

产物：一致性分析报告

检查项	说明
覆盖率	每个需求是否都有对应任务？
一致性	spec 和 plan 之间是否有矛盾？
完整性	tasks 是否完整覆盖 plan？
边界条件	异常流程是否被覆盖？

价值：在动手写代码之前发现文档间的不一致，避免实现阶段大规模返工。

第七步：Implement — 执行实现

做什么：按任务列表顺序执行，生成代码、测试、文档。

AI 在 Implement 阶段会执行 5 件事：

读取所有文档（spec、plan、tasks）
按顺序和依赖关系逐个执行任务
为每个任务生成代码、测试、文档
在 tasks.md 中标记已完成的任务
确保合规

关键节点检查（人类必须介入的三个时机）：

时机	检查内容
Phase 完成后	运行项目，确保基本功能正常
任意时刻	运行单元测试，确保覆盖率达标
全程	审查关键代码文件，确认风格和架构符合预期

如果 AI 生成的代码有问题——不要直接改代码，而是回到 spec.md 或 plan.md 修正规范，再重新 Implement。这是 SDD 的核心优势：系统性修正，而非打补丁。

四、Spec Kit 安装与使用

环境准备

# 1. 安装 UV（包管理器）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 验证安装
uv --version

# 2. 用 UV 安装 Spec Kit
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 验证安装
specify --help
specify check

初始化项目

# 创建独立项目
specify init my-feature --ai claude --script ps

# 在当前目录初始化（不创建子目录）
specify init --here --force --ai claude --script ps

⚠️ 前提：项目必须已初始化 Git 仓库（git init）

项目初始化后自动生成的目录结构

项目名/
├── .claude/commands/          # Claude Code 斜杠命令（/speckit.*）
├── .specify/
│   ├── memory/
│   │   └── constitution.md    # 团队宪法
│   ├── scripts/               # 辅助脚本
│   └── templates/             # 文档模板
└── specs/                     # 功能规范（按编号管理）
    └── 001-功能名/
        ├── spec.md            # 功能规范
        ├── plan.md            # 技术计划
        ├── tasks.md           # 任务列表
        ├── data-model.md      # 数据模型
        ├── quickstart.md      # 快速启动
        └── research.md        # 研究文档

五、Spec Kit 适用场景判断

场景	推荐方式
快速原型 / 小脚本 / 一次性需求	Vibe Coding（普通 AI Coding）
中大型项目 / 团队协作 / 长期维护	SDD + Spec Kit
Bug 修复	Cursor（项目索引 RAG 定位更精准）

一个简单的判断标准：如果项目复杂到在写代码之前就需要考虑架构和数据模型，就值得用 SDD。

六、进阶技巧与最佳实践

1. 规范力度控制（大型项目）

按功能拆分规范，而非把所有功能写在一个巨大的 spec.md 里。

specs/
├── 001-auth/          # 认证功能，独立走完完整流程
├── 002-blog-post/     # 博客文章功能
├── 003-comment/       # 评论功能
└── 004-search/        # 搜索功能

好处：

AI 上下文窗口不会被撑爆
每个功能可独立验收
出问题更容易定位根因

2. 迭代开发模式

添加新功能 ≠ 修改旧规范，而是回到 /speckit.specify，Spec Kit 会自动创建新的编号目录（003-新功能），不影响已有功能规范。

3. 用 Checklist 做规范级"单元测试"

/speckit.checklist

生成验收清单，相当于给规范做一次完整性检查，确保每个需求都有对应实现。

4. 修改顺序：规范 → 代码

AI 生成的代码不符合预期时：

❌ 直接改代码（打补丁，下次可能又被覆盖）
✅ 回到 spec.md / plan.md 修正规范，重新 Implement（系统性修正）

5. `.specify` 目录必须提交 Git

.specify/ 是项目的重要资产，包含团队的规范和决策上下文，必须版本控制，确保：

团队所有人访问一致的上下文
新加入的 AI 也能获得完整背景

七、常见问题解答

Q1：Spec Kit 只能和 Claude Code 一起用？

不是。Spec Kit 支持 Copilot、Claude Code、Gemini CLI、Cursor 等多种 AI 编程工具。同样，Claude Code 也不只能用 Spec Kit，也可以配合 OpenSpec 等其他 SDD 工具。

Q2：小型项目用 SDD 是否过于复杂？

是。SDD 更适合中大型项目。如果复杂到需要先考虑架构和数据模型，就值得用 SDD。简单到几个小时能做完的小脚本，直接 Vibe Coding 更高效。

Q3：规范文件是否需要手动维护？

可以直接编辑 markdown 文件，但更推荐通过 Claude Code 修改——AI 会确保修改后的文档和其他文件保持一致，避免手动编辑引入的不一致。

Q4：一次 Implement 没跑完所有任务怎么办？

完全正常。可用 /speckit.implement 继续，或者用提示词指定实现某个 Phase 的任务：

继续完成 Phase 2 的剩余任务

Q5：如何更新模板？

specify init --here --force

加上 --force 会更新模板和命令文件，但不会覆盖已有的 specs/ 目录和源代码。

八、核心总结

SDD 的本质

把软件开发从"直接写代码"转换为"先定义意图，再生成代码"。规范是源头，代码是产物。

人类 vs AI 的分工

角色	职责
人类（掌舵者）	定义意图、审核产出、做最终决策
AI（执行者）	在每个阶段忠实地执行人类意图

完整实践路径

安装环境
  ↓
初始化项目（specify init）
  ↓
定义原则（/speckit.constitution）     ← 第一个检查点
  ↓
编写规范（/speckit.specify）          ← 第二个检查点
  ↓
澄清规范（/speckit.clarify）          ← 可选，推荐做
  ↓
制定计划（/speckit.plan）            ← 第三个检查点
  ↓
生成任务（/speckit.tasks）            ← 第四个检查点
  ↓
一致性分析（/speckit.analyze）        ← 可选，推荐做
  ↓
执行实现（/speckit.implement）        ← 最终验收

SDD 的核心价值

维度	提升
可控性	每个阶段都有检查点，方向始终可干预
可追溯性	每步都有文档记录，决策有据可查
迭代成本	修改规范即可重新生成代码，无需重写
团队协作	规范作为共同语言，减少沟通偏差
AI 使用质量	从"开盲盒"变为"按图施工"

视频标题：告别盲盒式编程！用 SDD + Spec Kit 让 AI 按图施工｜AI 编程实战 #03
作者：NOVA
平台：Bilibili
原链接：https://www.bilibili.com/video/BV1QvwuzTEoT
字幕字符数：8,318 字
内容深度：★★★★★

整理依据：Bilibili 视频字幕原文（8,318 字），视频作者 NOVA，AI 编程实战系列第 3 期