规范驱动开发（SDD）全解：从理念到实践

mindmap
  root((规范驱动开发 SDD))
    ("权力的反转")
      ("代码曾为王，规范附庸")
      ("SDD 反转：代码服务于规范")
      ("消除规范与实现的鸿沟")
      ("AI 让规范可执行")
    ("SDD 工作流实践")
      ("从模糊想法到完整 PRD")
      ("AI 提问澄清 → 定义验收标准")
      ("研究代理收集上下文")
      ("生成实现计划：技术决策可追溯")
      ("规范驱动测试与代码生成")
      ("生产反馈 → 更新规范")
    ("为什么 SDD 恰逢其时")
      ("AI 已能可靠生成代码")
      ("软件复杂性指数级增长")
      ("需求变化更频繁")
      ("SDD 将变更转化为系统性再生成")
    ("核心原则")
      ("规范是通用语言")
      ("规范可执行")
      ("持续精炼")
      ("研究驱动上下文")
      ("双向反馈")
      ("分支探索优化目标")
    ("实施途径")
      ("AI 助手：迭代规范")
      ("研究代理：收集上下文")
      ("代码生成工具")
      ("版本控制：规范优先")
      ("AI 一致性检查")
    ("命令简化 SDD")
      ("/specify → 生成规范")
      ("/plan → 实现计划")
      ("/tasks → 可执行任务清单")
      ("示例：聊天功能开发")
    ("结构化自动化")
      ("模板保障完整性与一致性")
      ("避免过早实现细节")
      ("强制标记不确定性")
      ("清单驱动结构化思考")
      ("架构关卡：简洁/反抽象/集成优先")
      ("分层信息架构")
      ("测试优先顺序")
      ("避免推测性功能")
    ("复合效应")
      ("规范完整、无歧义、可测试、可维护、可实现")
      ("LLM 从写手 → 规范工程师")
    ("宪法基础")
      ("九条原则")
        ("库优先")
        ("CLI 强制")
        ("测试优先")
        ("简洁 & 反抽象")
        ("集成优先测试")
      ("模板执行：关卡检查")
      ("不可变原则：保持一致与质量保障")
      ("宪法演化：修订流程")
      ("开发哲学：可观测、简洁、集成、模块化")
    ("转变")
      ("不是取代开发者，而是增强能力")
      ("通过可执行规范保持意图与实现的对齐")

权力的反转 🔗

几十年来，代码一直是王者。规范服务于代码——它们是我们搭建的脚手架，而一旦“真正的工作”——写代码——开始了，规范就被丢弃。我们写 PRD（产品需求文档）来指导开发，写设计文档来辅助实现，画架构图来帮助可视化。但这些始终从属于代码本身。代码才是事实真相，其它最多只是“美好意图”。代码是唯一的真理来源，而当代码不断演进时，规范几乎从来跟不上。由于资产（代码）和实现是同一个东西，没有直接基于代码去构建，就很难做到并行实现。

规范驱动开发（SDD）颠倒了这种权力结构。规范不再服务于代码——而是代码服务于规范。PRD 不再是实现的指导书，而是直接生成实现的源头。技术方案也不再是提示编码的文档，而是能够产出代码的精确定义。这不是对软件开发方式的渐进式改进，而是对“什么驱动开发”这一根本问题的重新思考。

规范与实现之间的鸿沟，从软件开发诞生之初就存在。我们尝试过用更详细的文档、更具体的需求、更严格的流程来弥合。但这些方法失败了，因为它们默认这个鸿沟不可避免。它们能缩小，却永远消除不了。而 SDD 消除了这个鸿沟：规范和由规范生成的具体实现计划是可执行的。当规范和实现计划能够直接生成代码时，就不存在鸿沟——只有“转换”。

这种转变如今成为可能，因为 AI 已经能够理解并实现复杂的规范，并生成细致的实现计划。但缺乏结构的 AI 生成只会带来混乱。SDD 提供了这种结构：通过精确、完整、毫不含糊的规范和随后的实现计划，生成可运行的系统。规范成为主要产物，代码则是它的表达（作为实现计划在特定语言和框架中的产出）。

在这个新世界里，维护软件意味着进化规范。开发团队的意图通过自然语言（“意图驱动开发”）、设计资产、核心原则以及其他指导方针来表达。开发的通用语言上升到了更高层次，而代码则是“最后一公里”的表达方式。

调试意味着修正规范和实现计划，以避免生成错误代码。重构意味着为了清晰度进行结构化调整。整个开发工作流围绕规范这个中心真理重组，实现计划和代码则作为不断再生成的输出。为应用更新新特性，或者因为创造力而构建新的并行实现，都意味着要回到规范并生成新的实现计划。因此，这个过程是一个从 0 -> 1，(1’，…)，2，3，N 的演进。

开发团队的关注点回归到创造力、实验精神和批判性思维上。

SDD 工作流的实践 🔗

工作流从一个想法开始——往往模糊且不完整。通过与 AI 的迭代对话，这个想法逐渐演化为完整的 PRD。AI 会提出澄清性问题，识别边界情况，并帮助定义精确的验收标准。在传统开发中，这些工作可能需要数天的会议与文档，而在这里，只需几个小时的聚焦式规范工作即可完成。这改变了传统的 SDLC（软件开发生命周期）——需求和设计不再是离散的阶段，而是持续的活动。这也支持了团队流程：团队评审的规范可以进行版本管理，在分支中创建，并合并。

当产品经理更新验收标准时，实现计划会自动标记受影响的技术决策。当架构师发现更优的模式时，PRD 会更新以反映新的可能性。

在整个规范过程中，研究代理会收集关键上下文。他们会调查库兼容性、性能基准和安全影响。组织约束会被自动发现并应用——公司的数据库标准、认证要求和部署策略会无缝地整合到每一份规范中。

基于 PRD，AI 会生成实现计划，将需求映射到技术决策。每一个技术选择都有记录的理由。每一个架构决策都能追溯到具体的需求。在这个过程中，一致性验证会持续提升质量。AI 会分析规范中的歧义、矛盾和缺口——不是一次性的检查，而是持续的精炼。

当规范和实现计划足够稳定时，就可以开始代码生成，但它们并不需要“完整”。早期的生成可能是探索性的——用来测试规范在实践中是否合理。领域概念会转化为数据模型。用户故事会转化为 API 接口。验收场景会转化为测试。开发与测试因此通过规范融合在一起——测试场景不是在代码之后才编写的，而是规范的一部分，既生成实现，也生成测试。

反馈循环延伸到初始开发之外。生产指标和事故不仅触发热修复，还会更新规范，以便在下一次生成中体现。性能瓶颈会转化为新的非功能性需求。安全漏洞会成为约束，影响所有未来的生成。这种规范、实现与运维现实之间的迭代舞蹈，才是理解真正出现的地方，也是传统 SDLC 转变为持续进化的地方。

为什么 SDD 恰逢其时 🔗

有三大趋势让 SDD 不仅可能，而且必要：

首先，AI 的能力已达到一个临界点，可以可靠地将自然语言规范生成可运行的代码。这不是要取代开发者，而是要通过自动化“从规范到实现”的机械性翻译来增强他们的效能。它可以放大探索与创造力，轻松支持“重新开始”，并支持加法、减法与批判性思考。

其次，软件复杂性持续呈指数级增长。现代系统集成了数十个服务、框架和依赖。通过人工过程保持所有这些部分与最初意图的一致性，变得越来越困难。SDD 通过规范驱动的生成提供系统化的一致性。框架可能会演化为“AI 优先”而不是“人类优先”，或者围绕可复用组件来架构。

第三，变化的速度加快。今天的需求变化比以往任何时候都更频繁。转向已不再是例外——而是常态。现代产品开发需要基于用户反馈、市场环境和竞争压力的快速迭代。传统开发把这些变化当作干扰。每次转向都需要手动在文档、设计和代码中传播变更。结果要么是缓慢而谨慎的更新，牺牲了速度；要么是快速而鲁莽的更新，累积了技术债务。

SDD 可以支持“假设/模拟”实验：“如果我们需要重新实现或改变应用，以支持一个卖更多 T 恤的商业需求，我们要如何实现并实验？”

SDD 将需求变更从障碍转化为正常的工作流。当规范驱动实现时，转向就变成系统化的再生成，而不是手工重写。在 PRD 中改变一个核心需求，受影响的实现计划会自动更新。修改一个用户故事，相应的 API 接口会重新生成。这不仅关乎初始开发——更关乎在不可避免的变化中维持工程速度。

核心原则 🔗

规范作为通用语言：规范成为主要产物，代码则是其在特定语言和框架中的表达。维护软件意味着不断进化规范。

可执行的规范：规范必须足够精确、完整且毫不含糊，以便生成可运行的系统。这消除了“意图”与“实现”之间的鸿沟。

持续精炼：一致性验证是持续进行的，而不是一次性的关卡。AI 会在整个过程中分析规范中的歧义、矛盾与缺口。

研究驱动的上下文：研究代理在规范过程中持续收集关键上下文，调查技术选项、性能影响以及组织约束。

双向反馈：生产环境的现实会推动规范的演化。指标、事件与运维经验会成为规范精炼的输入。

探索性的分支：从同一份规范生成多种实现路径，以探索不同的优化目标——性能、可维护性、用户体验、成本。

实施途径 🔗

今天，实践 SDD 需要整合现有工具，并在整个过程中保持纪律。方法论可以通过以下方式落地：

• 使用 AI 助手进行迭代式的规范开发
• 借助研究代理收集技术上下文
• 使用代码生成工具将规范翻译为实现
• 使用适配于“规范优先”工作流的版本控制系统
• 借助 AI 对规范文档进行一致性检查

关键在于将规范视为唯一的真理源，而代码只是生成的产物，用来服务于规范，而不是反过来。

用命令简化 SDD 🔗

通过三个强大的命令，SDD 方法论在“规范 → 规划 → 任务”工作流上得到了极大增强：

/specify 命令 🔗

这个命令能把一个简单的功能描述（用户输入）转化为完整、结构化的规范，并自动进行仓库管理：

1. 自动功能编号：扫描现有规范，确定下一个功能编号（如 001、002、003）
2. 分支创建：基于描述生成语义化分支名，并自动创建
3. 基于模板的生成：复制并定制功能规范模板，填入需求
4. 目录结构：在 specs/[branch-name]/ 下创建所有相关文档的正确结构

/plan 命令 🔗

在功能规范存在后，这个命令会创建一个全面的实现计划：

1. 规范分析：读取并理解功能需求、用户故事和验收标准
2. 宪法式合规性：确保符合项目宪章和架构原则
3. 技术翻译：将业务需求转化为技术架构与实现细节
4. 详细文档：生成数据模型、API 合约和测试场景的配套文档
5. 快速验证：生成 Quickstart 指南，捕捉关键验证场景

/tasks 命令 🔗

在计划生成后，这个命令会分析计划及相关设计文档，输出可执行的任务清单：

1. 输入：读取 plan.md（必需），以及存在时的 data-model.md、contracts/、research.md
2. 任务推导：将合约、实体与场景转化为具体任务
3. 并行化：标记独立任务为 [P]，并划分安全的并行任务组
4. 输出：在功能目录下生成 tasks.md，供 Task agent 执行

示例：构建聊天功能 🔗

以下是这些命令如何改造传统开发工作流的对比：

传统方式：

1. 写 PRD 文档（2-3 小时）
2. 创建设计文档（2-3 小时）
3. 手动搭建项目结构（30 分钟）
4. 编写技术规范（3-4 小时）
5. 制定测试计划（2 小时）
总计：约 12 小时的文档工作

使用命令的 SDD 方式：

# 步骤 1: 创建功能规范（5 分钟）
/specify Real-time chat system with message history and user presence

# 这会自动：
# - 创建分支 "003-chat-system"
# - 生成 specs/003-chat-system/spec.md
# - 填充结构化需求

# 步骤 2: 生成实现计划（5 分钟）
/plan WebSocket for real-time messaging, PostgreSQL for history, Redis for presence

# 步骤 3: 生成可执行任务（5 分钟）
/tasks

# 这会自动创建：
# - specs/003-chat-system/plan.md
# - specs/003-chat-system/research.md (WebSocket 库对比)
# - specs/003-chat-system/data-model.md (消息与用户的 schema)
# - specs/003-chat-system/contracts/ (WebSocket 事件、REST 接口)
# - specs/003-chat-system/quickstart.md (关键验证场景)
# - specs/003-chat-system/tasks.md (由计划推导出的任务清单)

在 15 分钟内，你就能获得：

• 带有用户故事和验收标准的完整功能规范
• 包含技术选择与理由的详细实现计划
• 已准备好用于代码生成的 API 合约和数据模型
• 自动化与手动测试的完整测试场景
• 所有文档都正确版本化，并存放在独立的功能分支

结构化自动化的力量 🔗

这些命令不仅仅节省时间——它们还能强制保证一致性和完整性：

1. 不遗漏细节：模板确保每个方面都被覆盖，从非功能性需求到错误处理
2. 决策可追溯：每一个技术选择都能追溯到具体需求
3. 活文档：规范始终与代码保持同步，因为代码就是由规范生成的
4. 快速迭代：修改需求后几分钟就能再生成计划，而不是几天

这些命令体现了 SDD 的核心原则：将规范视为可执行的产物，而不是静态文档。它们让规范过程从“必要的麻烦”变成开发的驱动力。

模板驱动的质量：如何用结构约束 LLM，获得更好结果 🔗

这些命令的真正力量不仅在于自动化，更在于模板如何引导 LLM 生成更高质量的规范。模板本身就像是复杂的提示，能在有效的范围内约束 LLM 的输出：

要不要我帮你把这两个表格合并成一张 双栏对照表（左边是“模板约束”，右边是“宪法原则”），方便在文稿中作为核心总结插图？

1. 防止过早落入实现细节 🔗

功能规范模板明确要求：

- ✅ 聚焦用户需要什么、为什么需要
- ❌ 避免实现方式（不要写技术栈、API、代码结构）

这种约束迫使 LLM 保持在正确的抽象层级。当它可能会自然倾向于写出“用 React + Redux 实现”时，模板会把它拉回到“用户需要实时更新数据”。这种分离确保了规范的稳定性，即使底层实现技术发生变化。

2. 强制标记不确定性 🔗

模板要求使用 [NEEDS CLARIFICATION] 标记：

创建规范时：
1. **标出所有模糊之处**：用 [NEEDS CLARIFICATION: 具体问题]
2. **不要猜测**：若提示未指定，就标记出来

这避免了 LLM 常见的“合理但可能错误的臆测”。比如遇到“登录系统”，它不会擅自假设是“邮箱/密码”，而是标记为 [NEEDS CLARIFICATION: 认证方式未指定 - 邮箱/密码，SSO，OAuth?]。

3. 用清单推动结构化思考 🔗

模板内置全面的检查清单，相当于给规范加上了“单元测试”：

### 需求完整性检查
- [ ] 没有遗留 [NEEDS CLARIFICATION] 标记
- [ ] 需求可测试且无歧义
- [ ] 成功标准可衡量

这些清单迫使 LLM 系统性地自我检查，补上可能遗漏的地方。就像给它一个质量保障框架。

4. 用关卡确保架构合规 🔗

实现计划模板通过阶段性关卡来执行架构原则：

### 阶段 -1: 前置实现关卡
#### 简单性关卡 (第七条)
- [ ] 使用 ≤3 个项目？
- [ ] 没有过度预留？
#### 反抽象关卡 (第八条)
- [ ] 直接使用框架？
- [ ] 单一模型表达？

这些关卡能防止过度设计，要求 LLM 显式说明任何复杂性。如果没通过，就必须在“复杂度追踪”部分写清原因，形成架构决策的责任感。

5. 分层管理细节 🔗

模板强制执行合理的信息架构：

**重要**: 实现计划应保持高层次和可读性。
代码示例、算法细节或大段技术规范
必须放到 `implementation-details/` 文件夹

这样避免规范沦为“代码堆”。LLM 学会在合适的层级提供细节，把复杂内容拆出去，保持主文档可读。

6. 测试优先的思维 🔗

实现模板要求严格的测试优先顺序：

### 文件创建顺序
1. 创建 `contracts/` 目录存放 API 规范
2. 按顺序创建测试文件：contract → 集成 → 端到端 → 单元
3. 编写源文件以通过测试

这种顺序保证 LLM 先考虑可测试性和合约，再写实现，生成更健壮、可验证的规范。

7. 防止“猜想性功能” 🔗

模板明确禁止推测性内容：

- [ ] 没有推测性或“可能需要”的功能
- [ ] 每个阶段都有清晰的前置条件和交付物

这避免了 LLM 添加“锦上添花”的功能，导致实现复杂化。所有功能必须能追溯到具体用户故事和明确的验收标准。

复合效应 🔗

这些约束相互配合，最终产出的规范具备以下特征：

• 完整性：检查清单保证无遗漏
• 无歧义性：强制澄清标记凸显不确定点
• 可测试性：测试优先的思维内置在流程里
• 可维护性：抽象层次与信息架构合理
• 可实现性：分阶段推进，并有明确交付物

模板把 LLM 从“创意写手”转变为“规范工程师”，将其能力引导至生成始终高质量、可执行、能真正驱动开发的规范。

宪法基础：架构纪律的强制执行 🔗

SDD 的核心是一部“宪法”——一组不可变的原则，规定了规范如何转化为代码。宪法文件（memory/constitution.md）相当于系统的架构 DNA，确保每一份生成的实现都保持一致性、简洁性和高质量。

九条开发原则 🔗

这部宪法定义了九条原则，塑造了开发过程的方方面面：

* 注：第四~六条在原文未展开，这里可作为预留，未来补充（如与架构、安全、可扩展性相关）。

第一条：库优先原则 🔗

每个功能必须作为独立库开始——无一例外。这强制在一开始就采用模块化设计：

在 Specify 中，每个功能都必须以独立库的形式开始。
任何功能不得直接实现在应用代码中，
必须先抽象为可复用的库组件。

这样能确保规范生成的不是臃肿的整体应用，而是模块化、可复用的代码。LLM 在生成实现计划时，必须把功能结构化为边界清晰、依赖最少的库。

第二条：CLI 接口强制要求 🔗

每个库都必须通过命令行接口暴露功能：

所有 CLI 接口必须：
- 接受文本输入（stdin、参数或文件）
- 产生文本输出（stdout）
- 支持 JSON 格式用于结构化数据交换

这保证了可观测性与可测试性。LLM 不得把功能藏在不透明的类里——一切都必须能通过文本接口访问和验证。

第三条：测试优先的强制要求 🔗

最具颠覆性的一条——测试先行，代码后写：

这是不可协商的：所有实现必须严格遵循测试驱动开发（TDD）。
不得在以下条件满足前编写实现代码：
1. 已编写单元测试
2. 测试已由用户验证和批准
3. 测试已确认 FAIL（红灯阶段）

这完全颠倒了传统的 AI 代码生成方式。LLM 不再是“先写代码再祈祷能运行”，而是必须先生成定义行为的完整测试，用它们得到认可，再进入实现。

第七与第八条：简洁性与反抽象 🔗

这两条配合，用于防止过度设计：

第 7.3 节：最小化项目结构
- 初始实现最多包含 3 个项目
- 额外项目必须有书面理由

第 8.1 节：信任框架
- 直接使用框架特性，而非再额外封装

当 LLM 倾向于制造繁复抽象时，这些条款会迫使它对每一层复杂性给出正当理由。实现计划模板中的“前置实现关卡（Phase -1 Gates）”就是直接执行这两条原则的工具。

第九条：集成优先测试 🔗

强调现实世界的测试优先于孤立的单元测试：

测试必须使用真实环境：
- 优先使用真实数据库，而不是 mock
- 优先使用实际服务实例，而不是 stub
- 合约测试必须在实现之前完成

这保证生成的代码不仅在理论上成立，更能在实践中运行良好。

宪法式约束的模板化执行 🔗

实现计划模板通过具体检查点来落实这些原则：

### 阶段 -1: 前置实现关卡
#### 简单性关卡 (第七条)
- [ ] 使用 ≤3 个项目？
- [ ] 没有过度预留？

#### 反抽象关卡 (第八条)
- [ ] 是否直接使用框架？
- [ ] 是否保持单一模型表达？

#### 集成优先关卡 (第九条)
- [ ] 合约是否已定义？
- [ ] 合约测试是否已编写？

这些关卡就像架构原则的编译时检查。LLM 在继续生成之前，要么通过这些关卡，要么必须在“复杂度追踪”部分记录合理的例外说明。

不可变原则的力量 🔗

宪法的力量在于其不可变性。实现细节可以演进，但核心原则保持恒定。这带来了：

1. 跨时间一致性：今天生成的代码与明年生成的代码遵循相同原则
2. 跨模型一致性：不同的 AI 模型产出架构兼容的代码
3. 架构完整性：每个功能都会强化，而不是破坏系统设计
4. 质量保障：测试优先、库优先、简洁优先的原则保证了可维护的代码

宪法的演化 🔗

虽然原则不可变，但其应用方式可以进化：

第 4.2 节：修订流程
对宪法的修改必须满足：
- 记录清晰的修改理由
- 经项目维护者评审和批准
- 进行向后兼容性评估

这样的方法既能保持稳定，又能从实践中学习与改进。宪法会记录带日期的修订，展示原则如何基于现实经验被逐步优化。

超越规则：一种开发哲学 🔗

宪法不仅是一份规则手册，更是一种塑造 LLM 思维的开发哲学：

• 可观测性优于不透明性：一切功能必须能通过 CLI 接口检查
• 简洁优于巧妙：从简开始，只有在必要时才增加复杂性
• 集成优于隔离：在真实环境中测试，而不是在虚拟隔离的环境里
• 模块化优于单体化：每个功能都是边界清晰的独立库

通过把这些原则嵌入到规范与规划流程中，SDD 确保生成的代码不仅能运行，还具备可维护性、可测试性和架构健全性。宪法让 AI 不再只是代码生成器，而是尊重并强化系统设计原则的架构伙伴。

转变 🔗

这不是为了取代开发者或自动化创造力，而是通过自动化“机械性翻译”来增强人的能力。 这是为了建立一个紧密的反馈循环，让规范、研究与代码共同演进，每一次迭代都带来更深的理解，以及更高的“意图—实现”一致性。

软件开发需要更好的工具来保持意图与实现的对齐。SDD 提供的方法论，正是通过可执行规范来生成代码，而不是仅仅指导它。