权力反转（The Power Inversion）

几十年来，代码一直是王者。规范服务于代码——它们是我们在开始所谓“真正的编码工作”之前搭建、而后丢弃的脚手架。我们写 PRD 来指导开发，编写设计文档来辅助实现，绘制图表来可视化架构。但这些始终从属于代码本身。代码才是真理，其他充其量只是善意的意图。代码是唯一的真实来源，而当代码不断向前推进时，规范很少能跟上。由于资产（代码）与实现是一体，若不从代码出发便很难同时维持一个并行实现。

规范驱动开发（SDD）颠覆了这种权力结构。规范不再服务于代码——代码服务于规范。产品需求文档（PRD）不再是实现的指南；它是生成实现的源头。技术方案不再是指导编码的文档；它们是可以产出代码的精确定义。这不是对软件构建方式的增量改进，而是对“是什么驱动开发”的一次根本性再思考。

规范与实现之间的鸿沟自软件诞生以来便困扰着我们。我们尝试用更好的文档、更细的需求、更严格的流程去弥合它。但这些方法之所以失败，是因为它们默认了鸿沟不可避免；它们努力缩小，却无法消除。SDD 通过让规范及其由规范派生出的具体实现计划可执行，从而消除这一鸿沟。当规范与实现计划可以生成代码时，便不再有鸿沟——只有“转换”。

这种转变之所以成为可能，是因为 AI 能够理解并实现复杂的规范，并创建详尽的实现计划。但没有结构的原始 AI 生成只会带来混乱。SDD 通过精确、完整、无歧义、足以生成可运行系统的规范与后续实现计划，为这一过程提供结构。规范成为首要产物。代码则是在特定语言与框架下，对实现计划的表达。

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

调试意味着修正会生成错误代码的规范及其实现计划。重构意味着为清晰度而重组。整个开发工作流围绕规范重构为中心真实来源，实施计划与代码作为持续再生成的输出。为应用增加新功能或创建一个并行实现（因为人类是富有创造力的）意味着回到规范并创建新的实现计划。这个过程因此成为一个 0 -> 1、(1' ..)、2、3、N 的演进。

开发团队将注意力集中于创造力、实验和批判性思维。

SDD 的实践工作流（The SDD Workflow in Practice）

工作流始于一个想法——通常模糊且不完整。通过与 AI 的迭代对话，这个想法会演化为一份全面的 PRD。AI 会提出澄清问题、识别边界情况，并帮助定义精确的验收标准。传统开发中可能需要数天会议与文档的工作，在这一过程中仅需数小时的聚焦规范工作即可完成。这也改造了传统 SDLC——需求与设计成为持续的活动，而非离散的阶段。这支持一种“团队流程”：由团队评审的规范被表达并版本化，在分支中创建并合并。

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

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

从 PRD 出发，AI 会生成将需求映射到技术决策的实现计划。每一个技术选择都有文档化的理由。每一项架构决策都可追溯到具体需求。贯穿这一过程，一致性校验持续提升质量。AI 持续分析规范中的歧义、矛盾与缺口——不是一次性门禁，而是不断的完善。

当规范与其实现计划足够稳定时，代码生成即可开始，但规范并不需要“完整”。早期的生成可能是探索性的——验证规范在实践中是否可行。领域概念成为数据模型。用户故事成为 API 端点。验收场景成为测试。这通过规范将开发与测试融合——测试场景不是在代码后面编写的，它们是规范的一部分，同时生成实现与测试。

反馈循环超越初始开发。生产指标与事件不再只是触发热修复——它们会更新规范以供下一次再生成。性能瓶颈成为新的非功能性需求。安全漏洞成为影响所有未来生成的约束。规范、实现与运营现实之间的迭代舞蹈，是理解真正涌现之处，也是传统 SDLC 转化为持续演进之处。

为什么是现在（Why SDD Matters Now）

三股趋势让 SDD 不仅成为可能，而且成为必要：

首先，AI 的能力已经达到阈值，能够从自然语言规范可靠地生成可运行的代码。这不是要取代开发者——而是通过自动化从规范到实现的机械性翻译，放大他们的效率。它可以放大探索与创造力，支持“重新开始”变得容易，并支持加、减与批判性思考。

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

第三，变化的节奏在加速。如今需求变化的速度远超以往。转向不再是例外——而是常态。现代产品开发要求基于用户反馈、市场条件与竞争压力快速迭代。传统开发把这些变化视为干扰。每一次转向都需要手动传播到文档、设计与代码。结果要么是缓慢、谨慎的更新从而限制速度，要么是快速、鲁莽的变更并积累技术债务。

SDD 可支持“假设/模拟”实验：
“如果我们需要重新实现或更改应用，以满足促进某项业务（例如卖更多 T 恤）的需求，我们会如何实现并进行试验？”

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

核心原则（Core Principles）

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

可执行的规范：规范必须足够精确、完整、无歧义，以生成可工作的系统。这消除了意图与实现之间的鸿沟。

持续完善：一致性校验是持续进行的，而非一次性的门禁。AI 会持续分析规范中的歧义、矛盾与缺口。

研究驱动的上下文：研究代理贯穿规范过程，调查技术选项、性能影响与组织约束。

双向反馈：生产现实会反哺规范演进。指标、事件与运营经验成为规范完善的输入。

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

实践路径（Implementation Approaches）

在今天，践行 SDD 需要把现有工具组装起来，并在整个过程中保持纪律。方法论可以借助以下工具来实践：

  • 用于迭代规范开发的 AI 助手

  • 用于收集技术上下文的研究代理

  • 将规范翻译为实现的代码生成工具

  • 适配“规范优先”工作流的版本控制系统

  • 通过 AI 对规范文档进行一致性检查

关键在于把规范当作真实来源，而代码是服务于规范的生成输出，而不是相反。

通过命令精简 SDD（Streamlining SDD with Commands）

SDD 方法论通过三条强大的命令显著增强，它们自动化了“规范 → 规划 → 任务”的工作流：

/speckit.specify 命令

该命令将一个简单的特性描述（用户提示）转化为完整、结构化的规范，并自动管理仓库：

  1. 自动特性编号：扫描现有规范，确定下一个特性编号（如 001、002、003）

  2. 创建分支：基于你的描述生成语义化分支名并自动创建

  3. 模板化生成：复制并定制特性规范模板，使其符合你的需求

  4. 目录结构：创建正确的 specs/[branch-name]/ 结构以容纳相关文档

/speckit.plan 命令

一旦特性规范存在，该命令会创建一份全面的实现计划：

  1. 规范分析：阅读并理解特性需求、用户故事与验收标准

  2. 宪法合规：确保与项目宪法及架构原则保持一致

  3. 技术翻译：将业务需求转化为技术架构与实现细节

  4. 详尽文档：为数据模型、API 合同与测试场景生成配套文档

  5. 快速验证：产出捕捉关键验证场景的快速入门指南

/speckit.tasks 命令

在计划创建后，该命令会分析计划及相关设计文档，生成可执行的任务清单：

  1. 输入：读取 plan.md（必需），若存在则同时读取 data-model.md、contracts/ 与 research.md

  2. 任务派生：把合同、实体与场景转化为具体任务

  3. 并行化：标记独立任务为 [P] 并列出安全的并行分组

  4. 输出：在特性目录写入 tasks.md，可被任务代理直接执行

示例：构建一个聊天特性（Example: Building a Chat Feature）

这些命令如何改变传统开发工作流：

传统方式：

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

命令驱动的 SDD 方式：

# 步骤 1：创建特性规范（5 分钟）
/speckit.specify Real-time chat system with message history and user presence

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

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

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

# 这将自动创建：
# - specs/003-chat-system/plan.md
# - specs/003-chat-system/research.md（WebSocket 库对比）
# - specs/003-chat-system/data-model.md（Message 与 User 模型）
# - specs/003-chat-system/contracts/（WebSocket 事件、REST 端点）
# - specs/003-chat-system/quickstart.md（关键验证场景）
# - specs/003-chat-system/tasks.md（由计划派生的任务清单）

在 15 分钟内，你将拥有：

  • 一份包含用户故事与验收标准的完整特性规范

  • 一份含有技术选择与理由的详细实现计划

  • 准备好用于代码生成的 API 合同与数据模型

  • 覆盖自动化与手工的全面测试场景

  • 所有文档都在特性分支中正确版本化

结构化自动化的力量（The Power of Structured Automation）

这些命令不仅节约时间——它们还强制一致性与完整性：

  1. 不遗漏细节：模板确保从非功能需求到错误处理的方方面面都被考虑

  2. 可追溯决策：每个技术选择都能回溯到具体需求

  3. 活文档：规范与代码保持同步，因为代码由规范生成

  4. 快速迭代：变更需求并在几分钟内再生成计划，而非数天

这些命令以“规范是可执行产物”而非“静态文档”的方式，体现了 SDD 原则。它们把规范过程从“必需之恶”转化为开发的驱动力。

模板驱动的质量：如何用结构约束 LLM 获得更好结果（Template-Driven Quality）

这些命令的真正力量不仅在自动化，更在模板如何引导 LLM 产出更高质量的规范。模板作为精巧的提示，以下列方式对 LLM 的输出进行有效约束：

1. 防止过早涉入实现细节（Preventing Premature Implementation Details）

特性规范模板明确要求：

- ✅ 关注用户需要什么（WHAT）和为什么（WHY）
- ❌ 避免讨论如何实现（HOW）（不涉及技术栈、API、代码结构）

这一约束迫使 LLM 保持正确的抽象层级。当 LLM 可能自然地跳到“用 React 和 Redux 来实现”时，模板会让它聚焦于“用户需要数据的实时更新”。这种分离确保即便实现技术发生变化，规范也能保持稳定。

2. 强制显式的不确定性标记（Forcing Explicit Uncertainty Markers）

两个模板都强制使用 [NEEDS CLARIFICATION] 标记：

当从用户提示创建规范时：
1. **标注所有模糊点**：使用 [NEEDS CLARIFICATION: 具体问题]
2. **不要猜测**：如果提示未说明某项内容，必须标记出来

这防止了 LLM 的常见行为——做出看似合理但可能不正确的假设。与其猜测“登录系统”使用电子邮件/密码认证，LLM 必须标记为：
[NEEDS CLARIFICATION: 认证方式未指定——电子邮件/密码、SSO、OAuth？]。

3. 通过清单促使结构化思维（Structured Thinking Through Checklists）

模板包含全面的清单，充当规范的“单元测试”：

### 需求完整性
- [ ] 不再存在 [NEEDS CLARIFICATION] 标记
- [ ] 需求可测试、无歧义
- [ ] 成功标准可度量

这些清单迫使 LLM 系统性地自我审查输出，捕捉原本可能遗漏的空白。就像给 LLM 配备了一套质量保证框架。

4. 通过门禁保证宪法合规（Constitutional Compliance Through Gates）

实现计划模板通过阶段门禁来执行架构原则：

### 阶段 -1：前置实现门禁
#### 简单性门（第七条）
- [ ] 是否使用 ≤3 个项目？
- [ ] 是否拒绝“为未来做准备”？
#### 反抽象门（第八条）
- [ ] 是否直接使用框架功能？
- [ ] 是否采用单一模型表示？

这些门禁防止过度工程化，要求 LLM 明确为每一层复杂性给出理由。如果某个门禁未通过，LLM 必须在“复杂性跟踪”部分记录原因，从而为架构决策建立责任追踪。

5. 分层细节管理（Hierarchical Detail Management）

模板强制遵循正确的信息架构：

重要：实现计划应保持高层次且可读。
任何代码示例、详细算法或大量技术规格
必须放入相应的 `implementation-details/` 文件。

这避免了规范沦为难以阅读的代码堆。LLM 学会保持适当的细节层级，将复杂性抽取到独立文件，同时让主文档保持可导航。

6. 测试优先思维（Test-First Thinking）

实现模板强制测试优先的开发：

### 文件创建顺序
1. 先创建含 API 规格的 `contracts/`
2. 按顺序创建测试文件：合同 → 集成 → 端到端（e2e） → 单元
3. 编写源代码使测试通过

这种顺序约束确保 LLM 在实现之前考虑可测试性与合同，从而得到更健壮、可验证的规范。

7. 防止投机性特性（Preventing Speculative Features）

模板明确不鼓励投机：

- [ ] 不允许投机性或“可能需要”的特性
- [ ] 所有阶段都有明确的前提与交付物

这阻止 LLM 添加那些“也许不错”的特性，从而让实现复杂化。每个特性都必须可追溯到具有明确验收标准的具体用户故事。

复合效应（The Compound Effect）

这些约束共同作用，产出如下特性的规范：

  • 完整：检查清单确保无遗漏

  • 无歧义：强制澄清标记高亮不确定点

  • 可测试：测试优先思维内建于过程

  • 可维护：恰当的抽象层级与信息架构

  • 可实现：各阶段具有明确交付物

模板把 LLM 从“创意写手”转变为“纪律严明的规范工程师”，引导其产生持续高质量、可执行、真正驱动开发的规范。

宪法基础：强制架构纪律（The Constitutional Foundation）

SDD 的核心是一部“宪法”——一组不可更改的原则，治理规范如何转化为代码。该宪法（memory/constitution.md）充当系统的架构 DNA，确保每一次生成的实现都保持一致性、简单性与质量。

九条开发条款（The Nine Articles of Development）

宪法定义了塑造整个开发过程的九条原则：

第一条：库优先原则（Library-First Principle）

每个特性都必须作为独立库开始——无例外。这从一开始就强制模块化设计：

Specify 中的每个特性必须以独立库的形式开始其存在。
任何特性不得直接在应用代码中实现，
除非首先将其抽象为可复用的库组件。

这一原则确保规范生成的是模块化、可复用的代码，而非单体应用。当 LLM 生成实现计划时，必须将特性结构化为具有清晰边界、最小依赖的库。

第二条：CLI 接口强制（CLI Interface Mandate）

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

所有 CLI 接口必须：
- 接受文本输入（通过 stdin、命令行参数或文件）
- 以文本输出（通过 stdout）
- 支持 JSON 格式以进行结构化数据交换

这强制可观测性与可测试性。LLM 不得把功能隐藏在不透明的类中——所有内容都必须通过文本化接口可访问且可验证。

第三条：测试优先强制令（Test-First Imperative）

最具变革性的条款——在测试之前不写实现代码：

这不可协商：所有实现必须严格遵循测试驱动开发（TDD）。
在以下事项完成前不得编写实现代码：
1. 单元测试已编写
2. 测试已由用户确认并获批
3. 测试已确认失败（红灯阶段）

这完全颠倒了传统的 AI 代码生成方式。不是先生成代码再期待它能工作，而是 LLM 必须先生成定义行为的全面测试、获得批准，然后才生成实现。

第七与第八条：简单与反抽象（Simplicity and Anti-Abstraction）

这对条款共同对抗过度工程：

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

第 8.1 节：信任框架
- 直接使用框架功能而非包裹封装

当 LLM 可能自然地创建复杂抽象层时，这些条款迫使其为每一层复杂性提供理由。实现计划模板中的“阶段 -1 门禁”直接执行这些原则。

第九条：集成优先测试（Integration-First Testing）

优先真实世界的测试而非孤立的单元测试：

测试必须使用真实环境：
- 更倾向真实数据库而非模拟
- 使用实际服务实例而非桩件
- 在实现前强制进行合同测试

这确保生成的代码不仅在理论上可行，更能在实践中运行。

通过模板执行宪法（Constitutional Enforcement Through Templates）

实现计划模板通过具体检查点将这些条款落地：

### 阶段 -1：前置实现门禁
#### 简单性门（第七条）
- [ ] 是否使用 ≤3 个项目？
- [ ] 是否拒绝“为未来做准备”？

#### 反抽象门（第八条）
- [ ] 是否直接使用框架功能？
- [ ] 是否采用单一模型表示？

#### 集成优先门（第九条）
- [ ] 合同是否已定义？
- [ ] 合同测试是否已编写？

这些门禁相当于架构原则的“编译时检查”。LLM 不得继续推进，除非通过这些门禁，或在“复杂性跟踪”部分记录合理的例外。

不可变原则的力量（The Power of Immutable Principles）

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

  1. 跨时间的一致性：今天生成的代码与明年生成的代码遵循相同原则

  2. 跨模型的一致性：不同的 AI 模型仍能生成架构兼容的代码

  3. 架构完整性：每个特性都在强化而非削弱系统设计

  4. 质量保障：测试优先、库优先与简单性原则确保可维护的代码

宪法的演进（Constitutional Evolution）

尽管原则不可变，它们的应用可以演进：

第 4.2 节：修订流程
对本宪法的修改需要：
- 明确记录变更的理由
- 由项目维护者评审并批准
- 进行向后兼容性评估

这使方法论在保持稳定的同时得以学习与改进。宪法以带日期的修订展示其演进，证明原则可基于真实经验被不断完善。

超越规则：开发哲学（Beyond Rules: A Development Philosophy）

宪法不只是一本规则书——它是一种塑造 LLM 思考代码生成方式的哲学：

  • 可观测胜过不透明：所有内容都必须可通过 CLI 接口进行检查

  • 简单胜过聪明：从简单开始，仅在确证必要时引入复杂性

  • 集成胜过隔离：在真实环境中进行测试，而非人为的环境

  • 模块化胜过单体：每个特性都是具有清晰边界的库

通过把这些原则嵌入规范与规划过程，SDD 确保生成的代码不仅“能用”，而且“易维护、可测试、架构稳健”。宪法将 AI 从“代码生成器”转变为“尊重并强化系统设计原则的架构伙伴”。

转化（The Transformation）

这不是关于取代开发者或自动化创造力，而是通过自动化机械性翻译来放大人的能力。这是关于创建一个紧密的反馈循环，使规范、研究与代码共同演进，每次迭代都带来更深的理解与更好地对齐“意图与实现”。

软件开发迫切需要更好的工具，来维持意图与实现之间的对齐。SDD 提供了一种方法论：通过可执行的规范来生成代码，而非仅仅指导代码，从而实现这种对齐。

本文翻译自：https://github.com/github/spec-kit/edit/main/spec-driven.md