一、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创建提案：备注：Claude Code中无法换行，需要在末尾加上\然后按Enter才能生效。

 /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的最新定义进行修改；

如果涉及的spec定义要进行调整，则对spec定义补充，补充完整后，提醒claude code: plan模式：

# 强制读取最新Proposal指令
忽略对话历史里所有旧版本Proposal、旧设计逻辑，以本地磁盘刚更新保存的Proposal文档为唯一权威标准。
执行以下步骤：
1. 重新完整读取【文件路径：xxx/proposal.md】最新全文，同步对照SDD；
2. 逐条梳理本次Proposal修改点，列出变更前后差异；
3. 生成开发Plan，每一条实现方案必须绑定Proposal对应条款编号；
4. Plan中所有和旧设计冲突的逻辑全部废弃，不兼容旧实现方案；
5. 输出Plan前自检：若存在任何和最新Proposal冲突的设计思路，直接剔除并标注冲突点。

edit模式：

# 重度强制刷新提案，代码全量对齐
1. 彻底丢弃本次对话中之前基于旧版Proposal生成的所有代码逻辑、架构方案；
2. 重新加载本地最新的 proposal.md（路径：xxx/proposal.md），以此为唯一开发依据，SDD作为顶层约束；
3. 本次所有代码修改、接口定义、数据结构、校验规则、异常分支必须严格遵循更新后的Proposal新增/修改条款；
4. 禁止自行补充文档未定义的字段、方法、依赖、业务分支；
5. 代码修改完成后，逐条做校验：每一处代码实现对应Proposal哪一段，列出所有不匹配项并自动修复；
6. 若现有存量代码和最新Proposal冲突，优先重构存量代码适配新提案，不得妥协沿用旧逻辑。

执行后生成的网站效果：

Sdd