From Vibe Coding to SDD：用 Spec-Driven Development 重构AI 编程工作流

Vibe Coding? Vibe Debugging!

过去一年，我们都在经历一场编程范式的剧变。Andrej Karpathy 在今年 2 月提出了"Vibe Coding"（氛围编程）的概念：你只需对着 AI 喊几句 prompt，代码就跑起来了——即所谓"Vibe check passed"。然而，这种看似高效的方式很快催生出了一个新词——"Vibe Debugging"。

这个词带着浓浓的讽刺意味。正如一些评论所言："20 分钟用 AI 生成 2 万行代码，却要花 2 年时间去调试"。开发者发现自己陷入了一个怪圈——花大量时间去理解和修复那些自己都未必完全看懂的 AI 代码。以至于有人调侃道：企业为了节省成本用 AI 替代熟练程序员，结果却不得不雇更多人来"擦屁股"。

作为有经验的开发者，你可能已经习惯用 Cursor 或 Claude Code 快速生成代码。但你是否遇到过这些场景：

  • 从零写 MVP 很爽，但在复杂的现有仓库里加功能时，AI 难以掌握项目全貌，写出的代码质量很差，甚至破坏现有逻辑。
  • 为了让 AI 了解项目情况，每次新开聊天窗口，你都要重复声明"你必须遵循 xx 规范；我的项目结构是 xx"。反复编写这些提示词让你十分烦躁。
  • 好不容易写了大段提示词，AI 生成的代码也跑通了，但你盯着 Diff 看半天，完全不敢合并——因为你不确定它是否引入了隐形 Bug。

这就是 Vibe Coding 的局限性。**对于工程而言，从零到一的创造是少数，从一到 N 的迭代才是常态。**实际上，在 AI 时代，实现代码（Coding）已经不是瓶颈，审查代码（Review）才是最大的隐形成本。

今天，我想聊聊如何通过规范驱动开发（Spec-Driven Development，SDD），把这种"概率性的抽奖"变成"确定性的工程"，让你告别 Vibe Debugging 的噩梦。

从一个思考开始：为什么开源项目的 Maintainer 敢合并陌生人的代码？

在 AI 出现之前，当我们向一个知名开源项目提交 PR 时，Maintainer 并不认识我们，不知道我们的技术水平。我们的代码对他们来说是不可知的黑盒——换句话说，我们就是那个"AI"，我们提供了一份代码，而他在审核我们的代码。那他们靠什么保证合入代码的质量？

其实，他们靠的是一套严密的契约系统：

  1. **问题对齐（Issue Alignment）：**PR 是否真正解决了它声称要解决的问题？通常 PR 应关联一个具体的 issue，Maintainer 会回溯该 issue，确认目标是否清晰、合理。
  2. **变更范围（Scope）：**PR 是否只做了它应该做的事情？是否"小而精"？好的 PR 通常聚焦于一个具体问题，避免引入不相关的改动。
  3. **代码质量（Code Quality）：**代码是否清晰可读、逻辑是否正确、是否有潜在的 bug（如空指针、数组越界、资源泄露）、是否引入不必要的性能开销或安全漏洞。
  4. **规范遵守（Compliance）：**是否遵循项目的代码风格指南（如缩进、命名规范）、提交信息格式（如 Conventional Commits）、以及文档更新要求。
  5. **测试覆盖（Testing）：**这里的测试不只是 Unit Test，更是对"需求规格"的验证。是否为新功能或修复添加了相应的单元测试、集成测试，并且所有测试都能通过。
  6. **自动化检查（CI/CD）：**大多数知名开源项目都会配置 CI 系统，自动运行测试套件、代码风格检查（linting）、静态分析和安全扫描。Maintainer 通常会先看这些 CI 是否全部通过。

仔细来看，我们与AI的交互编程也应该是这样的。我们希望AI能够:

  • 聚焦具体问题域: 只解决我们提出的具体需求,不引入无关改动
  • 遵守代码质量要求: 生成逻辑清晰、无明显bug的代码
  • 遵循项目代码风格: 自动适配项目的命名规范、代码格式等
  • 完成测试覆盖: 每次编码后自动生成或更新相应的测试用例
  • 执行静态检查: 提交前自动运行linting、类型检查等工具

但问题在于：如何让 AI Agent 自动化地做到这些，而不用我们每次在新对话窗口里重复提示？这正是 SDD 要解决的核心问题。SDD 基于一个观点：AI 就像能力很强但缺乏业务背景的"名校实习生"——给它模糊的指令（Vibe），只能得到模糊的代码；给它明确的 Spec，它就能交付工程级的实现。

什么是 Spec-Driven Development（SDD）？

Spec-Driven Development（SDD）是一种以规范（specification）为核心的现代软件开发方法论。它强调在编写任何代码之前，先创建详细、结构化、甚至可执行的规范文档，然后将这些规范作为输入，交由 AI 来生成、修改和维护代码。

虽然传统软件开发也强调"规范先行"，但 SDD 与之有着本质的不同——将规范从辅助性文档提升为核心工件，从沟通工具升级为 AI 的可执行蓝图。

SDD 与传统 Specification 的三大区别

1. 核心地位的转变

传统开发中，代码才是王者（code has been king），规范只是辅助性的"脚手架"。而在 SDD 中，规范被提升为首要的、核心的工件（primary artifact），代码反而成了根据规范生成的"最后一公里"产物（"last-mile" output）。

2. 形式与用途的革新

传统规范往往是非结构化的文本（如 Word 文档、PRD）或半形式化的（如 UML 图），主要供人阅读，难以被机器理解。SDD 的规范则是结构化、形式化的，通常采用特定格式（如 YAML、JSON 或 Markdown），不仅是沟通工具，更是 AI 的可执行蓝图（executable blueprints），能够被 AI 精确解析和理解。

3. 迭代与维护方式的简化

传统开发中，一旦代码开始编写，规范文档很容易与代码实现脱节，维护成本高，最终变成"死文档"。**而在 SDD 中，由于代码由规范驱动生成，当需求变更时，开发者只需更新规范，然后重新生成代码即可。**规范始终是单一事实来源（Single Source of Truth），这使得迭代和维护变得异常简单。

为什么 AI 时代需要 SDD？

回到文章开头提到的 Vibe Coding 困境——当我们在复杂项目中反复向 AI 声明规范、却仍然不敢合并生成的代码时，问题的本质是什么？是 AI 能力不足吗？不，问题在于我们给 AI 的"施工图纸"不够清晰。SDD 正是为了解决这些核心痛点而生：

1. 解决"Vibe Coding"的质量危机

开发者通过模糊的提示词让 AI 生成代码，这种方式虽然快速，但容易导致代码质量低下、难以维护且缺乏一致性。SDD 通过强制要求清晰、精确的规范，为 AI 提供了明确的指令，从根本上解决了"20 分钟生成代码，2 年时间调试"的窘境。

2. 提升 AI 的可靠性与可预测性

AI 模型本身具有随机性和不确定性。一个高质量的规范可以极大地约束 AI 的输出，使其行为更可预测、结果更可靠。开发者的工作重心从"微观管理"AI 的每一行代码，转变为清晰地定义需求和约束——这正是人类应该做的事情。

3. 应对复杂系统和企业级开发

正如前文所说，实际工程中"从一到 N 的迭代才是常态"。在构建复杂的"棕地"项目（软件开发中的一个术语，描述在已有系统或代码库基础上进行开发、改造或集成的项目）时，仅靠模糊提示是行不通的。SDD 通过提供结构化的知识（如编码标准、架构决策、API 文档）来指导 AI，使其能够胜任更复杂的任务——就像给 AI 配备了"项目手册"和"施工图纸"。

4. 提供高密度与高质量的Context

现在的 LLM 都有 Context Window 限制。相比于把整个代码库塞给 AI（噪声多、效率低），一份精准的 Spec 能提供更高密度的上下文，让 AI 生成更精准的代码。这解决了"每次新开聊天窗口都要重复声明规范"的痛点。

SDD 的四个核心属性

在 AI 辅助编程的语境下，一份好的 Spec 应该具备以下特性：

  1. **事实性（Source of Truth）：**明确定义软件"做什么"，而不是"怎么做"。它是所有利益相关者对需求达成共识的基础，也是系统的"长期记忆"。
  2. **可执行性（Executable）：**规范不是供人阅读后"意会"的文档，而是能被 AI 直接解析和转化为代码步骤的结构化指令，类似于 SOP（标准操作流程）。
  3. **协作性（Collaboration）：**规范成为产品经理、开发者、测试人员甚至 AI 之间的共同语言，所有人都可以基于同一份文档进行沟通和决策。
  4. **迭代友好（Iterative）：**规范记录了系统的"变化历程"和"为什么改"。代码会频繁变动，但业务逻辑的演进轨迹都沉淀在 Spec 中。Spec 是逻辑的沉淀——只要 Spec 在，即使换一种语言、换一个框架，AI 也能根据 Spec 快速复现系统。

SDD 的核心价值：从"概率性抽奖"到"确定性工程"

回到文章开头那个类比：当你向知名开源项目提交 PR 时，Maintainer 靠什么保证代码质量？靠的是一套严密的契约系统——问题对齐、变更范围、代码质量、规范遵守、测试覆盖、自动化检查。SDD 做的正是同样的事情：它利用结构化的规范作为人与 AI 之间的高效沟通桥梁，将 AI 编程从"凭感觉的概率性抽奖"转变为"有章可循的确定性工程"。

代码的 Diff 只能告诉你"改了哪几行"，Spec 的版本迭代能告诉你"为什么改""改了什么业务逻辑"。这对于长期维护和知识传承至关重要。最终，我们构建出的是更高质量、更可靠、更易维护的软件系统——这正是我们在 AI 时代真正需要的工程能力。

SDD 的实践工具

理论需要工具来落地。在 SDD 的实践中，有两个重要的工具值得关注：AGENTS.md 和 OpenSpec。它们分别从不同层面解决了"如何让 AI 理解项目"和"如何结构化地管理变更"这两个核心问题。

AGENTS.md：给 AI 的项目说明书

AGENTS.md 是一个面向 AI 编程助手的开放标准，本质上是放在代码仓库根目录的 Markdown 文件，可以理解为"给 AI 智能体的 README"。它的目标是为 AI 提供清晰、结构化的项目上下文与操作指引。

当 AI 编程助手（如 Cursor、Claude Code、GitHub Copilot、Devin 等）参与项目开发时，会自动读取 AGENTS.md 文件，了解项目的环境配置、构建步骤、测试方式、代码规范、安全限制等关键信息。这就像给 AI 配备了一本"项目手册"，让它不再需要反复询问或猜测。

核心特点：

  • 开放通用：不绑定特定 AI 工具，已被 20,000+ 开源项目采用，包括 Apache Airflow、OpenAI Codex 等
  • 工程化标准：不是临时的提示词，而是可执行的操作手册，确保 AI 行为可预测、可复现
  • 灵活扩展：支持在大型 Monorepo 中使用嵌套的 AGENTS.md，每个子项目可以有自己的定制指令

使用示例：

# AGENTS.md 示例
## 开发环境
- 使用 Node.js 18+
- 包管理器：pnpm

## 构建与测试
- 安装依赖：`pnpm install`
- 运行测试：`pnpm test`
- 构建项目：`pnpm build`

## 代码规范
- 使用 ESLint 和 Prettier
- 提交前必须通过所有测试
- PR 标题格式：[模块名] 简短描述

通过 AGENTS.md，你可以一次性告诉所有 AI 工具"这个项目该怎么玩"，不再需要在每个聊天窗口重复相同的上下文。

OpenSpec：变更驱动的规范管理

OpenSpec 是一个专门为 SDD 设计的开源项目，它将"对代码的变更"结构化，形成一个完整的闭环工作流。OpenSpec 的核心理念是**"先写规范，再写代码"**——在动手编码前，先让人与 AI 对需求、接口、实现方案达成共识。

工作原理：

OpenSpec 的核心流程是一个四步闭环，类似于我们熟悉的 Code Review 流程，只不过审查对象变成了 Spec：

┌────────────────────┐
│ 1. Draft Proposal  │ 
│ (定义需求与变更)    │
└────────┬───────────┘
         │ 告诉 AI 你想做什么
         ▼
┌────────────────────┐
│ 2. Review & Align  │
│ (对齐规格与任务)    │◀──── 反馈循环 ──────┐
└────────┬───────────┘                    │
         │ 确认方案 (Plan)                   │
         ▼                                  │
┌────────────────────┐                      │
│ 3. Implement Tasks │──────────────────────┘
│ (AI 编写代码)       │
└────────┬───────────┘
         │ 交付代码
         ▼
┌────────────────────┐
│ 4. Archive & Update│
│ (归档并更新 Spec)   │
└────────────────────┘

核心优势：

  • 人机对齐：在编码前就功能、接口、行为等达成一致，避免"写完才发现理解错了"
  • 变更可追踪：所有规范变更都有记录，便于回溯和协作
  • 工具集成：原生支持 Cursor、Claude Code、Cline 等主流 AI 编程工具，可通过斜杠命令（如 /openspec:proposal）直接调用

实战：如何使用 OpenSpec

假设你要在现有项目中引入 OpenSpec：

  1. 初始化：
npm install -g @fission-ai/openspec@latest
openspec init

这会在项目根目录生成 openspec/ 目录，包含 project.md（填写项目上下文）和 AGENTS.md（AI 会自动读取）。

  1. 创建变更提案：

当你想添加新功能时，不要直接写代码，而是先创建提案：

/openspec:proposal "实现用户 JWT 登录功能"

AI 会帮你起草一份初步规范，包括需求描述、技术方案、涉及文件等。

  1. 评审与完善：

与 AI 协作，反复修改提案，直到规范清晰、无歧义。这一步是关键——你在这里投入的时间，会在后续编码和调试中成倍节省回来。

  1. AI 实现代码：

确认提案后，让 AI 根据规范逐步生成代码：

/openspec:apply <change-name>

AI 会严格按照 Spec 中的任务列表（tasks.md）执行，生成符合规范的代码。

  1. 归档变更：
/openspec:archive <change-name>

OpenSpec 会将此次变更的逻辑吸收到主规范文档中，形成新的"单一事实来源"。下次迭代时，AI 就能基于最新的 Spec 继续工作。通过这种方式，你的项目始终拥有一份最新、可读、结构化的规范文档。

值得注意的是，类似理念也在其他工具中实践，例如 Kiro IDE 的 Spec-Driven Development 强调通过属性测试实现规范的自动验证，而 spec-kit 更侧重于从零开始的绿色项目初始化。OpenSpec 则在棕地项目迭代（1→N）和跨模块变更管理上做了针对性优化。

展望：AI 时代，开发者的新定位

从 Vibe Coding 到 Spec-Driven Development，这场转变揭示了一个更深层的趋势：AI 正在重新定义"开发者"这个角色。

回顾本文开头提到的困境——从零到一很爽，但从一到 N 却举步维艰。根本原因在于，传统的编程范式假设"人写代码"，而 AI 时代的现实是"AI 写代码，人做决策"。这要求我们从"代码的生产者"转变为"代码的架构师与审查者"。

在这个新范式下，开发者的核心竞争力将不再是熟练背诵 API 或手写算法，而是：

  1. 结构化表达能力：能否用清晰、明确、无歧义的语言描述复杂的业务逻辑？你能不能把脑中的想法准确翻译成 Spec，让 AI 理解你的真实意图？
  2. 系统与架构思维：如何拆解任务、定义接口、设计可扩展的架构？如何在动手前就预见性能瓶颈、安全隐患和协作成本？
  3. 跨领域的复合型知识：能够跨越前端、后端、基础设施等多个技术领域，理解它们之间的协同效应，做出全局最优的技术决策。
  4. 深度理解业务与需求：技术不是目的，而是手段。真正优秀的开发者能将业务、技术和设计结合，理解需求的本质和边界，而非仅仅"照着 PRD 实现功能"。
  5. 审查与质量把控能力：既然 Coding 交给了 AI，你的精力将主要集中在 Design Review 和 Code Review 上——确保生成的代码符合规范、不引入技术债、不破坏现有逻辑。

这种分工的本质是：我们专注于 Spec（What & Why），让 AI 专注于 Implementation（How）。这不仅是工具的升级，更是思维方式的升维——从"我能写出这段代码"到"我能设计出这个系统"。

SDD正是这一转变的具体实践。它让我们在 AI 编程时代，重新掌握主动权：不再被 AI 的"氛围输出"牵着走，而是通过结构化的规范，建立起人与 AI 的高效协作模式。

如果你还在为"AI 写代码总是不靠谱"而烦恼，不妨试试 SDD。**让代码回归工程，让 Vibe 回归理性。**在这个 AI 原生的时代，那些能够驾驭 AI、而非被 AI 驾驭的开发者，才能真正脱颖而出。

推荐阅读