如何 Vibe Coding

这篇文章讨论如何从零开始和 AI 一起完成一个项目，它是阐述了做项目的方法论，同时也是一份给 AI 看的指导性文档。

它告诉 AI，程序员和 AI 之间应该如何协作，遇到一个新项目时，应该先做哪些准备工作、应该写哪些文档、文档里应该包含哪些内容、以及如何维护这些文档。

Vibe Coding 总体流程

下面的每一步，只要是由 AI 来做的，都应该由程序员来评审和确认，确保 AI 没有跑偏。

1. 编写项目协作总则

在本文内容基础上，并结合项目实际情况，由 AI 生成一份项目协作总则，它应该包含以下内容：

项目协作总则不是项目简报、需求文档或技术方案文档，它的作用是定义这个项目里程序员和 AI 默认遵守的协作规则。

它应该是一份短、小、稳定、可执行的工作协议，而不是一篇冗长的方法论文档。通常控制在 1 到 2 页内比较合适。

项目协作总则建议包含以下内容：

1. 项目定位和性质

   • 是一个什么类型的项目（例如：个人项目、开源项目、商业项目、demo项目等）
   • 项目的主要目标是什么（验证想法、解决实际问题、交付产品、沉淀技术能力、形成作品集等）
   • 项目面向的主要对象是谁（自己、团队内部、特定用户、公开用户）

2. 程序员与 AI 的职责分工

   • 程序员负责需求拍板、风险取舍、最终评审和关键操作确认
   • AI 负责文档草拟、任务拆解、实现、测试、调试以及同步更新文档
   • 哪些操作默认不能由 AI 直接执行
   • 哪些操作必须由程序员确认，例如主分支合并、发布、回滚、删除数据、修改关键配置

3. AI 的默认工作流程

   • 每轮任务开始前先确认目标、边界和验收标准
   • AI 根据文档执行任务
   • 执行完成后更新文档，并说明改了什么、如何验证、还有什么风险
   • 最后由程序员进行评审和确认

4. 文档优先级和读取顺序

   • AI 开始工作前应该先读取哪些文档，后读取哪些文档
   • 当多个文档冲突时，怎么办（向程序员提出问题，还是按照优先级处理）

5. 文档维护原则

   • 哪些文档允许直接更新
   • 哪些文档只能追加更新，不能覆盖历史记录
   • 哪些文档按版本新增

项目协作总则不应该写入以下内容：

• 详细功能需求
• 详细技术设计
• 具体版本的实现细节
• 大段背景介绍
• 只在某个短期阶段有效的临时规则

这些内容应该分别放在项目简报、需求文档、技术方案文档和版本文档中。

项目协作总则最适合采用“由 AI 起草，由程序员定稿”的方式生成：

1. 程序员先提供项目背景、目标、约束、协作偏好和权限边界
2. AI 根据本文方法论和项目实际情况生成第一版项目协作总则
3. 程序员审核并修改其中不准确、过重或不符合习惯的部分
4. 后续随着项目推进，由 AI 协助维护，但每次重大调整都应由程序员确认

也就是说，AI 适合负责整理和起草，程序员负责最终拍板和长期拥有这份规则。

2. 项目规划

1. 建立项目文档目录，并放入项目级协作总则。
2. 程序员向 AI 提供项目背景、目标、约束和非目标。
3. AI 先列出缺失信息、关键假设和建议的最小文档集合。
4. 双方对齐后，AI 生成第一版核心文档：项目简报、需求文档、技术方案文档、工程约束文档。
5. 在核心文档稳定后，再按需生成上下文工程工具，例如 agent、instruction、prompt 模板、必要的 skill。

3. 执行

1. AI 按“版本文档 + 主文档”的约束执行当前迭代任务，进行实现、构建、测试和调试。
2. 每轮任务结束后，先更新文档，再由程序员评审代码、测试结果和文档变更。
3. 涉及主分支合并、发布和关键 git 操作时，由程序员执行或确认。

项目规划

项目规划阶段，本质上是要在项目启动之前先明确这三点：做什么、怎么做、按什么规则做。

主要确定以下内容

1. 确定项目的目标和边界（背景、需求、目标群体、预期效果、覆盖的场景等）
2. 确定项目的技术方案、开发流程和工具链
3. 制定项目的约束和规范（编码规范、设计规范、测试规范等）

从零开始做一个项目，要避免“大而全”的前置文档，应该采用“小步对齐、边做边固化”的方式来逐步完善文档，并保持文档的实用性和时效性。

文档维护原则

这一节解决文档如何随版本一起持续迭代的问题。

对 Vibe Coding 来说，要遵循“上下文分层管理的原则”，最合适的做法不是“每个版本重写整套文档”，也不是“所有文档都在原地持续覆盖”，而是采用“少量主文档保持当前有效 + 每个版本补一份轻量增量文档”的方式。

适合 Vibe Coding 的方案是两层结构：

1. 主文档
   始终保持“当前有效”，给 AI 当长期上下文用。比如项目简报、技术方案、工程约束、架构说明。这些文档应该随项目演化直接更新，确保 AI 读到的是当前版本，而不是历史版本。
2. 版本文档
   每次迭代单独新增一份，给 AI 当“本轮任务边界”用。比如 V1、V1.1、V2 的版本目标、范围、验收标准、非目标、风险、发布条件。这类文档不应该覆盖旧版本，因为它们本来就是时间切片。

从落地的角度，文档可以这样分：

• 持续更新主文档：项目简报、技术方案文档、工程约束文档、系统架构文档、工程规范文档
• 按版本新增文档：版本需求文档、发布清单、风险清单、迭代计划
• 持续追加文档：决策记录

核心文档集合

这版文档集合的目标不是“完整”，而是“足够开工，并且不容易跑偏”。

它适合以下场景：

• 单人项目或小团队项目
• 从零开始、仍然存在较多不确定性的项目
• 希望先快速做出第一版，再逐步补全文档和规范的项目

通常 4 到 5 份文档就够了。

1. 项目简报

这份文档用来回答“项目为什么做、给谁做、做到什么程度算成功”。

建议包含以下内容：

• 项目一句话介绍
• 项目背景和要解决的问题
• 目标用户
• 核心使用场景
• 版本目标和非目标
• 发布标准
• 成功标准（项目发布以后，什么样的结果算成功）
• 已知风险和假设

这份文档决定大方向。

2. 需求文档

这份文档用来回答“当前版本做什么、不做什么”。

建议包含以下内容：

• 功能清单
• 每个功能的优先级
• 核心用户流程
• 关键页面或模块
• 验收标准
• 异常流程和边界情况
• 本版本明确不做的内容
• 后续版本候选项

这份文档决定做什么先、做什么后。

3. 技术方案文档

这份文档用来回答“项目怎么落地”。

建议包含以下内容：

• 技术栈选择
• 为什么这么选
• 整体架构
• 核心模块划分
• 数据模型概要
• 接口边界概要（描述模块的职责和依赖）
• 状态管理或数据流
• 测试方案（单元测试和集成测试）
• 开发调试环境配置
• 构建和部署方式
• 主要技术风险
• 暂不处理的技术问题

这份文档决定怎么落地。

接口边界概要，描述的是模块之间如何协作，“边界”指的是职责边界和依赖边界。也就是：

• 这个模块负责什么
• 不负责什么
• 它能依赖谁
• 谁可以调用它
• 输入输出是什么
• 哪些内部细节不能泄漏出去

4. 工程约束文档

这份文档用来为项目的开发制定规范和约束。

建议包含以下内容：

• 目录组织规范
• 命名规范
• 代码风格要求
• 格式化和静态检查要求
• 日志规范
• 错误处理约定
• 配置和环境变量约定
• 测试最低要求
• 提交和评审约定
• 禁止事项
• 文档编写和维护规范（包括开发文档和用户文档）

这份文档决定大家怎么协作、怎么保持一致。

5. 决策记录

这份文档用来回答“为什么当时这样选，而不是那样选”。

建议包含以下内容：

• 决策标题
• 决策时间
• 背景
• 备选方案
• 最终选择
• 选择理由
• 代价和影响
• 后续是否允许调整

这类文档的价值很高，因为它记录的是“为什么”，而不是只有“最后是什么”。