规格驱动开发（Specification-Driven Development, SDD）
权力倒置
几十年来，代码一直是王者。规格说明为代码服务——它们是我们搭建然后在"真正的编码工作"开始后就丢弃的脚手架。我们编写产品需求文档（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 命令
此命令将简单的功能描述（用户提示）转换为完整、结构化的规格说明，并自动进行仓库管理：
- 自动功能编号：扫描现有规格以确定下一个功能编号（例如 001、002、003）
- 分支创建：从你的描述生成语义分支名称并自动创建它
- 基于模板的生成：复制并使用你的需求自定义功能规格说明模板
- 目录结构：为所有相关文档创建适当的
specs/[branch-name]/结构
/speckit.plan 命令
一旦功能规格说明存在，此命令创建一个全面的实施计划：
- 规格说明分析：读取并理解功能需求、用户故事和验收标准
- 宪法合规性：确保与项目宪法和架构原则保持一致
- 技术转换：将业务需求转换为技术架构和实施细节
- 详细文档：为数据模型、API 合约和测试场景生成支持文档
- 快速入门验证：生成捕获关键验证场景的快速入门指南
/speckit.tasks 命令
创建计划后，此命令分析计划和相关设计文档以生成可执行任务列表：
- 输入：读取
plan.md（必需）以及（如果存在）data-model.md、contracts/和research.md - 任务派生：将合约、实体和场景转换为具体任务
- 并行化：标记独立任务
[P]并概述安全的并行组 - 输出：在功能目录中写入
tasks.md，准备由任务代理执行
示例：构建聊天功能
以下是这些命令如何改变传统开发工作流：
传统方法：
1. 在文档中编写 PRD（2-3 小时）
2. 创建设计文档（2-3 小时）
3. 手动设置项目结构（30 分钟）
4. 编写技术规格说明（3-4 小时）
5. 创建测试计划（2 小时）
总计：约 12 小时的文档工作使用命令的 SDD 方法：
# 步骤 1：创建功能规格说明（5 分钟）
/speckit.specify 实时聊天系统，包含消息历史和用户在线状态
# 这会自动：
# - 创建分支 "003-chat-system"
# - 生成 specs/003-chat-system/spec.md
# - 用结构化需求填充它
# 步骤 2：生成实施计划（5 分钟）
/speckit.plan WebSocket 用于实时消息传递，PostgreSQL 用于历史记录，Redis 用于在线状态
# 步骤 3：生成可执行任务（5 分钟）
/speckit.tasks
# 这会自动创建：
# - specs/003-chat-system/plan.md
# - specs/003-chat-system/research.md（WebSocket 库比较）
# - specs/003-chat-system/data-model.md（消息和用户模式）
# - specs/003-chat-system/contracts/（WebSocket 事件、REST 端点）
# - specs/003-chat-system/quickstart.md（关键验证场景）
# - specs/003-chat-system/tasks.md（从计划派生的任务列表）在 15 分钟内，你拥有：
- 包含用户故事和验收标准的完整功能规格说明
- 包含技术选择和理由的详细实施计划
- 准备用于代码生成的 API 合约和数据模型
- 自动和手动测试的全面测试场景
- 所有文档都在功能分支中进行了适当的版本控制
结构化自动化的力量
这些命令不仅节省时间——它们还强制执行一致性和完整性：
- 不会遗忘细节：模板确保考虑每个方面，从非功能需求到错误处理
- 可追溯的决策：每个技术选择都链接回特定需求
- 活文档：规格说明与代码保持同步，因为它们生成代码
- 快速迭代：在几分钟而不是几天内更改需求并重新生成计划
这些命令体现了 SDD 原则，将规格说明视为可执行的产物，而不仅仅是静态文档。它们将规格说明过程从必要之恶转变为开发的驱动力。
模板驱动的质量：结构如何约束 LLM 以获得更好的结果
这些命令的真正力量不仅在于自动化，还在于模板如何引导 LLM 行为朝向更高质量的规格说明。模板充当复杂的提示，以富有成效的方式约束 LLM 的输出：
1. 防止过早的实现细节
功能规格说明模板明确指示：
- ✅ 专注于用户需要什么和为什么
- ❌ 避免如何实现（没有技术栈、API、代码结构）这种约束迫使 LLM 保持适当的抽象级别。当 LLM 可能自然地跳到"使用 React 和 Redux 实现"时，模板使它专注于"用户需要其数据的实时更新"。这种分离确保规格说明保持稳定，即使实现技术发生变化。
2. 强制显式不确定性标记
两个模板都要求使用 [NEEDS CLARIFICATION] 标记：
从用户提示创建此规格时：
1. **标记所有歧义**：使用 [NEEDS CLARIFICATION: 具体问题]
2. **不要猜测**：如果提示没有指定某些内容，请标记它这防止了 LLM 做出看似合理但可能不正确的假设的常见行为。LLM 必须将其标记为 [NEEDS CLARIFICATION: 未指定身份验证方法 - 电子邮件/密码、SSO、OAuth？]，而不是猜测"登录系统"使用电子邮件/密码身份验证。
3. 通过检查清单进行结构化思考
模板包括充当规格说明"单元测试"的全面检查清单：
### 需求完整性
- [ ] 没有 [NEEDS CLARIFICATION] 标记
- [ ] 需求可测试且明确
- [ ] 成功标准可衡量这些检查清单强制 LLM 系统地自我审查其输出，捕获可能会溜走的差距。这就像给 LLM 一个质量保证框架。
4. 通过门控实现宪法合规性
实施计划模板通过阶段门控强制执行架构原则：
### 阶段 -1：实施前门控
#### 简洁性门控（第七条）
- [ ] 使用 ≤3 个项目？
- [ ] 没有面向未来的设计？
#### 反抽象门控（第八条）
- [ ] 直接使用框架？
- [ ] 单一模型表示？这些门控通过使 LLM 明确证明任何复杂性来防止过度工程。如果门控失败，LLM 必须在"复杂性跟踪"部分记录原因，为架构决策创建问责制。
5. 分层细节管理
模板强制执行适当的信息架构：
**重要**：此实施计划应保持高级别和可读性。
任何代码示例、详细算法或大量技术规格说明
必须放在适当的 `implementation-details/` 文件中这防止了规格说明变成不可读的代码转储的常见问题。LLM 学会保持适当的细节级别，将复杂性提取到单独的文件中，同时保持主文档的可导航性。
6. 测试优先思维
实施模板强制执行测试优先开发：
### 文件创建顺序
1. 使用 API 规格说明创建 `contracts/`
2. 按顺序创建测试文件：合约 → 集成 → e2e → 单元
3. 创建源文件以使测试通过这种排序约束确保 LLM 在实现之前考虑可测试性和合约，从而产生更健壮和可验证的规格说明。
7. 防止投机性功能
模板明确反对投机：
- [ ] 没有投机性或"可能需要"的功能
- [ ] 所有阶段都有明确的先决条件和可交付成果这阻止 LLM 添加使实现复杂化的"最好有"功能。每个功能都必须追溯到具有明确验收标准的具体用户故事。
复合效应
这些约束共同作用以产生以下规格说明：
- 完整：检查清单确保不会遗忘任何内容
- 明确：强制澄清标记突出不确定性
- 可测试：测试优先思维融入流程
- 可维护：适当的抽象级别和信息层次
- 可实现：具有具体可交付成果的明确阶段
模板将 LLM 从创意作家转变为有纪律的规格说明工程师，引导其能力产生始终如一的高质量、可执行的规格说明，真正驱动开发。
宪法基础：强制执行架构纪律
SDD 的核心是宪法——一套管理规格说明如何成为代码的不可变原则。宪法（memory/constitution.md）充当系统的架构 DNA，确保每个生成的实现保持一致性、简洁性和质量。
开发的九条原则
宪法定义了塑造开发过程每个方面的九条原则：
第一条：库优先原则
每个功能都必须首先作为独立库——没有例外。这从一开始就强制模块化设计：
Specify 中的每个功能都必须从独立库开始其存在。
未经首先抽象为可重用的库组件，任何功能都不得直接
在应用程序代码中实现。此原则确保规格说明生成模块化、可重用的代码，而不是单体应用程序。当 LLM 生成实施计划时，它必须将功能构建为具有清晰边界和最小依赖性的库。
第二条：CLI 接口强制
每个库都必须通过命令行接口公开其功能：
所有 CLI 接口必须：
- 接受文本作为输入（通过 stdin、参数或文件）
- 产生文本作为输出（通过 stdout）
- 支持 JSON 格式进行结构化数据交换这强制执行可观察性和可测试性。LLM 不能将功能隐藏在不透明的类中——一切都必须通过基于文本的接口可访问和可验证。
第三条：测试优先命令
最具变革性的条款——代码之前先测试：
这是不可协商的：所有实现都必须遵循严格的测试驱动开发。
在以下之前不得编写任何实现代码：
1. 编写单元测试
2. 用户验证和批准测试
3. 确认测试失败（红色阶段）这完全颠覆了传统的 AI 代码生成。LLM 必须首先生成定义行为的全面测试，获得批准，然后才能生成实现，而不是生成代码并希望它有效。
第七和第八条：简洁性和反抽象
这对配对的条款对抗过度工程：
第 7.3 节：最小项目结构
- 初始实现最多 3 个项目
- 额外项目需要书面理由
第 8.1 节：框架信任
- 直接使用框架功能而不是包装它们当 LLM 可能自然地创建复杂的抽象时，这些条款强迫它证明每一层复杂性。实施计划模板的"阶段 -1 门控"直接强制执行这些原则。
第九条：集成优先测试
优先考虑现实世界测试而不是孤立的单元测试：
测试必须使用现实环境：
- 优先使用真实数据库而不是模拟
- 使用实际服务实例而不是存根
- 实现前强制合约测试这确保生成的代码在实践中有效，而不仅仅是理论上。
通过模板强制执行宪法
实施计划模板通过具体检查点操作化这些条款：
### 阶段 -1：实施前门控
#### 简洁性门控（第七条）
- [ ] 使用 ≤3 个项目？
- [ ] 没有面向未来的设计？
#### 反抽象门控（第八条）
- [ ] 直接使用框架？
- [ ] 单一模型表示？
#### 集成优先门控（第九条）
- [ ] 合约已定义？
- [ ] 合约测试已编写？这些门控充当架构原则的编译时检查。LLM 不能继续进行，除非通过门控或在"复杂性跟踪"部分记录合理的例外。
不可变原则的力量
宪法的力量在于其不可变性。虽然实施细节可以演变，但核心原则保持不变。这提供：
- 跨时间的一致性：今天生成的代码遵循与明年生成的代码相同的原则
- 跨 LLM 的一致性：不同的 AI 模型产生架构兼容的代码
- 架构完整性：每个功能都加强而不是破坏系统设计
- 质量保证：测试优先、库优先和简洁性原则确保可维护的代码
宪法演化
虽然原则是不可变的，但它们的应用可以演变：
第 4.2 节：修正流程
对本宪法的修改需要：
- 明确记录变更理由
- 项目维护者审查和批准
- 向后兼容性评估这允许方法论在保持稳定性的同时学习和改进。宪法通过日期修正展示其自身的演变，展示了如何基于现实世界经验改进原则。
超越规则：开发哲学
宪法不仅仅是规则手册——它是塑造 LLM 如何思考代码生成的哲学：
- 可观察性优于不透明性：一切都必须通过 CLI 接口可检查
- 简洁性优于聪明：从简单开始，仅在证明必要时添加复杂性
- 集成优于隔离：在真实环境中测试，而不是人工环境
- 模块化优于单体：每个功能都是具有清晰边界的库
通过将这些原则嵌入规格说明和计划过程，SDD 确保生成的代码不仅是功能性的——而且是可维护的、可测试的和架构健全的。宪法将 AI 从代码生成器转变为尊重和加强系统设计原则的架构合作伙伴。
转型
这不是要取代开发人员或自动化创造力。而是通过自动化机械转换来放大人类能力。这是关于创建一个紧密的反馈循环，其中规格说明、研究和代码一起演化，每次迭代都带来更深的理解和意图与实现之间更好的对齐。
软件开发需要更好的工具来维护意图与实现之间的对齐。SDD 提供了通过生成代码而不仅仅是指导代码的可执行规格说明来实现这种对齐的方法论。