规范驱动开发（SDD）开发规范

Spec-Driven Development · PRD → spec.md → plan.md → task.md → 代码

AI 时代下，技术负责人先把 PRD 转成明确规范，Agent 再基于规范进行规划、拆解和代码执行。

版本：v1.0 ｜ 日期：2026-06-01 ｜ 状态：Draft / 可评审

1. 核心定义

本文中的 SDD 定义为 Spec-Driven Development（规范驱动开发），不是传统的 Software Design Document。它强调：先把需求转换成可审查、可执行的规范，再让 Agent 按规范生成计划、任务和代码。

SDD 的核心不是"让 AI 直接写代码"，而是建立一条稳定的交付链路：

1. 产品经理或业务方给出 PRD / 需求输入。
2. 技术负责人将 PRD 转换为 spec.md，明确做什么、为什么做、验收口径和边界。
3. Agent 基于 spec.md 生成 plan.md，补齐架构、数据、接口、异常和风险方案。
4. Agent 基于 plan.md 拆出 task.md，把方案变成一步步可执行任务。
5. Agent 按 task.md 自动化执行，开发人员在关键节点审查、构建和发布。

1.1 角色边界

2. AI 时代下的"真理"反转

核心表达是：技术负责人根据 PRD 编写规范，Agent 根据规范生成代码。

2.1 关键原则

• 规范比一次性 Prompt 更重要。Prompt 可以触发动作，规范负责约束结果。
• 代码不是第一产物，spec.md / plan.md / task.md 才是可审查、可复用、可追溯的交付物。
• 人负责意图、边界、判断和验收；Agent 负责信息整理、方案生成、任务拆解和重复执行。
• 每个阶段都必须有审查点。审查不通过时，回到上一阶段修正规范，而不是在代码里硬改。

3. SDD 工作流程

3.1 标准流程

3.2 回路规则

• 需求不清：回到意图定义，补充 spec.md。
• 方案不稳：回到技术规划，补充 plan.md。
• 任务不可执行：回到任务分解，细化 task.md。
• 代码不符合预期：回到自动化执行，按任务修复；如果发现设计错误，需要同步更新 plan.md。
• 任何实现和文档不一致的地方，合并前必须更新对应文档。

4. SDD 四个阶段

4.1 阶段说明

4.2 每阶段完成定义

5. 文件产物规范

统一目录建议：

docs/sdd/<feature-name>/spec.md
docs/sdd/<feature-name>/plan.md
docs/sdd/<feature-name>/task.md
docs/sdd/<feature-name>/review.md

5.1 spec.md：意图定义文档

作用：回答"做什么、为什么做、做到什么程度"。spec.md 是后续 plan.md 和 task.md 的唯一需求依据。

• 必须包含：背景、目标、非目标、用户场景、功能范围、验收标准、约束、风险和待确认问题。
• 禁止包含：未经确认的实现细节、无验收口径的主观描述、临时口头约定。
• 质量标准：一个没参加讨论的人，看完 spec.md 能判断功能是否做对。

5.2 plan.md：技术规划文档

作用：回答"如何做、为什么这样做、失败时怎么办"。plan.md 是任务分解和代码执行的设计依据。

• 必须包含：总体架构、模块边界、数据设计、接口设计、状态流转、异常降级、安全权限、性能容量、部署配置、兼容迁移和回滚方案。
• 必须说明技术选择原因，不能只写"采用先进架构"这种空话。
• 质量标准：另一个开发人员看完 plan.md 可以独立拆任务。

5.3 task.md：任务分解文档

作用：回答"一步步怎么做"。task.md 必须足够小、足够明确、可执行、可验证。

• 每个任务只完成一个明确目标。
• 每个任务必须写输入、修改文件、执行步骤、验收标准和测试命令。
• 任务必须排序，前置依赖必须写清楚。
• 任务执行中发现计划不合理，要暂停并回写 plan.md，而不是继续硬写代码。

5.4 代码产物：执行结果

• 代码提交必须能追溯到 task.md 中的任务编号。
• 每个 PR 必须链接 spec.md、plan.md、task.md。
• 实现和文档不一致时，优先更新文档，再合并代码。
• 必须包含必要的测试、构建结果和回滚说明。

6. 审查门禁

6.1 硬性规则

• 没有 spec.md，不进入技术规划。
• 没有 plan.md，不拆 task.md。
• 没有 task.md，不允许 Agent 自动化执行代码。
• 未通过审查的文档不能作为下游阶段输入。
• 上线前必须能从代码反查到任务、从任务反查到方案、从方案反查到需求。

7. Agent 协作规范

7.1 输入包要求

• 需求输入：PRD、Issue、用户故事、截图或验收标准。
• 代码上下文：仓库路径、技术栈、关键目录、已有接口、已有数据结构。
• 约束条件：不能改什么、兼容要求、性能要求、安全要求、上线时间。
• 输出要求：本轮只输出 spec.md / plan.md / task.md / 代码中的一个，不跨阶段混做。

7.2 分阶段 Prompt 模板

# 阶段 1：生成 spec.md
请基于以下 PRD 生成 spec.md。
要求：只澄清"做什么"和"为什么做"，不要写具体代码实现。
必须包含：背景、目标、非目标、用户场景、验收标准、约束、风险、待确认问题。

# 阶段 2：生成 plan.md
请基于已确认的 spec.md 生成 plan.md。
要求：说明如何实现，并解释技术选择原因。
必须包含：架构、模块、数据、接口、状态、异常、权限、安全、性能、部署、回滚、测试方案。

# 阶段 3：生成 task.md
请基于已确认的 plan.md 拆分 task.md。
要求：每个任务都要小、可执行、可验收。
每个任务包含：编号、目标、输入、修改文件、执行步骤、验收标准、测试命令、回滚说明。

# 阶段 4：自动化执行
请按 task.md 从上到下执行。
规则：一次只执行一个任务；完成后运行对应测试；如发现 plan.md 不合理，暂停并说明需要更新的设计点。

7.3 Agent 输出约束

• 遇到需求不清必须先提问，不能靠猜。
• 生成 plan.md 时必须列出备选方案和取舍理由。
• 生成 task.md 时必须避免"大任务"，例如"完成整个后端开发"不合格。
• 执行代码时必须更新任务状态，保留测试结果。
• 任何自动修改都应控制在当前任务范围内，禁止顺手重构无关模块。

8. 团队落地规范

8.1 仓库目录

docs/
  sdd/
    <feature-name>/
      spec.md       # 意图定义
      plan.md       # 技术规划
      task.md       # 任务分解
      review.md     # 审查记录，可选
src/
  ...
tests/
  ...

8.2 命名规范

8.3 状态流转

8.4 PR 规则

• PR 描述必须包含：关联 spec.md、plan.md、task.md 的路径。
• PR 描述必须列出完成的任务编号。
• PR 必须贴出测试命令和结果。
• 涉及数据库、权限、计费、支付、更新、状态机的变更，必须补充回滚方案。

9. SDD Review Checklist

9.1 一句话合格标准

一个没参加前期讨论的开发人员，看完 spec.md、plan.md、task.md 后，能知道为什么做、怎么做、按什么顺序做、怎么测试、怎么上线、出问题怎么回滚。

附录 A：模板

A.1 spec.md 模板

# <功能名称> spec.md
状态：Draft / Reviewing / Approved
作者：
关联 PRD / Issue：
创建时间：
最后更新：

## 1. 背景
- 当前问题：
- 业务影响：
- 为什么现在要做：

## 2. 目标
- 目标 1：
- 目标 2：

## 3. 非目标
- 本期不做：

## 4. 用户场景
- 场景 1：作为 <用户>，我希望 <能力>，以便 <价值>。

## 5. 功能范围
- 功能点：
- 边界：

## 6. 验收标准
- AC1：
- AC2：

## 7. 约束与风险
- 约束：
- 风险：

## 8. 待确认问题
- Q1：

A.2 plan.md 模板

# <功能名称> plan.md
状态：Draft / Reviewing / Approved
输入：spec.md

## 1. 总体方案
- 方案摘要：
- 技术选型：
- 取舍理由：

## 2. 架构与模块
- 模块 A：职责 / 不负责
- 模块 B：职责 / 不负责

## 3. 数据设计
- 表结构：
- 索引：
- 迁移：
- 回滚：

## 4. 接口设计
- API：
- 请求参数：
- 响应结构：
- 错误码：

## 5. 状态流转
- 状态定义：
- 状态机：

## 6. 异常与降级
- 超时：
- 重试：
- 降级：

## 7. 安全与权限
- 身份来源：
- 权限规则：
- 越权风险：

## 8. 测试方案
- 单元测试：
- 集成测试：
- 回归测试：

## 9. 上线与回滚
- 上线步骤：
- 监控指标：
- 回滚方案：

A.3 task.md 模板

# <功能名称> task.md
状态：Draft / Reviewing / Approved / Implementing / Done
输入：plan.md

## 执行规则
- 一次只执行一个任务。
- 每完成一个任务必须运行对应测试。
- 如发现设计不合理，暂停并回写 plan.md。

## 任务列表

### T01 <任务名称>
- 目标：
- 前置依赖：
- 输入：
- 修改文件：
- 执行步骤：
  1.
  2.
- 验收标准：
- 测试命令：
- 回滚说明：
- 状态：Todo / Doing / Done

### T02 <任务名称>
- 目标：
- 前置依赖：
- 输入：
- 修改文件：
- 执行步骤：
- 验收标准：
- 测试命令：
- 回滚说明：
- 状态：Todo