SDD实战：规范驱动开发之道

版权信息

书名：SDD实战：规范驱动开发之道

ISBN：978-7-115-70147-3

本书由人民邮电出版社发行数字版。版权所有，侵权必究。

您购买的人民邮电出版社电子书仅供您个人使用，未经授权，不得以任何方式复制和传播本书内容。

我们愿意相信读者具有这样的良知和觉悟，与我们共同保护知识产权。

如果购买者有侵权行为，我们可能对该用户实施包括但不限于关闭该帐号等维权措施，并可能追究法律责任。

版　　权

著    黄　佳

责任编辑 秦　健

人民邮电出版社出版发行　　北京市丰台区成寿寺路11号

邮编　100164 　电子邮件　315@ptpress.com.cn

网址　http://www.ptpress.com.cn

读者服务热线：(010)81055410

反盗版热线：(010)81055315

内 容 提 要

本书系统阐述了AI时代的规范驱动开发（Specification-Driven Development，SDD）方法论。针对当前Vibe Coding带来的需求蒸发、代码不可维护等痛点，书中提出了“规范先行”的核心理念，详细拆解了从需求定义、架构设计到任务拆解的标准化工作流。全书不仅涵盖了SDD的核心思想、工具链全景及规范撰写实战，还深入探讨了SDD与AI Agent设计模式的融合，以及如何在团队中落地协作与自动化，旨在帮助开发者构建可迭代、规范化的现代化工程体系。

本书适合深受AI辅助编程“上下文漂移”与“代码不可维护”困扰的软件开发者、技术负责人及架构师阅读。

前  言
胸有丘壑，以终为始

这本书的起点，是一个困扰了我很久的矛盾。

AI辅助编程工具（如Claude Code、Cursor、GitHub Copilot、Windsurf）的能力越来越强，每一个都宣称自己能带来“10倍效率提升”。但我在工程师社区中反复听到的故事是：第一天效率飙升，第一周开始返工，第一个月便陷入自我怀疑。

问题出在哪里？

不是AI不够聪明。2026年的大模型已经能通过大多数编程面试，理解复杂的业务逻辑，写出语法正确的代码。问题在于：你给AI的信息不够完整。

你说完“帮我做一个用户认证系统”，AI就噼里啪啦写了2000行代码。你一看，方向完全偏了——它选了你不想用的框架，加了你不需要的功能，改了你不让它碰的文件。你回退，重新来，写了一大段描述。结果AI给出的方向还是偏了，因为你漏说了数据库迁移的事。

每一轮失败都在消耗你的时间和Token（词元）。核心问题不是AI能力不足，而是你的指令不够完整。

这就是SDD出现的背景。它的核心主张极其简单：

先撰写规范，再编写代码。

Vibe Coding通常依赖用户通过简短的自然语言指令让AI去猜；而SDD则要求用户（或在AI辅助下）先生成一份结构化的规范文档，内容包括要做什么、为什么做、怎么做以及分几步做，然后让AI严格按照规范执行。

SDD不是什么新发明。

Stephen Covey在《高效能人士的七个习惯》中提出了一个深刻的洞察：以终为始（Begin with the End in Mind）——所有事物都经过两次创造。第一次是在头脑中的心智创造（mental creation），第二次才是在现实中的物质创造（physical creation），如图1所示。建筑师先画蓝图，再盖房子；企业家先写商业计划，再创办公司；作曲家先在脑海中听见旋律，再落笔成谱。

图1　心智创造与物质创造

如果你跳过第一次创造——不画蓝图就盖房，不写计划就创业——你得到的将不是效率，而是混乱。因为你把“想清楚”的成本转嫁到了“返工”上。

SDD本质上就是Covey的这一洞察在AI辅助编程时代的具体实现。

• proposal.md是心智创造：你在头脑中构建“这个系统应该是什么样”。

• design.md是架构创造：你在图纸上规划“这个系统怎么实现”。

• tasks.md是执行蓝图：你在清单上明确“按什么顺序建造”。

• Code（代码）是物质创造：AI按照前三份蓝图，将想法变成可运行的软件。

三份规范构成第一次创造，代码是第二次创造。

Vibe Coding的问题恰恰在于跳过了第一次创造，直接进入第二次创造——让AI凭空建造一栋没有蓝图的房子。房子也许能盖起来，但大概率歪歪扭扭，而且你说不清它为什么长成这样。

这个道理在AI出现之前就成立。瀑布模型把“先设计后编码”制度化，敏捷方法又提醒我们不要把设计冻结成厚重的交付物。SDD吸收了前者“先想清楚”的纪律，同时继承了后者“保持迭代”的灵活性，而不是回到一次性、不可变的瀑布模型。

差异在于，AI时代的规范不再只是给人看的参考材料，而是给Agent执行的输入。你没有写下来的意图，AI不会知道；你没有明确的约束，AI不会遵守。规范文档从“可选的说明”变成“必要的工程接口”。

Covey说得对：所有事物都经过两次创造。SDD只是让这个道理在AI时代不再是可选项。

这本书讲什么

本书系统讲解SDD的完整方法论与工程实践。全书共10章，按“为什么→怎么做→怎么做好”三个阶段展开。

第一阶段，认识问题（第1章和第2章）。第1章通过一个真实项目的“三天崩塌”故事，揭示Vibe Coding的本质缺陷；第2章确立SDD的核心思想框架——规范是第一手工件，代码是规范的衍生物。

第二阶段，掌握方法（第3章至第7章）。第3章梳理SDD工具链全景，先介绍OpenSpec、Spec-Kit、BMAD等规范框架，再通过四层能力模型说明原子技能、上下文持久化、规范生成框架与完整方法论之间的关系。第4章至第7章展示实战，分别涉及需求分析与规范撰写（第4章）、架构设计与技术决策（第5章）、任务拆解与执行编排（第6章），以及验证、迭代与演进（第7章）。

第三阶段，深入应用（第8章至第10章）。第8章讨论SDD与5种Agent设计模式的结构性融合，并进一步说明Harness Engineering如何将规范转化为上下文、工具、权限、验证与反馈回路。第9章介绍团队中的SDD实践。第10章思考SDD的边界、未来与哲学意涵。

一个正在达成的共识

2025年下半年以来，开源社区、AI IDE（Integrated Development Environment，集成开发环境）、代码平台和Agent工具团队开始从不同方向趋近同一个判断：当代码生成成本越来越低，真正稀缺的是清晰、可执行、可验证的意图。

有的工具从规范生成切入，有的从项目记忆、技能、子智能体或工作流编排切入，还有的把重点放在Harness Engineering上，即围绕模型构建上下文、工具、权限、验证与反馈回路。名字不同，入口不同，但都在试图回答同一个工程问题：怎样让AI在明确的边界内可靠地完成软件开发任务。

本书不会具体介绍某个工具的按钮与命令——那些内容适合放在更新更快的电子书“加餐”里。这里要讨论的是更稳定的部分：规范如何承载意图，如何约束执行，如何让人类判断与AI能力形成可复用的协作结构。

本书适合谁阅读

本书适合以下读者阅读。

• 正在使用AI辅助编写代码但经常返工的开发者：本书从第1章就直面你的痛点，随后用9章内容给出系统性解法。

• 想在团队中推广AI辅助编程的技术负责人：第9章专门介绍团队的SDD实践，内容涉及从渐进式引入到度量指标，从规范治理到工具选型。

• 对Agent设计模式感兴趣的架构师：第8章深入分析SDD与5种Agent设计模式的结构性融合，并说明Harness Engineering为何会成为Agent工业化的重要方向。

• 已在使用OpenSpec、Spec-Kit、Kiro、BMAD、Superpowers等工具，但想理解底层方法论的开发者：本书不是工具教程，而是方法论讲解。工具会更新换代，方法论是稳定的。

在AI辅助编程进入工程深水区后，真正稀缺的能力是懂架构、会设计，能把需求、架构与验收边界定义清楚。

proposal.md回答“要解决什么问题”，design.md回答“用什么结构解决”，tasks.md回答“按什么顺序交付”。这三份规范构成了本书的主线。

从Vibe Coding到SDD的核心就是从“先试试看”转向“先定义清楚再执行”。

这个转变，不会因为某个工具更新而过时。

黄佳

2026年5月

资源与支持

资源获取

本书提供如下资源：

• 书中源代码文件；

• 书中图片文件；

• 本书思维导图；

• 异步社区7天VIP会员。

要获得以上资源，您可以扫描下方二维码，根据指引领取。

提交勘误信息

作者和编辑尽最大努力来确保书中内容的准确性，但难免会存在疏漏。欢迎您将发现的问题反馈给我们，帮助我们提升图书的质量。

当您发现错误时，请登录异步社区（https://www.epubit.com），按书名搜索，进入本书页面，点击“发表勘误”，输入勘误信息，点击“提交勘误”按钮即可（见下页图）。本书的作者和编辑会对您提交的勘误信息进行审核，确认并接受后，您将获赠异步社区的100积分。积分可用于在异步社区兑换优惠券、样书或奖品。

与我们联系

我们的联系邮箱是contact@epubit.com.cn。

如果您对本书有任何疑问或建议，请您发邮件给我们，并在邮件标题中注明本书书名，以便我们更高效地做出反馈。

如果您有兴趣出版图书、录制教学视频，或者参与图书翻译、技术审校等工作，可以发邮件给我们。

如果您所在的学校、培训机构或企业，想批量购买本书或异步社区出版的其他图书，也可以发邮件给我们。

如果您在网上发现有针对异步社区出品图书的各种形式的盗版行为，包括对图书全部或部分内容的非授权传播，请您将怀疑有侵权行为的链接通过邮件发送给我们。您的这一举动是对作译者权益的保护，也是我们持续为您提供有价值的内容的动力之源。

关于异步社区和异步图书

“异步社区”是由人民邮电出版社创办的IT专业图书社区，于2015年8月上线运营，致力于优质内容的出版和分享，为读者提供高品质的学习内容，为作译者提供专业的出版服务，实现作译者与读者在线交流互动，以及传统出版与数字出版的融合发展。

“异步图书”是异步社区策划出版的精品IT图书品牌，依托于人民邮电出版社在计算机图书领域四十余年的发展与积淀。异步图书面向各行业的信息技术用户。

第1章　空中楼阁：Vibe Coding的甜蜜与陷阱

没有图纸的装修队施工——干得快，返工更快（见图1-1）。

图1-1　没有图纸的装修队在施工

小冰最近接手了一个紧急项目。

周五下午，客户突然提出一项需求：在三天内开发一个内部知识库搜索工具。该工具不仅要对接飞书文档，还需要支持语义搜索。小雪让小冰加班，并定于下周一向全公司演示。鉴于时间紧、任务重，小冰决定全程利用Claude Code来完成这项工作。

第一天的进展异常顺利。小冰仅在Claude中描述了需求，Claude便迅速生成了代码——涵盖FastAPI后端、向量数据库接入以及飞书文档API（Application Programming Interface，应用程序接口）对接等模块。不到4h，核心功能便可以运行。小冰心中暗喜，深感以往需要耗时一周的工作，如今一天即可完成。

第二天，工作重心转向功能扩展。小冰指挥Claude增设用户认证、搜索结果排序和缓存功能。然而，到了下午，问题接踵而至：Claude生成的认证模块采用了与前期代码截然不同的错误处理风格；搜索排序逻辑与前一天构建的数据结构无法匹配；缓存模块更是引入了项目原本未包含的新依赖。为此，小冰不得不耗费3h手动修复这些不一致之处。

第三天正值周日。小冰打开计算机，发现昨天的对话记录找不到了——原来她此前关闭了终端窗口。她试图向Claude复述昨天的决策：“我们昨天决定采用Redis作为缓存方案，而不是本地文件缓存。”Claude礼貌地回复：“好的，我来帮你实现Redis缓存。”然而，Claude生成的代码采用了与昨天截然不同的接口设计。无奈之下，小冰又耗费了2h才将新旧代码重新对齐。

周一的演示如期举行，系统功能确实能够运行。小雪满意地点点头，随后问了一句让小冰脊背发凉的话：“不错，下周我们要加上权限管理和多租户支持。你把设计文档发给我看看。”

设计文档？哪里来的设计文档？小冰在使用Claude的过程中没有撰写设计文档（见图1-2）。

图1-2　小冰在使用Claude的过程中没有撰写设计文档

小冰翻遍了最近三天的聊天记录，却发现它们散落在七八个独立的对话窗口中，部分窗口甚至因为已经关闭而彻底丢失。她试图回忆当初的技术选型逻辑：为什么选用这个向量数据库而不是那个？为什么认证采用 JWT而不是Session？缓存策略又是如何制定的？然而，这些关键决策都是在对话过程中即时生成的，从未被正式记录。

代码还在，但代码背后的“为什么”消失了。

小冰将最近三天的开发经历梳理成一张图（见图1-3），越看心里越发凉。

图1-3　小冰的三天开发经历：从甜蜜期到崩塌

小冰将这段开发经历向咖哥倾诉。咖哥听完沉默数秒，随后缓缓说道：“你这三天所做的事情，有个专门的名称——Vibe Coding。”

1.1　什么是Vibe Coding

Vibe Coding这一概念，由Andrej Karpathy于2025年初提出。他用这一略带自嘲的说法描述了一种日益盛行的编程范式：开发者坐在AI辅助编程工具前，仅凭自然语言描述意图，由AI即时生成代码，开发者只需要审视结果——如果能运行便接受，如果报错则重新描述需求。在这种模式下，需求在对话中传递，架构在脑海中构建，决策在聊天窗口中做出。一切都发生在“当下”，唯独缺少了最关键的一步：将这些思维火花与决策逻辑，持久化为正式的工程制品。

“Vibe”一词的妙处在于，它精准捕捉了这种工作方式的本质——凭感觉。

• 凭感觉描述需求：摒弃了严谨的需求文档，仅在对话中勾勒出一个模糊的轮廓。

• 凭感觉做出决策：框架设计和技术选型未经过深思熟虑的论证，而是遵从AI的推荐，或随对话的流向“走到哪算哪”。

• 凭感觉验收代码：验收标准简化为单一的“能否运行”，而没有追问“为什么选择这个方案”“是否存在更优解”或“潜在的风险在哪里”。

这绝非某个人的个人习惯，而是AI辅助编程工具的交互方式天然诱导的行为模式。

不妨试想，当你打开Claude Code或Cursor时，映入眼帘的是一个对话窗口。这种界面的设计语言在人的潜意识里暗示着“聊天”——你抛出一句，AI回复一段代码，经过几轮交互便能解决问题。

这与打开Word或Notion时面对的空白文档所暗示的行为模式截然不同——空白文档暗示的是“写作”，即有结构、有章法地组织语言表述思想，严谨地推敲措辞。然而，对话窗口通常没有标题栏，没有大纲视图，缺乏完善的版本历史管理。它优化的是即时性和流畅性，而非持久性和结构性。

咖哥用一个比喻来阐释这一问题。

“想象你在装修新房，找了一支特别能干的装修队。你说‘我想要一个开放式厨房’，他们二话不说，立刻开始砸墙；你说‘客厅想要暖色调’，油漆师傅马上开始刷漆。效率固然惊人，一天下来，房子已经有模有样了。

“但是，问题很快便出现了。你发现厨房的管道与客厅的地暖冲突，因为没人绘制过全屋的管线图；你发现卧室的开关位置有误，因为没人进行过电路设计；你发现卫生间的下水管道对不上，因为拆墙时没人看过建筑图纸。

“结果如何？干得快，返工更快。最终耗费的时间和成本，往往远超老老实实先画图纸，再按图纸施工的传统模式。”

这就是Vibe Coding的本质：它用即兴对话取代了系统设计和规范。人类给AI的反馈是即时的，交互性很强，但往往不是全面的思考。这种模式在短期内营造出一种“效率惊人”的假象，但长期来看，它实际上是以极高的利息积累一种新型的技术债务。图1-4将这一对比呈现得更为直观。

图1-4　装修比喻：没有图纸的装修队施工与按图施工

1.2　甜蜜的陷阱：5个致命问题

Vibe Coding的危险之处，恰恰在于它提供的短期正反馈是真实且强烈的。AI确实能在几分钟内生成数百行可运行的代码；确实能协助你将一个模糊的想法迅速转化为原型；速度也确实比从零开始手写快了数倍。这种即时的成就感极易令人上瘾——它就像信用卡消费带来的快感，刷卡时消费的爽快是真实的，但还款日的痛苦同样真实且残酷。

技术债务的问题终究会显现，它们通常以5个系统性问题的形式呈现。

1.2.1　问题一，需求蒸发

在小冰构建知识库搜索工具的三天里，她至少做出了20个决策：选用哪种向量数据库？API是否需要分页？搜索结果按什么规则排序？缓存设置多久过期？错误码如何定义？……这些至关重要的决策散落在七八个对话窗口的数百条消息中——有些窗口早已关闭，有些对话已经被上下文压缩“吞噬”。

一周后，当CTO（Chief Technology icer，首席技术官）询问“为什么选择这种向量数据库”时，小冰却哑口无言。并非她遗忘了细节，而是那个决策当初并未被正式记录——它仅仅是在对话中自然达成的。Claude推荐了一个选项，小冰认为合理便直接采纳。因此，没有任何文档记录下这一决策的上下文、候选方案以及取舍理由。

这就是需求蒸发——决策虽已做出，却未留下任何痕迹。对话本质上是一种线性且转瞬即逝的交流方式，天生不适合承载那些需要持久化保存的工程制品。试图通过对话来做出设计决策，无异于用铅笔在沙滩上编写合同——落笔时清晰可见，浪潮一旦袭来便踪迹全无。

1.2.2　问题二，上下文漂移

小冰在第二天遇到的问题——认证模块风格不一、数据结构错位，实则源于一个更根本的限制：AI的上下文窗口存在容量限制。

尽管Claude的上下文窗口容量高达20万Token，看似充裕，实则捉襟见肘。对一个中等规模的项目而言，仅核心代码文件的总量便可能轻易突破这一上限。更重要的是，对话交互本身也在不断消耗上下文空间——你与Claude的每一轮问答，都在将早期信息向窗口边缘推挤。一旦对话累积到一定长度，那些重要的早期决策（如“我们决定所有错误处理均采用Result类型”），便会不知不觉被截断或压缩，最终导致模型“遗忘”。

其后果便是上下文漂移，由于早期关键信息已溢出模型的“工作记忆”，Claude在对话后半段生成的决策，可能与前半段的决策大相径庭。开发者常常难以察觉这种潜移默化的漂移——因为单独看每一段生成的代码似乎都是逻辑自洽的，但将它们整合在一起时，便会暴露出深层的矛盾与冲突。图1-5直观地展示了这一过程。

图1-5　上下文漂移：早期决策被挤出对话窗口后，AI的后续决策与之矛盾

1.2.3　问题三，不可审查

当CTO提出“把设计文档发给我看看”时，他实际上是在向小冰追问一个更深层的问题：我该如何确信这个系统的设计架构是合理且可靠的？

在传统软件工程中，代码审查（Code Review）能够行之有效的关键，在于审查员可以洞察完整的设计意图——这得益于拉取请求（Pull Request，PR）描述、设计文档以及架构决策记录（Architecture Decision Record，ADR）的完备支撑。审查员的职责并非局限于验证代码的正确性，还在于判断技术选型的方向是否正确：当前的架构选择是否合理，引入的依赖是否必要，接口设计是否会给未来的扩展埋下隐患。

然而，在Vibe Coding模式下，这些设计意图却被禁锢在对话记录之中——前提是这些对话记录尚未因上下文溢出而丢失。审查员面对的是一堆“从天而降”的代码，既不清楚其生成逻辑，也不了解其做过哪些取舍，更难以判断是否充分评估过替代方案。这种信息断层，迫使代码审查退化为纯粹的语法检查，从而丧失其核心价值：对设计决策的质疑与讨论。

1.2.4　问题四，不可复现

假设小冰负责的知识库搜索工具在生产环境中突发bug——搜索结果排序异常。为了修复这个bug，她需要追溯当初排序逻辑的设计脉络。然而，那段代码竟是Claude在某个早已关闭的对话窗口中，根据小冰的口头描述即时生成的，原始交互上下文已无从寻觅。此刻，小冰只能看到代码“是什么”（What），却看不到“为什么”（Why）。

这种不可复现性在个人项目中或许只是维护不便，但在团队协作中则是一场工程灾难。当原作者离职或调岗时，继任者面对的是一堆没有任何设计背景的代码——它就像一座缺失建筑图纸的大楼：你虽然能看到外墙和房间，却不知道哪面墙是承重墙、哪些管道埋在地下。在这种情况下，任何一处看似微小的改动都可能牵一发而动全身，而开发者却无法预判改动会引发哪些问题。

1.2.5　问题五，不可维护

1.2.1小节至1.2.4小节所讨论的4个问题，最终汇聚成一个核心问题——不可维护。

在软件系统的全生命周期中，维护阶段的成本往往占总成本的60%~80%。代码一旦交付，便会被无数次阅读、修改、扩展与重构。若编写这段代码时的设计意图未能被记录，每一次修改都将演变为艰难的“数字考古”——维护者被迫从晦涩的代码逻辑中反推原始意图，猜测当初为何做出这样的抉择。这一过程不仅极度耗时，更易导致判断失误。

Vibe Coding产出的代码，恰似一位缺失完整病历的患者——医生虽能观测当下症状，却对患者的既往病史、用药记录、手术方案等一无所知。在这种信息不对称的情况下，每一次治疗都无异于盲人摸象。

咖哥在白板上勾勒出一张全景图，将这5个问题串联成一条因果链，如图1-6所示。

图1-6　5个致命问题形成的因果链

小雪听完咖哥对这5个致命问题的剖析，陷入短暂沉默。片刻后，她缓缓开口：“这么看来，Vibe Coding的问题并不在于AI生成的代码质量差，而是整个开发过程缺少了一种……结构？”

咖哥指了指她，说道：“你说到了关键词——结构。Vibe Coding欠缺的从来不是代码生成能力，而是一套严谨的方法论。AI可以生成漂亮的代码，但好代码不等于好软件。真正优秀的软件，需要包含清晰的需求、合理的设计、可追溯的决策以及可验证的交付。这些支撑软件生命周期的底层架构，光靠零散的对话是撑不起来的。”

1.3　案例：一个“AI写的项目”为何没人敢改

小冰的故事并非虚构，类似的情况正在无数开发团队中真实上演。

2025年下半年，一位开发者在技术社区分享了一段亲身经历。他的同事利用AI，严格遵循SDD模式，为一套存量系统设计了功能迭代方案。该方案是，先撰写需求规范，再进行架构设计，随后拆解任务，最后由AI生成代码。方案顺利通过审查，代码开发完成并成功上线。

然而，系统上线后出现了严重问题：用户端操作超过7s仍无法获得响应，项目最终“爆雷”。

问题究竟出在哪里？事后复盘发现，AI生成的代码在功能逻辑上完全正确，却在性能设计上踏入了一个陷阱：它在一条高频调用的路径中，嵌入了同步的远程API调用，而该API在生产环境中的响应时间竟是测试环境的5倍之多。究其根源，在于需求规范文档的缺失——文档中仅明确了功能需求（如“用户提交操作后应收到结果确认”），却遗漏了关键的性能需求（如“响应时间应控制在2s以内”）。

这一案例揭示了一个微妙但重要的教训：SDD并非万能药，但缺乏规范驱动的开发模式，甚至连问题诊断都举步维艰。图1-7直观对比了Vibe Coding与SDD两种模式下的问题回溯路径。

当这位开发者回溯问题时，他至少还能找到最初的设计文档，从中发现规范中缺失的性能约束，从而明确改进方向——补充非功能需求规范并加入性能预算。相对地，如果整个开发过程完全依赖Vibe Coding模式，那么连这一步都无法实现。因为在这种模式下，“当初为什么这么设计”的关键线索根本无从寻觅。

图1-7　两种模式下的问题回溯对比

听完这个案例，小冰提出了一个好问题：“既然Vibe Coding存在隐患，那么回归传统瀑布模型，撰写详尽的文档行不行？”

咖哥摇了摇头，说道：“行不通。这正是我接下来要阐述的核心——为什么答案既不是Vibe Coding模式，也不是瀑布模型，而是一条全新的路径。”

1.4　三次范式迁移：从瀑布模型、敏捷开发到SDD模式

软件开发方法论的演进，本质上是人类对“如何在不确定性中交付可靠软件”这一永恒命题的持续探索与回应。每一次技术环境的重大变化，都会催生软件开发方法论的范式迁移。而AI辅助编程技术的出现，正在催生第三次范式迁移。图1-8展示了软件开发方法论的演进。

图1-8　软件开发方法论的演进

1.4.1　第一代，瀑布模型——有规范，无迭代

1970年，Winston Royce提出了著名的“瀑布模型”。该模型的核心思想朴素但不失严谨：先明确要做什么（需求），再规划怎么做（设计），随后编码实现，最后测试验收。各阶段严格按照顺序执行，前一阶段完成后方能进入下一阶段，就像瀑布一样自上而下、单向流动。

瀑布模型的优点在于其结构清晰，每个阶段均产出明确的交付物——从需求规格说明书、概要设计文档、详细设计文档到测试计划。这些文档构成了一条完整的决策链条，确保了任何人在任何时候都能回溯“当初为什么这样设计”，为软件的可维护性奠定了基础。

然而，瀑布模型存在一个致命缺陷，即它建立在需求不变的假设上。在真实的软件工程中，需求往往具有高度的不确定性，几乎不可能在一开始就完全明确。当团队耗费数月完成代码并交付测试后，如果客户反馈“这不是我想要的”，整个项目便可能需要推倒重来。Winston Royce后来也承认，纯粹的瀑布模型在实际操作中几乎不可行。

如果以建筑图纸来比喻，瀑布模型就像在动工之前，耗费半年绘制一套极其详尽的图纸——每根管道、每个开关都标注得十分清晰。然而，如果图纸最终交付时，甲方突然改口：“我改变主意了，不要开放式厨房。”那么这张图纸便成了废纸。

1.4.2　第二代，敏捷开发——有迭代，轻规范

2001年，17位软件专家在美国犹他州的雪鸟滑雪胜地共同提出了《敏捷宣言》。该宣言的核心主张是：

可工作的软件，胜过详尽的文档。

这一理念深刻改变了软件行业。以Scrum、XP和Kanban为代表的敏捷方法论，用“短周期迭代”取代了瀑布模型的“一步到位”。在这种模式下，团队通常每两周交付一个可工作的版本，并根据反馈调整改进方向。此外，需求不需要在项目初期就完全明确，而是可以在迭代中逐步澄清。

敏捷开发虽然解决了瀑布模型的核心问题，但也带来了一个新的问题——在“轻文档”理念的号召下，很多团队走向了另一个极端，即完全放弃文档撰写。具体表现为：设计决策仅停留在口头讨论，需求变更仅在Jira中以一句话描述，架构选择处于“大家心照不宣”的状态却从未被正式记录。

这种模式在人类开发者主导的时代尚可勉强运转——毕竟代码由人编写，开发者自己清楚代码背后的逻辑，遇到问题也可面对面直接沟通。然而，当AI成为代码的主要生产者之后，这套基于“默契”的协作机制彻底崩塌了。AI无法参与团队的每日站会，无法参加架构讨论，更不可能了解你上周在白板前做出的决策，它所能掌握的，往往仅限于当前对话窗口内的信息。

如果用建筑装修来比喻，敏捷开发好比边盖边改的小型装修，每周与甲方确认方向，随即开展两周的施工。这种方式效率高，适应性强。但试想一下，如果施工队不是固定班组，而是每天更换一批新工人呢？那些缺乏图纸的口头约定，在人员发生更替时就会全部失效。而目前的AI，恰恰就是那支“每天都换”的施工队——每次新的对话请求往往都是一个全新的AI实例，导致其对之前的决策一无所知。

1.4.3　第三代，SDD模式——有迭代，有规范

2025年，随着AI辅助编程工具的大规模普及，一种全新的软件开发方法论开始浮现。它并未经历某个正式的“宣言时刻”，而是由众多独立的实践者不约而同地孕育而成。其中既有OpenSpec框架的设计者、Spec-Kit工具的作者、BMAD方法的提出者，也有无数在与AI协作过程中踩过坑的开发者。

这种方法论被称为规范驱动开发（Specif ication-Driven Development，SDD）。该方法论的核心思想可以用一句话概括：规范是第一手工件，代码是规范的衍生物。

这句话的每个词语都极具分量。“第一手工件”意味着在SDD的工作流中，人类工程师的核心产出并非代码，而是规范，包括需求规范、架构设计文档、接口契约以及任务拆解清单等。这些结构化的文档才是人类智慧的真正载体。“代码是规范的衍生物”意味着代码是依据规范生成的，恰如建筑是依照图纸建造而成。基于同一份图纸，可以选用不同材料建造房屋；同理，依据同一份规范，也能利用不同的技术栈生成代码。只要图纸不变，房子的“骨架”便始终如一。

SDD模式并非对瀑布模型的回归。它保留了敏捷开发最重要的“遗产”——迭代与拥抱变化，同时弥补了敏捷开发中常被忽视的一环：将设计决策从非正式的对话记录中提取出来，固化为正式且可版本控制的规范文档。

图1-9展示了SDD六阶段工作流的全景概览，对各个阶段的详细介绍参见第2章。

图1-9　SDD六阶段工作流全景概览

表1-1从多个维度对比了三代软件开发方法论的差异。

表1-1　三代软件开发方法论的差异

小雪看完表1-1后，指着“第一手工件”那一列说道：“SDD模式的核心迁移在于从‘代码即产出’转变为‘规范是产出，代码仅是副产品’。”

“没错。”咖哥点了点头，“而且注意看‘代码生产者’这一列，前两代方法论都基于‘代码由人编写’这一假设。当这个假设被打破，代码的编写者变成AI时，整个方法论的根基就需要重新设计。而SDD模式，正是重新设计的产物。”

“但这不就意味着……”小冰犹豫了一下说道，“撰写规范成了开发者最重要的工作？”

“是的。”咖哥看着她说道，“在AI时代，能写出好规范的工程师，比能写出好代码的工程师更稀缺。毕竟，代码可以由AI生成，但撰写规范——那个将模糊需求转化为精确、可执行工程制品的过程——目前仍只有人类能够胜任。”

本章小结

本章以小冰接手的一个紧急项目为切入点，深入剖析了当前AI辅助编程的主流方式——Vibe Coding——的本质及其潜在代价。

Vibe Coding并非个别开发者的习惯偏差，而是由对话式AI辅助编程工具天然诱导出的行为模式。它虽然能在短期内带来显著的效率提升，但同时在5个维度上悄然积累技术债务：需求蒸发（决策痕迹丢失）、上下文漂移（AI的前后决策不一致）、不可审查（设计意图变得不可见）、不可复现（决策背后的“为什么”无法回溯）、不可维护（修改代码如同拆一座没有图纸的房子）。

究其根本，这5个致命问题的症结同源：用即时对话取代了系统设计与规范。

图1-10展示了主流软件开发方法论与迭代速度/开发效率、规范程度之间的关系。

图1-10　主流软件开发方法论与迭代速度/开发效率、规范程度之间的关系

瀑布模型确立了规范，却缺失了迭代；敏捷开发引入了迭代，却轻视了规范；而Vibe Coding模式则走向了另一个极端——既没有规范可言，也称不上真正的迭代。SDD模式试图找到一个平衡点：保留敏捷的迭代节奏，重塑被遗忘的工程规范，同时摒弃烦冗，转而采用更轻量、更结构化的方式。它不再依赖数百页的需求规格说明书，而是通过proposal.md、design.md、tasks.md等文档，构建出“恰好足以驱动AI执行”的规范。

从第2章开始，我们将深入剖析SDD的核心思想与工作流，亲眼见证“规范是第一手工件，代码是规范的衍生物”这一理念在实践中的具体呈现。

思考题

1.回顾你最近一次使用AI辅助编程工具（如Claude Code、Cursor、GitHub Copilot 等）完成的项目或功能模块：在开发过程中，你做出了哪些设计决策？这些决策是否有相应记录？如果有新同事接手这段代码，他能否追溯并理解这么设计背后的考量？

2.本章归纳了Vibe Coding的5个致命问题：需求蒸发、上下文漂移、不可审查、不可复现和不可维护。结合你的实际工作经历思考：哪一个问题最先显现？目前你采用什么方式应对——依赖个人记忆、依赖代码注释，还是已建立起某种文档化实践？

3.咖哥提出一个观点：在AI时代，能写出好规范的工程师，比能写出好代码的工程师更稀缺。你是否认同这一判断？如果认同，这对你个人的职业规划有何启示？如果不认同，你认为AI时代最稀缺的工程师应具备何种核心能力？