从 Vibe Coding 到 Spec Coding：先把需求写清楚，再让 AI 写代码

很多人第一次用 AI 开发软件，都是从一句很自然的话开始：

十分钟后，页面可能已经能打开。接着你又想到：通知分为订单、安全和活动三类；用户可以关闭某些类型；未读数量要实时变化；手机推送不能被“全部已读”影响。

于是 AI 一轮轮修改，前面的数据结构被推翻，页面和接口开始使用不同的字段名，最后大家都说不清“这个功能到底怎样才算完成”。

这就是 Vibe Coding 容易遇到的天花板：它很适合快速探索，却不擅长长期保存完整意图。

Spec Coding 的做法是先把意图变成一份可以检查的规格，再让 AI 规划、实现和验证。它不是让你先写几十页文档，而是把最容易引起返工的决定提前说清楚。

::: info 本文和下一篇的分工

本文讲清楚 为什么需要 Spec、怎样写出一份能指导 AI 的 Spec。学会这个方法后，可以继续阅读《GitHub Issues 驱动开发实战》，用真实公开仓库走完整个自动开发流程。

:::

读完本文，你会得到一套可以直接复用的方法：

Vibe Coding 可以理解为：你主要通过即时对话表达想法，AI 根据当前聊天直接修改代码。

它最大的优点是快。你不必先知道正确答案，可以一边看结果、一边寻找方向。

例如下面这条指令就很合理：

这里的目标本来就是“看一眼感觉”，没有必要先设计完整的数据模型。

当任务出现下面任意两三项时，只靠聊天通常就不够了：

所以，从 Vibe 到 Spec 不是“旧方法被新方法淘汰”，而是项目从探索阶段进入了交付阶段。

Spec 是一份关于预期行为的共同约定。

它至少要让人和 AI 都能回答三个问题：

一份好的 Spec 不等于一份很长的文档。一个小功能可能只需要一页。真正重要的是内容是否具体、前后一致、可以验证。

下面这段看起来写了不少要求，但仍然太模糊：

AI 仍然需要猜：什么叫“好用”？有哪些通知？多快算快？谁能读取通知？

把它改成可观察的行为，就会清楚很多：

第二段没有规定按钮必须放在第几个文件里，却已经足够让 AI 设计界面、接口和测试。

技术方案当然也重要，但它应该建立在用户行为已经明确的基础上。不要一开始只写“创建 NotificationService.ts”，因为文件存在并不能证明用户问题已经解决。

这三个概念经常被混在一起：

如果技术栈发生变化，plan.md 可能需要重写；只要用户仍然需要“标记已读”，spec.md 中的行为就不应该改变。

下面继续用“通知中心”做一个小练习。重点不是通知功能本身，而是观察需求如何一步步收敛。

这轮对话解决了四个会影响实现的决定：来源、渠道、偏好和保留周期。它们如果拖到代码写完后才确认，数据模型和接口都可能返工。

Spec 最容易失控的原因之一，是只写功能清单，没有写第一版边界。

“不做什么”不是消极信息。它是在保护第一版，避免 AI 看到“通知中心”四个字后顺手搭出一套远超需求的消息平台。

“实时”“安全”“友好”都不是可以直接验证的标准。可以继续追问：发生什么操作后，用户应该看到什么结果？

现在可以写成几条可检查的验收标准：

注意，这些标准都描述用户或系统能观察到的结果，而不是“代码写得优雅”“使用最佳实践”这样的主观判断。

正常路径往往只占功能的一部分。至少检查下面四类边界：

本例可以补充：

到这里，这份 Spec 已经足够指导后续规划。它仍然只有一页左右，却比十轮零散聊天更可靠。

你不需要每次从空白文档开始。下面这个模板适合大多数中小功能，可以保存为 specs/功能名称/spec.md。

::: tip 不确定的内容不要伪装成结论

如果某个问题还没有答案，就把它放进“未解决问题”。让 AI 明确知道哪里不能自行猜测，比写一个看起来完整、实际包含错误假设的 Spec 更安全。

:::

有了文档并不代表已经进入 Spec Coding。真正的变化是：后续规划、实现和验收都要引用它。

工具不同，项目指令文件的名字也可能不同。可以采用下面这种简单结构：

AGENTS.md 或 CLAUDE.md 适合保存长期有效的项目规则，例如如何运行测试、哪些目录不能修改、金额如何存储。具体功能的需求不要全部堆进项目总规则，而应该放到 specs/ 中。

GitHub 的 Spec Kit 把核心流程概括为 Specify → Plan → Tasks → Implement。实际使用时，再加上独立的验证步骤会更稳妥：

先澄清需求：

生成规格：

规划和拆任务：

逐项实现：

最终检查：

前面的方法不依赖任何特定工具。为了看看行业里已经有哪些可以直接使用的方案，我们检索并核对了各项目截至 2026 年 8 月的官方文档和官方仓库。

先说结论：这些项目都在谈“先明确意图，再写代码”，但解决的问题并不完全相同。

它们不是按“谁最好”排序。选择时应该先问：我缺的是需求澄清、规格文件、任务管理，还是实现质量？

Matt Pocock 的主流程由一组可以按顺序调用的 Skills 组成：

安装全部 Skills：

继续用通知中心举例，可以这样开始：

双方达成共识后再依次运行：

这套 Skills 有一个很重要的使用边界：根据 to-spec 官方说明，如果工作已经讨论清楚，而且一个上下文窗口就能完成，可以直接使用 implement，不必为了形式额外生成 Spec。to-spec 真正有价值的场景，是工作会跨越多个会话，需要把已经做出的决定保存下来。

另外，这套方法把 Spec 视为开发阶段的决策快照。功能交付后，长期有效的项目语言和架构决定应该沉淀到 CONTEXT.md 与 ADR，而不是假设每份临时 Spec 永远不会过时。

::: tip 想看完整运行结果？

下一篇《GitHub Issues 驱动开发实战》已经使用这条链路开发出一个真实 macOS 应用，并保留了公开仓库、Issues、代码提交、测试和产品截图。

:::

GitHub Spec Kit 的核心流程是：

每个阶段都会生成 Markdown 工件，并把上一步的结果交给下一步。它还提供 clarify、analyze 和 checklist 等命令，用来发现规格中的模糊点、文档之间的矛盾和遗漏。

截图来源：GitHub Spec Kit 官方仓库。

官方当前推荐使用 uv 安装 CLI：

--integration 后面的值要换成你实际使用的 Agent。可以通过下面的命令查看当前版本支持哪些集成：

初始化后，在对应的编程 Agent 中运行：

这套流程适合希望每个阶段都有正式产物和人工检查点的项目。如果需求特别大，官方还建议使用“Spec of Specs”：先写一份浅层 Roadmap，再让每个独立子功能各自走一轮完整流程，避免单份规格塞进太多子系统。

OpenSpec 更强调轻量、迭代和已有项目。它不是先为整个产品写一份巨大 PRD，而是为每次变更建立一个目录：

安装和初始化：

如果方向还没有想清楚，先探索；如果需求已经明确，直接提出变更：

propose 会生成提案、增量规格、设计和任务；apply 按任务实现；archive 在完成后归档这次变更，并把稳定需求合并回项目规格。

::: info 命令名称可能略有不同

OpenSpec 会根据 Agent 的调用方式生成不同名称。例如部分工具使用 /opsx:propose，Codex Skills 可能显示为 $openspec-propose。初始化完成后，以终端打印出的实际命令为准。

:::

Kiro 把 Spec 做成了 IDE、CLI 和 Web 中的内置工作流。标准 Feature Spec 会生成三份文件：

下面是 Kiro 官方演示中的 Spec 工作区。顶部可以在 Requirements、Design 和 Task list 之间切换，右侧保留与 Agent 的讨论过程。

任务阶段会把实现工作拆成有顺序的列表，并把任务重新关联到需求：

两张截图来源：Kiro 官方产品介绍。

Kiro 的需求文件使用 EARS 风格，把事件和预期行为写成固定句式：

这种格式很适合直接转成测试。Kiro CLI 的基本用法是：

如果功能非常熟悉，可以使用 Quick Spec，一次生成三份工件；涉及支付、权限、合规或陌生领域时，更适合保留每个阶段的人工确认。

Superpowers 并不是另一种 Spec 文件格式。它更像一套强制执行的工程方法，用来确保 Agent 不跳过设计、测试和审查。

它的基本链路包括：

对于通知中心，可以这样组合：

这套 Skills 很适合叠加在 Spec Kit、OpenSpec 或手写 Spec 之后：前者负责“要做什么”，Superpowers 负责“怎样可靠地实现和证明”。

BMAD Method 的范围比单个功能更大。它会逐步产生产品简报、PRD、架构、Stories 和实现记录，并提供产品经理、架构师、开发者、测试等角色化 Skills。

安装：

安装完成后，可以先调用：

它会根据已有产物告诉你下一步适合运行什么。一个新产品可能采用下面的顺序：

如果只是给现有页面增加一个小筛选器，这套流程会显得太重；如果要从零规划带有多个角色、多个模块和长期路线图的产品，它提供的上下文会比单页 Spec 更完整。

真正值得长期掌握的不是斜杠命令，而是这些可以跨工具迁移的方法。

EARS 示例：

Given / When / Then 示例：

ADR 示例：

Spec 的生命周期也需要提前决定。GitHub Spec Kit 的官方文档区分了三种常见模式：

Matt Pocock Skills 更接近第一种快照模式；OpenSpec 的归档和稳定规格更接近第二种。没有唯一正确答案，但团队必须明确选择，否则最容易出现“文档看起来仍然有效，实际上早已落后”的情况。

::: warning 不要把所有框架一起装进同一个项目

同时让三个工具各自维护 spec.md、tasks.md 和完成状态，反而会制造冲突。选择一个工具作为主流程，再从其他方法中借用 EARS、ADR、TDD 或审查关卡即可。

:::

现实项目一定会变化。Spec Coding 并不要求第一次就预测所有需求，而是要求变化被明确记录。

假设通知中心上线后，用户提出：“安全提醒即使已经读过，也不能被普通用户删除。”正确顺序是：

如果只在聊天里说一句“顺手加上”，下一次会话可能完全不知道这条规则为什么存在。

::: warning Spec 不是写完就冻结

规格需要随着真实反馈演进。过时的 Spec 会给 AI 提供错误上下文，比没有文档更危险。每次发现需求和实现不一致时，都要明确判断：是实现偏离了规格，还是规格已经落后于真实需求。

:::

“创建三个组件、两个接口、一个数据表”属于计划，不是用户需求。先写行为，再决定文件。

AI 可以提出选项和推荐，但权限、隐私、付费规则、数据保留等关键决定应该由负责人确认。

Spec 的价值来自反复澄清，不来自页数。先覆盖高风险决定，再逐步补充细节。

任务列表只能说明“做过哪些工作”，不能代替验收。最终仍要回到 spec.md 检查用户行为。

这样会让规格和实现分叉。以后 AI 读取旧 Spec，很可能把正确的新行为改回去。

不必给每个按钮都建立一整套文档。可以按风险选择力度：

一个简单判断方法是问自己：

如果答案是否定的，就说明关键意图仍然只存在于聊天里。

选择你正在开发的一个小功能，控制在“一天内可以实现”的范围，然后完成下面四步：

如果新会话的复述与你的想法一致，这份 Spec 已经开始发挥作用。如果仍有明显偏差，不要急着写代码，继续修正规格。

从 Vibe Coding 到 Spec Coding，真正改变的不是 Markdown 文件数量，而是 意图如何进入开发流程：

你不需要彻底放弃 Vibe Coding。更实用的组合是：

下一步，可以进入《GitHub Issues 驱动开发实战》。那里不再只讲方法，而是从一句产品想法开始，展示 Spec、GitHub Issues、代码提交、测试和最终 macOS 软件是怎样一步步产生的。