SDD：让 AI 写代码，先写一份好「剧本」

2025 年 AI 领域的主题是 Context Engineering，这个时期的 AI 演进，随着大模型能力的提升，AI Coding 正式从一个「可以试试」的玩具变成能落地到生产环境的核心工具，而其背后的关键方法论就是 SDD。

2026 年 AI 的主题是 Harness Engineering。对 AI Coding 而言，它是对 SDD 的增强和简化——把 SDD 中的一些能力逐渐固化到 AI Agent 中去，让开发变得更加简单。

所以，如果我们想真正做好 AI Coding，理解 SDD 的基本原理是必要的。这套方法在 2025 年已经得到了充分验证，到现在也依然有效。更重要的是，理解它背后的思想，才能在 AI 能力持续演进的路上始终走在前面。

▏What

SDD 即规范驱动开发（Spec-Driven Development），是一种在 AI Coding 普及背景下被重新定义和推广的软件开发范式。

它的核心思想极其朴素：在让 AI 写任何一行代码之前，先写好一份结构化的、可验证的规格说明书，并让它成为整个开发过程中人类和 AI 共享的唯一事实来源。

这份规格不是传统意义上写完就丢进 Wiki 吃灰的「文档」，而是一份可执行的契约。它定义了你要构建什么、边界在哪里、什么叫「做完了」——AI 代理把它当作唯一指引来生成代码，自动化工具用它来验证代码。如果实现偏离了规格，构建在代码审查之前就直接失败。

IBM 给出了一个更精炼的描述：SDD 是一种在开发开始之前就撰写并达成一致的详细实现规格的方法论。微软则直指要害：SDD 让结构化规格成为人类和 AI 之间共享的唯一真相来源。

本质上，SDD 把模糊的软件构想升级为 「意图 → 规范 → 计划 → 任务 → 实现」 的可验证闭环。

▏Why

SDD 之所以有效，根本原因在于它做了一次关键的翻转：把软件开发的核心从「围绕人」展开，转换为「围绕 AI」展开。

在传统开发中，我们的流程是这样的：产品经理把构想变成 PRD（给人看的自然语言文档）→ 架构师和开发者阅读 PRD 做「人脑编译」，翻译成技术设计 → 开发者再把人脑里的技术设计变成代码。每个环节都在发生信息损耗——有些约定俗成的东西没写进文档，有些写法只是给人看的，跟 AI 的理解方式并不吻合。

直接把给人写的文档丢给 AI 去编码，质量一定会打折扣。

SDD 做了一次转换：它让所有工作都先变成 「AI 友好的规范」，然后 AI 编码时，代码服务于规范。在这场反转中：

• 维护软件的核心，从「修改代码」变成了「演进规范」。

• 调试 Bug 的核心，从「修复错误代码」变成了「修正产生错误代码的规范或方案」。

• 技术重构的核心，从「大规模迁移代码」变成了「基于同一份规范，生成一个全新技术栈的实现」。

AI 拿着对自己更友好的文档去做编码，质量自然会提升，也更容易让开发成果一步到位。

那为什么是现在？有三个趋势正在同时发生。

第一个趋势是 AI 编码的安全债。 AI 生成代码的速度确实惊人，但质量远没有速度那么可靠——不同基准测试中，LLM 生成代码的安全漏洞率高达 9.8% 到 42.1%。你写得越快，积累的隐性债务就越多。SDD 把安全约束直接编码进规格中，让每次生成都必须通过验证门禁，从源头拦截漏洞。

第二个趋势是编码代理正在从**「辅助」走向「自主」。** 当 AI 不仅仅是补全代码，而是接受任务、独立实现、甚至自主提交 PR 时，你需要的就不只是一个好 prompt，而是一份结构化的、可被机器验证的契约。正如 ThoughtWorks 的 Birgitta Böckeler 所说：「因为 AI 太容易生成可演示的原型了，许多人忽视了良好工程实践的重要性，导致了太多不可维护、有缺陷的一次性代码。SDD 恰恰帮助我们把需求分析、软件设计和人工治理重新带回画面中。」

第三个趋势最根本：规格本身正在从「被动文档」进化为「可执行合约」。 传统规格说明书是静态的——写完就过时。AI 时代的 SDD 把规格变成了活的验证门禁：每次代码生成都触发一轮对齐检查，偏离就拦截，闭环自动完成。

SDD 最好的理解方式，或许就是把它和它的反面——Vibe Coding——放在一起看。Vibe Coding 的画面很诱人：打开 Cursor，用一两句自然语言描述想法，AI 在几秒钟内吐出一整段代码。魔法般的体验。但撞过墙的人都知道后续是什么：接口不一致、边界条件被忽略、架构在不知不觉中漂移——「像十个互不沟通的开发者分别写出来的」，有人这样形容。

Scalable Path 的说法更尖锐：「AI 改变了团队构建软件的速度，但没有改变他们构建正确软件的能力。速度来自于用推特长度的句子描述想法，让 AI 写代码，然后在崩溃的地方修修补补。SDD 将思考前置到规格阶段，节省了后续的调试、重写和返工。」

▏How

SDD 把软件开发的主流程转换为四个阶段：需求 → 方案 → 任务 → 实施。 前三个阶段分别对应一份核心文档（spec.md、plan.md、tasks.md），实施阶段才是实际的 AI Coding 过程。

实施阶段的主线是完成 tasks.md 中的每一项任务，而执行每个任务的依据，则依托于前两个阶段的 spec.md 和 plan.md。

第一阶段：意图定义 → spec.md

• 目标：澄清并固化「做什么」（WHAT）和「为什么做」（WHY）。

• 输入：开发者或产品经理提出的高层级、模糊的自然语言想法。

• 核心活动：人机协作进行头脑风暴，挖掘边缘场景，澄清模糊地带，定义验收标准。

• 输出产物：spec.md——需求规范。这份文档的核心是完全与技术实现解耦，它只关心用户故事、功能需求和成功标准。它是后续所有阶段的唯一输入和「宪法」。

Google Chrome 团队的工程负责人 Addy Osmani 是这样描述他的实践的：「我先和 AI 一起 brainstorm，描述我的想法，然后让 LLM 迭代地向我提问，直到我们充分梳理了所有需求和边界条件。最终编纂成一份全面的 spec.md——包含需求、架构决策、数据模型，甚至测试策略。」

第二阶段：技术规划 → plan.md

• 目标：决定「如何做」（HOW）。

• 输入：spec.md 和开发者提供的技术栈约束。

• 核心活动：AI Agent 基于规范，结合自身工程知识，进行技术选型、架构设计、模块划分、API 契约定义。

• 输出产物：plan.md——技术方案及其附属文档（如 data-model.md、api-spec.json）。这份方案将业务需求精确映射到技术实现上。

这一阶段的关键是定义接口和边界。一份好的 plan 不仅仅描述「要做什么」，还定义了模块之间的契约——数据流、依赖关系、架构上的关键决策。你在这一步定义得越精确，后续 AI 编码时就越不需要你纠正那些「内部逻辑没问题但跟外部对接不上」的实现。

第三阶段：任务分解 → tasks.md

• 目标：将「如何做」分解为「一步步怎么做」（ACTIONS）。

• 输入：plan.md 及其所有附属设计文档。

• 核心活动：AI Agent 分析技术方案，将其拆解成一系列具体的、原子化的、可执行的开发任务，并识别任务之间的依赖关系和可并行点。

• 输出产物：tasks.md——AI Agent 的「待办事项清单」，格式和内容必须是机器友好的。

这一步的价值怎么强调都不为过。AI 代理在长上下文中的一致性仍然有限——如果让它一次性生成整个应用，你会得到一段看起来连贯但内部逻辑支离破碎的代码。把工作拆分为小的、可增量验证的步骤，让每一次迭代携带前一阶段的上下文，最终拼出一个内在一致的整体。 这既是 AI Coding 的最佳实践，也是人类开发的基本工程纪律。

第四阶段：自动化实现

• 目标：完成所有任务，生成最终产物。

• 输入：tasks.md.

• 核心活动：AI Agent 严格按照 tasks.md 逐一执行——创建文件、编写代码、运行测试。开发者在此阶段的核心职责是监督、审批高风险操作、验收最终结果。

• 输出产物：可运行的软件代码、测试用例、文档等。

这四个阶段，构成了一个从「抽象意图」到「具体实现」的完整逻辑链条。每一步的输出都是下一步的输入，每一步都有明确的验收标准。

▏SDD 的三个层次

SDD 并不是一个「全有或全无」的选项。ThoughtWorks 的 Birgitta Böckeler 区分了三个实践层次，为不同阶段的团队提供了一个清晰的成长路径。

第一层：Spec-First（规格优先）。 团队在开发开始前写好一份深思熟虑的规格，然后在 AI 辅助开发流程中使用它。规格是参考文档，但不是硬约束。AI 读取规格理解意图，最终实现仍以开发者判断为准。这是入门最容易的方式，适合快速迭代中的实验性功能。

第二层：Spec-Driven（规格驱动）。 规格不仅仅是参考，而是驱动整个实现流程的引擎。AI 代理严格根据规格生成代码，任务拆解、实现顺序和验收标准全部来自规格。规格成为人类和 AI 之间唯一的事实来源。 这是大多数生产系统团队当前最实用的目标。

第三层：Spec-Verified（规格验证）。 最高层次。规格不仅驱动实现，还自动化地验证实现。每一次代码生成都触发一轮对齐检查——接口一致性、行为合规性、安全约束——任何偏离都会在构建阶段被拦截。本质上是把规格变成了 CI/CD 管道中的可执行门禁。

这三个层次不是互斥的，而是一个渐进的成熟度光谱。你可以在核心支付模块上实践 Spec-Verified，同时对快速试错的新功能采用更轻量的 Spec-First。关键是知道你在哪个模块上需要多高的严谨度，并做出有意识的选择。

▏一个真实的例子

假设你要为电商平台构建一个支付集成模块。

Vibe Coding 的做法： 在 Claude Code 里输入「给我的应用加一个 Stripe 支付，支持信用卡和 Apple Pay」。AI 哗啦啦生成一堆代码——路由有了，Webhook 处理有了，前端组件也有了。看起来不错。但你随后发现：idempotency key 没有实现，重试场景下可能重复扣款；退款逻辑散落在三个不同的地方；每种支付方式的错误处理覆盖不一致。你开始修修补补，一个「快速集成」变成了三天的调试和半夜的生产事故。

SDD 的做法： 先花时间撰写规格。明确定义：支持的支付方式及各自的接口契约、idempotency 的实现策略（每次请求携带唯一幂等键，重复请求返回已有结果）、退款流程的状态机和回滚路径、Webhook 事件类型及其处理逻辑、错误分类和降级策略。这份规格经过 AI 和你之间的几轮对话打磨，直到没有模糊地带。然后 AI 代理以这份规格为唯一指引，分步生成代码——每完成一个模块，就对照规格中的验收标准进行验证。构建管道中嵌入自动化检查：任何生成的支付端点如果没有包含 idempotency 头，直接构建失败。

前一种路径：10 分钟生成代码，3 天修 bug。后一种路径：1 小时写规格，1 小时生成和验证。表面上看前者更快，但任何一个带过生产系统的人都知道，后者才是真正的捷径。

▏工具与生态

SDD 的工具生态在 2025-2026 年间快速成熟。目前的工具大致分两类：

第一类：专用 SDD 工具，安装到 AI Coding Agent 中使用。

• GitHub Spec Kit：GitHub 官方出品，目前关注度极高（star 数已超 110K）。支持安装到 Claude Code、Codex、Gemini CLI 等 Agent 中。它把 SDD 流程变成了四个命令：/speckit.specify（生成 spec.md）→ /speckit.plan（生成 plan.md）→ /speckit.tasks（生成 tasks.md）→ /speckit.implement（开工干活）。上手极其简单：第一行描述你的需求，后面三步直接调用命令即可，AI 会和你交互式地确认技术栈和功能细节。目前已知的一个局限是工作流主要针对全新功能创建，更新已有规格的支持还在完善中。

• Kiro：由前 GitHub 和 Google 工程师创建，是一个从规格到部署的端到端平台。从自然语言生成结构化规格，划分执行任务，提供上下文感知的代码生成。更适合需要完整管线的团队。

• Tessl：专注于规格的「合约」属性。让团队以声明式方式描述期望的系统行为，通过自动化测试和合约验证来强制执行——本质上是一个规格驱动的质量保障框架。

第二类：直接与大模型交互，按 SDD 方法论手动推进。

现在大模型的能力越来越强，即便不安装专用 SDD 工具，直接按 SDD 的方法论与大模型交互也能达到很好的效果：

> 我要做一个支付集成模块，帮我写出 spec.md，有问题需要与我澄清
> 根据 spec.md 写出开发计划，保存到 plan.md
> 根据 plan.md 做工作分解，保存到 tasks.md  
> 参考 spec.md 和 plan.md，完成 tasks.md 中的全部任务

Claude Code 的 /plan 模式、/goal 模式等，本质上也是在简化 SDD 的样板套路，把方法论内化到了工具中。对于小功能迭代，直接在 plan 模式下描述需求，AI 会先思考、编写计划、再逐步实施，效果和效率都很不错。

企业级方面，Augment Code 的 Context Engine 通过语义依赖图分析处理超过 40 万个文件，解决了当前大多数 SDD 工具的主要局限——「规格和代码放在单一仓库中，而现代架构横跨微服务、共享库和基础设施仓库」——实现了跨仓库的规格一致性管理。

▏切记！切记！

SDD 的全套文档，虽然大部分场景下都是 AI 自己生成的，没有问题，但每个文档都必须要经过人工审核。 你自己要看一下 AI 生成的内容是否符合预期：

1. 规格文档阶段：看它列出的内容与你想做的需求是否有不一致的地方，有的话要及时干预改过来。规格是后续一切的宪法，宪法写错了，后面的代码不可能对。

2. Plan 制定阶段：看它采用的技术栈、架构设计与你的预期是否一致。如果你是开发人员，对技术有自己的要求，这里就是让 AI 写实际代码之前做纠偏的地方。

3. Task 工作分解阶段：看它的任务拆解是否合理。特别推荐在生成 plan 和 task 时强调使用 TDD（测试驱动开发）方式来做开发。 TDD 不仅是人类开发时的最佳实践，在 AI Coding 中同样是写代码的最佳实践套路。让 AI 先写测试再写实现，出来的成果一般更加靠谱，后续迭代时也更不容易在已有成果中引入新 bug。

另外，SDD 也有它的边界，并不是所有场景都适用：

• 小型团队和高频变更环境（2-5 人）：规格维护的开销可能不成比例地消耗开发时间。当整个产品还在快速试错阶段，「先写规格」可能变成「先浪费时间」。

• 遗留系统改造：要为已有多年隐性业务逻辑的遗留系统写出足够准确的规格，本质上是在反向工程整个系统的设计意图——成本可能远超收益。

• 快速原型和探索性项目：当目标不是交付一个正确系统，而是验证假设或探索想法时，Vibe Coding 式的快速试错反而更高效。SDD 的价值在于生产软件的可维护性，而不是速度本身。

不要过度工程化。 为一个下个月可能被删除的功能投入三周争论 JSON key 的命名，这不是 SDD——这是 SDD 的反面教材。将规格视为活的产物：代码在变，业务在变，规格必须随之演进。好的规格应该在系统成熟后逐渐瘦身，因为稳定的部分已经内化到架构和测试中了。

▏What’s More

SDD 不是一个新概念——写规格说明书从来都是良好工程实践的一部分。它之所以在 AI 时代被重新推到聚光灯下，不是因为理论有了突破，而是因为杠杆效应发生了质变：当一份好规格的读者不再只是人类同事，而是一个能在几分钟内完成几天工作量的 AI 代理时，写好规格的回报被放大了几个数量级。

ThoughtWorks 将 SDD 称为「2025 年最重要的工程实践之一」。这或许恰如其分：SDD 不像一段炫酷的 demo 那样吸引眼球，但它回答了 AI 辅助开发中最根本的问题——在速度被无限放大的时代，什么才是正确的边界？

答案正在浮现：思考在前，执行在后；规格是约束，也是自由。 软件工程正在从 AI 辅助的任务执行走向 AI 原生的端到端工作流。随着编码代理变得越来越自主，人类开发者的角色正在从代码书写者转变为规格制定者、AI 输出评审者和系统设计决策者。

把规格写好，AI 会把代码写好。这不是未来的趋势，而是现在正在发生的事。

本文参考了 IBM、Microsoft、GitHub、ThoughtWorks、Augment Code 及 Martin Fowler 等多方资料。