VibeCoding — AI 协同开发经验指南
归纳自多个项目的 Cursor 对话记录（演示系统、知识库平台、展厅大屏等），提炼可复制的思维脉络与工作方法。面向团队传播，非某一项目的架构说明。
一、什么是 VibeCoding
VibeCoding 指在 Cursor 等 AI 编程环境中，通过结构化对话推进软件开发：人负责目标、约束与验收，AI 负责检索、方案起草与代码实现。三个项目实践表明，成果质量差异主要来自协作方式，而非模型能力本身。
共同特征
| 维度 | 有效做法 | 常见失误 |
|---|---|---|
| 起手 | 先喂资料、定边界，再要产出 | 直接说「帮我做一个 XX」 |
| 大功能 | 讨论 → 文档 → 计划 → 实现 | 边想边改、大范围重写 |
| 小改动 | DOM / 日志精确定位 | 「整体再优化一下」 |
| 收尾 | 同步任务清单与规格文档 | 只改代码、不更新上下文 |
二、核心原则
1. 文档先行
功能迭代前，先让 AI 读懂并维护一组上下文锚点：
- 产品目标与边界（需求说明、产品规格）
- 架构与模块约定（架构说明、智能体约定文件）
- 阶段计划与任务勾选（计划、任务清单）
规则：行为、接口或配置变更，须回写文档后再动代码；下一任协作者（人或 AI）应能仅凭文档接续。
2. 先收敛、再动手
方案存疑时，优先问答式决策（选择题、逐条确认），而非长段自然语言拉扯。复杂领域典型路径：
AI 主动提问消歧 → 用户逐条定规则 → 只更新规格 / 计划 → 确认后再实现争议时明确：「有问题先问我」，避免 AI 自作主张。
3. 大计划、小步交付
大功能统一 Plan → Implement 两段式：先产出含待办项的计划并确认，再执行实现口令。小修不走计划，直接改。
模块化交付的通用顺序：
内容 / 剧本 / 契约 → 数据层 / 状态 → 界面 / 组件接入数据与展示解耦，便于分步验收与回滚。
4. 精准反馈，控制范围
界面与布局类问题，用 DOM Path + 组件名 指向具体元素，配合短指令（颜色、边距、动效）。比「那个按钮再调调」可靠一个数量级。
视觉精修推荐话术格式（可直接复制）：
- 第 N 页，「某某标签」位置偏高；删除某某装饰元素
- 某某元素距左侧约 2 m，朝向与某某平行
- 玻璃炫光过亮，且未随视角变化页码、元素名、空间关系、期望数值越具体，迭代轮次越少。
5. 内容可信、演示有边界
演示类项目须提前声明边界（如 Mock 驱动、不接外部 API），剧本与数据须学科真实、链路完整，避免 AI 编造演示内容。行业场景应绑定具体应用，科学表述须可核验。
6. 人机分工
部分工作由人完成更高效：参考图与蒙版手工编辑、关键参数手动微调、线上日志与截图提供。AI 负责将人的输入接入管线，而非替代专业判断。
三、可复制的推进路径
① 立项与资料对齐 → ② 文档与脚手架 → ③ 模块化功能交付
↓ ↓ ↓
④ 视觉 / 体验精修 → ⑤ 集成与发版 → ⑥ 验证与知识回写阶段 1：立项与资料对齐
输入清单（首条消息尽量齐备）：
- 自然语言描述业务目标与非目标（演示优先 / 生产可用等）
- 参考界面图、竞品或兄弟项目路径
- 既有 Markdown 方案、配图提示词、算法或素材仓库
- 硬约束（语言、密钥、测试门禁、不可改动的架构红线）
做法：让 AI 并行阅读资料 → 输出计划或方案 → 用户确认后一次性落地文档与骨架。
阶段 2：文档与脚手架
产出：需求说明、设计说明、架构说明、智能体约定；最小可运行骨架；目录与命名约定。
经验：兄弟项目的构建、部署、目录结构可对标参考，但视觉与产品定位应独立定义，避免照抄。
阶段 3：模块化功能交付
每个大功能遵循同一模板：
- 先定内容或接口契约（场景剧本、API 形状、表结构）
- 再定数据与状态（与 UI 解耦，支持分步替换）
- 最后接组件（复用已有模块，避免重复造轮子）
新能力优先：文档定契约 → 单模块实现 → 集成入口，避免跨层一锅炖。
阶段 4：视觉与体验精修
- 一次性给出可执行的视觉 Brief（信息架构、色板、字体、图标体系、禁用项如 emoji）
- 大问题拆成逐条清单，逐条验收
- 壳与内容解耦：导航壳稳定，场景内容可独立迭代、可白标替换
阶段 5：集成、发版与验证
- 构建产物、版本号、下载页、对象存储等多处版本须人工核对一致
- 生产验证模式：部署 → 按功能清单冒烟 → 输出测试记录
- 故障排查：贴 HTTP 状态 / 日志 / 复现路径，分层定位（网关 → 服务 → 任务）
阶段 6：知识回写
每完成一个计划阶段，更新任务清单；踩坑与决策记入文档，供后续项目复用。
四、高质量讨论模式
1. 选择题式架构拍板
模糊技术选型用「A / B 选项 + 理由 + 你的选择」一次性锁定，AI 直接改规格文档，减少来回澄清。
2. 「先讨论，暂不改代码」
复杂或方向性议题，先口头达成共识再动刀。例：「你觉得圆弧路径合理吗？先别改代码。」
3. 问题驱动深挖
线上故障或效果不达标时：贴日志与样例 → 分层排查 → 先补规格再开发，避免盲目改代码。
4. 类型与边界隔离
扩展共用类型前评估污染范围；演示彩蛋、旁路功能用独立类型与状态，不侵入主链路。
5. 跨项目对标排障
打包签名、部署命令、构建流水线等问题，直接 @ 可参考的成熟项目对比配置，比泛泛搜索更快。
五、参考资料如何组织
| 类型 | 用途 | 使用方式 |
|---|---|---|
| 项目内规格文档 | 防架构漂移 | 每条开发消息首行 @ 引用 |
| 业务方案 Markdown | 场景、文案、行业绑定 | 作为内容唯一来源 |
| 配图提示词 | 视觉生成约束 | 与参考图一并提供 |
| 外部算法 / 素材仓库 | 可核验的参数与几何 | 提取数值，而非凭感觉实现 |
| Cursor Skills | 框架与视觉规范 | 实现前 @ 对应技能 |
| MCP / 文档检索 | 库的最新用法 | 查 API，减少幻觉 |
| 互联网检索 | 概念与竞品 | 立项阶段积累，写入 references |
| 用户截图 / 日志 | 验收与排障 | DOM Path + 现象描述 |
心法：先喂资料，再要产出——首条 prompt 的信息量，往往决定后续十轮对话的质量。
六、协作侧高频约束（建议写入 AGENTS.md）
- 中文提交信息与文档；标题简明
- 不修改无关代码；不做无请求的大重构
- 密钥不进仓库；环境变量驱动
- 架构红线写清写死，多次对话中反复确认
- UI 样式体系统一，新页面遵循既有设计约定
- 全功能测试或冒烟清单作为合并门禁（视项目而定）
七、常见陷阱（抽象版）
- 文档与代码脱节：只改实现，不更新规格 → 后续 AI 会话架构漂移
- 版本多处不一致：包版本、制品地址、落地页展示版本未同步核对
- 大范围重写：应用「整体再改一版」→ 应用 DOM 级小步迭代
- 演示内容虚构：对话剧本、数据与真实资料不一致 → 损害可信度
- 组件销毁导致状态丢失：频繁挂载 / 卸载 → 优先隐藏保留实例
- 类型扩展污染主链路：旁路功能未隔离 → 引发隐性耦合
八、给后来者的最短路径
- 读智能体约定 + 需求 / 架构说明，把约束写进第一条消息
- 大功能先 Plan，小改动用 DOM Path 或日志定位
- 数据与契约先于界面；演示剧本按模块分文件
- 视觉素材走「命名 → 压缩 → 同步」管线，避免手工散落
- 每完成一阶段更新任务清单；发版后核对各处版本一致
本文档为团队级归纳，随实践可增量更新。项目专属细节以各仓库 docs/ 规格为准。
