权力反转
几十年来，代码一直占据主导地位。规范服务于代码——它们是我们搭建然后在开始“真正工作”即编码后抛弃的脚手架。我们编写产品需求文档（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 命令
此命令将简单的功能描述（用户提示）转换为完整的、结构化的规范，并自动管理存储库：
- 自动功能编号：扫描现有规范以确定下一个功能编号（例如，001、002、003）
- 分支创建：根据描述生成语义分支名称并自动创建
- 基于模板的生成：复制并定制功能规范模板以满足您的需求
- 目录结构：创建适当的
specs/[branch-name]/ 结构以存储所有相关文档
/plan 命令
一旦功能规范存在，此命令创建全面的实现计划：
- 规范分析：读取并理解功能需求、用户故事和验收标准
- 宪法合规性：确保与项目宪法和架构原则对齐
- 技术翻译：将业务需求转换为技术架构和实现细节
- 详细文档：生成数据模型、API合约和测试场景的支持文档
- 快速入门验证：生成捕获关键验证场景的快速入门指南
/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分钟）
/specify 实时聊天系统，包含消息历史和用户在线状态
# 这会自动：
# - 创建分支“003-chat-system”
# - 生成 specs/003-chat-system/spec.md
# - 用结构化需求填充它
# 步骤2：生成实现计划（5分钟）
/plan 使用WebSocket进行实时消息传递，PostgreSQL存储历史记录，Redis管理在线状态
# 步骤3：生成可执行任务（5分钟）
/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. 创建 `contracts/` 包含API规范
2. 按顺序创建测试文件：合约 → 集成 → 端到端 → 单元
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通过生成代码而非仅指导代码的可执行规范，提供实现这种对齐的方法论。
