Vibe Coding 实践：规划先行，人机协同

一、Vibe Coding：被误读的“氛围感编程”

Vibe Coding 是近两年在 AI 辅助编程领域迅速走热的一个说法。在大众语境里，它常被演绎成一种“凭感觉写代码”的姿态：开发者不细读代码，把需求口语化地丢给 AI，生成什么就收什么，程序能跑就继续，跑不通就再补一句提示词。这种理解只保留了“氛围”，却丢掉了工程，其典型结局是：短期速度惊人，两周之后代码库面目模糊、模块互相缠绕，没人敢动也说不清哪里会坏。

真正值得长期采用的 Vibe Coding，恰恰是它的另一面：规划先行、人机协同。它的核心不是“放手”，而是“约束下的高效”——通过先写文档、维持上下文一致性、小步迭代与持续验证，让 AI 始终在一个结构清晰、规则明确的环境里参与协作，从而成为可靠的编码助手，而不是一个不可预测的黑盒。

为什么不能让 AI 自由发挥？至少有三条硬理由：

1. 生成具有不确定性。 大模型的输出本质上是概率性的，同一个需求两次生成，可能在目录结构、命名风格、错误处理方式上大相径庭。没有约束的自由生成，等于不断引入新的“局部解”，最终拼出一个无人能维护的整体。
2. 上下文天然有限。 会话拖得越长，早期约定越容易被稀释，AI 会逐渐“忘记”自己定下的接口与模块边界，开始自相矛盾、重复造轮子，甚至悄悄偏离架构。
3. 责任无法转移。 AI 可以产出代码，但需求取舍、架构权衡与质量把关始终是开发者的责任。放弃审核，等于放弃对产品的控制权。

二、核心理念：Planning is Everything

规划先行是这套方法论的第一原则，可以拆成四个连贯的动作。

1. 先写设计文档

写任何一行代码之前，先把构想写清楚：做游戏就写游戏设计文档（GDD），做产品就写产品需求文档（PRD），以纯文本标记格式（如 Markdown）落盘。文档至少要回答四个问题：目标用户是谁、核心功能有哪些、关键交互流程如何走、边界条件与非功能需求是什么。落盘的意义在于：文档成为人与 AI 之间可引用的契约——口头描述随会话消失，而文件可以被反复读取、逐条对照、持续修订。

2. 生成实现计划，而不是直接生成代码

设计文档完成后，让 AI 基于设计文档与技术选型，产出一份实现计划（Implementation Plan）。注意这里的本质差别：这一步的产出是“步骤清单”，不是代码。一份合格的实现计划应当：

• 把目标拆解为有序的 Step，每步聚焦一个可独立验证的改动；
• 写明每步的输入、输出与验收标准；
• 标注步骤间的依赖关系与风险点。

让 AI 先出计划而不是先写代码，本质是把评审时机前移：改一段计划只要几十秒，而纠正一版方向跑偏的代码往往要花数小时。计划，是人和 AI 达成共识最便宜的地方。

3. 小粒度推进，每步附带测试

实现计划中的每一个 Step 都应保持小粒度——一个函数、一个模块或一条完整的功能路径，并附带测试验证。粒度小的收益是直接且可叠加的：影响范围可控，出问题不殃及全局；验证成本低，几分钟就能确认对错；回退容易，任何时候都能退回上一个稳定点。测试则是“机器可执行的验收标准”，有了它，“这一步做完了”从主观感受变成客观事实，也为后续回归提供了安全网。

4. 技术选型同样落盘

动手前，把语言、框架、构建工具、部署形态等选型写成文档，与设计文档一起作为 AI 生成的硬约束。否则 AI 可能在不同步骤里各自挑选“当下最顺手”的技术，造成风格分裂与技术债。

三、上下文一致性：建立 memory-bank 文档体系

如果说规划解决“做什么”，上下文管理解决的则是“AI 记得住什么”。长会话中的上下文漂移，是人机协作失败的头号原因。对策是：把关键信息从聊天记录迁移到文件系统，建立一套记忆库（memory-bank）：

memory-bank/
├── game-design-document.md   # 设计文档（GDD 或 PRD）
├── tech-stack.md             # 技术选型说明
├── implementation-plan.md    # 实现计划
├── progress.md               # 进度记录
└── architecture.md           # 架构说明

这套体系的价值不在目录本身，而在三条使用纪律：

1. 生成前必读。 让 AI 在每次生成代码前，先读取 architecture.md 与设计文档等关键文档，确保输出贴合既有架构，而不是凭会话残存的印象自由发挥。
2. 完成后必记。 每完成一个 Step，就在 progress.md 里登记。一份有用的进度记录大致长这样：

## Step 7：用户注册接口
- 状态：已完成，测试 8/8 通过
- 变更：src/api/user.ts、tests/user.test.ts
- 遗留：邮箱格式校验延后至 Step 9

1. 架构演进必更新。 模块结构一旦变化，及时在 architecture.md 中补充模块职责、依赖关系与设计理由，避免文档与代码脱节。

坚持执行，memory-bank 就会从“一个文件夹”升级为“项目知识库”：隔了一周回来继续开发、换一位协作者接手、或开启全新会话，AI 都能在几分钟内重建完整的项目认知，而不依赖任何一段历史对话。这相当于把“AI 的记忆”从易失性的会话，换成持久化的工程资产。

四、迭代循环：实现—验证—提交—新对话

有了规划和记忆库，日常开发就收敛成一个四步循环。

第一步：AI 实现。 从实现计划中取出当前 Step，让 AI 完成，并给出明确的上下文引用与边界约束，例如：

请先阅读 memory-bank/architecture.md 与 memory-bank/game-design-document.md，
然后仅实现 implementation-plan.md 中的 Step 7，不要改动其他模块。
完成后列出本次修改的文件与验证方式。

第二步：手动验证。 运行测试、实际启动、把核心流程走一遍，确认行为符合预期。这一步不能省，也不能只看“代码看起来对”——AI 生成的代码经常出现“结构正确、逻辑偏差”的情况，只有真正运行才能暴露问题。

第三步：版本提交。 每完成一步，就通过版本控制系统提交一次，写清本次改动内容。提交粒度与实现粒度对齐，意味着任何一步走错，都能干净地回退到上一个稳定点，而不必在混乱代码里人工“找不同”。

第四步：新对话继续。 这是最反直觉、也最有效的一步：不要在同一个会话里无限聊下去，而是开启新对话，让 AI 重新读取 memory-bank 与 progress.md 后继续。新会话带来干净的上下文窗口，能有效避免长对话累积出的自相矛盾与“幻觉惯性”。

两个关键点值得单独强调：

• 不要马上继续下一步，先验证当前步骤。 节奏上的克制，是整套方法里成本最低、收益最高的纪律。带着未验证的改动叠加新改动，排错成本会成倍上升。
• 为每个大功能单独维护 feature-implementation.md。 当功能复杂到超出单一计划的承载范围时，拆出独立的实现文档，避免主计划膨胀到失控。

五、错误处理：回退、日志分析与整体诊断

再顺的流程也会出错，关键是有一套分级处理策略，而不是本能地在坏代码上继续打补丁。

1. 回退重试。 当某个 Step 的生成方向明显跑偏时，优先使用编码助手或编辑器提供的历史回退能力，回到上一步重新尝试，而不是在错误结果上继续叠改。在错误的地基上修补，通常会把小偏差放大成大混乱。
2. 日志分析。 遇到运行报错，把控制台的完整错误信息复制进代码编辑器，连同相关代码一起交给 AI 分析。结构化的“错误 + 上下文”，远比一句“程序崩了”能换来质量高得多的诊断结论。
3. 整体诊断。 当局部修复反复无效时，问题多半出在更高的层面。这时可以把整个仓库整合导出为一份完整的上下文文件，让 AI 从整体视图审视架构与模块关系，判断究竟是设计缺陷还是实现偏差。

处理错误有一条通用心法：把报错当信号，而不是当噪音。先区分“实现错误”（这一步没做对）与“设计错误”（计划本身有问题）：前者回退重做即可；后者需要回到实现计划乃至设计文档层面修正，否则同样的错误会在后续步骤里反复出现。

六、适用边界与工程判断

这套方法并非万能钥匙。它在原型验证、独立开发、中小规模项目以及功能边界清晰的新模块上收益最大；而在超大型遗留代码库、强合规或安全攸关的场景中，人工评审与既有工程流程仍然不可替代。合理的定位是把它当作“增益器”：文档、计划、测试、提交这些骨架本来就该有，AI 只是让维护这些骨架的成本大幅下降，从而让更多团队真正“做得起规范”这件事。

七、总结：把氛围用在体验上，把纪律用在代码上

Vibe Coding 的成熟形态，不是“让 AI 替我写代码”，而是一次重新分工：人负责目标、设计、评审与决策；AI 负责初稿生成、样板代码与问题分析。人维护一套可读的项目记忆，AI 在每次交互中读取并遵循它；人控制节奏，小步验证、及时提交，AI 在受限范围内高速输出。

这套方法背后没有任何玄学，只是把软件工程久经考验的原则——文档先行、小步提交、持续验证、可回退——投影到了人机协作场景。规划先行、上下文落盘、四步循环、分级排错，四件事做到位，AI 就能从“时不时惊艳、经常失控的黑盒”，变成可以托付日常开发任务的可靠搭档。这份既流畅又可控的开发体验，才是 Vibe Coding 真正值得“上头”的地方。