--- type: article title: "什么是规范驱动开发？（Spec-Driven Development, SDD）" date: 2026-09-05 09:40:00 +0800 tags: [translation, spec-driven-development, sdd, ai-coding, ai-agent, context-engineering] --- 以下是 IBM 文章 **《什么是规范驱动开发？》（What is Spec-Driven Development?）** 的中文翻译： --- **作者：** Anna Gutowska（IBM AI 工程师、开发者倡导者） **发布日期：** 2026年5月19日 --- ## 规范驱动开发的定义 **规范驱动开发（Spec-Driven Development, SDD）** 是一种软件开发方法论。在正式编码之前，团队需先编写并达成一份关于实现细节的详细规范（Specification）。换句话说，这份规范将作为“构建什么”以及“如何构建”的**唯一真实来源（Single source of truth）**。 随着 Microsoft GitHub Copilot、Anthropic Claude Code 或 IBM Bob 等 AI 工具与编程助手的普及，生成代码的门槛已大幅降低。基于先进 AI 模型的 LLM 驱动型 AI Agent，只需用户输入一条自然语言提示词（Prompt），即可随时实时运行一系列迭代任务。 对于软件开发而言，这意味着我们可以优化并自动化构建原型、新功能、单元测试等的开发工作流。生成代码从未如此简单。然而，“氛围程序员”（Vibe Coders）需要警惕一个潜在风险：**AI 的表现上限完全取决于它所接收到的指令质量**。 --- ## 技术债务的抬头：一个典型场景 你可能在现实世界中见过技术债务，甚至自己都没意识到。技术债务早在“氛围编程”（Vibe Coding）出现前就已存在数十年，通常是由于为了追求速度而采取捷径所积累下来的。然而，Vibe Coding 加速了技术债务的产生——因为它能极其轻松地生成大量代码，而开发者可能并未完全理解或验证这些代码。这可能是由于急于交工的压力，或者 Vibe Coder 根本缺乏在技术债务萌芽阶段阻止它的技术背景。 在 AI 辅助开发中，技术债务主要表现为以下几种形式： * **上下文漂移（Context Drift）：** 在修复某一区域的 Bug 时，不小心破坏了另一区域的功能。这是在未完全理解整个系统架构的情况下盲目生成代码的典型症状。 * **碎片化（Fragmentation）：** 新生成的特性无法与现有的架构规范保持一致，逐渐侵蚀代码库的一致性和可维护性。 * **运维成本提升：** 如果没有清晰的规范来锚定代码生成过程，开发者可能会陷入漫长而重复的 Prompt 调试循环中。这种方式可能会消耗数万个 Token 来解决错误，而一个定义良好的规范（Spec）本可以完全避免这些错误。 想象一个行业内许多开发者都非常熟悉的场景：你连续几天或数周开发一个新功能，眼看就要准备上线。然而，在临近截止日期的压力下，你通过一连串 AI 提示词（Prompt）急促地做出了最后的修改。 从用户的角度来看，这些新生成的代码（无论是由 Python 还是其他语言编写）运行起来似乎一切正常。然而在底层，系统已被暴露了多个安全漏洞、引入了依赖冲突，甚至完全忽略了边界情况的处理和测试。 在前期确立一套正式的规范，能为团队提供一个共同的真实来源，从而在整个软件开发生命周期（SDLC）中起到监管作用，无论这段代码最初是由谁（或 AI）编写的。 --- ## 规范的维度光谱（The Spectrum of Specification） 规范驱动开发存在多种不同的实现方式与模板，它们在规范维护力度和折衷权衡（Trade-offs）上各有侧重。这并非简单的“谁比谁更好”，而是取决于你的代码库、团队状况以及所面对的问题域。在选择之前，请充分评估团队的需求与限制。 ### 1. 规范优先开发（Spec-first Development） 在生成任何代码之前，先以用户故事（User Story）、验收标准（Acceptance Criteria）或正式需求文档的形式编写规范。当规范提供了初始的清晰度并完成了代码生成后，规范本身**不一定会持续维护**。随着软件的演进，规范可能会逐渐过时。它的主要目的是在不增加后续维护负担的前提下提供初始的方向指导。这一阶段被视为“进入 SDD 的入口”。 ### 2. 规范锚定开发（Spec-anchored Development） 规范与软件同步演进。随着需求变更和新功能加入，规范会被持续更新以反映系统的当前状态。这对于服务于大型战略项目的工程团队尤其有用。 自动化测试充当了文档与实现之间的桥梁，通常集成在 CI/CD 流水线中，以确保文档和代码在整个开发生命周期中保持同步且可执行。这种结构性与灵活性的平衡，使得规范锚定开发成为对大多数工程团队而言最实用、可扩展的方法。 ### 3. 规范即源头开发（Spec-as-source Development） 这是该光谱上最偏向“AI 优先”（AI-first）的极致形态。在 Spec-as-source 开发中，**规范（Spec）的变更会自动触发代码的变更**，没有任何人类开发者会直接去重构代码。 这种将规范提升至绝对权威级别的做法，要求对 AI 代码生成流水线的质量和一致性抱有极高信心——而目前 AI 生成在本质上仍具有不可预测性（Nondeterministic）。在实践中，这意味着如果缺乏强大的人工监督，它的严谨度可能会打折扣。在采用该模式前，团队应仔细评估其技术栈与 Spec 工具集（Spec Kit）的成熟度、相关系统的关键程度，以及团队验证 AI 输出的能力。 ### 4. 混合方法（Hybrid Approaches） 在实践中，许多团队采用混合模式： * 将规范作为可叠加的、带版本控制的工件处理（例如架构决策记录 ADRs），而不是时刻保持绝对最新。 * 使用外部系统（如 Issue 追踪工具）作为真实来源，故意制造适度的解耦。 * 在极度复杂或由社区驱动、对变更控制要求极其严格的项目中，避免过度的自动化。 每种方法都有其优势和局限性；**具体的应用场景比死板地遵循某种单一模式更为重要。** --- ## 如何编写一份高效的规范 根据你所偏好的规范权威度，一份高效的规范形式可能有所不同。但假设你处于光谱的中间位置（即选择“规范锚定开发”），一份合格的规范应当用**清晰且可测试的语言**描述系统需要做什么，并避免过早地陷入“具体如何实现”的细节中。 规范应足够详细，包含输入/输出定义、数据模式（Data Schema）、边界情况（Edge Cases）和成功标准（Success Criteria）。同时，它也应足够轻量，以便随着对问题理解的加深而动态演进。**最重要的是，一份优秀的规范应当能加速开发**：如果它不能帮你更快地写出更好的代码，或者不能减少理解偏差，那它可能就过于冗长繁琐了。 --- ## 实际案例解析 为了说明高效规范在实践中的样子，以一个用户身份验证功能为例： > **需求描述：** 你正在为 Web 应用实现用户登录功能。请将以下规范作为你的**唯一真实来源**，不要对未列出的需求做出任何假设。 > **功能（FEATURE）：** 用户登录 > **概述（OVERVIEW）：** 允许注册用户使用其电子邮箱和密码进行安全身份验证。 > **验收标准（ACCEPTANCE CRITERIA）：** > 1. 登录表单必须接受电子邮箱和密码。 > 2. 如果凭据有效，将用户重定向至仪表盘（Dashboard）。 > 3. 如果凭据无效，显示通用错误提示，不得透露具体是哪个字段出错。 > 4. 连续 5 次登录失败后，锁定该账户 15 分钟。 > 5. 密码必须仅通过 HTTPS 传输，绝不能以明文形式存储。 > > > **范围外（OUT OF SCOPE）：** > * 第三方社交登录（OAuth） > * 双因子身份验证（2FA） > * 密码重置流程 > > > **边界情况（EDGE CASES）：** > * 在提交前于客户端拦截空字段。 > * 将已过期的会话重定向至登录页面，并附带提示信息。 > * 如果禁用了 JavaScript，表单仍必须能够正常工作。 > > > *在确认完全理解上述验收标准之前，请勿开始代码实现。* 这类规范与产品经理编写的功能规范类似，但严格限定于**实现必须包含的内容（验收标准）**以及**如何优雅地处理边界情况**。 最常见的情况是，该规范会作为 Markdown 文件（如 `SPEC.md` 或 `/docs/auth-login.md`）存放在 GitHub 的项目代码库（Repo）中，并通过 Git 与代码一同进行版本控制。AI 编程 Agent 可以通过用户直接粘贴至 Prompt 中来读取，或者（更推荐的方式）通过 CLI 引用该文件，由 Agent 从项目目录中直接读取。例如指令：“*请实现 `/docs/auth-login.md` 中描述的功能。*” 在自动化程度更高的流水线中，规范文件会在任务开始时作为系统提示词（System Prompt）或上下文窗口的一部分传递给 Agent，在 Agent 动手前赋予其明确的行动指南。 --- ## 警惕“过度工程”（Over-Engineering）陷阱 尽管规范驱动开发能为你节省大量时间和技术债务，但同样重要的是要记住：**可能会存在“过度工程化”的倾向**。如果你花整整三周时间去争论一个 JSON 键名或某个 API 端点的具体命名，而这个功能可能在一个月后就被废弃，这就背离了规范驱动开发的初衷。 不要过分沉迷于预测所有可能的未来。**优先选择轻量、可演进的规范，而不是事无巨细、不可更改的“终极”规范。** 编写足以让你向前推进的内容，在代码中快速验证，并随着现实情况的变化进行迭代。 > **核心原则：** 完善规范的成本，应当始终低于修复因理解偏差而导致的实现错误的成本。当这种平衡被打破时，就意味着该停止琢磨规范，开始动手构建了。 --- ## 结语 随着 AI 编程助手的兴起，受测试驱动开发（TDD）和行为驱动开发（BDD）启发，迎来了新一代的风潮——**规范驱动开发（SDD）**。 * **TDD** 要求开发者通过**测试**来定义预期结果； * **BDD** 要求开发者通过**协作**来定义行为； * **SDD** 则率先抛出一个更根本的问题：**我们是否已经清晰地定义了我们要构建什么、以及为谁而建？** 当 AI Agent 在实现工作中承担越来越多的份额时，其交付质量将直接与它们所接收到的指令质量挂钩。编写良好的规范绝非对开发流程的束缚，反而是在现代软件开发体系中实现加速的核心引擎。