一、SDD 基础理论认知

1.1 什么是 SDD

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

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

1.2 SDD 核心优势

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

1.3 主流开发模式对比

开发模式	核心流程	核心痛点
传统业务开发	需求→设计→编码→测试	后期改需求频繁，返工量大
DDD领域驱动	领域建模→聚合设计→业务落地	偏重业务模型，缺少接口验收标准
SDD规格驱动	规格定义→技术设计→测试先行→编码→验收	契约优先，全流程标准统一

1.4 SDD 标准四文档体系

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

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

二、OpenSpec + Claude Code 联动原理

它采用经典的 Proposal → Apply → Sync → Archive 四步闭环工作流，把 AI 编码从“艺术创作”升级为“规范工程”。三大核心技能（Claude Code 环境中）：

/opsx:propose：创建结构化需求提案
/opsx:apply：AI 严格按提案执行代码实现
/opsx:archive：完成归档，保持 Spec 与代码同步

2.1 工具定位

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

2.2 核心工作原理

OpenSpec：统一规范目录、强制标准文档格式
使用者：只编写 Spec（定义输入、输出、报错、验收）
Claude Code：读取文档、严格执行、不脑补、不跑偏
Tasks：强制 TDD 流程，保障代码质量

2.3 完整联动流程

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

三、本地环境快速搭建

3.1 安装依赖

# 全局安装 OpenSpec
npm install -g @fission-ai/openspec@latest

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

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

初始化时，openspec会让你选择具体使用的AI工具，支持：Claude Code、Qoder等。初始化后的目录结构：

|-- CLAUDE.md
`-- openspec
    |-- changes
    |   `-- archive
    |-- config.yaml
    `-- specs

四、实战演练

4.1. 简介

创建一个名字叫零越起点的长租公寓项目。

4.2. 开发

创建项目名ly-start并进入到目录中用claude命令并初始化项目，初始化项目后再claude中用/opsx:apply创建提案：

 /opsx:propose 创建一个长租公寓展示网站，用java spring实现：
主要功能包括：
- 添加房源信息
- 房源能添加修改照片
- 能标记房源已经出租了，出租了要标记出租到期时间
- 添加房源信息能添加房间的基本介绍，如：是否有阳台、是否有冰箱、租金价格等

执行后会的目录结构为：

|-- CLAUDE.md
`-- openspec
    |-- changes
    |   |-- apartment-rental-website
    |   |   |-- design.md
    |   |   |-- proposal.md
    |   |   |-- specs
    |   |   |   `-- property-spec.md
    |   |   `-- tasks.md
    |   `-- archive
    |-- config.yaml
    `-- specs

对生成的proposal.md、property-spec.md、desgin.md、tasks.md文件检视有问题可以让claude code直接修改：

对apartment-rental-website中的property-sepc文件进行修改
- 所有房源管理和详情管理不需要用api，直接用配置文件配置，每个房源有个配置，在配置中配置房间图片信息、房间详情描述、是否租赁等；
- property-spec修改后，design和tasks文件要按最新的property-spec的最新定义进行修改；

执行后生成的网站效果：

参考文章

Claude Code 进阶必学：OpenSpec 规范驱动开发完整指南

Sdd