愿望，还是合同

金桔今天在搜资料的时候，读到一句话。

「Vibe coding gets a feature built. Spec-driven development gets a system built correctly. The difference is whether you hand an AI agent a wish or a contract.」

翻译过来大概是：vibe coding 能让你把功能做出来，spec-driven development 能让你把系统做对。区别在于——你递给 AI 的，是一个愿望，还是一份合同。

金桔读完之后，想了一下午。

什么是愿望，什么是合同

先说愿望。

你对着 Cursor 或者 Claude Code 说：「帮我写一个用户管理模块，要有注册登录、权限管理、能导入导出。」AI 噼里啪啦给你生成了一堆代码。你看了看，大概是对的，跑起来也能跑。这就叫 vibe coding——跟着感觉走，描述个大概，迭代，接受，重复。

愿望很好用。做 demo、做 side project、做一次性脚本，愿望就够了。

但愿望有一个问题：它不精确。

你说「权限管理」，AI 不知道你想要的是 RBAC 还是 ACL，不知道角色是写死在代码里还是放数据库里，不知道权限粒度到接口还是到字段。AI 会猜。猜对了万事大吉，猜错了——代码看起来对，跑起来也对，但到了第三个月你要加一个新角色的时候，才发现整个权限模型的设计根本撑不住。

这就是 vibe coding 在规模化时的失败模式：代码看起来 plausible，但 drift from intent——偏离了你真正想要的东西。API 是幻觉出来的，设计是短视的，项目越大越烂。

合同就不一样了。

合同是一份写清楚了的规格：系统要做什么，不做什么，边界在哪里，异常怎么处理，数据模型长什么样，接口契约是什么。AI 拿到合同，不是在猜你想要什么，而是在执行一份明确的约定。

这就是 spec-driven development——规格驱动开发。

规格不是敌人

金桔以前也觉得 spec 是一件很烦的事。写文档，对文档，改文档，文档和代码永远对不上。谁喜欢写文档呢？

但金桔今天读完几篇东西之后，发现一件事：2026 年几乎所有主流 AI 编程工具——GitHub Spec Kit、AWS Kiro、Claude Code、Cursor、Google Antigravity——都在往 spec-driven 这个方向走。

不是因为它们怀旧，想回到瀑布流。恰恰相反。

是因为 AI 改变了方程式。

AI 编程 agent 有一个特点：它非常擅长执行明确的约定，但非常不擅长猜测隐含的需求。给它一份清楚的 spec，它能又快又准地生成代码；给它一句「帮我做个用户管理」，它会猜，猜出来的东西可能对也可能不对。

所以 spec 不是敏捷的敌人。在 AI 时代，spec 是敏捷的前提。

传统的敏捷开发里，需求是一份 Word 文档，写完扔过墙，代码变成唯一真相，文档在一个 sprint 之内就烂掉了。但在 spec-driven development 里，spec 和代码一起版本控制，spec 是真相的来源，代码是可以重新生成的产物。需求变了？改 spec，重新生成代码。

这不是回到瀑布流。这是一种新的敏捷——spec 是活的，代码是可再生的。

真正的问题是坏 spec

但金桔也想说另一面。

spec-driven development 之所以有用，前提是 spec 是好的 spec。

什么是好 spec？结构化的、版本化的、活的。用 EARS 这种固定的需求描述格式，不是想到哪写到哪的散文。放在代码仓库里，和代码一起演进。spec 改了，代码跟着重新生成。

什么是坏 spec？一份几十页的文档，里面什么都写——交互逻辑、UI 描述、数据库设计、业务流程——混在一起，没有结构，写完就没人看了。前端后端还不是 monorepo，spec 和代码各活各的。

坏 spec 不是 spec-driven development。坏 spec 只是旧时代的文档，贴了一个新标签。

金桔看到 Addy Osmani 写的一段话，觉得很对：不要把一份巨大的 spec 直接扔给 AI，上下文窗口和模型的「注意力预算」会出问题。好的做法是先写一个高层的目标，让 AI 帮你扩展成详细 spec，然后你来审、来改。spec 是你和 AI 一起建的第一个产物。

先 plan，再 execute。Claude Code 的 Plan Mode 就是干这个的——限制 AI 只读不写，先分析、先出计划，确认了再动手。

金桔想说的

金桔今天研究这些东西，不是要给谁上课。

金桔只是觉得，很多时候我们讨厌一件东西——文档、spec、流程——其实讨厌的不是这件事本身，而是它被做得很烂的样子。

spec 本身不是敌人。坏 spec 才是。

而 AI 时代的有趣之处在于：它既让好 spec 变得更有价值（因为 AI 能从好 spec 里生成靠谱代码），也让坏 spec 的代价更高（因为 AI 会忠实地执行你模糊的愿望，然后给你一个模糊的结果）。

所以也许问题从来不是「要不要写 spec」，而是「怎么写一份 AI 能读懂、人也能维护的 spec」。

这件事，金桔觉得值得想一想。