AI 规范编程：从 SDD 理念到 Spec-Kit 落地实践

SDD 诞生的背景：AI 时代软件工程的范式变革

1 、传统开发范式的痛点

在 AI 编码助手（如 GitHub Copilot 、Claude Code 、Cursor ）普及之前，软件开发遵循 "代码优先、文档次之" 的模式，面临三大核心痛点：

痛点	具体表现	影响
意图与实现鸿沟	需求文档模糊、变更频繁，代码与文档长期脱节	沟通成本高，重构风险大，维护困难
协作效率低下	团队成员对需求理解不一致，缺乏统一 "事实来源"	重复工作多，冲突频繁，交付周期长
质量保障滞后	测试在编码后进行，缺陷发现晚，修复成本高	产品稳定性差，用户体验受损

随着 AI 编码工具的普及，这些问题被进一步放大：AI 能快速生成代码，但缺乏对整体系统架构和业务逻辑的理解，容易产生 "局部正确但全局错误" 的代码；同时，开发者过度依赖 AI 提示词，导致代码质量参差不齐，可维护性急剧下降。

2 、SDD 的核心定义与价值

规范驱动开发 (Spec-Driven Development, SDD) 是生成式 AI 时代下适配工程化开发的新型软件开发方法论，核心是先由技术人员定义简洁、可测试、形式化的系统规格说明 (Spec)，将其作为人、团队与 AI 之间的 "动态契约" 和开发过程的唯一事实来源。

SDD 带来三大革命性转变：

权力反转：将软件开发的 "单一事实来源" 从易变的代码转移到人类意图的直接表达 —— 规范本身
流程重构：从 "编码→测试→修复→文档" 转变为 "规范→设计→实现→验证" 的线性流程
人机协同：规范成为 AI 的 "操作手册"，消除 AI 猜测意图的成本，提升代码生成质量

3 、SDD 的发展历程

SDD 并非全新概念，而是在传统软件工程理论基础上的进化：

早期起源：可追溯至 20 世纪 80 年代的 "契约式设计"(Design by Contract) 和 "测试驱动开发"(TDD) 理念
现代演进：2025 年，GitHub 发布 Spec-Kit 工具，正式将 SDD 从理论推向实践
生态成熟：2026 年，OpenSpec 、Superpowers 等工具相继出现，形成完整的 SDD 工具生态
行业认可：微软、亚马逊等科技巨头开始在内部推广 SDD 方法论，将其纳入官方培训课程

Spec-Kit 案例实践

以 "XXL-API 项目代码重构" 为例，展示 Spec-Kit 的完整实践流程。

本次改造项目为正式项目，对代码规范性与质量存在要求；另外，该重构需求涉及 “9 个功能模块”、“前后端代码逻辑修改”，累计需要修改 130+ 项目文件，为中型颗粒度需求。本次改造需求存在一定复杂度。

Specify - 生成功能规格

执行如下命令 + 填写功能需求描述，生成 “功能规格（ Spec ）”：

/speckit.specify  针对 XXL-API 项目按照如下要求重构：

1 、按照下面项目规范结构，重构重构项目目录结构：

xxl-api-admin/src/main/java/com/xxl/api/admin
- /framework: 基础框架代码，包含公共的 登录、util 、过滤器等组件。
- /business：业务代码，包含具体业务模块的 controller 、service 、model 、mapper 子分层代码。
  xxl-api-admin/src/main/resources/templates
- /framework：基础模板，基础框架实体 对应的。
- /business：业务模板，业务领域实体对应的。
  xxl-api-admin/src/main/resources/mapper
- /framework：基础 Mapper 文件，基础框架实体 对应的。
- /business：业务 Mapper 文件，业务领域实体对应的。


2 、业务代码分类判断逻辑：Java 代码部分，当前 com/xxl/api/admin/controller/biz 下除了 UserController 都是 业务领域，保留 User 相关 Java 代码不变，其他按照规范调整。模板部分，当前 help.ftl 、index.ftl 、login.ftl 属于基础框架，其他属于业务领域； Mapper 部分，当前 XxlApiUserMapper.xml 属于基础框架，其他属于业务部分。

执行后将会生成 .specify/specs/001-project-structure-refactor/spec.md 文件，内容如下：

Plan - 生成技术规划

执行如下命令，生成 “技术规划”：

/speckit.plan

执行后将会生成 .specify/plans/001-project-structure-refactor/plan.md 文件，内容如下：

Tasks - 拆解任务

执行如下命令，生成 “任务清单”：

/speckit.tasks

执行后将会生成 .specify/tasks/001-project-structure-refactor/tasks.md 文件，内容如下：

Implement - 生成代码实现

执行如下命令，将会按照拆解任务（ tasks.md ）进行 “代码生成”：

/speckit.implement

Agent 会按照任务清单（ tasks.md ）逐个实现，每个任务完成后自动对照requirements.md检查。

所有任务完成后，人工进行 Review 验收，确认符合要求后合并代码（当前该 PR 已合入 XXL-API master 分支，交付符合预期）。

Spec 完整实践记录见： https://www.xuxueli.com/blog/?blog=ai/speckit