2026年8月3日...大约 15 分钟
SDD 模式实战指南 — 决策清单 + 三份标准模板
上篇博客《SDD 模式 AI Coding 实战感悟》讲了流程与踩坑。这篇是可直接复用的模板——包含"该不该用 SDD"的决策清单 + spec / design / tasks 三份标准模板。
写在前面：为什么需要这份模板
SDD 模式不是万能的，但用对了是质变工具。用错了则是浪费时间。
本文解决两个核心问题：
1. 我这个项目，到底适不适合用 SDD？
2. 如果适合，三份文档应该怎么写？第一部分：SDD 适用性决策清单
一、SDD 不是银弹
【SDD 的本质】
- 不是文档模板
- 是工作纪律
- 是"先想清楚再动手"
【SDD 的代价】
- 前期文档投入大
- 一个人承担多个角色
- 认知负荷高
- 适合中小项目
【SDD 的真实定位】
- 把"AI 写代码"从"碰运气"变成"有纪律"
- 适合 1-4 周中等项目
- 不适合 1 天小项目，也不适合 3 月大项目（拆分）二、适用的 7 大场景
✅ 1. 需求清晰但模糊
- 你知道大概要做什么
- 但边界 / 异常路径不清楚
- SDD 帮你"写清楚"✅ 2. 技术栈熟悉
- 你对设计中的技术 80%+ 熟悉
- 不需要花时间学习新技术
- SDD 才能发挥效率✅ 3. 复杂度中等
- 1-4 周项目
- 1-2 人月
- 太大了不行，太小了浪费✅ 4. 需求变更可控
- 不会每周大改
- spec 一旦稳定 = 后续小修
- 频繁变更 = SDD 文档会过期✅ 5. 团队 / 个人愿意写文档
- 不是"赶紧出活"
- 愿意"先想再干"
- 文化匹配✅ 6. 有可验证里程碑
- 能拆分 phase
- 每个 phase 跑起来看效果
- 不可验证 = 别用 SDD✅ 7. 独立可交付
- 不强依赖其他团队
- 不需要每日联调
- 可以独立 E2E 验证三、不适用的 6 大场景
❌ 1. 紧急上线
- 时间紧到没时间写文档
- 1-3 天要上线
- 用 SDD = 拖延上线❌ 2. 技术完全陌生
- 你对设计中的技术 50% 以下熟悉
- SDD 的 design 阶段 = 学习阶段
- 不如直接看代码 + 学❌ 3. 需求完全模糊
- 你不知道要做什么
- 客户自己也说不清
- SDD = 把模糊变精确，但起点不能太模糊❌ 4. 小项目 / 玩具
- 一个脚本 / 一个工具
- 1-2 天能写完
- SDD 文档时间 > 开发时间❌ 5. 高频变更
- 每周大改需求
- 客户没想清楚
- SDD 文档会变成废纸❌ 6. 强依赖其他团队
- API 没稳定
- 数据没准备好
- 强依赖 = 你的 spec 不可控四、10 个关键判断问题
Q1：项目时间跨度？
【< 1 周】 → 不适合 SDD，直接干
【1-4 周】 → 适合 SDD ✅ 性价比最高
【1-3 月】 → 适合 SDD，但要拆分多个项目
【> 3 月】 → 必须拆分，每个独立 SDDQ2：你的技术熟悉度？
【100% 熟悉】 → 适合 SDD ✅ design 阶段最快
【80% 熟悉】 → 适合 SDD ✅ 1-2 天补 20%
【50% 熟悉】 → 边缘情况，慎用 SDD
【< 50% 熟悉】 → 不适合 SDD，先学习技术Q3：需求清晰度？
【非常清晰】→ 适合 SDD ✅ spec 阶段最快
【基本清晰】→ 适合 SDD ✅ spec 帮你"写清楚"
【模糊】 → 不适合 SDD，先做原型 / spike
【完全模糊】 → 完全不适合 SDD，先做需求调研Q4：需求变更频率？
【基本不变】 → 适合 SDD ✅
【小变更(<5%/周)】→ 适合 SDD ✅
【中变更(5-20%)】 → 边缘情况
【大变更(>20%)】 → 不适合 SDD，文档会过期Q5：可验证里程碑？
【可拆分 phase + 每个可跑】→ 适合 SDD ✅ 最佳情况
【只能整体验证】 → 边缘情况，需要拆 phase
【不可验证】 → 不适合 SDD，重新设计项目Q6：依赖关系？
【独立项目】 → 适合 SDD ✅
【弱依赖】 → 适合 SDD ✅ mock 即可
【强依赖】 → 不适合 SDD，等依赖稳定Q7：团队 / 个人文化？
【重视文档】 → 适合 SDD ✅
【重视速度】 → 不适合 SDD，用敏捷 + 短迭代
【重视规范】 → 适合 SDD ✅
【重视灵活】 → 不适合 SDDQ8：失败成本？
【高（生产环境 / 钱）】→ 适合 SDD ✅ 文档 = 风险控制
【低（demo / 内部）】 → 不一定要 SDD
【极高（医疗 / 金融）】→ 必须 SDD + 额外规范Q9：复盘价值？
【项目值得长期维护】→ 适合 SDD ✅
【一次性项目】 → 不一定要 SDD
【学习项目】 → 不适合 SDDQ10：AI 能力？
【AI 能写 70%+ 代码】→ 适合 SDD ✅
【AI 能写 30-70%】 → 适合 SDD，但 review 工作量大
【AI 能写 < 30%】 → 不适合 SDD五、决策流程图
【步骤 1】时间跨度
< 1 周？ → 不适合
> 3 月？ → 拆分
1-4 周？ → 进入步骤 2
【步骤 2】技术熟悉度
< 50%？ → 不适合
50-80%？ → 慎用
> 80%？ → 进入步骤 3
【步骤 3】需求清晰度
完全模糊？ → 不适合
基本清晰 / 非常清晰？ → 进入步骤 4
【步骤 4】变更频率
> 20%/周？ → 不适合
< 5%/周？ → 进入步骤 5
【步骤 5】可验证里程碑
不可验证？ → 重新设计
可验证？ → 进入步骤 6
【步骤 6】依赖关系
强依赖？ → 等稳定
独立 / 弱依赖？ → 进入步骤 7
【步骤 7】失败成本
高？ → 强烈推荐 SDD ✅
低？ → 看你
【最终决策】
5/7 通过 = 用 SDD ✅
3-4/7 通过 = 慎用
< 3/7 通过 = 不用六、SDD 失败的 5 大征兆
【征兆 1】spec 写了 1 周还没定稿
= 需求太模糊 / 项目太大
= 应该拆分 / 先做原型
【征兆 2】design 改了 10+ 轮还没稳定
= 技术选型有问题
= 应该回到 spec 重新定义
【征兆 3】tasks 拆分完发现 phase 跑不起来
= 可验证性设计失败
= 应该重新拆 phase
【征兆 4】develop 阶段频繁大改 spec
= 需求变更失控
= 暂停开发，重新对齐
【征兆 5】文档没人看 / 没人维护
= 团队文化不匹配
= 改用敏捷 / 不写文档七、SDD 成功的 5 大征兆
【征兆 1】spec 1-3 天稳定
【征兆 2】design 3-6 轮收敛
【征兆 3】tasks 拆分清晰可验证
【征兆 4】develop 阶段 spec/design 基本不变
【征兆 5】完成时文档 = 真实交付物第二部分：三份标准模板
模板使用 5 大原则
1. 不要追求一次写对
- spec 迭代 3+ 次是正常的
- design 校验 6+ 次是正常的
- tasks 拆分调整是正常的
2. 每个 phase 必填可验证
- phase 完成后必须能跑起来
- 不能"等联调"才验证
- 不可验证 = phase 拆分有问题
3. 每个 phase 必填 checklist
- 防止中期遗忘
- 沟通完成度
- 自我校准
4. 三份文档一起迭代
- spec 改 → design 跟着改
- design 改 → tasks 跟着改
- 不能脱节
5. 坚持串讲
- spec 写完串讲
- design 校验完串讲
- tasks 拆完串讲
- 串讲 = 发现盲区📄 模板 1：spec.md（需求规格）
完整模板
# [项目名] - Spec
> 本文档是项目需求的精确描述。所有模糊点在串讲中解决。
## 1. 项目背景
### 1.1 业务背景
[为什么做这个？解决什么问题？]
### 1.2 目标用户
[谁会用？有什么特点？]
### 1.3 核心价值
[做完之后，用户的最大收益是什么？]
## 2. 功能需求
### 2.1 核心功能（Must-have）
- [ ] F1: [功能描述]
- 输入：[...]
- 输出：[...]
- 边界：[...]
- 异常：[...]
- [ ] F2: [功能描述]
### 2.2 次要功能（Nice-to-have）
- [ ] F3: [...]
- [ ] F4: [...]
### 2.3 非功能需求
- 性能：[QPS / 响应时间]
- 安全：[鉴权 / 数据加密]
- 可用性：[99.9% / 容灾]
- 可维护性：[代码规范 / 测试覆盖率]
## 3. 用户故事
### US1: [用户角色] 能 [做什么] 从而 [获得什么价值]
- 验收标准 1：[...]
- 验收标准 2：[...]
## 4. 数据模型
### 4.1 核心实体
- Entity1: [字段定义]
- Entity2: [字段定义]
### 4.2 实体关系
[ER 图或文字描述]
## 5. 接口定义（可选）
### API 1
- 方法：POST /api/xxx
- 入参：[...]
- 出参：[...]
- 错误码：[...]
## 6. 边界与异常
### 6.1 边界情况
- 边界 1：[...]
- 边界 2：[...]
### 6.2 异常路径
- 异常 1：[场景 + 处理]
- 异常 2：[场景 + 处理]
## 7. 验收标准
### 7.1 功能验收
- [ ] F1 满足所有验收标准
- [ ] F2 满足所有验收标准
### 7.2 质量验收
- [ ] 测试覆盖率 ≥ 80%
- [ ] 无 P0 / P1 bug
- [ ] 性能达标
## 8. 范围之外（Out of Scope）
- 不做 X：[原因]
- 不做 Y：[原因]
## 9. 待澄清问题（Open Questions）
- Q1: [...] → 待确认
- Q2: [...] → 待确认
## 10. 修订历史
| 版本 | 日期 | 作者 | 变更 |
|------|------|------|------|
| v1.0 | 2026-08-03 | [...] | 初稿 |实战示例（数字员工 AI 项目）
# 数字员工 AI - Spec
> 项目：基于大模型的测试用例自动生成工具
## 1. 项目背景
### 1.1 业务背景
传统测试流程中，工程师 60% 时间花在重复劳动上
（用例编写 / Bug 分析）。数字员工 AI 旨在通过
AI 辅助，将重复工作自动化。
### 1.2 目标用户
- 主要：测试工程师
- 次要：开发工程师 / 项目经理
### 1.3 核心价值
- 用例编写时间减少 50%
- Bug 分析效率提升 3x
## 2. 功能需求
### 2.1 核心功能
- [ ] F1: AI 自动生成测试用例
- 输入：需求文档（文本）
- 输出：结构化测试用例
- 边界：长文档（> 1 万字）/ 短文档 / 多语言
- 异常：AI 失败 → 兜底提示
### 2.3 非功能需求
- 性能：单次生成 ≤ 30 秒
- 安全：API Key 加密存储
- 可用性：99.5%
## 9. 待澄清问题
- Q1: 是否需要支持多语言？
→ 决定：v1.0 只支持中文📄 模板 2：design.md（设计文档）
完整模板
# [项目名] - Design
> 本文档是技术方案的蓝图。经过多轮校验后稳定。
## 1. 架构总览
### 1.1 系统架构图
[架构图：客户端 / 网关 / 业务层 / 数据层]
### 1.2 技术选型
| 层 | 技术 | 理由 |
|----|------|------|
| 前端 | Vue3 | 团队熟悉 |
| 后端 | Python | AI 生态 |
| 数据库 | PostgreSQL | 复杂查询 |
| 缓存 | Redis | 高频读 |
### 1.3 部署架构
[单机 / 集群 / K8s]
## 2. 模块设计
### 2.1 模块 A: [名称]
- 职责：[...]
- 接口：[...]
- 依赖：[...]
- 数据：[...]
## 3. 数据流
### 3.1 核心流程
[用户操作 → 系统响应 → 数据变化]
### 3.2 异常流程
[异常 → 检测 → 兜底]
## 4. 数据模型
### 4.1 表结构
```sql
CREATE TABLE entity (
id BIGINT PRIMARY KEY,
...
);4.2 索引设计
- idx_xxx: [字段] → [查询场景]
5. 接口设计
5.1 RESTful API
- GET /api/v1/xxx → [用途]
- POST /api/v1/xxx → [用途]
5.2 错误码定义
- 200: 成功
- 400: 参数错误
- 500: 系统错误
6. 关键算法
6.1 算法 A: [名称]
- 输入：[...]
- 输出：[...]
- 步骤：
- [...]
- [...]
7. 性能与可用性
7.1 性能目标
- 接口响应：P99 ≤ 500ms
- 吞吐量：1000 QPS
7.2 可用性设计
- 容灾：[主从 / 多活]
- 限流：[QPS / 并发数]
- 降级：[策略]
8. 安全设计
8.1 鉴权
- JWT / OAuth
8.2 数据安全
- 加密：[算法]
- 脱敏：[字段]
9. 可观测性
9.1 日志
- 业务日志：[字段]
- 错误日志：[字段]
9.2 监控
- 关键指标：[QPS / 延迟 / 错误率]
- 告警：[阈值]
10. 测试策略
10.1 单元测试
- 覆盖率目标：≥ 80%
10.2 集成测试
- 关键场景：[...]
10.3 端到端测试
- 验收场景：[...]
11. 风险与对冲
| 风险 | 概率 | 影响 | 对冲 |
|---|---|---|---|
| AI 接口不稳定 | 高 | 中 | 多家供应商 |
| 数据量超预期 | 中 | 高 | 分库分表 |
12. 修订历史
| 版本 | 日期 | 作者 | 校验轮次 | 变更 |
|---|---|---|---|---|
| v1.0 | ... | ... | 1 | 初稿 |
| v1.5 | ... | ... | 6 | 6 轮校验后稳定 |
### 实战示例（数字员工 AI 项目）
```markdown
# 数字员工 AI - Design
## 1. 架构总览
### 1.1 系统架构
┌─────────┐ ┌─────────┐ ┌─────────┐
│ 前端 │────▶│ 网关 │────▶│ AI 服务 │
└─────────┘ └─────────┘ └─────────┘
│ │
▼ ▼
┌─────────┐ ┌─────────┐
│ 用户 DB │ │ Prompt DB│
└─────────┘ └─────────┘
### 1.2 技术选型
| 层 | 技术 | 理由 |
|----|------|------|
| 前端 | Vue3 + TS | 团队熟悉 |
| 后端 | FastAPI | Python 生态 + 异步 |
| AI | Claude / GPT | 多家供应商 |
| 数据库 | PostgreSQL | 复杂查询 + JSON |
| 缓存 | Redis | 高频读 |
## 11. 风险与对冲
| 风险 | 概率 | 影响 | 对冲 |
|------|------|------|------|
| AI 接口超时 | 高 | 中 | 多家供应商 + 超时降级 |
| Prompt 泄漏 | 中 | 高 | 加密存储 + 访问审计 |📄 模板 3：tasks.md（任务拆分）
完整模板
# [项目名] - Tasks
> 本文档是开发任务的拆分。按 phase 划分，每个 phase 可验证。
## Phase 总览
| Phase | 名称 | 周期 | 可验证产出 |
|-------|------|------|----------|
| P0 | 项目脚手架 | 1 天 | 项目跑起来 |
| P1 | 核心功能 A | 2 天 | 功能 A 可用 |
| P2 | 核心功能 B | 2 天 | 功能 B 可用 |
| P3 | 联调 + 集成 | 2 天 | E2E 通 |
| P4 | 优化 + 测试 | 1 天 | 性能达标 |
---
## Phase 0: 项目脚手架
### 目标
项目能跑起来
### 任务
- [ ] T0.1: 初始化仓库
- [ ] T0.2: 配置 CI
- [ ] T0.3: 配置部署
### 验收
- [ ] 仓库可访问
- [ ] CI 跑通
- [ ] 部署成功
### Checklist
- [ ] README 写好
- [ ] 环境变量文档化
---
## Phase 1: [核心功能 A]
### 目标
[功能 A] 能跑通
### 任务
- [ ] T1.1: 数据模型
- [ ] T1.2: API 实现
- [ ] T1.3: 前端页面
- [ ] T1.4: 联调
### 验收
- [ ] API 返回正确数据
- [ ] 前端展示正确
- [ ] 错误处理完备
### Checklist
- [ ] 单元测试覆盖
- [ ] 边界测试
- [ ] 错误日志
---
## Phase 2: [核心功能 B]
（同 Phase 1 结构）
---
## Phase N: 联调 + 集成
### 目标
所有功能 E2E 通
### 任务
- [ ] TN.1: 集成测试
- [ ] TN.2: 性能测试
- [ ] TN.3: 安全审计
### 验收
- [ ] 核心场景 E2E 通
- [ ] 性能达标
- [ ] 无 P0/P1 bug
---
## 风险跟踪
| 风险 | 状态 | 处理 |
|------|------|------|
| T1.2 可能超时 | 待观察 | 预留 buffer |
## 修订历史
| 版本 | 日期 | 作者 | 变更 |
|------|------|------|------|
| v1.0 | ... | ... | 初稿 |实战示例（数字员工 AI 项目）
# 数字员工 AI - Tasks
## Phase 总览
| Phase | 名称 | 周期 | 可验证产出 |
|-------|------|------|----------|
| P0 | 项目脚手架 | 0.5 天 | 项目能跑 |
| P1 | AI 用例生成 | 2 天 | 单功能可用 |
| P2 | AI Bug 分析 | 2 天 | 单功能可用 |
| P3 | 用户系统 | 1 天 | 登录可用 |
| P4 | 集成 + E2E | 1 天 | 完整流程通 |
---
## Phase 1: AI 用例生成
### 目标
输入需求文档 → 输出结构化测试用例
### 任务
- [ ] T1.1: Prompt 模板设计
- [ ] T1.2: AI 服务调用封装
- [ ] T1.3: 结果解析 + 格式化
- [ ] T1.4: 前端页面
### 验收
- [ ] 输入需求 → 30 秒内输出用例
- [ ] 用例结构化（场景 + 步骤 + 预期）
- [ ] 失败有兜底
### Checklist
- [ ] 单元测试覆盖
- [ ] 边界测试（空 / 长 / 短文档）
- [ ] 错误日志完整
- [ ] 用户体验：进度提示第三部分：常见坑 + 我的真实经验
写 spec 时的 3 个常见坑
坑 1：写得太泛
❌ "系统要快"
✅ "API P99 ≤ 500ms"坑 2：写得太细
❌ "按钮颜色是 #FF0000"
✅ 移到 design 文档坑 3：不写边界
❌ "用户登录"
✅ "连续失败 5 次锁定 30 分钟"写 design 时的 3 个常见坑
坑 1：选错技术栈
- 太新 / 太小众
- 团队不熟悉
- 招不到人维护坑 2：模块边界不清
- A 模块调用 B 模块内部
- 接口不清晰
- 测试难写坑 3：没考虑异常
- AI 调用失败 = 整个服务挂
- 必须有兜底
- 必须有降级写 tasks 时的 3 个常见坑
坑 1：phase 太大
- 做完才能验证
- 不可验证 = 拆错
- 重新拆 phase坑 2：任务太碎
- 1 小时任务 = 太小
- 拆得太细 = overhead 大
- 1-2 天任务 = 合适坑 3：缺 checklist
- 中期遗忘 = 返工
- checklist = 导航仪
- 必填第四部分：SDD 实战 checklist（开始用前必看）
【决策 checklist】
- [ ] 项目时间 1-4 周
- [ ] 技术熟悉度 ≥ 80%
- [ ] 需求基本清晰
- [ ] 变更频率 < 5%/周
- [ ] 可拆 phase + 可验证
- [ ] 独立 / 弱依赖
- [ ] 失败成本不低
- [ ] 愿意写文档
【spec checklist】
- [ ] 业务背景写清楚
- [ ] 核心功能 + 边界 + 异常
- [ ] 非功能需求具体（性能 / 安全 / 可用性）
- [ ] 用户故事可验收
- [ ] 范围之外明确
- [ ] 待澄清问题列出
【design checklist】
- [ ] 架构图清晰
- [ ] 技术选型有理由
- [ ] 模块边界清晰
- [ ] 数据流自洽
- [ ] 异常路径有兜底
- [ ] 风险与对冲列出
- [ ] 6 轮校验后稳定
【tasks checklist】
- [ ] 每个 phase 可验证
- [ ] 每个 phase 有 checklist
- [ ] 任务大小合适（1-2 天）
- [ ] 依赖关系清晰
- [ ] 风险跟踪机制第五部分：SDD 的 4 大变体
根据项目规模选择不同变体：
变体 1：极简 SDD（1-3 天小项目）
- spec + tasks + 简短 design（1 页）
- 适合：脚本 / 工具 / 内部小工具
- 时间投入：1-3 天变体 2：标准 SDD（1-4 周）
- 完整的 spec + design + tasks + develop
- 适合：中等项目 / 个人开发
- 时间投入：1-4 周（含文档）变体 3：严格 SDD（1-3 月）
- 完整的 SDD + 多次迭代 + 串讲
- 适合：复杂项目 / 团队协作
- 时间投入：1-3 月（含文档 30%+）变体 4：SDD + 敏捷混合
- 用 SDD 做主框架
- 用敏捷做小迭代
- 适合：长期项目 / 持续交付
- 时间投入：长期写在最后：模板只是起点
三份模板不是"填空"，而是"思考框架"。
【模板的本质】
- 不是格式
- 是思考路径
- 是"这个项目你真的想清楚了吗？"
【用模板的方法】
1. 复制模板
2. 改 30% 适配项目
3. 串讲发现盲区
4. 迭代 3-6 次
5. 稳定后再开始开发思维模型附录
1. 第一性原理：从本质理解 SDD = 工作纪律
2. 系统思维：四份文档是有机整体
3. 反馈闭环：AI 上下文 = 你的反馈质量
4. 边界管理：一个人 = 多个角色 = 知道极限
5. 决策矩阵：7 个适用 + 6 个不适用
6. 模板复用：模板是起点，不是终点给读者的 3 个问题
1. 你在决策时最容易忽视哪个维度？
我：可验证里程碑（容易做得太大）
2. 你的 spec 阶段最长花过多少时间？
我：1 天 + 3 次迭代
3. 你在 design 阶段发现的最大问题是什么？
我：技术选型在实践上行不通SDD 不是工具，是纪律。模板不是填空，是思考路径。
用对 SDD = 把"AI 写代码"从碰运气变成有纪律。
贡献者
Sun Rong