TR;DR(Gemini 提炼总结，人工审核)

这篇文章的核心逻辑可以精炼为一句话：在 AI 编程时代，将“代码”视为副产品，将“规格（Spec）”视为唯一的真理来源。

以下是精简版要点：

1. 核心理念：从“写代码”转向“定意图”

  • 告别 Vibe Coding：反对没有计划地盲目写代码。
  • 规格即指南：先用结构化的文档（.md）定义清楚要做什么，再让 AI 执行。

2. 标准五步工作流

  1. 宪法 (Constitution)：设定项目的死理和技术底线（如：必须用 TS，必须写测试）。
  2. 规格 (Specify)：明确产品逻辑（做什么、为什么做）。
  3. 方案 (Plan)：明确技术实现（怎么做、用什么接口）。
  4. 任务 (Tasks)：将方案拆解为 AI 能在几分钟内完成的原子级任务。
  5. 实施 (Implementation)：AI 根据任务清单精准生成代码。

3. SDD 的杀手锏

  • 解决 AI 幻觉：给 AI 极度精准的上下文，不再让它盲目猜测。
  • 应对复杂性：通过文档记录决策，防止项目变大后 AI 或人类“失忆”。
  • 降低沟通成本：规格书是团队与 AI 共同遵守的“契约”。

一句话总结： SDD 是把开发者从“码农”升级为“系统架构师”的一套标准作业程序（SOP）。

权力反转

​ 几十年来，代码一直是王者。规格说明为代码服务——它们是我们搭建起来、然后在编码这一“真正工作”开始后便丢弃的脚手架。我们编写 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 方法论通过三条强大的命令得到了显著增强，这些命令可自动化“规范 → 规划 → 任务分配”的工作流程：

/speckit.specify 命令

​ 此命令可将简单的功能描述（用户提示）转换为完整、结构化的规范，并自动进行存储库管理：

  1. 自动功能编号：扫描现有规范以确定下一个功能编号（例如，001、002、003、…、1000 —— 自动扩展到 3 位以上）
  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，供任务代理执行

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

​ 这些命令的真正力量不仅在于自动化，还在于这些模板如何引导 LLM 的行为，使其产出更高质量的规范。这些模板充当了复杂的提示词，以富有成效的方式约束 LLM 的输出：

1. 防止过早引入实现细节

功能规范模板明确指示：

1
2

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

​ 这一约束迫使 LLM 维持适当的抽象层级。当 LLM 可能自然地跳到“使用 React 和 Redux 实现”时，该模板会使其专注于“用户需要其实时更新其数据”。这种分离可确保规范即使在实现技术发生变化时仍保持稳定。

2. 强制使用显式不确定性标记

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

1
2
3

当从用户提示符创建此规范时：
1. **标记所有歧义**：使用[需要澄清：具体问题]
2. **不要猜测**：如果提示没有明确说明，请标记出来。

这可以防止 LLM 出现常见行为，即做出看似合理但可能不正确的假设。LLM 不会去猜测“登录系统”使用的是电子邮件/密码认证，而是必须将其标记为【需要澄清：未指定身份验证方法 - 电子邮件/密码、单点登录 (SSO) 还是 OAuth？】。

3. 通过清单进行结构化思考

这些模板包含全面的清单，可作为该规范的“单元测试”：

1
2
3
4

### 需求完整性 
- [ ] 无 [需要澄清] 标记 
- [ ] 需求可测试且明确无误 
- [ ] 成功标准可衡量

4. 通过关卡实现宪法合规

1
2
3
4
5
6
7
8
9

### 第一阶段：实施前关卡 

#### 简洁性关卡（第七条） 
	- [ ] 是否使用≤3个项目？ 
	- [ ] 是否考虑未来兼容性？ 

#### 反抽象性关卡（第八条） 
	- [ ] 是否直接使用框架？ 
	- [ ] 是否仅使用单一模型表示？

这些关卡通过要求 LLM 对任何复杂性作出明确论证，来防止过度工程化。如果某个关卡未通过，LLM 就必须在“Complexity Tracking”部分记录原因，从而为架构决策建立问责机制。

5. 分层细节管理

这些模板强制执行恰当的信息架构：

1
2
3

**重要提示**：此实现计划应保持概要性和可读性。 
任何代码示例、详细算法或详尽的技术规范 
都必须放在相应的 `implementation-details/` 文件中。

这可以防止规范沦为难以阅读的代码堆砌这一常见问题。LLM 会学会保持适当的细节层级，将复杂内容提取到单独的文件中，同时使主文档保持便于导航。

6. 测试优先思维

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

1
2
3
4

### 文件创建顺序 
1. 创建包含 API 规范的 `contracts/` 目录 
2. 按以下顺序创建测试文件：合同测试 → 集成测试 → 端到端测试 → 单元测试 
3. 创建源文件以使测试通过

这种顺序约束确保 LLM 在实现之前先考虑可测试性和契约，从而形成更健壮、更可验证的规格说明。

7. 防止臆测性功能

模板明确劝阻臆测：

1
2

- [ ] 不要包含推测性的或“可能需要”的功能
- [ ] 所有阶段都有明确的前置条件和交付成果

这可以防止 LLM 添加那些“可有可无”的功能，从而使实现复杂化。每个功能都必须追溯到一个具有明确验收标准的具体用户故事。

复利效应

这些约束协同作用，生成的规格说明具有以下特点：

  • 完成：检查清单确保不会遗忘任何事项
  • 无歧义：强制澄清标记会突出不确定性
  • 可测试：测试优先的思维被内置到流程中
  • 可维护：恰当的抽象层级和信息层次结构
  • 可实现：清晰的阶段划分和具体的交付成果

这些模板将 LLM 从创意写作者转变为严谨的规格工程师，将其能力引导到持续产出高质量、可执行、真正推动开发的规格说明上。

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

​ SDD 的核心在于一部宪章——一组不可变的原则，用以规范规范如何转化为代码。该宪章（memory/constitution.md）如同系统的架构 DNA，确保每一个生成的实现都保持一致性、简洁性与质量。

开发的九项条款

该宪章定义了九条条款，塑造开发过程的方方面面：

第一条：库优先原则

每个功能都必须从一个独立库开始——没有例外。这从一开始就强制采用模块化设计：

1
2
3

Specify 中的每个功能在其诞生之初都必须作为一个独立库存在。
任何功能都不得直接在应用程序代码中实现，而必须
先被抽象为可复用的库组件。

这一原则确保规范生成的是模块化、可复用的代码，而非单体式应用程序。当 LLM 生成实现计划时，它必须将功能构建为边界清晰且依赖最少的库。

第二条：CLI 接口强制要求

每个库都必须通过命令行界面公开其功能：

1
2
3
4

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

这强制实现可观测性与可测试性。LLM 不能将功能隐藏在不透明的类中——一切都必须能够通过基于文本的接口进行访问和验证。

第三条：测试优先原则

最具变革性的条款——先有测试，后有代码：

1
2
3
4
5
6

这是不可协商的：所有实现都必须遵循严格的测试驱动开发。
在以下事项完成之前，不得编写任何实现代码：

1. 已编写单元测试
2. 测试已由用户验证并批准
3. 测试已被确认失败（红色阶段）

这彻底颠覆了传统的 AI 代码生成方式。LLM 不是先生成代码并寄希望于其可行，而是必须首先生成全面定义行为的测试，获得批准后，才生成实现。

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

这些成对的条款用于防止过度工程化：

1
2
3
4
5
6

第 7.3 节：最小化项目结构
- 初始实施最多 3 个项目
- 额外项目需要有文档化的理由说明

第 8.1 节：框架信任
- 直接使用框架功能，而不是对其进行包装

第九条：集成优先测试

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

1
2
3
4

测试必须使用真实环境：
- 优先使用真实数据库而非模拟对象
- 使用实际服务实例而非桩
- 实施前必须进行契约测试

通过模板实施宪章式约束

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

### 第 -1 阶段：实施前关卡

#### 简洁性关卡（第 VII 条）

- [ ] 使用 ≤3 个项目？
- [ ] 没有为未来做预防性设计？

#### 反抽象关卡（第 VIII 条）

- [ ] 直接使用框架？
- [ ] 单一模型表示？

#### 集成优先关卡（第 IX 条）

- [ ] 已定义契约？
- [ ] 已编写契约测试？

这些门禁机制充当架构原则的编译时检查。LLM 若未通过这些门禁，或未在“复杂度跟踪”部分记录有充分理由的例外情况，则无法继续进行。

不可变原则的力量

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

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

宪制演进

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

1
2
3
4
5

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

这使得该方法论能够在保持稳定性的同时学习和改进。宪章通过带有日期的修订展示了其自身的演进，表明原则可以基于现实世界的经验而不断完善。

超越规则：一种发展哲学

规范不仅仅是一本规则手册——它是一种塑造 LLM 如何思考代码生成的哲学：

  • 可观测性优于不透明性：一切都必须能够通过 CLI 接口进行检查
  • 简洁性优于炫技：从简单开始，仅在被证明确有必要时才增加复杂性
  • 集成优于隔离：在真实环境中测试，而非在人为构造的环境中测试
  • 模块化优于单体：每个功能都是一个具有清晰边界的库

通过将这些原则嵌入规范制定和规划过程，SDD 确保生成的代码不仅仅是可运行的——它还是可维护、可测试且在架构上健全的。宪章将 AI 从代码生成器转变为尊重并强化系统设计原则的架构合作伙伴。

转型

​ 这并不是要取代开发者，也不是要将创造力自动化。而是要通过自动化机械性的转换来增强人类能力。这是为了创建一个紧密的反馈循环，使规范、研究和代码共同演进，在每一次迭代中都带来更深的理解，以及意图与实现之间更好的对齐。

​ 软件开发需要更好的工具来维持意图与实现之间的一致性。SDD 提供了实现这种一致性的方法论：通过可执行规范来生成代码，而不只是对其进行指导。