个人知识库

2026-07-23-woshipm-vibe-coding-system-pitfalls

10分钟阅读

让AI从零做完一个系统，这几条避坑铁律我建议你先看再动手

「Vibe Coding AI编程实战」第7篇收尾：智能数据分析代理完成前后端联调；铁律是固定一方（后端真实字段）再让另一方适配、人当「仪表盘」盯服务状态、用真实 API Key 跑全链路防「假测试通过」、MCP 按需 + Rules 大道至简，维护文档比维护代码更关键。

基本信息

  • 来源类型：文章（人人都是产品经理 · share）
  • 原文位置：raw/articles/2026-07-23-woshipm-vibe-coding-system-pitfalls.md（Telegram stub 2026-07-23-212459-tg-3f791d.md 回填）
  • 提取路径：raw/extracts/20260724-001438/woshipm.com/ai.md（Converter: defuddle）
  • 原文 URL：https://www.woshipm.com/share/6433991.html
  • 作者：东哥说AI（页面字段含 Jonnystone / 东哥说AI）
  • 发布日期：2026-07-22
  • 页面信息：约 867 浏览 · 7 分钟读 · 1 评论（抓取时）
  • 消化日期：2026-07-24
  • 系列定位：「Vibe Coding AI编程实战」第7篇 / 智能数据分析代理收尾篇
  • 抓取信息：baoyu-url-to-markdown · URL_CHROME_HEADLESS=1 · extract 20260724-001438

核心观点

  1. 联调铁律：固定一方「准」，另一方去适配
    翻车常见于前后端两边都不确定。作者做法：联调前切 Claude Code Plan 模式，让 AI 对比前端接口与后端真实返回字段；以后端真实字段为准，前端适配（后端上一阶段逐个测过，字段可信）。两边都飘 → AI 自我怀疑、来回改、debug 无头。固定基准是联调一次过的前提。

  2. 阶段4交付：API 服务层 + SSE 流式 + 图表绑定 + 端到端测试
    字段对齐后做三件事：前端封装 API 服务层、实现 SSE 流式接收、绑定图表数据，再跑端到端。典型坑：① SSE「响应完整性」——后端必须推结束标识，前端才停监听；② 删除会话接口清理步骤失败——报错丢给 AI 自改；③ AI 又新建虚拟环境，双 venv、多占 8000 端口，后端起不来。

  3. 人的角色是「看仪表盘」，不是甩手掌柜
    服务起不来时，若不告知「已有多余虚拟环境」，AI 第一反应往往是再建一个，越修越乱。人要结合端口、进程、虚拟环境判断方向；写代码可交 AI，服务状态与环境卫生必须人盯。

  4. 「假测试通过」是最隐蔽的坑
    AI 报端到端「通过」，实则未配大模型 API Key，只验了 UI 框架与接口连通，没跑真实 LLM 对话。正确验收：真实 Key + 全链路 提问 → 理解意图 → 生成 SQL → 查库 → 出图 → 回答。涉及外部服务的接口，禁止只信口头「测试通过」。

  5. 上下文记忆会「偷懒」
    同会话重复提问时，Agent 可能直接复用历史答案，跳过 NL2SQL，图表变「暂无数据」。处置：新建会话再测，强制走查库路径。

  6. MCP 按需接 + Rules 大道至简 + 维护文档不维护代码

    • MCP：全接会吃 Token、占上下文、搞乱架构；按需（用 LangChain 才接 LangChain MCP、任务管理才接 Linear），并用 Rules 按文件类型触发（改 .py 才加载对应 MCP）。
    • Rules：别迷信万能规则；别抄通用模板、别硬手写——喂官方文档 + 需求让 AI 写；先最简 MVP，同一处反复犯错再迭代规则。
    • 范式：全程维护的是需求文档、调研报告、Plan、字段规范——文档越准，AI 越稳；流程可迁移到下一项目。

实操内容保留

代码/配置

（本文无完整代码块；以联调与验收流程为主。）

Prompt 模板

（本文无独立 Prompt 模板；联调前可用 Plan 模式指令示意：）

进入 Plan 模式，不要先改代码。
请对比：
1) 前端声明的接口与字段
2) 后端真实返回（以已跑通接口为准）
列出不匹配项，并给出「以后端真实字段为准」的前端适配清单。
确认前不要同时改前后端。

操作步骤

前后端联调与端到端验收清单（可复用）

  1. 联调前切 Plan 模式：对齐前端契约 vs 后端真实字段；固定后端为真源，前端适配。
  2. 阶段交付：API 服务层 → SSE 流式（含结束标识）→ 图表数据绑定。
  3. 环境卫生：检查是否出现重复虚拟环境、多进程抢同一端口（文中示例 8000）；禁止让 AI 无提示地「再建一个 venv」。
  4. 拒绝假通过：配置真实 API Key；跑全链路 提问→意图→SQL→查库→出图→回答。
  5. 会话隔离：怀疑记忆偷懒时，新会话重测 NL2SQL。
  6. MCP：按当前任务接入；Rules 按扩展名/路径触发，避免全量挂载。
  7. Rules：官方文档驱动生成 → 最简 MVP → 仅对反复错误点加规则。
  8. 资产沉淀：持续更新需求文档 / Plan / 字段规范，而非只盯生成代码。

关键概念

  • Vibe Coding — 本篇为系列实战收尾，强调联调与治理而非「一次生成」
  • Claude Code Plan 模式 — 联调前字段对比与适配清单的入口
  • 智能数据分析Agent — 项目对象：NL2SQL + 出图 + 对话代理
  • 假测试通过 — AI 声称通过但未覆盖真实外部依赖（新建）
  • MCP 模型上下文协议 — 按需接入、按文件类型加载，防 Token/架构膨胀
  • MVP — Rules 与功能都先最小闭环
  • 经验沉淀 — 文档/字段规范/Plan 才是长期资产
  • LangChain MCP / Linear MCP — 文中举例，按任务选用（纯文本）
  • SSE 结束标识 / 双虚拟环境 / NL2SQL 记忆偷懒 — 工程坑点（纯文本）

与其他素材的关联

原文精彩摘录

联调最容易翻车的地方，是前端和后端两边你都不确定对不对。……关键是以后端真实字段为准，让前端去适配。……如果你两边都不确定，AI会陷入自我怀疑，一会儿改前端一会儿改后端，反复debug找不到头。固定一方、适配另一方，是联调能一次过的前提。

端到端测试报”通过”，我一查，AI压根没配大模型的API Key，它所谓的”测试”只验了UI框架和接口连接，没跑真实的LLM对话。这种”假通过”最坑人……后来我让它用真实API Key、跑完整的对话流程来测：提问→理解意图→生成SQL→查库→出图→回答，整条链路走完，才敢说”通过”。

完全甩手交给AI，它会在你眼皮底下做一堆莫名其妙的事。你的角色是当那个”看仪表盘的人”，AI偏了就拽一把，写代码的事交给它就行。

整个项目做下来，我维护的始终是文档，不是代码。需求文档、调研报告、Plan规划、字段规范，这些越来越准，AI照着写就越来越稳。

相关页面

关系图谱

快速导航

反向链接