跳至主要内容

AI 时代开发新范式：SDD 规范驱动开发文档管理策略

Fen9Pi2026/5/30方法论方法论大约 9 分钟

AI 时代开发新范式：SDD 规范驱动开发文档管理策略

AI协作开发

当 AI 成为你的开发伙伴，谁来维护规范？以哪个文档为准？如何推进？

这些问题，正是 SDD（Specification-Driven Development）要解决的。

一、传统开发的文档困境

文档混乱

在传统开发模式下，文档往往陷入以下困局：

  • 需求文档写了一版又一版，但没人知道哪版是最终版
  • 架构设计写在 Wiki 上，和实际代码逐渐脱节
  • 开发计划更新靠自觉，项目管理形同虚设"
  • 团队新人入职后，要花两周搞清楚"以什么为准"

而当 AI 加入开发团队后，这些问题被进一步放大——AI 不会主动去问"该看哪个文档"，它只能依据你喂给它的上下文来行动。

如果上下文混乱，AI 的输出就会混乱。

二、SDD：让文档各司其职

分层架构

SDD（Specification-Driven Development）的核心思想是：通过分层级的文档体系，明确每个文档的职责、维护者与流转关系。

不是"把文档堆在一起"，而是"让文档形成一条清晰的链路"。

2.1 六层文档体系

┌─────────────────────────────────────────┐
│         AGENTS.md（宪法层）              │  最高指导原则
├─────────────────────────────────────────┤
│         Standards（规范层）              │  技术约束与标准
├─────────────────────────────────────────┤
│         Features（需求层）               │  需求规格与字段映射
├─────────────────────────────────────────┤
│         Designs（设计层）                │  系统真实设计的来源
├─────────────────────────────────────────┤
│         Plans（计划层）                  │  任务拆分与进展追踪
├─────────────────────────────────────────┤
│         TDD（开发实践层）                │  测试驱动代码实现
└─────────────────────────────────────────┘

每一层都有明确的定位，不可替代。

三、各层详解

🏛️ 宪法层：AGENTS.md

宪法与规则

定位： 最高指导原则，统领所有规范与流程。

这是整个文档体系的"宪法"。它定义了：

  • 团队（或 AI Agent）的基本行为准则
  • 开发流程的全局规则
  • 各层文档之间的引用关系

类比： 就像一个国家的宪法，它不规定具体怎么征税，但它定义了"谁有权制定税法"。

# AGENTS.md

## 开发原则
- 所有功能必须有需求文档（Features）才能启动
- 所有数据库变更必须更新设计文档（Designs）
- 所有任务必须有对应的 Plan

## 文档流转规则
Features → Designs → Plans → TDD

📏 规范层：Standards

技术标准

定位： 定义技术约束，让 AI 和团队在框架内行动。

包含：

  • 架构规范：项目结构、模块划分、依赖管理
  • 建表规范：命名规则、字段类型、索引策略
  • API 规范：接口风格、错误码、版本控制
  • 命名规范：变量、函数、类、表名的命名约定
  • 安全规范：敏感数据处理、认证授权、输入校验

关键原则： 规范是"约束"，不是"建议"。AI 在生成代码时，必须遵守这些约束。

# Standards/建表规范.md

## 命名规则
- 表名：复数名词，snake_case（如 `user_orders`）
- 字段名：snake_case（如 `created_at`）
- 主键：统一使用 `id`（BIGINT, AUTO_INCREMENT）
- 外键：`{关联表名}_id`（如 `user_id`）

## 必备字段
每张表必须包含：
- `id`：主键
- `created_at`：创建时间
- `updated_at`：更新时间
- `deleted_at`：软删除标记（可为 NULL）

📋 需求层：Features

需求分析

定位： 开发起点，由产品或 BA（业务分析师）维护。

包含：

  • 需求规格：用户故事、功能描述、验收标准
  • 字段映射表：前端字段 → 后端字段 → 数据库字段的对应关系
  • 业务规则：计算逻辑、状态流转、边界条件

关键原则： 需求是"起点"，不是"终点"。它驱动后续所有层的工作。

# Features/用户注册.md

## 用户故事
作为新用户，我希望通过手机号注册账号，以便使用系统功能。

## 字段映射表
| 前端字段 | 后端字段 | 数据库字段 | 类型 | 校验规则 |
|---------|---------|-----------|------|---------|
| 手机号 | mobile | mobile | VARCHAR(20) | 必填，11位数字 |
| 验证码 | code | - | VARCHAR(6) | 必填，6位数字 |
| 密码 | password | password_hash | VARCHAR(256) | 必填，≥8位 |

## 验收标准
- [ ] 手机号格式校验
- [ ] 验证码有效期 5 分钟
- [ ] 同一手机号不能重复注册

🏗️ 设计层：Designs

数据库设计

定位： 事实来源（Source of Truth），管理当前系统的真实设计。

包含：

  • 数据库设计：表结构、关系图、ER 图
  • 接口设计：API 文档、请求/响应格式
  • 系统架构：模块关系、部署拓扑

关键原则： 设计文档必须与实际系统保持一致。系统变了，文档必须同步更新。

# Designs/database/users.md

## users 表

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| id | BIGINT | AUTO_INCREMENT | 主键 |
| mobile | VARCHAR(20) | NOT NULL | 手机号 |
| password_hash | VARCHAR(256) | NOT NULL | 密码哈希 |
| nickname | VARCHAR(50) | NULL | 昵称 |
| avatar_url | VARCHAR(500) | NULL | 头像 URL |
| status | TINYINT | 1 | 状态：1=正常，0=禁用 |
| created_at | DATETIME | NOW() | 创建时间 |
| updated_at | DATETIME | NOW() | 更新时间 |
| deleted_at | DATETIME | NULL | 软删除时间 |

## 索引
- UNIQUE INDEX `idx_mobile` (`mobile`)
- INDEX `idx_status` (`status`)
- INDEX `idx_created_at` (`created_at`)

## 最后更新
- 更新时间：2026-05-30
- 更新原因：新增 nickname、avatar_url 字段
- 更新人：@张三

📊 计划层：Plans

项目计划

定位： 记录每轮任务的进展、工作状态及具体任务拆分。

包含：

  • 任务拆分（Tasking）：将需求拆分为可执行的开发任务
  • 工作状态：待办 / 进行中 / 已完成 / 已阻塞
  • 进展记录：每轮的完成情况、遇到的问题、变更记录

关键原则： 计划是"执行路线图"，让每个人（和 AI）都知道"现在该做什么"。

# Plans/2026-05-30-sprint.md

## Sprint: 用户注册功能

### 任务拆分
| 序号 | 任务 | 负责人 | 状态 | 预计工时 |
|------|------|--------|------|---------|
| 1 | 设计 users 表结构 | @张三 | ✅ 已完成 | 2h |
| 2 | 实现手机号校验 API | @李四 | 🔄 进行中 | 4h |
| 3 | 实现验证码发送 | @李四 | ⏳ 待办 | 3h |
| 4 | 前端注册页面 | @王五 | ⏳ 待办 | 6h |
| 5 | 集成测试 | @赵六 | ⏳ 待办 | 4h |

### 阻塞项
- [ ] 短信服务商 API 密钥尚未申请（@王五 推动中）

### 变更记录
- 2026-05-30：初始创建
- 2026-05-30：任务 1 完成，更新 Designs 中的 users 表

🧪 开发实践层：TDD

测试驱动开发

定位： 测试驱动开发，用测试来验证实现是否符合规范。

关键原则： 先写测试，再写实现。测试就是"活的规范"。

// tests/user-registration.test.js

describe('用户注册', () => {
  it('应拒绝格式错误的手机号', async () => {
    const res = await register({ mobile: '123', code: '000000' });
    expect(res.status).toBe(400);
    expect(res.error).toBe('手机号格式错误');
  });

  it('应拒绝重复注册', async () => {
    await register({ mobile: '13800138000', code: '000000' });
    const res = await register({ mobile: '13800138000', code: '000001' });
    expect(res.status).toBe(409);
    expect(res.error).toBe('该手机号已注册');
  });

  it('应校验验证码有效期', async () => {
    // 模拟 6 分钟后的请求
    jest.advanceTimersByTime(6 * 60 * 1000);
    const res = await register({ mobile: '13800138000', code: '000000' });
    expect(res.status).toBe(400);
    expect(res.error).toBe('验证码已过期');
  });
});

四、流转机制：Plan/Go 模式

工作流

文档分层只是静态结构，真正的价值在于流转。

4.1 流转路径

需求（Features）
    ↓ 需求评审通过
设计（Designs）
    ↓ 设计评审通过
计划（Plans）
    ↓ 任务拆分完成
开发（TDD）
    ↓ 测试通过
部署（Go）

每一步流转都需要明确的准入条件和责任人。

4.2 Plan/Go 模式

这是 SDD 中最关键的流转机制：

Plan 阶段（计划模式）：

  • 从需求层拉取规格
  • 在设计层创建/更新设计
  • 在计划层拆分任务
  • 确认所有约束（规范层）

Go 阶段（执行模式）：

  • 按照计划执行开发
  • 用 TDD 验证实现
  • 完成后更新设计层（如果实现有偏差）
  • 标记任务完成

核心要点： Plan 时不写代码，Go 时不改计划。

4.3 规格同步

当实现发现设计偏差时：

发现偏差 → 暂停 Go → 回到 Plan → 更新 Designs → 重新确认 → 继续 Go

绝不允许： 在 Go 阶段悄悄改设计而不更新文档。

五、AI 协作的关键洞察

AI与人类协作

5.1 AI 需要明确的上下文

AI 不会"猜"你想要什么。你喂给它 AGENTS.md，它就按全局规则行事；你喂给它 Standards，它就按技术约束写代码；你喂给它 Features，它就按需求规格实现。

上下文越清晰，AI 输出越准确。

5.2 AI 维护文档的优势

AI 天然适合维护文档：

  • 实时更新：代码改了，AI 可以同步更新 Designs
  • 一致性检查：AI 可以扫描所有层，发现不一致
  • 自动流转：Plan 完成后，AI 可以自动触发 Go 阶段
  • 版本追溯：AI 的每次操作都可以被记录

5.3 避免"AI 幻觉"

没有明确规范时，AI 会"创造"规则：

  • 自己发明命名方式
  • 自己决定字段类型
  • 自己设计接口格式

SDD 的作用： 让 AI 在框架内创造，而不是自由发挥。

六、落地建议

落地执行

6.1 从小处开始

不需要一开始就建立完整的六层体系：

  1. 第一步： 先建 AGENTS.md，定义基本原则
  2. 第二步： 建 Standards，整理现有规范
  3. 第三步： 在新需求中尝试 Features → Designs → Plans 流转
  4. 第四步： 引入 TDD，用测试固化规范

6.2 工具选择

层级推荐工具
AGENTS.mdMarkdown（放在仓库根目录）
StandardsGit 仓库 + Wiki
Features飞书文档 / Notion / 腾讯文档
Designs数据库版本管理（如 Flyway）+ Markdown
Plans项目管理工具（如 Linear）+ Markdown
TDD测试框架（Jest / Pytest / Go Test）

6.3 度量指标

追踪 SDD 的效果：

  • 文档覆盖率：有需求文档的功能占比
  • 设计一致率：Designs 与实际系统的一致性
  • 计划完成率：Plans 中已完成任务的占比
  • 缺陷返工率：因规范不清晰导致的 bug 占比

七、总结

总结

SDD 不是一套复杂的框架，而是一种思维方式：

先立规矩，再写代码。让文档形成链条，让规范驱动开发。

无论你是个人开发者还是团队协作，无论你是否使用 AI 辅助，清晰的文档分层和流转机制，都能让你的开发工作更加有序、可追溯、可扩展。

下一步行动：

  1. 检查你当前项目中是否有 AGENTS.md
  2. 盘点现有文档，看看它们分别属于哪一层
  3. 选择一个正在进行的需求，尝试走一遍 SDD 流转

规范不是束缚，而是让创造力更有方向的力量。

最近更新:
贡献者: Fen9Pi
Copyright © 2016-2022 风派 | 苏ICP备2025227748号-3