SDD规格驱动开发 从理论到实战完整指南

基于 OpenSpec + Claude Code 工程化落地

标签：#SDD #规格驱动开发 #AI编程 #ClaudeCode #OpenSpec #TDD

一、SDD 基础理论认知

1.1 什么是 SDD

SDD（Specification-Driven Development）规格驱动开发 核心思想：先定规范契约，再动手编码，以标准化规格文档作为项目唯一可信数据源，提前定义接口、入参、出参、异常逻辑、验收标准，再开展业务开发。

• 人负责：定义做什么、业务范围、边界规则、验收标准
• AI/开发负责：技术实现、编码、单元测试、联调自测
• 核心本质：把模糊口头需求，转为可量化、可校验、可评审的正式研发契约

1.2 SDD 核心优势

1. 需求零偏差：杜绝自由开发、私自增删业务逻辑
2. 天然适配 TDD：规格等同于测试用例，实现测试先行
3. 文档可追溯：全流程文档留存，迭代维护清晰
4. AI 开发最优解：大模型可完整读取规范，严格遵守约束开发
5. 降低协作成本：前后端、多服务接口提前对齐，减少联调返工

1.3 主流开发模式对比

1.4 SDD 标准四文档体系

企业级标准 SDD 项目固定由四类文档组成，缺一不可：

1. proposal.md：需求提案，定义背景、目标、业务范围
2. specs/*.md：核心规格文档（SDD 灵魂），接口、参数、错误码、验收规则
3. design.md：技术设计，架构分层、库表、缓存、事务、流程
4. tasks.md：TDD 开发任务清单，固定开发执行顺序

二、OpenSpec + Claude Code 联动原理

2.1 工具定位

• OpenSpec：SDD 标准化脚手架，一键生成统一目录结构与文档模板，统一团队研发书写规范
• Claude Code：长文本强理解 AI 编码终端，本地读取全套 SDD 文档，严格遵循规范完成编码

2.2 完整联动流程

1. 借助 OpenSpec 初始化标准 SDD 项目目录
2. 人工填写提案、规格、技术设计三大核心文档
3. 启动 Claude Code 读取本地所有规范 Markdown 文件
4. AI 按照 tasks.md 顺序执行 TDD 开发
5. 开发完成对照规格逐条验收，确保代码与需求完全一致

2.3 组合使用优势

• 轻量化无复杂配置，纯文件驱动，接入成本极低
• 所有规范纳入 Git 版本管理，团队同步高效
• Claude 超长上下文可完整吃透整套业务+技术规范
• 跨技术栈通用，Java / Go / Python / 前端均可使用

三、本地环境快速搭建

3.1 安装依赖

# 全局安装 OpenSpec 脚手架
npm install -g openspec-cli

# 创建项目目录
mkdir sdd-practice && cd sdd-practice

# 初始化 SDD 标准目录结构
openspec init

# 新建业务需求（自动生成全套空白文档）
openspec new "用户手机号验证码登录"

# OpenSpec \+ Claude Code SDD 实战手册

# 1\. 简介

本文为**工业级 SDD（规格驱动开发）标准实战模板**，采用 **OpenSpec \+ Claude Code** 组合，实现：**先规范、后编码、TDD 先行、可验收、可追溯**。

示例业务：**手机号\+验证码登录**（SpringBoot \+ MySQL \+ Redis）。

# 2\. 环境部署

## 2\.1 安装依赖

```bash
# 全局安装 OpenSpec
npm install -g openspec-cli

# 创建项目
mkdir sdd-demo && cd sdd-demo

# 初始化 OpenSpec 目录结构
openspec init

# 新建需求（自动生成标准目录）
openspec new "用户手机号验证码登录"

生成路径：openspec/changes/user\-login\-sms/

3. SDD 标准文档结构

openspec/
└── changes/
    └── user-login-sms/
        ├── proposal.md    # 业务提案
        ├── design.md      # 技术设计
        ├── tasks.md       # TDD任务清单
        └── specs/
            └── login.spec.md  # 核心规格

4. 文档内容

4.1 业务提案 proposal.md

4.1.1 业务背景

系统提供轻量化登录能力，用户无需密码，通过手机号+短信验证码完成登录，新用户自动注册。

4.1.2 开发目标

• 实现手机号+验证码登录

• 未注册用户自动注册

• 登录成功返回 JWT

• 拦截非法参数、过期、错误验证码

4.1.3 包含范围

• 手机号、验证码格式校验

• 验证码校验逻辑

• 自动注册用户

• JWT 登录态返回

• 统一错误码体系

4.1.4 不包含范围

• 真实短信发送（内存模拟验证码）

• 第三方登录、密码登录

• 图形验证码

4.1.5 依赖组件

• Redis：验证码存储、过期管控

• JWT：签发登录令牌

• MySQL：用户数据持久化

4.2 核心规格 login.spec.md

4.2.1 接口信息

• 请求方式：POST

• 请求地址：/api/v1/login/sms

• 接口描述：手机号验证码登录

4.2.2 入参定义

4.2.3 通用出参结构

{
  "code": int,
  "msg": string,
  "data": object
}

4.2.4 成功返回示例

{
  "code": 200,
  "msg": "登录成功",
  "data": {
    "userId": 10001,
    "phone": "13800138000",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

4.2.5 错误码规范

4.2.6 验收标准

• [x] 手机号非法 → 40001

• [x] 验证码非法 → 40002

• [x] 验证码过期/不存在 → 40003

• [x] 验证码不匹配 → 40004

• [x] 新手机号自动注册

• [x] 老手机号直接登录

• [x] 返回合规 JWT

• [x] 无脏数据、重复请求不重复创建用户

4.2.7 边界场景

• 多次输错验证码

• 验证码5分钟超时

• 同一手机号高频请求

4.3 技术设计 design.md

4.3.1 执行流程

用户请求 → 参数校验 → 查询Redis验证码 → 比对验证码 → 无用户则注册 → 生成JWT → 返回结果

4.3.2 代码分层

• Controller：参数接收、统一返回封装

• Service：登录业务、验证码校验

• Dao：用户查询、新增

• Util：JWT工具类

4.3.3 数据库表设计（user）

• id：bigint 主键

• phone：varchar 唯一索引

• create_time：datetime

4.3.4 Redis 存储规范

• Key：sms:code:\{phone\}

• Value：6位数字验证码

• 过期时间：5分钟

4.3.5 安全规范

• 手机号唯一防重复

• 验证码一次性校验

• JWT 有效期 2h

• 禁止返回敏感字段

4.3.6 日志规范

• 打印请求手机号

• 记录验证码校验结果

• 记录用户注册/登录行为

4.4 开发任务 tasks.md（TDD 顺序）

• [ ] 1. 依据 Spec 定义入参、出参 DTO

• [ ] 2. 编写手机号、验证码校验工具

• [ ] 3. 编写4条参数异常单元测试

• [ ] 4. 编写 Redis 验证码读取工具

• [ ] 5. 实现用户查询、自动注册逻辑

• [ ] 6. 编写 JWT 生成工具

• [ ] 7. 实现登录主业务流程

• [ ] 8. 编写正常流程单元测试

• [ ] 9. 边界场景测试（过期、错误、重复请求）

• [ ] 10. 代码格式化、补充注释

• [ ] 11. 对照 Spec 逐条验收

5. Claude Code 绑定指令（直接复制使用）

现在严格使用 OpenSpec + SDD 模式开发。
请读取当前目录 openspec/changes/user-login-sms/ 下全部文档：
1.proposal.md
2.specs/login.spec.md
3.design.md
4.tasks.md

硬性约束：
1. 严格遵守SPEC，禁止私自加字段、加逻辑
2. 必须TDD：先写测试，后写业务代码
3. 全部异常场景必须覆盖
4. 代码分层严格按照design执行
5. 开发完成后，逐条勾选tasks验收，输出验收报告

技术栈使用：Java SpringBoot / MySQL / Redis

6. 通用万能 SDD 指令（所有项目通用）

你现在是标准SDD开发模式，绑定OpenSpec：
一切以spec为唯一标准。
spec没写的一律不做，spec写的一律不能漏。
流程固定：写测试→跑红→写代码→跑绿→边界自测→输出验收报告。
禁止任何主观新增逻辑，禁止简化异常分支。
所有代码必须贴合design架构。

7. 核心工作原理

1. OpenSpec：统一规范目录、强制标准文档格式

2. 使用者：只编写 Spec（定义输入、输出、报错、验收）

3. Claude Code：读取文档、严格执行、不脑补、不跑偏

4. Tasks：强制 TDD 流程，保障代码质量

（注：文档部分内容可能由 AI 生成）

• Previous
  领域驱动设计