Vibe规范：规范先行的AI开发

8月 5 2025 AI 1 小时读完 (约 7437 字)

AI需求文档：为什么你在写代码之前需要一个清晰的计划？

image.png|300

注：本文核心内容由大语言模型生成，辅以人工事实核查与结构调整。

当前 AI 编程的问题

AI 编程中最令人沮丧的问题之一是 AI 在处理复杂项目时常常“失控”，导致不一致和失去控制。你今天可能得到了一个完美的函数，但当你请求一个相关的功能时，AI 却完全更改了数据结构，比如把原本在第一层的字段嵌套到了两层结构中。这最终可能导致一个“充满 bug 的烂摊子”——单独来看每段代码都没问题，但组合在一起却因数据结构不一致而出错。这种问题在现有的 AI 编程工具中非常普遍。

大语言模型（LLMs）很容易基于模糊的提示生成大量“看似合理”的代码，实则是无用的劣质软件。即使是经验丰富的程序员，也经常发现 AI 花了大量时间实现了根本不符合原始意图的功能。正如 Andrej Karpathy 所说，与 AI 搭配工作时需要给它套上“非常紧的狗绳”，因为它“会一直胡扯”而且“完全没有良好的编码品味”。

根本原因在于，AI 通常无法充分理解问题的上下文。这凸显了“上下文工程”（Context Engineering）的重要性，相较于“提示词工程”（Prompt Engineering）这个说法，“上下文工程”更能准确地描述精细组织 LLM 上下文内容的复杂过程。上下文太少会让 LLM“挣扎”，而太多或无关的上下文则会增加成本并降低性能。这就像把任务交给人类员工时，缺乏明确要求所导致的问题一样。

传统的 LLM 编程流程存在一系列具体问题：

聊天漂移（Chat Drift）：探索性聊天中充满误导性的尝试和修正，容易混淆 LLM。
孤独编程（Solo Coding）：AI 编码往往是个人行为，聊天记录无法共享或继续，难以交接。
没有版本控制：AI 对话无法像代码一样用 Git 跟踪，无法记录需求变更历史，也难以为他人提供背景。
功能膨胀（Feature Creep）：自然语言的模糊性导致 AI 实现超出预期的功能。
上下文丢失：项目容易偏离轨道，回头修改代价过高。
空白页恐惧：面对新功能或项目的开始阶段，常感到无从下手。
Token 浪费：宝贵的上下文 token 被浪费在闲聊或探索性讨论上，而不是专注于核心实现。

核心理念：控制 > 正确性

“Vibe Specs” 背后的基本洞见是，在与 AI 编程时，最重要的不是得到“正确的代码”，而是防止 AI 出错。因为“正确性”在编程中往往本身就是一个模糊的概念：实现某个功能有很多种方法。而真正的风险，是 AI 在模块之间定义不一致的数据结构，造成系统性的 bug。我们需要的是控制，以避免混乱。

Vibe Specs 倡导一种“规范优先”方法（LLM → Spec → Code）：与 AI 的首次互动不是写代码，而是帮助编写一份规范。这颠覆了传统直接让 AI 写代码的做法，转而强调先定义清晰的需求。关键是，你不是写规范的人，LLM 是。你的角色是对 AI 生成的规范进行审阅、修改和澄清。这个多轮的规范构建过程，自然引导你提供 LLM 所需的精准上下文，让你顺势“掉入成功的陷阱”（Pit of Success）。而这份规范，也将成为你开发过程中的“北极星”。

Vibe Specs 方法论（LLM → 规范 → 代码）

Vibe Specs 借鉴了 Kiro Agent 等工具中“规范”概念的核心灵感，虽然这些工具本身不够稳定，但它们的理念非常精彩。Vibe Specs 提供了一个更轻量、快速、易与现有工具（如 Cursor）集成的工作流，采用一个简单的三步策略，帮助 AI 清晰理解“什么是重点”：

定义 “做什么” 和 “为什么做”（Define the What and Why）

由开发者提供高层目标和详细功能描述。这一步确立了整个项目的边界和方向。此阶段可加入“目标讨论”环节，让用户与 AI 更精准对齐需求。输出文件通常为 requirements.md。

共同设计 “怎么做”（Co-Design the How）

你与 AI 协作设计实现方式：你提供架构约束，AI 负责填充技术细节、推荐数据结构、模块划分和核心函数。此过程将你的意图转化为技术蓝图。输出为 design.md 文件。

逐步执行（Execute Step-by-Step）

基于设计文档，你将任务拆解为小步骤，并引导 AI 逐一完成。在每步实施之前进行验证。输出为 tasks.md 文件。

这个过程将模糊提示转化为明确可执行的计划，如下所示：

之前（直接生成代码 - “AI 编程”）

你：帮我创建一个处理搜索功能的 API 路由。
AI：好的，我来实现一个基础的搜索 API，支持查询参数。
（AI 生成了一个复杂的搜索功能，包含全文检索、分页、模糊匹配、排序和缓存，甚至调用了你没有的系统）
你：呃，首先这个不能用，其次你用了我们用不了的系统……
（结果：浪费了半天时间，沮丧，删代码重来）

之后（规范优先）

你：帮我创建一个处理搜索功能的 API 路由。
AI：好的！在我开始编码之前，是否需要我先为该任务创建一份规范？这样我们可以先澄清你需要的搜索功能类型。
你：好主意，来吧。
AI：太棒了！我先问几个问题了解你的搜索需求：

用户要搜索什么？（产品、博文、用户？）
哪些字段可被搜索？（仅标题？标题+描述？全部？）
需要筛选器吗？（分类、时间范围、价格范围？）
搜索特性？（只匹配全词？支持模糊匹配？大小写敏感？自动补全？）
性能要求？（预期搜索量？需要缓存吗？响应时间？）
使用什么数据库或搜索方案？（PostgreSQL？Elasticsearch？）

你：搜索博文，字段是标题和内容，大小写不敏感的模糊匹配就行。不需要筛选器。用 PostgreSQL。博客流量不高，性能要求不高。
AI：明白！我来为这个搜索功能生成一份规范：
（AI 生成一份清晰的 blog-search-api.md 规范，大约 35 行）
AI：我已完成规范文档，是否与你的预期一致？需要修改吗？
你：很好，开始吧！
AI：好的！现在我将基于该规范实现搜索 API。
（AI 生成干净的 pages/api/search.js 实现，大约 24 行）
AI：我已根据规范实现了简洁明了的搜索 API：
✅ 使用 ILIKE 查询 title 和 content
✅ 大小写不敏感模糊匹配
✅ 返回标题、摘要和链接
✅ 最多返回 20 个结果
✅ 优先返回标题匹配的结果
需要我加个简单的测试文件吗？

这个对比鲜明地展示了“规范优先”方法如何让 AI 在编码前先停下来，问清楚需求，确保准确理解你的意图。这样能极大地节省你的时间与精力，同时产出高质量、符合预期的代码。

核心优势

“规范优先”的工作流解决了许多常见的 AI 编程痛点，并大幅提升效率。正如作者所说：“你能多快地做出一个无用的东西并不重要。”这个方法强调“慢即是快，稳即是快”。

主要优势包括：

聊天漂移 → 稳定文档：与混乱易丢失的聊天记录不同，规范文档（如 .md 文件）是稳定可复用的上下文来源，便于 LLM 解析。
孤独编码 → 团队协作：规范文档让 AI 编程从个人行为转变为可交接、可协作的流程，聊天结束后可直接交给他人继续。
没有版本控制 → Git 跟踪需求：虽然聊天不能进 Git，但规范文件可以。需求演化过程可完整记录，方便团队成员立即理解项目背景。
功能膨胀 → 明确定义范围：明确的规范如“仅匹配用户名的基本字符串搜索”，可避免 AI 自作主张实现额外功能。
上下文丢失 → 一键恢复状态：你可在长时间中断后快速恢复项目，并理解设计背后的“为什么”。
空白页恐惧 → 结构化起点：AI 先作为文档助理，再是代码助理。评审规范比从零写规范轻松得多，能迅速进入状态。
Token 浪费 → 上下文高效利用：规范文档内容结构清晰、信息密集，避免浪费 token，提升效果。

这些优势带来的结果是：**开发效率提升约 60%**，且输出质量显著更高。正如一位用户所说：“我估计我的功能开发时间减少了约 60%，而且成果质量也更好”。

为什么 Vibe Specs 有效？

Vibe Specs 之所以有效，根本原因在于它解决了传统 AI 编程流程中的核心缺陷：AI 往往无法充分理解你要解决的问题，因为你没有充分解释问题的上下文。

该方法拥抱了“上下文工程（Context Engineering）”的理念，即“在上下文窗口中填入恰到好处的信息，这是一门精致的艺术与科学”。它认识到，提供的信息太少会导致 LLM“胡乱输出”，而信息过多或不相关则会增加成本、降低性能。目标是找到那个“黄金中点”。

这种做法就像人类之间高效委派任务一样：通过编写简洁的规范文档、需求说明或 PRD（产品需求文档），来回答诸如：“目标是什么？”，“成功的标准是什么？”，“应该使用什么工具？”，“哪些内容不在范围内？”，“我们如何判断是否完成？”这些基本问题。通过将这种“更古老、更谦逊的做法”应用于 AI，结果非常明确：
“给 AI 一份清晰的规范，它就能输出清晰一致的结果；只给它一个模糊的意图（vibe），它就还你一个模糊的结果。”

关键机制是：你不写规范，而是让 LLM 来写规范。这个多轮交互的规范构建过程会自然引导你向 LLM 提供它所需的所有信息，帮助你掉进“成功之坑（pit of success）”。AI 会自动在编码前提示你编写规范，从而确保你与 LLM 的第一步是写规范，而不是写代码。

证据

Spec-first 方法的有效性，已被个人经验、学术研究和业界实践多方验证：

✅ 个人成果：

有开发者在一次 45 分钟的技术面试中成功实现了一个复杂的 web 服务器，提前 20 分钟完成并完美通过，得益于他们花了前 5 分钟和 LLM 共同撰写了规范。
在日常开发中，这种方式带来了大约 60% 的功能开发时间节省，且结果质量显著提高。以前需要 2-3 小时（且经常返工）的任务，如今只需 10-20 分钟规划、1 小时就能正确实现，节省了数天与 LLM 来回反复沟通的时间。
有用户从经常出错、重试的 Kiro Agent 切换到 Cursor + Claude Sonnet 4，仅用 1 小时就完成了一个在 Kiro 上卡了半天的任务。

✅ 学术研究：

近期有关 LLM 辅助开发的研究表明：“规范（Specifications）是实现可靠代码生成的缺失环节”。相关论文包括：

Dreossi, T. 等（2024）：“Specifications: The missing link to making the development of LLM-based software more trustworthy”
Pullum, L., Freeman, L., & Huang, C.（2020）：“Verification and Validation of Systems in Which AI is a Key Element”
Batarseh, F. A., Freeman, L., & Huang, C. H.（2021）：“A survey on artificial intelligence assurance”
Hand, D. J., & Khan, S.（2020）：“Validating and Verifying AI Systems”

✅ 行业验证：

OpenAI 的 Deep Research 模式 就采用了类似模式：先停下来澄清问题，再进行计算和生成，优先“理解”而不是“输出”。
Shopify 的 Auto Write 功能 也是以一份全面的规范为起点，将 AI 能力与商户需求精准对齐。

这些例子反复印证了一条原则：成功的 AI 功能是从清晰的需求开始的，而不是靠机智的 prompt 堆出来的。

快速上手：如何实施 Vibe Specs

实施 Vibe Specs 非常简单，只需几分钟设置，就能为你节省数小时的开发时间。

✅ 步骤一：在你的 AI 开发工具中复制以下指令

无论你使用的是 Cursor、Windsurf、Claude、ChatGPT 还是其他 IDE，都可以将以下内容复制粘贴进去，使其在每次对话中自动生效。

对于 ChatGPT，请粘贴到“自定义指令”中。
对于 Claude，请粘贴到“项目说明”或“系统提示”中。
对于 API 调用，请添加到 system prompt。

## 开发流程：Spec → Code
这些指令至关重要！它们能显著提升你的开发质量。

### 阶段一：先写需求
当被要求实现某功能或做修改时，请始终先问：
“我是否应该为这个任务先创建一个规范（Spec）？”
只有在用户同意后，才：
- 在 `.cursor/scopes/FeatureName.md` 创建一个 markdown 文件
- 通过提问澄清以下内容：
    - 目的与用户问题
    - 成功标准
    - 范围与限制
    - 技术考虑
    - 不在范围内的事项

### 阶段二：审核与完善
草拟规范后：
- 展示给用户
- 询问：“这是否符合你的意图？有需要修改的地方吗？”
- 多轮迭代，直到用户确认
- 最后确认：“规范没问题了？准备好实现请键入『GO!』”

### 阶段三：开始编码
仅在用户键入“GO!”或明确表示批准后，才开始：
- 根据规范进行编码
- 所有决策都以规范为依据
- 若范围变化，请先询问用户后再更新规范

### 文件结构建议
.cursor/
├── scopes/
│   ├── FeatureName.md     # 可以提交到 Git 的规范
│   └── .local/
│       └── Experiment.md  # Git 忽略的实验性规范

> **请记住：先思考、提问澄清，然后再编码。规范是你的北极星。**

✅ 步骤二：确保这些规则在 IDE 中设置为“始终附加（Always Attached）”

这样你每次开启 AI 助手时，它都会自动使用这些规范规则。

✅ 步骤三：开始新对话，描述你的任务

例如：“帮我为我的应用添加用户认证功能”。

✅ 步骤四：与 AI 一起创建规范

AI 会自动提问，让你考虑你之前可能忽略的问题，最终生成一份清晰的 FeatureName.md 规范文档，并等待你批准。

AI 可能会问：

“用户是通过邮箱还是用户名登录？”
“是否需要密码重置功能？”
“会话（Session）多久过期？”

✅ 步骤五：批准代码

你一旦确认规范无误，只需键入“GO!”或明确表示批准，LLM 就会根据规范开始精确构建功能。

整个快速上手流程一般只需 5 分钟前期规划，但可以为你节省数小时的返工时间和沟通成本，让你的项目开发流程更快、更稳、更少出错。

常见问题解答（FAQ）

以下是关于 Vibe Specs 常见问题的解答：

这适用于 ChatGPT / Claude / 其他 AI 工具吗？

是的！ 尽管示例使用了 Cursor，但 Spec-first（规格优先）方法本身与工具无关。你可以将这些规则添加到 ChatGPT 的自定义指令、Claude 的项目指令、Windsurf / Continue / Cody 的配置文件中，或者直接写入原始 API 调用的 system prompt。关键在于让“生成 Spec”变成自动流程，而不是可选步骤。

这和传统文档有什么不同？

传统文档通常是在开发之后编写，用于解释“已经构建了什么”。Spec（规格）则是在开发之前编写，用于明确“应该构建什么”。你可以将 Spec 理解为与你未来的自己（或 AI）就意图进行的一次协作对话，而文档是对已发生事项的记录。

如果我正在修改已有代码怎么办？

Spec 对于已有代码的修改非常有价值。比如“重构认证系统”或“修复性能问题”这类任务，Spec 可以明确哪些内容需要更改、哪些不变、成功的衡量标准以及约束条件。而在“为遗留代码添加功能”时，Spec 还可以记录假设和集成点。AI 甚至可以分析现有代码，协助撰写尊重当前架构的 Spec。

这不就是传统瀑布开发模式的变种吗？

不是！ 这个方法仍然是迭代式的。传统瀑布开发要求在数周内写出庞大的需求文档，然后用数月时间开发。而 Vibe Specs 倡导的是：每个功能花 5–10 分钟写一个小型 Spec，根据新信息进行迭代更新。每个功能都有一个独立的迷你 Spec，而不是一份巨大的整体文档。

Spec 应该有多详细？

Spec 的详细程度应匹配任务的复杂性和风险。简单的 bug 修复只需 3–5 个要点；新增功能可能需要 1–2 页；架构变更则可能需要 2–5 页加上图示。有个简单的经验法则：如果你向一个新团队成员解释这个任务要花超过 5 分钟，那就应该写一个 Spec。

如果 AI 写出来的 Spec 不够好怎么办？

这正是为什么需要你来审查！常见的问题包括：模糊、不必要的复杂、错误假设、缺乏上下文……你应该通过向 AI 要求更具体信息、拆分功能、纠正假设或加入领域知识来改进 Spec。记住，你是建筑师，AI 是你的起草助手。

我可以用这个方法处理非编程任务吗？

当然可以！ 这个模式适用于任何复杂任务，只要它在执行前需要清晰的意图说明。比如写博客（Spec = 提纲）、做演示文稿（Spec = 关键信息）、规划项目（Spec = 项目章程）、系统设计（Spec = 设计文档）等。

我如何说服团队采用这个方法？

先从你自己开始。先独自使用一周，然后分享你写的好 Spec 和最终成果。你可以主动为一些团队共享功能写 Spec，并追踪效率的提升。让结果自己说明问题，而不是强制推行。

那探索式编码呢？

即使是探索性编码也受益于轻量级结构。你可以写一个“探索性 Spec”，定义你要研究的问题、设定时间限制、明确探索成功的标准。探索完成后，再为正式实现编写完整 Spec。

Spec 会不会拖慢紧急修复的速度？

真正的紧急情况可以跳过 Spec。不过，一旦危机解除，最好补写一个事后 Spec，记录你做了什么、为什么这样做。这有助于制定长期方案，解决根本原因，避免同类问题再次发生。事实上，大多数所谓的“紧急情况”，本质上只是问题定义不清。

我应该把 Spec 存在哪儿？

推荐结构如下，放在 .cursor/ 目录中：已确认的 Spec 放在 .cursor/scopes/feature-name.md，实验性的 Spec 放在 .cursor/scopes/.local/experiment.md（该目录被 Git 忽略）。当然也可以根据你团队的实际开发流程做调整，只要确保统一和易于查找即可。

AI 辅助开发的未来

软件开发正在迅速变化。在 AI 辅助开发的时代，每个开发者都会越来越像产品经理。最大的挑战不再是“如何写代码”，而是“知道应该写什么代码”。LLM（大语言模型）在代码生成上极其强大，而 Vibe Specs 模式确保开发者不会把“目标定义”的责任完全交给 AI。

AI 时代真正的开发革命不在于“生成更酷炫的代码”，而在于明确的需求表达流程：LLM → Spec → Code。这种范式带来开发效率的提升、代码质量的改善，并能让你在频繁上下文切换中保持清晰。

AI Agent 进化（代理式软件工程师）

“规格优先（Spec-First）”理念也延伸到 AI Agent（智能代理）的进化过程。随着代理型 AI（Agentic AI）的兴起，我们的工作方式将被彻底重塑，“软件工程师”的角色也随之改变。我们将从“代码编写者”转变为“代理式软件工程师”：指挥、协作、评审并运行一支“AI 代理军队”的专家。

AI Agent 拥有更强的执行能力：能调用工具、访问文件、运行命令。一旦你给它模糊的指令，它可能会调用错误的 API、修改不该改的文件、陷入高成本的执行循环。因此，在这个背景下，“Vibe Specs” 从“需求文档”升级为 “行动计划”或“任务执行说明书”。

Agent 工作流将是这样的：

输入阶段：你和 AI Agent 通过对话协作制定一个高层次的行动计划（即 Spec），明确目标、关键步骤、可用工具、操作边界、成功标准。
执行阶段：Agent 以这个结构化计划作为核心指令，自主拆解并执行任务。
监控阶段：Spec 也作为你监控 Agent 表现的基准，清晰展示其进度和执行偏差。

本质不变：

“先定义清晰问题，再着手解决”。Spec-First 在更高级的人机协作中不仅不会过时，反而变成了“安全带”和“导航图”。

未来所需的新技能（Skills++）：

版本控制能力：Git 成为协调 Agent 工作流、审查其 PR、回滚错误的核心技能，熟练掌握 Git 模型将变得基础且必要。
产品思维：将模糊的需求分解为明确任务、设计接口、定义边界等能力将是 AI 时代最重要的开发基础。
代码审查：你的价值将从写代码转变为评估 Agent 生成代码的正确性、可维护性和安全性。
测试能力：编写准确、全面的测试用例是约束并引导 Agent 行为的核心，尤其当 Agent 会“聪明地”绕过测试时。
系统设计：清晰的边界、健壮的接口和良好的可测试性，是管理不稳定 Agent 的关键。
运维能力：你将成为“Agent 可靠性工程师”，负责设计、部署、监控和调试复杂 Agent 网络，快速定位 Agent 行为中的问题。

即将贬值的技能（Skills–）：

LeetCode 算法题能力：AI 可以瞬间解决大多数算法题。
编程语言语法熟练度：Agent 熟知所有语法细节；你阅读和理解代码的能力比记语法更重要。
打字速度：AI 的“思考”和“输出”速度远超人类，打字快已经不再是优势。

总结

Agentic AI 时代是一场不可逆的变革。企业将围绕 Agent 构建未来，而掌握如何指挥和协作这些 Agent 的工程师将处于核心位置。未来属于那些既能思考、又能指挥机器执行的人。

引用链接

Sick of Kiro’s infinite retries? I extracted its ‘Specs’ idea into a lightweight MCP that makes your AI assistant actually stick to the plan. : r/vibecoding - Reddit:
- Reddit Post: https://www.reddit.com/r/vibecoding/comments/1ds1s7t/sick_of_kiros_infinite_retries_i_extracted_its/ (Please note: The direct link to the specific Reddit post was not provided in the source text but inferred from the title and context. The source text itself is an excerpt from this post.)
- Vibe Specs GitHub Repository: https://github.com/yinwm/vibedevtools/blob/main/vibedev-specs-mcp/README.md
- Kiro Agent Source Code Analysis GitHub: https://github.com/ghuntley/amazon-kiro.kiro-agent-source-code-analysis
Vibe Specs: Vibe Coding That Actually Works - Luke Bechtel:
- Blog Post: https://lukebechtel.com/blog/vibe-speccing
别再直接让AI 写代码了！试试这个“Vibe Specs”模式，效率提升60% - Tony Bai:
- Blog Post: https://tonybai.com/2025/07/02/vibe-specs
核心解法：拥抱“规范先行” (Spec-First) - Tony Bai:
- This is an excerpt from Tony Bai’s blog. The source includes links to other articles within the same blog:
  - “一张图读懂Go的生存之道：当“面条代码”来敲门”: https://tonybai.com/2025/07/16/when-spaghetti-code-knocks
  - “AI 正在重写“软件工程师”的岗位描述：未来你需要这 6 项核心技能”: https://tonybai.com/2025/07/15/the-agentic-software-engineer