SDD：规范驱动开发（Spec-Driven Development）

SDD：规范驱动开发（Spec-Driven Development）是什么？

它的核心思想是：先明确需求和技术规范，再让 AI 根据规范编写代码，最后通过测试和验证确保实现符合预期。

举个例子。

你告诉 AI：

帮我开发一个设备管理页面，实现设备的增删改查。

这只是一个模糊需求。AI 可能自行决定字段名称、接口格式、分页参数、权限处理方式，甚至使用与你现有项目不同的代码风格。

采用 SDD 后，你会先明确：

设备包含哪些字段，哪些字段必填。
列表接口如何分页，查询条件有哪些。
新增、编辑、删除分别调用哪个接口。
设备编号是否唯一，在线设备能否删除。
哪些操作需要权限校验。
页面如何复用项目已有的组件、API 封装和表单校验。
什么条件下算开发完成。

规范越明确，AI 的自由发挥空间越小，生成结果就越容易预测、验证和维护。

SDD 的完整开发流程

以目前比较有代表性的开源工具 GitHub Spec Kit 为例，它将 SDD 流程组织为 Specify → Plan → Tasks → Implement → Converge。复杂项目还可以加入需求澄清、质量检查和规范一致性分析。

Specify：定义需求规范

明确要解决什么问题、有哪些用户、业务规则是什么、哪些情况不允许发生。

产物：spec.md，需求规范

Plan：制定技术方案

根据项目现有架构，确定技术栈、模块边界、数据库设计、接口契约、依赖关系及安全约束。

产物：plan.md，技术实施计划（其他AI称为design.md）

Tasks：拆分开发任务

将技术方案拆成可以独立完成和验证的任务，明确先后顺序和依赖。

产物：tasks.md，任务清单

Implement：按任务实现

让 AI 按任务逐项编写代码，包括前端、后端、数据库脚本和测试。每完成一组任务就进行检查。

产物：代码、测试、数据库变更等

Converge：对照规范收敛

检查实现是否覆盖所有需求，运行测试，发现遗漏后补充任务，再继续修复，直到达到验收条件。

产物：验证结果、未解决问题清单、符合规范的实现

这里的 spec.md、plan.md 和 tasks.md 是便于理解的典型产物名称；实际文件组织以所使用的工具和团队约定为准。

SDD、Prompt Engineering、TDD、RAG 有什么区别？

这几个概念经常一起出现在 AI 辅助开发中，但解决的问题不同。

|--------------------|----------------|------------------------|
| 概念 | 核心问题 | 主要作用 |
| SDD | 到底要构建什么？ | 用规范约束需求、设计和实现 |
| Prompt Engineering | 如何向 AI 表达任务？ | 提升指令的清晰度和输出质量 |
| TDD | 如何用测试驱动实现？ | 通过先写测试、再实现代码来验证行为 |
| RAG | AI 需要依据哪些外部知识？ | 检索文档、代码或业务知识，为生成提供上下文 |
| AI Agent | 如何完成多步骤任务？ | 规划、调用工具、执行操作、观察结果并继续处理 |

SDD 的规范文件应该包含哪些内容？

一个比较实用的项目规范可以分为四类。

项目级规范

技术栈、目录结构、命名约定、代码风格、分层架构、权限和安全要求。

例如：后端必须遵守 Controller、Service、Mapper 分层。

功能级需求规范

业务目标、用户操作、字段定义、异常场景、业务规则和验收标准。

例如：设备编号唯一，删除有关联数据的设备需要受限。

技术实现规范

数据库表、API 契约、模块依赖、状态流转、缓存策略、消息处理和事务边界。

例如：设备命令接口需要区分"指令已发送"和"设备已执行成功"。

验收与质量规范

单元测试、接口测试、构建检查、权限检查、性能约束及安全检查。

例如：重复编号、未授权请求和设备不存在时均有明确结果。

这些内容不一定全部放进同一个 Markdown 文件。项目级规则可以单独维护，具体功能再维护自己的规范、方案和任务清单。

SDD 的优缺点与适用场景

优点

需求、技术方案和验收条件更加清晰。
多轮 AI 开发可以持续引用明确的项目约束。
更适合复杂业务、多人协作和较长周期的功能开发。
规范和任务清单可作为代码评审与回归测试的依据。

缺点

前期需要整理和澄清需求，简单任务可能显得流程过重。
规范本身也可能有遗漏或错误，不能因为文档完整就认定设计正确。
如果需求变化后不更新规范，AI 仍可能按照过时的规则生成代码。
规范检查和测试并不能替代人工代码审查，尤其是权限、并发、事务和设备控制等关键逻辑。

比较合适的做法是：小改动采用轻量规范；复杂业务采用完整流程；高风险功能增加更严格的测试、代码审查和上线验证。

以物联网管理平台为例

先编写需求规范 spec.md

设备管理模块需求规范

1. 功能目标

实现设备的分页查询、新增、编辑、详情查看和删除。

2. 设备字段

id：数据库主键

deviceName：设备名称，必填

deviceCode：设备唯一编号，必填且不可重复

productId：所属产品

status：设备状态

createTime：创建时间

3. 业务规则

设备编号必须唯一。

新增和编辑时必须校验必填字段。

删除前校验设备是否存在。

对有关联数据或正在执行任务的设备，

必须按业务规则限制删除。

设备状态以服务端数据为准，不能由前端任意修改。

4. 页面要求

使用项目已有的 Vue3、Element Plus 组件。

支持分页、设备名称和设备编号查询。

表单使用统一校验规则。

复用现有 API 封装和权限指令。

统一处理加载状态、请求失败和空数据。

5. 验收标准

重复设备编号无法保存。

查询条件和分页参数传递正确。

无权限用户不能执行受保护的操作。

新增、编辑、删除后列表数据正确更新。

前后端构建通过，相关测试通过。

这份规范的重点不是写得多，而是把 AI 不能自行决定的业务规则说清楚。

例如，"删除设备"到底是物理删除、逻辑删除，还是有关联数据时禁止删除？如果规范没有说明，AI 即使生成了正确的 SQL，也可能实现错误的业务行为。

再制定技术方案 plan.md

针对已有的 RuoYi-Vue3 项目，技术方案可以明确：

|-------|-------------------------------------------|
| 层次 | 约束与设计 |
| 前端 | Vue3、Element Plus，复用现有页面模板与公共组件 |
| API 层 | 沿用项目已有请求封装、统一响应处理 |
| 后端 | Spring Boot Controller → Service → Mapper |
| 数据库 | MySQL，唯一约束和索引根据业务规则设计 |
| 权限 | 复用现有登录认证、权限校验机制 |
| 缓存 | 如果设备数据使用 Redis 缓存，明确更新和失效策略 |
| 测试 | 覆盖正常流程、重复编号、无权限、数据不存在等情况 |

尤其要注意：SDD 不是让 AI 重新设计一套系统，而是让 AI 在已有架构约束下完成任务。

在老项目中，应先让 AI 阅读现有的设备模块、产品模块、公共表单、API 封装和后端分层代码，再生成技术方案。

将方案拆分成 tasks.md

设备管理模块开发任务

1. 检查现有设备模块及公共代码规范

2. 确认设备表结构、唯一约束和关联关系

3. 实现后端分页查询接口

4. 实现新增、编辑、详情、删除接口

5. 实现参数校验、权限校验和异常处理

6. 编写前端设备列表页面

7. 编写新增、编辑表单及校验逻辑

8. 对接接口并处理加载、错误和空状态

9. 编写或完善相关测试

10. 运行构建和测试，逐项对照需求验收

为什么要拆任务？

因为让 AI 一次生成整个前后端模块，容易出现接口字段不一致、业务逻辑遗漏、文件修改范围过大等问题。分阶段执行更容易发现错误并控制变更范围。