VibeCoding 实战手册：用工程化思维驾驭 AI 编程

VibeCoding 不是“一句话生成应用”的玄学，而是人与 Agent 协作的新工程范式。真正决定产出的，从来不是单次对话的模型智商，而是一套可退可进的环境、可复用的方法、以及清晰的沟通纪律。

一、环境与协作契约：让 Agent 随时可退、可接、可验

开工前先初始化 Git 仓库，并在 agents.md 中写清规则：遇到新会话或无关新需求时，清空暂存区再提交 commits，让代码始终处于可回退状态。agents.md 本身要保持精简，强调“最小化修改、测试先行”。

与 Agent 交互时，采用标准化输出：

• 接收需求后：输出“用户意图 / 假设 / 验收标准”，有歧义立即澄清，不默认用户绝对正确。
• 完成修改后：输出“验证步骤 / 后续优化”，防止功能蔓延，同时暴露潜在风险。
• 工具约束：优先用 codegraph 查代码，用 procm-mcp 重启进程（避免多实例），读取日志，修改后自动提交。

会话结束必须沉淀：生成 handoff 交接文档（让下一个 Agent 快速接力，无需扫全量代码）、可复用 skill，或补全 docs。知识留在仓库里，而不是某次聊天记录里。

二、开发纪律：脚手架、模块化与精准需求

项目优先使用脚手架工程，拒绝“上帝文件”。好的脚手架自带最新技术方案、UI 规范、清晰路由、测试文件、代码规范与 CI/CD 脚本，能约束 AI 沿现有规范修改。

关键禁忌与建议：

• 组件层：不让 AI 手写组件（风格易漂移），改用 shadcn 等高自定义组件库，先完成基础布局再定制。
• 需求输入：禁用“一句话需求”。用 grillme 让 AI 反问澄清，先产出完整 PRD，再谈实现。
• 架构：UI、数据模型、逻辑分层放置；复用逻辑抽通用函数/组件，或独立成 npm 包。split-god-files 按职责拆文件，降低歧义。
• 测试：必须让 AI 生成测试文件，形成完整测试逻辑，每次改动后快速回归验证。

三、调试与定位：给 AI 精确坐标，而不是让它“大海捞针”

调试效率取决于你给的上下文精度：

• 定位：用 vue-devtools / react-dev-inspector 点击元素直跳 VSCode；配置扩展复制指定行号，提需求时带上文件路径、行号或路由，避免全局搜索误改和浪费 token。
• 日志：在关键位置（尤其是修 bug 时）让 AI 补调用链调试信息。能读日志，90% 以上的 bug 可自行定位。
• 验证：配合 diagnose 类标准测试流程，确保修改经得起验证。

四、工具链推荐：少即是多

Skills 和 MCP 要精简。模型能力越强，堆砌过多 skill/mcp 反而拖后腿。

推荐 Skills

• handoff：生成临时交接文档，下个 Agent 免读大量代码。
• grillme：模糊需求时反问澄清，过滤伪需求。
• planning-with-files：长程任务生成目标/进度/探索三文档，新窗口可续做。
• init-project：维护根目录与模块文档（职责、接口、数据模型、测试、FAQ、变更记录等），保持“文档即代码”。
• diagnose / split-god-files：标准测试流程与拆文件工具。

推荐 MCP

• codegraph：生成代码地图，快速定位符号与依赖，免全局搜索。
• procm-mcp：读取启动命令，控制进程启停、避免多开，并支持 Agent 读日志做自动化测试。

五、人机心态：别跟模型斗气，要跟流程对齐

• 不依赖单个模型：真正重要的是 harness 约束、环境、已积累的 skills/docs。
• 不爆粗口：情绪化输入会让 AI 逻辑混乱、质量下降。若五轮仍搞不定，大概率是理解偏差或需求有误——对齐后 handoff，开新会话让新实例处理。
• 精确表达：把“会/不会”改成“需要/不需要/应该/不应该”，并明确操作步骤、出现的结果、预期的结果。

核心要点

• 环境即契约：Git + agents.md + handoff/skills/docs，让每一次 AI 介入都可追溯、可接力。
• 工程即约束：脚手架、模块化、测试与精准需求，防止 Vibe 变成混沌。
• 沟通即代码：给坐标、给日志、给标准；不斗气、不模糊、不堆工具。

金句：VibeCoding 的质感，不来自模型的即兴发挥，而来自你为它搭建的舞台与乐谱。