SDD：规格驱动开发 📋
"先规格，后代码 — 让 AI 成为你可控的执行者，而非不可预测的创作者。"
随着 AI 编程助手的普及，一种新的开发范式正在兴起：Spec-Driven Development（规格驱动开发，SDD）。它强调在代码生成前建立清晰的规格文档，让人类与 AI 在实现前达成共识，从而驾驭 AI 的强大能力，同时避免其不可预测性。
1. 为什么需要 SDD？
1.1 "Vibe Coding" 的问题
传统的 AI 编程交互往往是这样的：
用户：帮我实现一个用户认证系统
AI：好的，我来帮你实现...（生成 500 行代码）
用户：不对，我想要 JWT 认证，不是 Session
AI：好的，让我重新实现...（又生成 500 行代码）
用户：等等，我还需要双因素认证...这种 Vibe Coding（氛围编程）的问题：
| 问题 | 描述 |
|---|---|
| 需求漂移 | 要求散落在对话历史中，容易丢失上下文 |
| 输出不可预测 | AI 可能"自由发挥"，添加不需要的功能或遗漏关键需求 |
| 迭代成本高 | 每次修正都需要 AI 重新理解需求并生成代码 |
| 难以审查 | 没有明确的需求文档，无法有效 Code Review |
| 团队协作困难 | 其他人无法理解某个实现的来龙去脉 |
1.2 SDD 的核心理念
┌─────────────────────────────────────────────────────────────────────────┐
│ 开发范式对比 │
├───────────────────────────────┬─────────────────────────────────────────┤
│ 代码优先 (Code-First) │ 规格优先 (Spec-First/SDD) │
├───────────────────────────────┼─────────────────────────────────────────┤
│ │ │
│ 用户需求 → AI 生成代码 → 验收 │ 用户需求 → 规格文档 → AI 生成代码 → 验收 │
│ │ ↑___反馈循环___| │
│ │ │
│ ❌ AI 自由发挥 │ ✅ AI 按规格执行 │
│ ❌ 需求在对话中迷失 │ ✅ 规格是持久化的真理来源 │
│ ❌ 难以追溯变更 │ ✅ 变更历史可追溯可审计 │
│ │ │
└───────────────────────────────┴─────────────────────────────────────────┘SDD 的核心信条：
- 规格是唯一真理来源 - 规格文档定义系统应该做什么，代码只是实现
- 先达成共识再写代码 - 确保人类与 AI 对需求的理解一致
- AI 是执行者，人类是决策者 - AI 拥有"快手"，人类保持控制力
- 变更需要显式记录 - 每次变更都有提案、审核、归档的完整流程
2. SDD 工作流程
2.1 标准四阶段流程
┌────────────────────┐
│ 1. Specify │
│ 定义需求规格 │
└────────┬───────────┘
│ 与 AI 协作迭代
▼
┌────────────────────┐
│ 2. Plan │
│ 制定实现计划 │◀──── 反馈循环 ────┐
└────────┬───────────┘ │
│ 达成共识 │
▼ │
┌────────────────────┐ │
│ 3. Implement │───────────────────┘
│ AI 执行任务 │
└────────┬───────────┘
│ 验证通过
▼
┌────────────────────┐
│ 4. Archive │
│ 归档更新规格 │
└────────────────────┘2.2 各阶段详解
阶段 1: Specify（规格定义）
在自然语言中描述你想要什么：
markdown
## 需求：添加双因素认证
### 目标
- 增强账户安全性
- 支持 TOTP（基于时间的一次性密码）
### 用户故事
- 用户可以在设置中启用 2FA
- 启用后，登录时需要输入 OTP 验证码
- 支持备用恢复码
### 约束
- 必须支持 Google Authenticator
- OTP 有效期 30 秒阶段 2: Plan（计划制定）
与 AI 协作，将需求转化为技术设计和任务清单：
markdown
## 技术设计
### 架构决策
- 使用 `otplib` 处理 TOTP 生成和验证
- OTP 密钥使用 AES-256 加密存储
### 数据库变更
- `users` 表新增：`otp_secret`, `otp_enabled`, `backup_codes`
### API 端点
- `POST /api/2fa/setup` - 初始化 2FA 设置
- `POST /api/2fa/verify` - 验证 OTP
- `POST /api/2fa/disable` - 禁用 2FA
---
## 任务清单
- [ ] 1.1 安装依赖 `otplib`, `qrcode`
- [ ] 1.2 数据库迁移
- [ ] 2.1 实现 OTP 生成接口
- [ ] 2.2 实现 OTP 验证接口
- [ ] 2.3 修改登录流程
- [ ] 3.1 前端设置页面
- [ ] 3.2 前端 OTP 输入组件阶段 3: Implement（执行实现）
AI 按照规格和任务清单逐个执行：
AI：根据任务 1.1，我将安装以下依赖...
AI：根据任务 2.1，我将实现 OTP 生成接口...
（AI 始终引用规格执行，而非"自由发挥"）阶段 4: Archive（归档更新）
实现完成后，将变更合并到主规格文档：
markdown
## Auth 规格 (更新于 2025-01-04)
### 双因素认证 [新增]
- 系统**必须**支持 TOTP 双因素认证
- OTP 有效期为 30 秒
- 用户禁用 2FA 时需要提供当前 OTP 或恢复码3. 主流 SDD 工具对比
3.1 工具全景
| 工具 | 类型 | 开发者 | 特点 |
|---|---|---|---|
| OpenSpec | CLI 框架 | Fission-AI | 轻量级，适合改造现有项目 |
| spec-kit | CLI 工具包 | GitHub | 完整模板，阶段式验证 |
| Kiro.dev | 专用 IDE | AWS | 功能最完整，内置 SDD 流程 |
3.2 OpenSpec
定位：轻量级 SDD 框架，专注于变更管理。
目录结构：
openspec/
├── specs/ # 当前规格（真理来源）
│ └── auth/
│ └── spec.md
└── changes/ # 变更提案（进行中）
└── add-2fa/
├── proposal.md # 变更提案
├── tasks.md # 任务清单
└── specs/ # 规格增量（Delta）
└── auth/
└── spec.md核心命令：
bash
# 安装
npm install -g @fission-ai/openspec@latest
# 初始化项目
openspec init
# 查看活跃变更
openspec list
# 验证规格格式
openspec validate add-2fa
# 归档已完成变更
openspec archive add-2fa与 AI 工具集成：
| 工具 | 集成方式 |
|---|---|
| Claude Code | @openspec-proposal, @openspec-apply, @openspec-archive |
| Cursor | .cursor/rules/ 或 /openspec-proposal |
| GitHub Copilot | .github/prompts/ |
| Gemini | .gemini/commands/openspec/ |
适用场景：
- ✅ 改造现有项目（Brownfield）
- ✅ 需要轻量级工具
- ✅ 团队已使用其他 AI 工具
3.3 GitHub spec-kit
定位：完整的 SDD 工具包，提供模板和阶段验证。
核心特性：
- 阶段式验证：每个阶段有明确的检查点
- Steering Prompts：引导 AI 行为的预设提示
- 模型无关：支持 Copilot、Claude、Gemini 等
标准模板：
.spec-kit/
├── requirements.md # 需求规格
├── design.md # 技术设计
├── tasks.md # 任务分解
└── steering/ # AI 引导提示
├── planning.md
├── coding.md
└── review.md工作流程：
bash
# 1. 创建规格
spec-kit init my-feature
# 2. 填写需求
spec-kit specify
# 3. 生成设计（AI 辅助）
spec-kit plan
# 4. 执行任务
spec-kit implement
# 5. 验证完成
spec-kit validate适用场景：
- ✅ 新项目启动（Greenfield）
- ✅ 需要严格的阶段控制
- ✅ 团队需要标准化模板
3.4 Kiro.dev
定位：AWS 推出的专用 SDD IDE，功能最完整。
核心特性：
| 特性 | 描述 |
|---|---|
| 内置 SDD 流程 | 自动生成 requirements.md, design.md, tasks.md |
| 多模态输入 | 支持文字、图表、代码仓库结构等 |
| MCP 集成 | 连接外部工具、数据库、API |
| Powers 动态加载 | 按需加载框架专业知识 |
| Agent 系统 | 多专业 Agent 协作执行 |
SDD 流程：
输入需求描述
│
▼
┌───────────────────────────────────────────────┐
│ Kiro 自动生成 │
│ ├── requirements.md (功能需求) │
│ ├── design.md (技术设计) │
│ └── tasks.md (实现任务) │
└───────────────────────────────────────────────┘
│
▼
人类审核 & 调整
│
▼
Kiro Agent 执行实现
│
▼
自动更新规格文档Powers 机制：
markdown
当 Kiro 检测到数据库相关术语时，自动加载：
- PostgreSQL 最佳实践
- 索引优化建议
- 事务处理模式适用场景：
- ✅ 企业级项目
- ✅ 需要端到端 SDD 支持
- ✅ 追求最高开发效率
3.5 对比总结
| 维度 | OpenSpec | spec-kit | Kiro.dev |
|---|---|---|---|
| 学习曲线 | 低 | 中 | 中 |
| 设置复杂度 | 简单 | 中等 | 简单（专用 IDE） |
| 现有项目适配 | ⭐⭐⭐ | ⭐⭐ | ⭐⭐ |
| 新项目支持 | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
| 团队协作 | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
| AI 工具集成 | 广泛 | GitHub 生态 | 内置 |
| 成本 | 免费 | 免费 | 免费（Preview） |
4. 实践指南
4.1 从零开始使用 OpenSpec
bash
# 1. 安装 CLI
npm install -g @fission-ai/openspec@latest
# 2. 在项目中初始化
cd my-project
openspec init
# 选择你使用的 AI 工具（Claude Code, Cursor 等）
# 3. 创建你的第一个变更
# 使用 AI 工具的 slash command：
# /openspec-proposal "添加用户头像上传功能"
# 4. 审核生成的规格
# 检查 openspec/changes/add-avatar-upload/ 中的文件
# 5. 执行实现
# /openspec-apply add-avatar-upload
# 6. 归档完成的变更
openspec archive add-avatar-upload4.2 规格文档最佳实践
使用 RFC 关键字
markdown
## 需求：密码策略
### 强制要求
- 密码**必须**至少包含 8 个字符 (MUST)
- 密码**必须**包含大写字母、小写字母和数字 (MUST)
### 推荐要求
- 密码**应该**包含特殊字符 (SHOULD)
- 用户**可以**使用密码管理器生成密码 (MAY)
### 禁止事项
- 系统**不得**以明文存储密码 (MUST NOT)场景化描述
markdown
### 需求：购物车上限
#### 场景：添加商品到满载购物车
- **给定** 购物车已有 99 件商品
- **当** 用户尝试添加新商品
- **那么** 显示"购物车已满"提示
- **且** 商品不被添加4.3 团队协作模式
┌─────────────────────────────────────────────────────────────┐
│ SDD 团队工作流 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 产品经理创建需求规格 │
│ │ │
│ ▼ │
│ 2. 技术负责人审核 & 补充技术约束 │
│ │ │
│ ▼ │
│ 3. 开发者使用 AI 生成实现计划 │
│ │ │
│ ▼ │
│ 4. 团队评审计划 (类似 PR Review) │
│ │ │
│ ▼ │
│ 5. 开发者执行实现，提交代码 │
│ │ │
│ ▼ │
│ 6. Code Review + 规格更新审核 │
│ │ │
│ ▼ │
│ 7. 合并代码，归档变更到主规格 │
│ │
└─────────────────────────────────────────────────────────────┘5. SDD 与其他概念的关系
5.1 SDD vs TDD
| SDD | TDD |
|---|---|
| 需求驱动 | 测试驱动 |
| 先规格后代码 | 先测试后代码 |
| 规格 → 代码 → 测试 | 测试 → 代码 → 重构 |
| 适合 AI 编程 | 适合人类编程 |
| 可结合使用 | 可结合使用 |
5.2 SDD 与 MCP/A2A
SDD 定义了 "做什么"，MCP/A2A 定义了 "怎么连接"。
┌─────────────────────────────────────────────────────┐
│ │
│ SDD 规格文档 │
│ "系统需要查询用户订单历史" │
│ │ │
│ │ 指导 AI 使用 │
│ ▼ │
│ MCP 工具调用 │
│ "调用 order-service MCP Server 的 listOrders 工具" │
│ │
└─────────────────────────────────────────────────────┘6. 常见问题
Q: SDD 会增加开发时间吗？
A: 短期看似乎增加了文档时间，但：
- 减少了返工次数（需求对齐）
- 加速了 AI 执行（明确指令）
- 提升了代码质量（可审查）
- 便于后续维护（有文档）
Q: 小项目也需要 SDD 吗？
A: 根据项目规模选择：
- 个人小项目：可以简化，使用单一 README 作为规格
- 团队项目：推荐使用
- 会持续迭代的项目：强烈推荐
Q: 如何迁移现有项目到 SDD？
A: 渐进式迁移：
- 为新功能创建规格文档
- 逐步为核心模块补充规格
- 使用 OpenSpec 管理变更
- 不需要一次性为所有代码补文档
7. 参考资源
官方文档
推荐阅读
SDD 是 AI 时代的软件工程最佳实践之一。通过建立清晰的规格文档，我们既能发挥 AI 的生产力优势，又能保持对系统的控制力和可维护性。