什么是规范驱动开发（SDD）？一份完整指南

规范驱动开发（Spec-Driven Development，简称SDD）是一种新方法论：它把"规范"当作可执行的契约，让AI智能体据此生成代码，并通过自动化机制硬性约束架构走向，而不是把规范当成可看可不看的文档摆在那儿。

一句话先说清楚

简单讲，SDD做的事情就是把那种"写完没人看"的文档，变成能真正卡住AI输出的执行性合约。一份合格的规范应该包含六个要素：预期结果、范围边界、约束条件、已定决策、任务拆分、验证标准。SDD能抓出单元测试结构上根本抓不到的架构违规和API契约漂移问题，再配合多智能体协作模式（协调者、实现者、验证者三种角色），就能撑起大规模并行工作的场景。

笔者接触过的团队，大多是被动地走上SDD这条路的——AI生成的代码单元测试都过了，但偏偏违反了架构模式、破坏了API契约，或者塞进去一些安全反模式，结果上了生产才暴雷。2026年2月那篇arXiv论文《Spec-Driven Development: From Code to Contract in the Age of AI》把核心区别讲得很清楚：传统的规范是给人看的，而SDD的规范是要作为校验关卡跑起来的。

为什么偏偏是现在火起来了

2025到2026年这段时间，有三股力量同时涌过来，让SDD从"听起来不错"变成"AI写的代码想活到生产，就得这么搞"。

第一，AI写代码的能力上来了，安全漏洞也跟着上来了。 大语言模型生成有漏洞代码的比例，在不同基准测试下从9.8%到42.1%不等（Yan et al., 2025）。到2026年2月，生产仓库里那些AI带进去、还没被发现修掉的问题已经超过11万个。SDD做的事情，就是在这些故障真正发生之前，把可执行的规范当成校验闸门卡在那儿。

第二，合规要求开始把"规范"当证据看了。 欧盟AI法案要求高风险AI系统从2026年8月2日起必须满足合规义务，违规的话最高罚1500万欧元或者全球营收的3%——这数字不是闹着玩的。

第三，分布式架构催着要正式的治理。 Deloitte《2026年AI现状》报告说，只有五分之一的公司在自主AI智能体方面有成熟的治理模型。一旦缺少结构化的规范来管跨服务的协作，多仓库架构一扩大，集成失败就会像滚雪球一样累积。笔者亲眼见过几次这种翻车现场。

数据说话：AI代码到底为什么需要规范来兜底

2025年8月那篇分析了五个大语言模型生成Java代码的arXiv论文（基于SonarQube）发现，Llama 3.2 90B检测出的漏洞里，超过70%是BLOCKER级别；GPT-4o和OpenCoder-8B大约三分之二是BLOCKER或CRITICAL级别。这种规律在文献里反复出现。

Pearce等人2023年发表在IEEE S&P上的论文显示，在安全敏感场景下生成的程序，大约40%包含漏洞。Yan等人2025年的研究把这个范围放在9.8%到42.1%之间。Fu等人2025年发表在ACM TOSEM上的目录化研究，在三款AI代码生成工具里识别出了43个CWE（通用弱点枚举）类别。到2026年2月，那篇大规模实证研究统计到生产仓库里幸存的AI引入问题已经超过11万个。

这些发现跟笔者的实际感受完全对得上。单元测试只能验证单个函数能不能跑，它根本抓不到架构违规、API契约漂移，或者那些跨服务边界才会显现的安全反模式。SDD的规范是在系统层面运作的，专门抓单元测试结构上抓不到的那类缺陷。

SDD跟PRD、设计文档、TDD、BDD到底有什么区别

SDD的规范不是PRD，也不是换了个标签的设计文档。笔者反复琢磨这件事，结论是：PRD或设计文档是写给人看的，人能解读模糊之处、能从组织里的隐性知识补全缺口。AI智能体也会补全缺口，但补的方向往往不是你想要的——没有明确的范围约束，智能体的"自由发挥"经常一路狂奔，跑得越远越离谱。

文档类型	主要读者	模糊处如何处理	更新频率
PRD	产品和工程的人	靠对话和团队默契补全	不频繁，经常过时
设计文档	工程同事	共享上下文 + 评审意见	某个时间点的快照
SDD规范	AI智能体 + CI流水线	明确的约束 + 验证规则	活文档，随工作进展同步更新

SDD所处的架构层次跟笔者日常用的那些代码级方法论也不一样。这种层次区分很关键，因为它意味着SDD不是来替代TDD和BDD的，而是可以叠加在它们之上。

维度	TDD	BDD	Vibe Coding（凭感觉编程）	SDD
主要产物	单元测试	Given-When-Then场景	自然语言提示词	可执行规范
作用范围	单个函数的正确性	跨职能的行为定义	整个应用生成	系统级架构契约
校验机制	自动化测试套件	人工对照文档	人工评审（有的话）	构建时检测到规范偏离就直接挂
AI治理	无	无	无	宪法式约束 + 检查点
真相归属	测试套件	工作坊产物	提示词历史	版本化的规范

TDD走的是红-绿-重构这套循环，在单元层面驱动接口设计。笔者会把TDD留在原位做实现层面的验证，然后在上面叠加SDD做架构层面的约束。

BDD通过跨职能工作坊产出Given-When-Then场景。SDD可以把这些场景吃进来，但要让它们可执行——BDD的场景常常停留在"团队会去翻看的文档"层面，而SDD把它们转换成可以真正运行起来的校验关卡。

**Vibe coding（凭感觉编程）**就是用AI模型从自然语言提示词出发构建应用，几乎没有结构化的评审。MSR '26那篇研究分析了807个GitHub仓库里Cursor AI的使用情况，发现短期速度提升的同时，代码复杂度持续走高。SDD的做法就是在前面先把约束讲清楚，从源头上避免这种漂移。

一份好规范应该包含的六个要素

写给AI智能体看的规范，得回答六个问题。任何一个留白，智能体都会替你回答，而且答得不是你想要的样子。

第一，工作完成时的预期结果。 别写"做一个登录流程"。要写成接近这样的话："用户能用邮箱密码注册，能收到验证邮件，登录不报错，会话刷新页面后能保留。"用结果陈述去描述目标，能逼出特征名称根本带不出来的清晰度。

第二，范围内和明确范围外的边界。 范围外清单的重要性，至少不输给范围内清单。智能体很会扩展范围，你不把门关上它就敢往外冲。比如"OAuth不在本任务范围内"这句话听着废，但对一个学过"认证系统通常包含OAuth"的智能体来说，这一句明示能省下你后面无数次返工。

第三，约束和假设。 现有的技术栈决策、第三方API的限制、性能要求——只要会影响实现选择，又不能光看代码就猜出来的，都写进规范里。规范配合一个AGENTS.md文件，给智能体提供持久化的项目上下文，再加上任务特定的范围，效果会更好。

第四，已经做出的决策。 数据库schema选好了、加密库定了，就写明白。不知道决策已经定下来的智能体，会自己拍脑袋做决定。把你的决策记录在前面，再把活儿交出去。

第五，任务拆分。 AI最大的失败模式之一就是一次塞太多东西过去。把工作拆成离散的子任务，让单个智能体各自处理一块，边做边验，互相不碰同一批文件的时候还能并行跑起来。

第六，验证标准。 验收标准和验证步骤。不是写"能不能跑"，而是写：哪些测试要通过、哪些边界情况要处理。这就是验证者后面要对照的清单。如果跑的是对抗式智能体模式（下面会讲），验证计划就是它的检查依据。

三种核心SDD模式：规范优先、规范锚定、规范即源码

笔者帮团队上手SDD时，会根据场景挑这三种模式之一。每种代表了规范对代码生成的不同权威级别。

模式	规范的角色	代码的角色	适用场景
规范优先（Spec-First）	引导和约束AI输出	主要交付物	刚开始上手SDD的团队
规范锚定（Spec-Anchored）	通过检查点和宪法式约束治理	经过校验的交付物	需要审计轨迹的企业团队
规范即源码（Spec-as-Source）	字面意义上的源代码	生成出来的产物	API优先、工具成熟的领域

规范优先开发是笔者带新团队入门时的起点。规范走在代码前面，约束AI生成什么，但代码本身仍然是主要交付物。

规范锚定开发在上面叠加了治理层、宪法式约束和监督检查点。如果合规要求审计轨迹、多个团队跨服务协作、或者AI生成的代码合并前必须经过人审，笔者就会上这套模式。2026年2月那篇后续的《Constitutional SDD》论文把这套形式化了，把安全约束跟具体的CWE漏洞映射一起嵌进规范里。

规范即源码开发走得最远——规范本身就是源代码。ThoughtWorks 2025年第33卷技术雷达把SDD放在"评估"环里，同时警告说"倾向于做大量前期规范、然后大爆炸式发布"会变成一种反模式。

对抗式智能体模式

笔者觉得规范驱动开发里最被低估的模式，是专门指派一个独立的智能体去检查工作，而不是指望干活的那个智能体自己验自己。

结构大致是这样：协调者把规范拆开，分派任务给一群实现者子智能体。每个实现者基于自己拿到的子规范干活。之后，验证者智能体对照规范检查产出，确认无误才标记完成。这里关键的点在于，实现者和验证者的目标是相反的——一个追求把任务完成掉，一个追求挑出失败之处。

实现智能体对自己产出的东西总是过于乐观。换一个独立的验证者，信号就干净多了。这种模式还反过来逼着规范必须包含明确的验证标准，这本身就改善了规范的质量。它也让并行智能体工作流更安全：多个实现者可以同时跑，验证者负责在合并之前抓出冲突。

子智能体一边干一边实时更新规范，所以协调者随时都能看到当前的真实进度。

什么时候该写规范，什么时候别写

大多数SDD的教程都跳过这个话题，结果整篇文章读起来像销售推销。但真实情况是：不是所有任务都需要详细的规范。规范本身是有开销的，笔者也在一些小修小改上浪费过这个开销——其实给一个智能体丢一个提示词就能搞定的事，根本不值得搭这套架子。

该写规范的场景	跳过规范的场景
工作要跨多个智能体会话	探索性或实验性工作
涉及多个服务或多个仓库	单条提示词就能产出可用结果
一旦理解偏了，回退代价很大	产出五分钟内就能审完
有合规或审计轨迹要求	一次性扔掉的原型
评审需要真正动脑（组件逻辑、端到端流程）	改动机械化且风险很低

笔者用的判断标准是：如果让智能体理解偏了我会觉得很烦，就写规范；如果输出错了一条快速跟进的提示词就能修好，就直接提示，跳过规范。

Spec Kit是怎么把规范执行起来的

笔者推荐刚上手的团队用GitHub Spec Kit这个开源脚手架。它是个Python CLI工具，截至2026年5月已经有10.5万颗星、147个发布版本，支持28个具名的AI智能体平台。工作流走四个命令：/speckit.specify捕捉业务上下文和成功标准，/speckit.plan把规范翻译成架构决策，/speckit.tasks把计划拆成可测试的单元，/speckit.implement让AI智能体在这些约束下运行。

InfoQ的分析里有句话说得很到位：“对AI生成的代码来说，代码问题其实是规范缺口的产物。因为AI生成有不确定性，那个缺口每次重新生成代码时都会换个形式重新冒出来。”

举个具体的对比就清楚了。

没有SDD的时候： 一个支付端点上线时漏了幂等性约束。重试逻辑在生产环境里制造出重复扣款。团队打补丁修了代码，但下一轮AI重新生成又把同样的漏洞带回来了，因为没有任何规范把这个约束记录下来。

有了SDD之后：

# 规范修正会传播到所有生成的产物
- endpoint: POST /charges
  constraints:
    - idempotency_key: required    # 在CI里强制
    - retry_window: 24h            # 生产事故之后加上的

之后只要任何AI智能体生成的charges端点没有幂等性强制，构建在到达评审之前就直接失败。

SDD工具横向对比

笔者评估团队时参考的SDD工具，覆盖了开源框架、API规范平台和企业级控制平面几个层次。

工具	规范格式	CI/CD执行	兼容AI智能体	适用场景
GitHub Spec Kit	Markdown / 结构化	通过智能体工作流	28个平台	跟AI智能体一起上SDD的团队
SwaggerHub / API Hub	OpenAPI、AsyncAPI	CLI + Git集成	MCP Server	需要API生命周期管理的API优先团队
Postman Spec Hub	OpenAPI、多协议	GitHub同步 + CI runner	MCP servers；Claude插件	完整API生命周期 + 治理
Spectral	OpenAPI、AsyncAPI、JSON Schema	CLI退出码	间接	API代码规范和标准执行
PactFlow	Pact + OpenAPI	can-i-deploy门禁	部分	跨服务边界的契约测试
Specmatic	OpenAPI（可执行）	是	智能体就绪	可执行API契约执行
TypeSpec	TypeSpec → OpenAPI	通过下游工具链	是（生成OpenAPI）	Azure/微软生态团队

InfoQ点出了笔者在企业团队那里碰得最多的一个限制：当前的工具"通常把规范跟代码放在同一个仓库里"，但"现代架构横跨微服务、共享库和基础设施仓库"。

一个真实项目的实操样子

把六要素框架套到一个真实项目上：一个10页的产品官网，Figma里完整comped出来的，设计系统覆盖导航、落地页、特性页、定价、文档布局。这种活儿，有经验的前端工程师做下来要好几天，要是顺手学一遍组件库就更久。

第一步：Figma MCP把设计系统拉进上下文

Intent接了Figma MCP之后，协调者智能体在写规范之前先去读Figma文件。它会拉出组件规格（按钮变体、卡片布局、字体层级）、布局约束（栅格结构、间距token、断点）、还有页面层级。协调者把这些设计上下文写进规范，这样每个实现单页的智能体都基于设计师定下的同一套组件库和间距规则去干活。

没有结构化的设计上下文，智能体会自己发明组件样式。一个智能体给卡片用16px内边距，另一个用24px；一个智能体造了个设计系统里根本不存在的按钮变体。把Figma MCP接进来，能在代码生成开始之前就把这种分歧抹平。

协调者从Figma设计系统里提取品牌色，跟验收标准、非目标、假设一起写进规范。

第二步：协调者按页拆解

协调者生成的规范带着页面级别的任务分配：一页一个任务，每个都有自己的验收标准、组件需求和从Figma上下文里拉出来的布局约束。按页拆这件事在这里能并行跑得起来，是因为静态站的页面之间不会写同一批文件。协调者把共享组件（导航、页脚）单独丢给一个最先跑的任务，这样后面的页面级智能体可以从一个稳定的组件库里import，而不是各自重新搭一套。

规范里还包括了几条约束：响应式断点要对齐Figma里的frame、设计token的颜色和间距值要照搬、每个页面要import哪些共享组件。每个实现者智能体拿到的都是一份自包含的任务契约，上下文足够它独立把自己那页做出来，不需要去读其他智能体的代码。

第三步：并行智能体在隔离的worktree里跑

子智能体并行处理各个页面，每个跑在自己的git worktree里。导航和页脚那个智能体最先完工。页面智能体接过共享组件去build。验证者对照规范检查每一页：用对组件了没、设计token应用了没、响应式行为跟Figma的断点对上没。

整个项目大概用了45分钟、几次会话，完成度到了95%。剩下5%是细节微调：间距小调和悬停状态的精细化。

三个落地页任务并行完成，还有四个排队中。协调者确认页面任务可以同时跑，因为它们写不同的文件，验证者在所有页面都构建完之后再跑。

设计师那边的交接

这个项目上的设计师从来没用过Git。换在标准流程里，那5%的微调会以一长串修改请求的形式回到工程师手上，每改一条都要在Figma和代码之间来回切换上下文。但这次不是这样，设计师在Intent里直接打开项目，自己就把细节调完了，不需要工程支持。改个间距值、换个颜色token，根本不需要懂代码，因为规范驱动的结构已经把项目组织成了一块块跟具体Figma frame绑定的、可导航的组件。

这种交接在提示词驱动的产出方式下根本跑不通。智能体从一个模糊提示词里吐出一坨整体代码时，只有写那条提示词的人能看懂结果。而智能体基于带页面级拆分的结构化规范来构建时，谁能读懂规范，谁就能在项目里穿梭。

上下文的精度比上下文的容量更重要

这次工作流还有另一个收获：每个智能体携带的无关上下文越少，输出质量越好。一百万token的代码库上下文听着挺唬人，但其实没有看起来的那么有优势。智能体在精准的、任务相关的上下文下表现得比泛泛接触整个仓库要好。Figma MCP + 规范这套组合能跑通，就是因为它把每个智能体的上下文收窄到了它那个具体任务的设计约束和验收标准上，而不是用整个代码库去淹没它。

在SDD工作流里做模型分层

协调者/实现者/验证者这套模式，让你可以根据每个角色的需要，给不同角色分配不同的模型。

写规范这件事，值得用手头最强的模型。规范里的错误会向下游一路传播，把整个流程染坏，所以在这一步抠成本是最贵的错误。

实现这件事，用一个中档模型 + 中等思考开销就够了（Sonnet那一档，或者GPT-5.1-Codex）。规范稳了以后，执行阶段不需要最贵的模型。

验证这件事，需要快速模型。验证者是对照具体标准检查具体输出：要的是准确率和低成本，不是深度推理。

多智能体工作流的模型调用次数会比单智能体提示多得多。每个子任务都用顶配模型，成本会成倍上去，但收益没有按比例上去。反过来分配（便宜模型写规范、贵模型干实现）就更糟——修正循环烧掉的成本会远超分层节省的那点。

SDD的局限

SDD不是放之四海皆准的。笔者见过它吃力或者不值得搭这套架子的场景：

• 探索性工作。 需求前期讲不清楚的时候，SDD会卡住。研发和实验类工作更适合轻量做法。
• 快速原型。 当从动手到拿到第一个用户反馈的时间是按天算的，SDD那套前期规范要求会让你陷入昂贵的重新生成循环。
• 小团队和高变化环境。 2-5人的小团队，规范开销可能会吃掉过大比例的开发时间。
• 需要大量文档的遗留系统。 把规范写到能让AI生成的精度，意味着要去逆向工程多年沉淀下来的隐式业务逻辑。Spec Kit有个已知问题（GitHub issue #1191）：工作流是为全新特性创建优化的，更新已有规范不太顺手。

写在最后

SDD做的事情，是把规范从被动文档转化成可执行的构建关卡，让架构契约在每一轮代码生成里都得到强制执行。大语言模型只在功能正确性这个窄维度上做了优化，但企业系统要的是架构一致性和监管合规，SDD正好把这中间的缺口补上。

笔者的建议是：从规范优先模式开始，挑一个已经有OpenAPI契约的服务作为起点，把GitHub Spec Kit集成进CI/CD，等多团队协作扩大了再升级到规范锚定治理。这条路走通了，AI代码才有机会真正"活到生产"，而不是上线就给你来场惊喜。

常见问题

• 规范驱动开发跟写详细需求文档有什么不一样？ 详细需求文档是给人读的，模糊处靠人补全；SDD规范是给AI智能体和CI流水线读的，模糊处靠明确约束和验证规则解决，而且是活文档。
• 怎么在不替代现有TDD或BDD的前提下落地SDD？ SDD在架构层运作，TDD在单元层验证实现，BDD在跨职能层定义行为——三者是叠加关系，不是替代关系。
• SDD能防住哪些失败、又有哪些权衡？ 防架构违规、API契约漂移、AI重新生成时漏洞复现；权衡是规范本身也是要维护的资产，会带来开销。
• SDD对合规和审计有没有用？ 有用，规范作为可执行契约能直接作为合规证据和审计轨迹。
• 大代码库和多仓库下SDD能跑得通吗？ 能，但需要跨仓库的依赖映射和语义分析工具支持，单仓库内的工具会力不从心。

参考资料：

• https://www.augmentcode.com/guides/what-is-spec-driven-development
• https://thoughtworks.medium.com/spec-driven-development-d85995a81387