[译]Specification-Driven Development (SDD)
规范驱动开发（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, …, 1000 — 自动扩展到3位数字以上）
- 分支创建：从你的描述生成语义分支名称并自动创建
- 基于模板的生成：使用你的需求复制并自定义功能规范模板
- 目录结构：为所有相关文档创建适当的
specs/[branch-name]/结构
/speckit.plan 命令
一旦功能规范存在，该命令创建全面的实现计划：
- 规范分析：阅读并理解功能需求、用户故事和验收标准
- 章程合规性：确保与项目章程和架构原则保持一致
- 技术转换：将业务需求转换为技术架构和实现细节
- 详细文档：生成数据模型、API合约和测试场景的支持文档
- 快速启动验证：生成捕获关键验证场景的快速启动指南
/speckit.tasks 命令
在方案创建之后，该命令分析方案和相关设计文档以生成可执行的任务列表：
- 输入：读取
plan.md（必需），以及如果存在的话，data-model.md、contracts/和research.md - 任务推导：将合约、实体和场景转换为具体任务
- 并行化：标记独立任务
[P]并概述安全的并行组 - 输出：在功能目录中写入
tasks.md，准备好由Task代理执行
示例：构建聊天功能
以下是这些命令如何变革传统开发工作流：
传统方法：
1 | 1. 在文档中写PRD（2-3小时） |
使用命令的SDD方法：
1 | # 第1步：创建功能规范（5分钟） |
在15分钟内，你拥有：
- 包含用户故事和验收标准的完整功能规范
- 包含技术选择和理由的详细实现计划
- 准备好进行代码生成的API合约和数据模型
- 用于自动化和手动测试的全面测试场景
- 所有文档在功能分支中正确版本化
结构化自动化的力量
这些命令不仅节省时间——它们强制执行一致性和完整性：
- 无遗漏细节：模板确保每个方面都被考虑到，从非功能性需求到错误处理
- 可追溯的决策：每个技术选择都链接回具体需求
- 活的文档：规范与代码保持同步，因为代码是由规范生成的
- 快速迭代：在几分钟内更改需求并重新生成方案，而不是几天
这些命令通过将规范视为可执行产物而非静态文档，体现了SDD原则。它们将规范过程从必要的苦差事转变为开发的驱动力。
模板驱动的质量：结构如何约束LLM以获得更好的结果
这些命令的真正力量不仅在于自动化，还在于模板如何引导LLM行为向更高质量的规范发展。模板充当复杂的提示词，以富有成效的方式约束LLM的输出：
1. 防止过早的实现细节
功能规范模板明确指示：
1 | - ✅ 关注用户需要什么以及为什么需要 |
这种约束迫使LLM保持适当的抽象层次。当LLM可能自然地跳转到”使用React配合Redux实现”时，模板使其聚焦于”用户需要数据的实时更新”。这种分离确保规范即使在实现技术发生变化时也保持稳定。
2. 强制明确的存疑标记
两个模板都要求使用 [NEEDS CLARIFICATION] 标记：
1 | 从用户提示创建此规范时： |
这防止了LLM常见的看似合理但可能不正确的假设。与其猜测”登录系统”使用邮箱/密码认证，LLM必须将其标记为 [NEEDS CLARIFICATION: 认证方法未指定 - 邮箱/密码、SSO、OAuth？]。
3. 通过检查清单进行结构化思考
模板包含全面的检查清单，作为规范的”单元测试”：
1 | ### 需求完整性 |
这些检查清单迫使LLM系统地自我审查其输出，捕获可能遗漏的漏洞。这就像给LLM一个质量保证框架。
4. 通过关卡确保章程合规性
实现计划模板通过阶段关卡强制执行架构原则：
1 | ### 阶段 -1：实现前关卡 |
这些关卡通过让LLM明确证明任何复杂性的合理性来防止过度工程化。如果关卡未通过，LLM必须在”复杂性跟踪”部分记录原因，为架构决策建立问责制。
5. 层次化细节管理
模板强制执行适当的信息架构：
1 | **重要**：此实现计划应保持高层次和可读性。 |
这防止了规范变成无法阅读的代码堆的常见问题。LLM学会了保持适当的细节层次，将复杂性提取到单独的文件中，同时保持主文档的可导航性。
6. 测试优先思维
实现模板强制执行测试优先开发：
1 | ### 文件创建顺序 |
这种排序约束确保LLM在实现之前思考可测试性和合约，从而产生更健壮和可验证的规范。
7. 防止投机性功能
模板明确阻止投机：
1 | - [ ] 没有投机性或"可能需要"的功能 |
这阻止了LLM添加会使实现复杂化的”锦上添花”功能。每个功能都必须追溯到具体的用户故事，并具有清晰的验收标准。
复合效应
这些约束共同作用，产生如下规范：
- 完整：检查清单确保没有遗漏
- 明确：强制的存疑标记突显不确定性
- 可测试：测试优先思维融入过程
- 可维护：适当的抽象层次和信息层次
- 可实现：清晰的阶段和具体的交付物
模板将LLM从创造性写作者转变为纪律严明的规范工程师，将其能力导向生产持续高质量、可执行规范的方向，真正驱动开发。
章程基础：强制执行架构纪律
SDD的核心是一个章程——一套不可变的原则，管理规范如何成为代码。章程（memory/constitution.md）作为系统的架构DNA，确保每个生成的实现保持一致性、简洁性和质量。
开发的九条章程
章程定义了九条条款，塑造开发过程的每个方面：
第一条：库优先原则
每个功能必须始于一个独立的库——没有例外。这从一开始就强制模块化设计：
1 | Specify中的每个功能必须始于一个独立的库。 |
这一原则确保规范生成模块化、可重用的代码，而非单体应用。当LLM生成实现计划时，它必须将功能结构化为具有清晰边界和最小依赖的库。
第二条：CLI接口强制要求
每个库必须通过命令行界面暴露其功能：
1 | 所有CLI接口必须： |
这强制执行可观察性和可测试性。LLM不能将功能隐藏在晦涩的类中——一切都必须通过基于文本的接口可访问和可验证。
第三条：测试优先准则
最具变革性的条款——在测试之前不编写代码：
1 | 这是不可协商的：所有实现必须遵循严格的测试驱动开发。 |
这完全颠倒了传统的AI代码生成。与其生成代码并希望它能工作，LLM必须首先生成定义行为的全面测试，获得批准，然后才生成实现。
第七条和第八条：简洁性与反抽象
这两条配对条款对抗过度工程化：
1 | 第7.3条：最小化项目结构 |
当LLM可能自然地创建复杂的抽象时，这些条款迫使其为每一层复杂性提供理由。实现计划模板的”阶段-1关卡”直接强制执行这些原则。
第九条：集成优先测试
优先采用真实环境测试而非隔离的单元测试：
1 | 测试必须使用真实的环境： |
这确保生成的代码在实践中工作，而不仅仅在理论中。
通过模板强制执行章程
实现计划模板通过具体的检查点实现这些条款：
1 | ### 阶段 -1：实现前关卡 |
这些关卡充当架构原则的编译时检查。LLM必须通过关卡或在”复杂性跟踪”部分记录合理的例外，否则无法继续进行。
不可变原则的力量
章程的力量在于其不可变性。虽然实现细节可以演进，但核心原则保持不变。这提供了：
- 跨时间的一致性：今天生成的代码遵循与明年生成的代码相同的原则
- 跨LLM的一致性：不同的AI模型产生架构兼容的代码
- 架构完整性：每个功能增强而非削弱系统设计
- 质量保证：测试优先、库优先和简洁性原则确保可维护的代码
章程演进
虽然原则是不可变的，但其应用可以演进：
1 | 第4.2条：修订流程 |
这使得方法论可以学习和改进，同时保持稳定性。章程通过标注日期的修订展示了其自身的演进，展示了原则如何基于实际经验进行精炼。
超越规则：一种开发哲学
章程不仅仅是规则手册——它是一种塑造LLM对代码生成思考方式的哲学：
- 可观察性优于晦涩性：一切都必须通过CLI接口可检查
- 简洁性优于取巧：从简单开始，只在证明必要时增加复杂性
- 集成优于隔离：在真实环境中测试，而非人工环境
- 模块化优于单体：每个功能都是一个具有清晰边界的库
通过将这些原则嵌入规范和方案制定过程，SDD确保生成的代码不仅仅是功能性的——它是可维护的、可测试的、架构合理的。章程将AI从代码生成器转变为架构伙伴，尊重并强化系统设计原则。
变革意义
这不是关于取代开发者或自动化创造力。这是关于通过自动化机械翻译来放大人类能力。这是关于创建一个紧密的反馈循环，使规范、研究和代码共同演进，每次迭代都带来更深的理解和意图与实现之间更好的对齐。
软件开发需要更好的工具来维持意图与实现之间的一致性。SDD提供了通过可执行规范实现这种对齐的方法论，这些规范生成代码而非仅仅指导代码。