Spec-Driven Development 详解：从 “Prompt and Pray” 到 “Spec and Steer”
1. 问题的起点
Coding agent 越来越强大后出现了一个模式：你描述目标，拿回一堆代码，看起来差不多对……但又不完全对。这种 “vibe coding” 方式做快速原型很好，但做严肃的、关键的应用时就不靠谱了。
Stack Overflow 2025 年开发者调查（覆盖 9 万+开发者）发现，66% 的人把"几乎对了但又不完全对"列为 AI 工具最大的挫败感，45% 的人说大量时间花在调试 AI 生成的代码上。[1]
问题不在 agent 的编码能力，而在我们给它的输入。我们把 coding agent 当搜索引擎用，但它其实是一个极度字面化的 pair programmer——它很擅长模式匹配，但需要明确无歧义的指令。
2. 核心定义
Spec-Driven Development 把规格说明（spec）而非代码视为 source of truth。AI 在执行结构化任务时表现远好于执行开放式 prompt。[2]
在 spec-driven 工作流中，spec 驱动实现、测试和任务拆解——你不会在 spec 被验证之前动手写代码。[3]
用一句话说：别让 AI 写代码，让它先写 spec，你确认 spec 没问题后，再让它按 spec 写代码。
3. 与 Vibe Coding 的对比
| Vibe Coding | Spec-Driven Development | |
|---|---|---|
| 输入 | 模糊的自然语言 prompt | 结构化的 spec 文档 |
| 验证时机 | 看到代码后才发现不对 | 写代码前就在 spec 层发现不对 |
| 修改成本 | 改代码（昂贵） | 改 spec 文档（廉价） |
| 可复现性 | prompt 丢了就没了 | spec 持久化在 repo 里 |
| 团队协作 | 依赖个人 prompt 技巧 | spec 是共享合约 |
一个具体例子说明差异：Vibe coding 的 prompt 是 “Build a rate limiter middleware for Express”。Spec-first 的 prompt 是 “Implement the rate limiter defined in .spec/features/rate-limiter.md, which specifies a sliding window algorithm, 100 requests per minute per API key, 429 responses with Retry-After headers, and Redis-backed state for horizontal scaling”。第二种不给 agent 任何即兴发挥的空间——应该由你做的决策不会被 agent 代替。[4]
关键洞察：两种方式花费的总时间往往差不多，但时间花在哪里不同。Vibe coding 把时间花在生成后反复迭代修改代码上；SDD 把时间花在生成前写 spec 上。而 spec 是可复用的，项目交付后还能当文档用。[4]
传统开发会把你锁定在早期决策上，而 spec-driven 使改变方向变得简单：只需更新 spec，重新生成 plan，让 agent 处理剩下的事。[5]
4. 四阶段工作流
GitHub 的 Spec Kit 和 Addy Osmani 的指南都描述了基本一致的四阶段模型：
Phase 1: Specification（写 spec）
从一个高层级的 prompt 开始，比如"Build a web app where users can track tasks, with user accounts, a database, and a simple UI"。Agent 会回应一个结构化的 spec 草案：概述、功能列表、技术栈建议、数据模型等。这个 spec 就成为你和 agent 都可以参考的 source of truth。[3]
Spec 不是 PRD，也不是 SRS，而是两者的结合。像 PRD 那样写可以确保你包含了以用户为中心的上下文（每个功能背后的"为什么"），这样 AI 就不会优化错误的方向。像 SRS 那样扩展可以确保你钉住了 AI 生成正确代码所需的具体细节（比如用什么数据库或 API）。[3]
一个 spec 通常包含：目标与动机、用户故事、验收标准（可测试的）、技术约束、非目标（明确不做什么）、集成点。
Phase 2: Plan（写技术计划）
让 agent 读 requirements.md 然后产出 plan.md——一个将需求映射到设计决策的技术实现计划。关键点：你还没有让它写代码。[1]
Plan 回答的是"怎么实现"：文件结构、模块拆分、API 设计、数据模型、依赖选择。
Phase 3: Tasks（拆解任务）
Coding agent 把 spec 和 plan 拆解成实际的工作单元——小的、可审查的块，每个解决一个具体的子问题。每个任务应该能独立实现和测试，就像对 AI agent 做 TDD 一样。不是"build authentication"，而是具体的任务如"create a user registration endpoint that validates email format"。[3]
Phase 4: Implement（执行实现）
Agent 逐个（或并行）处理任务。但不同于审查上千行代码转储，你审查的是解决特定问题的聚焦变更。Agent 知道要构建什么（specification 告诉它），知道怎么构建（plan 告诉它），知道当前做什么（task 告诉它）。[5]
你在每个阶段的角色不只是指挥，而是验证：spec 是否捕获了你真正想要的？plan 是否考虑了现实约束？有没有 AI 遗漏的边界情况？
5. 为什么 Spec-Driven 在 AI 时代比传统开发更重要
传统开发中，spec 写得不够好，人类开发者可以中途调试、自适应——发现认证服务需要不同的方式，或者包版本有破坏性变更，都能灵活处理。
AI agent 目前缺乏这种自适应调试和研究能力。它们按照 spec 字面执行，不完整的研究会滚雪球式地导致实现失败。[6]
另一个关键点：AI 辅助开发极大地提高了歧义的代价。当 AI agent 参与时，不清晰的意图不只是拖慢进度，而是主动创造风险。Spec 不再是有用的提示，而是约束条件。[7]
6. Spec 作为"活文档"
把 spec 做成活文档：不要写了就忘。当你和 agent 做出决策或发现新信息时更新它。如果 AI 不得不改变数据模型或者你决定砍掉一个功能，把它反映到 spec 里，让 spec 始终是 ground truth。把它当作版本控制的文档。[3]
好的版本控制习惯在 AI 辅助开发中更加重要。把 spec 文件提交到 repo。这不仅保存了历史，agent 甚至可以用 git diff 或 blame 来理解变更。[3]
这直接呼应了 harness 文章的核心观点：文件系统是 agent 的持久记忆层。Spec 就是这个记忆层中最重要的文件之一。
7. 三个成熟度等级
一篇 2026 年初的 arXiv 论文描述了三个不同的级别。[1] 行业中的实践也大致分成这三层：
Level 1: Spec-First（先写 spec，手动执行）。就是你在 AGENTS.md 里定义的那个流程——先澄清需求，写 spec，确认后再实现。没有自动化工具，依靠 agent 的纪律性。这是 2026 年大多数团队应该的起点。
Level 2: Spec-Validated（spec 验证自动化）。加入了自动漂移检测——如果实现偏离了 spec，CI 会 fail。GitHub Spec Kit、Amazon Kiro 这类工具属于这个层级。
Level 3: Spec-as-Code（spec 就是代码）。更激进的观点——spec 是唯一需要维护的产物，代码是自动生成的中间产物。类似 SQL 生成查询计划，或者 Terraform 生成基础设施。这还处于实验阶段。
8. 当前的工具生态
2026 年领先的 spec-driven 开发工具分为两类：living-spec 平台（在 agent 工作时保持文档与代码同步）和 static-spec 工具（前期结构化需求但实现偏离时需手动调整）。[8]
主要工具：
GitHub Spec Kit（开源，MIT）。通过 Python CLI 提供 spec-driven 工作流脚手架，72.7k stars，支持 22+ AI agent 平台。[9] 适合绿地项目。
Amazon Kiro。用 EARS（Easy Approach to Requirements Syntax）实现 spec-driven，深度集成 AWS 生态。
AGENTS.md / CLAUDE.md + 手动流程。这就是你目前在做的——不依赖特定工具，用 Markdown 文件和 agent 行为规范来实现 spec-first 工作流。如果你使用 Cursor 或 Claude Code 这类方法论中立的工具，你需要找到适合自己的工作流。SDD 的核心是超越 vibe coding，分离设计和实现阶段。[10]
9. 与你已有知识的关联
与 Harness Engineering 的关系。Spec 是 harness 的 Context Injection 层的一部分——它是注入 agent context 的最重要的结构化信息。一个好的 spec 直接决定了 agent 在整个工作周期中的行为质量。
与 Ralph Loop 的关系。Ralph Loop 的核心前提就是有一个明确的"完成条件"（completion criteria）。没有 spec 中的 acceptance criteria，Ralph Loop 的 verification step 就无法判断任务是否真正完成。那篇 Ralph 文章里说的"好的 agent 效果不是靠模型聪明，而是靠你写好 spec"，指的就是这个。
与你的 AGENTS.md 的关系。你加入的 Spec-Driven Development section 实际上是在 Level 1 层面实现了 SDD。agent 的行为规范（AGENTS.md）+ spec 文件（specs/FEATURE_NAME.md）+ 验收标准 + 确认机制，构成了一个轻量但完整的 spec-driven 工作流。
10. 一个诚实的 caveat
经验丰富的程序员可能会发现过度形式化的 spec 会造成不必要的麻烦，减慢变更和反馈周期——就像我们在瀑布开发早期遇到的那样。[10]
Martin Fowler 也指出：“neither Kiro nor spec-kit are suited for the majority of real-world coding problems”。[11]
SDD 的主要问题不是 AI——而是人的因素。SDD 要求开发者精确地指定意图，但这恰恰是最大的挑战。在 10 多年的软件开发中，很少有项目在实现前需求就完全明确了。[12]
这是一个真实的风险。SDD 最适合中等以上复杂度的功能。对于一行修复、简单重构、快速原型，走完整的 spec 流程是过度工程化。判断什么时候需要 spec、什么时候直接动手，这个直觉本身就是工程经验的一部分。
引用来源
推荐阅读材料
按主题分组，由浅入深排列。
入门理解：什么是 SDD，为什么需要它
| 标题 | 来源 | 说明 |
|---|---|---|
| The uncomfortable truth about vibe coding | Red Hat Developer (2026.02) | 最直白地解释了 vibe coding 为什么在三个月后就崩溃，以及 SDD 如何解决这个问题 |
| Beyond Vibe-Coding: A Practical Guide to Spec-Driven Development | Scalable Path (2025.11) | 面向技术领导者的入门指南，很好地解释了 SDD 对团队的价值 |
| Spec-Driven Development: Write the Spec, Not the Code | DEV Community (2026.03) | 用一个 rate limiter 的具体例子对比 vibe coding prompt 和 spec-first prompt 的差异 |
- https://developers.redhat.com/articles/2026/02/17/uncomfortable-truth-about-vibe-coding
- https://www.scalablepath.com/machine-learning/spec-driven-development-guide
- https://dev.to/bobbyblaine/spec-driven-development-write-the-spec-not-the-code-2p5o
核心方法论：怎么写 Spec
| 标题 | 来源 | 说明 |
|---|---|---|
| How to Write a Good Spec for AI Agents | Addy Osmani / O’Reilly (2026.02) | 必读。Google Chrome 团队工程总监写的，是目前最全面的 spec 写作指南 |
| How to write PRDs for AI Coding Agents | David Haberlah / Medium (2026.01) | 专注于 PRD 格式和 Agent Skills 的结合，包含 Replit PRD skill 的实战案例 |
| How to Vibe Code like a Google Engineer | Drew Maring / Substack (2025.12) | 用一个完整的开源项目（MacroMetric）展示从 spec 到实现的全过程，可以 clone 代码学习 |
- https://addyosmani.com/blog/good-spec/ （同步发布在 https://www.oreilly.com/radar/how-to-write-a-good-spec-for-ai-agents/ ）
- https://medium.com/@haberlah/how-to-write-prds-for-ai-coding-agents-d60d72efb797
- https://carlytaylor.substack.com/p/ai-spec-driven-development
工具与框架：用什么来实施 SDD
| 标题 | 来源 | 说明 |
|---|---|---|
| Spec-driven development with AI — GitHub Spec Kit | GitHub Blog (2025.09) | GitHub 官方介绍 Spec Kit 的四阶段工作流，是 SDD 工具生态的起源文章 |
| Diving Into Spec-Driven Development With GitHub Spec Kit | Microsoft Developer Blog (2025.09) | 微软视角的 Spec Kit 实战指南，包含多变体实现的高级用法 |
| 6 Best Spec-Driven Development Tools for AI Coding in 2026 | Augment Code (2026.03) | 横向对比 Intent、Kiro、Spec Kit、OpenSpec、BMAD、Cursor 的评测 |
| SDD Framework Guide — BMAD, GSD, Ralph Loop | Pasquale Pillitteri (2026.01) | 对比所有主流 SDD 框架的安装、使用和实战案例，包含 Ralph Loop 与 SDD 的关系 |
- https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
- https://developer.microsoft.com/blog/spec-driven-development-spec-kit
- https://www.augmentcode.com/tools/best-spec-driven-development-tools
- https://pasqualepillitteri.it/en/news/158/framework-ai-spec-driven-development-guide-bmad-gsd-ralph-loop
行业分析与趋势
| 标题 | 来源 | 说明 |
|---|---|---|
| Spec-driven development | ThoughtWorks (2025.12) | ThoughtWorks 的行业分析，包含对"spec 是否应该取代代码成为 source of truth"的辩论 |
| Spec-Driven Development Is Eating Software Engineering | Vishal Mysore / Medium (2026.03) | 30+ 框架的全景地图，按 Spec 层 → Orchestration 层 → Execution 层 → IDE 层分类 |
| Beyond vibe coding: the case for spec-driven AI development | The New Stack (2026.02) | 企业视角：没有治理的生产力是在自动化创造技术债 |
| Spec-Driven Development with AI Coding Agents — The Workflow Replacing “Prompt and Pray” | Java Code Geeks (2026.03) | 面向 Java 企业团队，包含三个成熟度等级的详细解读和工具选择建议 |
- https://thoughtworks.medium.com/spec-driven-development-d85995a81387
- https://medium.com/@visrow/spec-driven-development-is-eating-software-engineering-a-map-of-30-agentic-coding-frameworks-6ac0b5e2b484
- https://thenewstack.io/vibe-coding-spec-driven/
- https://www.javacodegeeks.com/2026/03/spec-driven-developmentwith-ai-coding-agents-the-workflow-replacingprompt-and-pray.html
Vibe Coding 完整指南（SDD 作为其中一个关键环节）
| 标题 | 来源 | 说明 |
|---|---|---|
| Vibe Coding: The Complete Guide to Building AI-Powered Apps in 2026 | Kumar Gauraw (2026.02) | 最全面的 vibe coding 指南，覆盖 17 个工具、4 个层级，SDD 作为核心方法论 |
| Vibe Coding Guide 2026 — AI-First Development | SitePoint (2026.03) | 技术深度最高的 vibe coding 指南，包含多模型编排、context 管理、模型选择建议 |
- https://www.gauraw.com/vibe-coding-complete-guide-2026/
- https://www.sitepoint.com/vibe-coding-2026-complete-guide/
推荐阅读顺序
如果时间有限，按这个顺序读：
- Red Hat: The uncomfortable truth about vibe coding — 5 分钟，建立问题意识
- Addy Osmani: How to Write a Good Spec for AI Agents — 30 分钟，核心方法论，最重要的一篇
- GitHub Blog: Spec-driven development with AI — 15 分钟，理解四阶段工作流和 Spec Kit
- Drew Maring: How to Vibe Code like a Google Engineer — 20 分钟，看一个完整的实战案例
- ThoughtWorks: Spec-driven development — 15 分钟，理解行业争论和 SDD 的边界
总共不超过 2 小时，覆盖从理念到实践到争议的完整图景。