当AI开始批量生成代码，真正稀缺的能力，已经从“如何编码”变成“如何定义意图”

导语：数十年来，代码一直是软件开发中无可争议的王者。需求文档会过时，设计图会失效，测试往往是事后补写。而代码——无论它实际做了什么——都会成为系统事实上的真相。这种以代码为中心的现实带来了难以破解的行业痛点：新开发者必须从复杂的实现中反向工程业务意图，利益相关者难以验证系统是否真正满足需求，而如今普及的AI编码助手，只能从模糊的提示中猜测开发者想要什么，最终陷入“凭感觉编码”的低效循环。

规范驱动开发（Spec-Driven Development, SDD）提供了一种截然不同的解题思路：让规范成为真相的唯一来源，让代码从规范中派生。团队先编写清晰的预期行为规范，再根据规范生成、实现或验证代码，而非先编码再记录（甚至根本不记录）。

为此，接下来精心整理了「SDD 规范驱动开发」系列文章，系统拆解这一AI时代的核心开发范式。本篇作为系列开篇，将聚焦SDD的核心概念与范式革命，厘清其从入门到激进的三层成熟度模型，帮你理解为何AI时代的软件开发必须先明确"要做什么"，再谈"怎么做"。后续两篇将分别深入SDD的全流程落地实操，以及它带来的实际价值、工具生态与开发者角色变革。

一、代码中心模式的困境与SDD的核心主张

传统软件开发的逻辑是“代码即真相”：所有的需求、设计、决策最终都沉淀在代码里，其他所有文档都是辅助性的、可被忽略的。这种模式在人类主导编码的时代有其合理性——毕竟只有代码是可执行的，只有代码能定义系统的实际行为。

但它带来的代价也日益凸显：

• 新人上手成本极高，必须逐行阅读代码才能理解系统的设计意图；

• 需求变更时，很容易出现“代码改了，文档没改”的脱节问题，文档逐渐沦为“僵尸文档”；

• 跨团队协作时，各方对需求的理解不一致，集成阶段频繁出现冲突；

• 当AI编码助手加入后，这个问题被无限放大——AI不会读心术，只能根据提示词的字面意思和常见模式生成代码，模糊的需求会导致AI做出大量错误假设。

SDD的核心主张正是对这一传统逻辑的彻底颠倒：规范是人类和机器理解、构建和维护系统的权威描述，代码只是规范的可执行表现形式。在SDD中，任何行为变更都必须先修改规范，再向下传导到代码；如果代码与规范不一致，要么修复代码，要么修订规范，绝不允许两者“各说各话”。

二、AI催化剂：SDD为何在今天成为刚需

虽然“规范优先”的思想并不新鲜——测试驱动开发（TDD）和行为驱动开发（BDD）早已倡导这一点——但AI编码助手的出现，让SDD从“可选的最佳实践”变成了“必需的生产力保障”。

问题的本质在于：大语言模型擅长模式补全，但不擅长理解意图。我们可以通过一个最常见的场景直观感受这种差异：

• 模糊提示（凭感觉编码）：“在我的应用中添加照片分享功能。”此时AI必须自行猜测：支持什么格式？权限模型是什么？大小限制多少？用云存储还是本地存储？是否需要压缩？最终生成的代码看起来合理，但其中包含了数十个未明确说明的假设，其中很多都不符合你的实际需求。

• 清晰规范（SDD模式）：“用户可以上传最大10MB的JPEG或PNG照片。照片存储在S3中，键名以用户ID为前缀。只有上传者可以删除自己的照片。上传时照片会被调整尺寸，最大维度不超过1024像素。”此时AI有了足够的信息来生成完全符合意图的代码，无需进行任何不必要的猜测。

SDD核心原则：在规范驱动开发中，代码是规范的实现细节，而非反之。规范声明意图；代码实现意图。

📚 核心解读

🔑 范式革命：传统开发中，代码是“第一公民”，文档是“事后补写的二等公民”；而在SDD中，规范是“唯一的真相来源”，代码只是规范的“可执行表现形式”。

💡 AI时代的必然性：当AI能在几分钟内生成人类几天才能写完的代码时，需求的清晰度和准确性就成为了新的生产力瓶颈。AI不会质疑你的意图，它只会忠实地实现你描述的东西——如果你描述得不清楚，它就会用最常见的假设来填补空白，而这些假设往往不符合你的实际需求。

⚠️ 常见误解：很多人认为SDD就是“写更多文档”，这是完全错误的。SDD的目的是减少歧义，提高效率，而不是增加文档量。好的SDD实践实际上会减少整体的文档工作，因为规范本身就是可执行的、可验证的。

三、SDD的三层成熟度谱系

并非所有规范驱动方法都是相同的。团队会根据自身需求、工具和领域约束采用不同程度的严谨性。这三个层级不是非此即彼的选择，而是一个可以逐步演进的成熟度阶梯，了解你的团队处于哪个位置——以及应该处于哪个位置——是有效采用SDD的第一步。

1. 规范先行：指导初始开发

在规范先行开发中，在编码之前编写规范以指导初始实现。一旦代码存在，规范可能会也可能不会被维护——其主要价值在于提供初始的清晰度。

这是SDD的入门点。开发者或团队在编写代码之前，明确说明代码应该做什么，通常采用带有验收标准的用户故事、BDD场景或详细的需求文档形式。规范指导实现，但一旦代码编写完成且测试通过，规范可能会被丢弃或允许过时。

这种方法在使用AI编码助手进行初始功能开发时效果特别好。预先编写的规范防止AI猜测需求，显著提高了生成代码的质量。对于原型和一次性功能，当长期维护规范与代码的成本不合理时，这种方法也很有价值。

2. 规范锚定：活文档

在规范锚定开发中，规范在系统的整个生命周期中与代码一起维护。行为的变更需要同时更新规范和代码，保持两者同步。

规范锚定开发将规范视为随代码演变的活文档。当功能发生变化时，规范会先于或与代码同时更新。自动化检查——通常是从规范派生的测试形式——确保规范和代码保持一致。如果它们出现偏差，测试就会失败，立即反馈系统的文档不再反映其行为。

这是大多数生产系统的最佳平衡点。它提供了清晰文档和可验证需求的好处，而不要求代码完全从规范生成。Cucumber等BDD框架就是这种方法的典范，使团队能够编写可作为自动化测试执行的人类可读场景。对于API开发，OpenAPI规范与Specmatic等契约测试工具结合使用，可以实现规范与实现之间的相同对齐。

3. 规范即源码：人类编辑规范，机器生成代码

在规范即源码开发中，规范是人类直接编辑的唯一工件。代码完全从规范生成，永远不应手动修改。任何行为变更都意味着修改规范并重新生成代码。

规范即源码代表了SDD最激进的形式。实际上，规范变成了源代码——只是以更高的抽象级别表达。开发者从需求和行为的角度思考；机器将其转换为可执行代码。如果你想更改功能，你更改规范并重新生成——你永远不会直接编辑生成的代码。

这种方法借鉴了契约式设计（Design by Contract）原则，从根本上颠倒了规范与代码之间的传统关系。手动代码编辑要么被禁止，要么被限制在明确定义的扩展点。这需要成熟、可信的生成工具——开发者必须有信心生成的代码能够正确实现规范。作为回报，偏差被设计消除：由于代码是重新生成而非手动编辑的，规范和代码在构造上始终保持一致。

规范即源码在具有明确定义代码生成的领域已经是标准做法，例如从OpenAPI规范生成API服务器存根，或从Simulink模型生成经过认证的嵌入式代码。Tessl等新兴AI工具旨在将这种方法扩展到通用软件开发，代表了规范成为“新源代码”的未来。

三级对比表

📚 核心解读

🔑 渐进式成熟度模型：这三个层级不是非此即彼的选择，而是一个可以逐步演进的成熟度阶梯。不要盲目追求最激进的“规范即源码”，对于90%以上的团队来说，“规范锚定”是性价比最高的选择。

⚠️ 架构师避坑指南：很多团队把 SDD 误读为“重回瀑布流写大部头文档”。记住，敏捷的规范不是长篇大论，而是精准和可验证。如果你的规范改了，代码却不需要自动化校验就能上线，那不叫 SDD，那叫“传统文档自嗨”。

结语

SDD的核心从来不是“写更多文档”，而是“消除歧义”。它的三层成熟度模型为不同团队、不同场景提供了灵活的选择：对于快速原型和短期项目，“规范先行”足以让AI编码的初始质量显著提升；对于需要长期维护的生产系统，“规范锚定”能从根本上解决“文档与代码两张皮”的问题；而在工具成熟的标准化领域，“规范即源码”则能实现开发效率的质的飞跃。

但仅有范式认知还不够，知道“为何做”之后，更要明确“怎么做”。很多团队在尝试SDD时，会陷入“规范写得像伪代码”“技术约束不明确”“验证环节缺失”等问题，最终导致SDD流于形式。在本系列的第二篇文章中，我们将聚焦SDD的全流程落地，从规范制定到自动化验证，拆解让“规范落地不悬空”的关键步骤，以及架构师视角下的核心责任闭环。

推荐阅读：

AI使用等级