如何让VibeCoding真正好用起来
Author: Guancheng Li and Jiashuo Liang of Tencent Xuanwu Lab
最近 VibeCoding 成为开发圈的新风潮。借助 Cursor、Claude Code 等工具，开发者只需描述需求，AI 就能自动生成代码。从批量完成重复性代码，到快速搭建原型、重构陈旧代码，极大地提升了研发效率。我们在尝试过程中，发现它完全可以胜任中等难度的工程开发工作。其带来生产力的提升令人印象深刻。然而，也有不少人初次接触时感到失望：AI 写出的代码无法运行，改动还把项目弄得一团糟，最终只好回到「祖传手写」或在普通AI对话界面里边问边写。这就形成了一种落差——一边是爱好者对提效体验的热情分享，另一边却是新用户的挫败与困惑。
为什么会这样？原因在于，VibeCoding Agent本质上只是一个工具，它确实拥有强大的潜力，但前提是用户需要掌握一定的使用方法。目前各平台虽然提供了不少“最佳实践”清单，但大多零散琐碎，很难直接套用，让人难以形成系统的理解。 本文将尝试回到根本，从几个最核心的原则出发，解释如何让 VibeCoding 真正好用起来，成为新生产力工具。
原则1: 清楚沟通
很多人在Vibe Coding时习惯凭感觉对 AI 下指令，但却忽略了一个关键事实：人脑子里有的那些项目背景知识，AI 并不知道。大多数失败的案例，并非因为模型不够强，而是没把需求讲清楚。
将Agent想象为加入团队的新同学
你可以想象项目团队来了一个新同学。面对新人，同步当前工程的进度情况本来就是一个需要好好处理的问题。你可能会先从项目的整体结构开始介绍，再逐步交代他要负责的具体任务。
对于AI，道理也是一样的，只是AI效率更高，沟通更简单了。
- AI读代码和组织语言回复很快，你可以要求它去看各种代码并复述自己对问题的理解；
- 如果AI理解有误，你可以立即打断，和它继续探讨。 大多数Vibe Coding工具提供了“计划模式”（Plan Mode），这是一个非常有用的机制。在这个模式下，Agent不会立即执行指令，而只是输出执行计划。你可以与Agent对齐目标，直到你确定它完全理解了你的任务，再允许它去写代码。
让Agent逐渐加深对项目的理解
在项目中准备简洁的项目说明文档与任务描述文档，让 AI 在每次执行前先阅读这些内容。这样，它会更容易把当前任务放入整个系统的语境中。 每次任务成功执行完成，你还可以让Agent 生成一份总结文档，记录它对项目结构、实现逻辑及变更原因的理解，将这些记录保存在项目文件或CLAUDE.md等规则文件之中作为长期记忆。这样，在下一次Vibe Coding时，已经讨论过的问题就不再需要再讨论了。
原则2: 理解Vibe Coding的长短处
很多人在 Vibe Coding 时会把 AI 当成全能专家，觉得它可以一次性改完整个系统。但事实是，AI 在一些场景非常可靠，在另一些场景却很容易出错。如果不了解它的优势和局限，就会对它抱有过高期待，结果往往是失望。
AI的短处
上下文越长，性能越差：当任务涉及多个文件、上下文内容过长时，大语言模型性能会显著下降； 没完全懂就直接开干：即使没理解透彻，它也会自信的开始干活，这样就容易跑偏； 爱走捷径：它有时倾向选择实现最简单的方案。比如把 dict 重构成 pydantic 模型时，它可能偷懒写个 converter，而不是在代码层面彻底替换。
AI的长处
快，还是快：这个优点前文提到过，但由于其太过于重要，在这里重新强调一遍，Vibe Coding的读写文字和代码的能力远超人类，所以你可以放心的与它进行高频的沟通和对齐需求，让它去看各种文件加深对项目的理解，也可以让它把理解写下来方便以后复用。你可以把他想象成一个具有量子速读和速写能力的同事，然后思考如何妥善的利用它这方面的能力。 熟悉并掌握大量工程领域的最佳实践：它知道常见项目的目录结构应该怎么组织；它理解常见的设计模式、单元测试方法、类型标注习惯；它能在看到一段代码时，立刻联想到主流工程规范里的更佳做法。这意味着，在 Vibe Coding 的过程中，你并不需要只让它机械地完成改动，还可以让它主动提出改进建议。每一次 Vibe Coding 不只是完成一个任务，更是让代码库逐步进化的机会。
如何扬长避短
要想让 Vibe Coding Agent 具有较好的表现，首先就要控制好上下文长度。比如先通过计划模式让 Agent 把复杂任务拆解为一些较小的子任务，然后再另起新的会话完成这些任务。如果代码模块化和抽象设计合理，Agent可以从抽象的角度理解不同模块的功能和关系，即便是复杂的跨模块开发任务也能保持不错的表现，这点会在原则 3 详细说明。 其次，为了防止没完全懂就直接开干，我们可以借用原则 1 提到的 Plan Mode 技巧：先让它解释自己的理解，确认目标是否准确，直到它“听明白了”再放去执行。 对于它爱走捷径的毛病，我们可以在任务说明时加上明确约束：要求它在执行前给出多种实现思路，并比较优劣；特别强调“不要只是包一层 converter”这种偷懒方案；在生成计划时，就排除掉明显走捷径的路径，确保它走上真正符合长远目标的路线。 最后还有一点容易被忽视：Vibe Coding Agent 的总结和复盘能力也非常强。每次它完成任务后，你都可以要求它写下“自己为什么这么做”“有哪些可能的替代方案”，这样既能帮你检查有没有错漏，也能帮助 AI 在后续会话里继承经验，越协作越顺畅。
原则3: 设计AI友好型代码结构
要让VibeCoding稳定地产出高质量代码，除了上文提到的原则，还可以设计AI友好型代码结构。通过改进项目组织方式，让人类与AI能高效协作、共同维护一个清晰可维护的系统。 一个对 AI 友好的代码结构，不仅能让模型更快定位相关代码，还能增强项目可维护性，让后续VibeCoding过程更加顺畅。
AI产出的代码结构问题和成因
Vibe Coding工具有强大的编程能力，但它产出的代码结构容易出现以下问题：
- 缺乏合理抽象 —— 模块间高耦合、功能交叉、模块边界不清。
- 过度封装、冗余代码 —— 做了很多没必要的中间层、兼容层。
- 命名不一致、风格混乱、和别的模块功能重复。 这些问题逐渐堆积，不仅降低人类开发者的阅读与维护效率，也妨碍 Agent 在后续任务的发挥。
经过长期观察和实践，我们总结了这些问题的成因：
- Agent倾向于在已有代码上小修小补来支持新的功能。除非用户要求，Agent不会主动做破坏性动作，如删除旧代码、进行大幅重构。补丁越打越多，代码越来越乱。
- Agent以完成用户指定的任务为首要目标，达成目标后对话就结束了。但是当前任务可能间接影响了其他功能，AI不会在事后整体评估任务完成方式的合理性。
- 没有检索到某些关键代码，导致Agent不了解已有模块的功能和风格，只好重新造轮子。
- Agent对项目背景认知与人类不一致，它会参考训练数据中的常见写法，误认为某些不重要的功能要做抽象，而对需要抽象的模块却没有抽象。
与AI共建良好的代码结构
“对 AI 友好”并不意味着牺牲人类可读性。两者其实是高度重合的：如果代码结构对人类清晰、职责边界明确，AI 在接入时也会更容易发挥作用。传统软件工程中的高内聚、低耦合等原则依然适用。不同的是，在 VibeCoding 模式下，AI 也成为代码结构治理的参与者，我们可以针对其特点调整组织方式，让项目更易维护。
- 面向文档编程。在项目中预先写好两类文档：项目介绍文档（通常包含项目整体背景说明、抽象层和模块关系）、编码规范文档（通常包含代码风格说明、第三方依赖关系）。让 AI 在每个任务时自动把必读文档添加到上下文。
- 让AI参与架构设计。在架构设计阶段，你就可以和AI一起讨论，想要达成项目预期目标，应该有怎样的功能模块设计、代码抽象层次。反复修改，直到你觉得靠谱为止。把最终讨论结果写入项目文档中，作为后续编程的 ground truth。
- 避免单个文件过于复杂。VibeCoding工具是以文件为单位来读取代码的，过大的文件容易使 AI “失焦”。代码结构上尽可能将代码模块切分好独立单元，每个模块专注一件事，职责明确，暴露一组清晰的接口，不需要跨一大堆文件依赖才能理解当前模块的功能。 自动化测试。让AI在当前功能实现完成后，同步生成相关单元测试。不仅有助于AI自动发现并修复一些bug，还可以避免AI在后续任务中间接影响到本模块功能而无所察觉。
- 代码回顾与重构。当项目逐渐复杂，当原本的代码结构在可预见的未来无法应对新的功能需求，可以和AI讨论规划代码重构方案，进行合适的抽象以增强扩展性，将复杂功能解耦、相似功能合并，并更新文档。
Reference