A Field Guide

Vibe Coding
实战手册

一个策划 × 一个 AI
80 天 · 20 个项目

2534 commits
9016 tests
92 skills
228+ reviews

从跨年夜写第一个城市模拟器，到多 Agent 并行驾驭 9 个正式工程项目

↓
01
DEFINITION

Vibe Coding 是什么

（不是什么）

Vibe Coding ≠ "让 AI 随便写代码"。
它是一种人机协作工程范式。

🧠

人

方向、决策、验收

⚡

AI Agent

执行、搜索、生成、验证

📐

中间层

结构化约定
文件，不是口头

核心命题：一个人如何同时驾驭十几个项目，而不让任何一个失控？

答案是三个词：纪律、复用、验证。

02
ORIGIN

从混乱中长出秩序

起源故事

用 fix 脚本修 fix 脚本的 bug

2025 年跨年夜，第一次 Vibe Coding——用 AI 写了一个城市模拟器和一个修仙放置游戏。没有 Git，没有测试，所有文件平铺在一个文件夹里。

修仙游戏留下了考古遗迹：4 个 fix_*.py。AI 的 70KB 代码有结构性错误，于是让 AI 写修复脚本——但修复脚本本身也有 bug，于是又写了第二个、第三个……

原始 Vibe Coding：用代码修代码的 bug，用新代码修修复代码的 bug。

同一个梦想，5 个文件夹

真正想做的是一款 LLM 驱动的 CRPG。4 天内从零开始了 5 次：

日期文件夹结局
2.09 下午AIProject3当天放弃
2.09 傍晚AIProject4当天放弃
2.09 晚上AICRPG持续到 2.11
2.11AIcrpg2空文件夹
2.13AICRPG31.1MB 设计，0 行代码
1.1MB 完美设计 + 0 行实现 = 精美的幻觉。
02
TURNING POINT

觉醒：先造工具，再造产品

被 50 天的混乱教训后，第一次使用 Agent 干的不是写产品——而是给 AI 建"记忆系统"和工程规范。

第一条记录在案的经验教训（P-01）：

执行前验证前置条件，不要一看到信号就行动。

这条到第 80 天依然是最高频被违反和重新学习的原则。

纪律不是知道了就会遵守的，它需要反复犯错来内化。
03
LESSONS LEARNED

血泪教训清单

按痛感排序 · 上

P0

部署 ≠ 修复

  • commit 了 fix 但忘了重新 build，线上跑了一天旧代码没人发现
  • 一次不小心 build 打入了未提交的实验代码，全站闪烁，紧急回滚
铁规：build 前 git diff --stat 确认工作目录干净；部署后线上验证
P0

API 静默吞错误

3 个不同功能的"页面空白但不报错"，根因都是 catch 块返回空数组而不是 throw。这种 bug 不会报错，只表现为"功能不存在"。

P0

God File 是项目的癌症

AutoMater 的 orchestrator.ts 膨胀到 1852 行、meta-agent.ts 2376 行。拆分后平均减少 50% 行数，效率立刻翻倍。

// 硬限制
JS/TS ≤ 800 行  |  React 组件 ≤ 200 行  |  设计文档 ≤ 150 行/文件
P0

git add -A 是并行开发的定时炸弹

两个 AI 会话各自 git add -A，把对方的未完成改动混入了自己的 commit。

唯一正确做法：git add <具体文件>
03
LESSONS LEARNED

血泪教训清单

按痛感排序 · 下

P1

LLM 输出的 JSON 一定会损坏

一层 JSON.parse 完全不够，需要五层降级解析策略。这是 Vibe Coding 中最被低估的工程挑战。

P1

迁移文件命名事故

团队页面空白整整一天。所有层面检查均正确。最终发现：迁移文件名的一个 b 后缀被 Supabase CLI 静默跳过——表缺少 5 个关键列，不报错。

P1

三端坐标系统一

前端（Three.js Y-up）、UE5（Z-up cm）、Unity（Y-up m）。
必须在项目初期定义 Canonical Schema，等对接时再转换 = 盲人拆弹。

P1

同一份代码 4 个物理副本

不同会话在不同副本上编辑，最终 339 行差异（整个材质系统丢失）。

解法：用 Junction / Symlink 消除副本，只保留一个 Golden Source
04
METHODOLOGY

CLAUDE.md：AI 的入职手册

方法论精华 · 4.1

每次新 AI 会话都是一张白纸。CLAUDE.md 是恢复上下文最快的方式。

7 段必备结构

01 项目使命
02 技术栈
03 活跃决策（含"为什么这样决定"）
04 当前状态
05 协作规范
06 禁止事项
07 项目结构地图
最重要的纪律：每次 commit 涉及进度变化 → 必须同一 commit 更新 CLAUDE.md。
不同步 = 下次 AI 基于过时信息工作 = 灾难。
MuseSea 前 4 次 commit 消息就是字面意义上的"提交"二字。直到实际吃了"AI 不记得上次做了什么"的亏，CLAUDE.md 才开始被认真执行。
04
METHODOLOGY

审查 > 开发

最反直觉的结论 · 4.2

写出第一版只需 1 天，让它达到可信赖的质量需要 5–30 倍的时间。

项目0 → 首版→ 质量达标审查轮次测试增长
NewCRPG1 天30 天41 轮374 → 1664
MuseSea-Studio1 天8 天20 轮987 → 3731
NovelForge1 天5+ 天70 轮26 → 691

审查方法论（分层递进）

1. 安全 → 数据完整性 → 内存泄漏 → 竞态 → 类型 → 状态管理 → 错误处理
2. 写代码的 Agent 和审代码的 Agent 必须分离
3. 修复后 tsc + test + build 三重验证
4. 35 轮审查后新一轮发现 0 问题 // 多轮审查确实能推到稳定态
MuseSea 12 轮审计发现 259 个问题（42 个 P0）。
如果在线上被发现，修复成本是审计时的 10 倍。
04
METHODOLOGY

技能复用 & 上下文管理

4.3 — 4.4

两次法则

1st 遇到 → 解决就好
2nd 立刻提取为 Skill
3rd 加载 Skill，10 分钟搞定

6 周积累 92 个可复用技能

上下文：最稀缺的资源

AI Agent 的本质瓶颈不是智能，是上下文窗口。

› 按需加载 — 索引存 summary，命中才读全文
› 上下文卸载 — 中间结果写文件
› 子 Agent 委派 — 3+ 文件查找交给子 Agent
› 防目标漂移 — 每 3 步写 Checkpoint
› 设计文档分片 — 单文件 < 150 行
内网 API 跨域方案在 3 个项目中出现。第一次半天，提取 Skill 后第三次 10 分钟。
04
METHODOLOGY

验证驱动 & 纪律 > 智能

4.5 — 4.6

AI 的输出是草稿，不是成品。

层次方法时机
编译tsc --noEmit每次修改后
测试vitest run每次修改后
构建build每次提交前
视觉独立子 Agent 截图评审UI 修改后
线上搜索 minified 代码中的字符串常量部署后

纪律 > 智能

Agent 连续工作 15+ 轮后会出现"纪律疲劳"——跳过验证、忘记更新文档、在错误目录编辑文件。

  • 每 5 个 commit 做一次卫生检查
  • 同一问题重试 3 次无果 → 记 known issue，停止
  • 硬约束写在代码里，不写在 prompt 里。Prompt 会被忽略，Guard 代码不会
05
EVOLUTION

并行能力的四级进化

Lv.0   单会话单项目
一个对话做一切 Day 1–3
Lv.1   同项目多会话
两个 AI 窗口改同一仓库 → git add -A 翻车 → 建立互感机制 Day 4–10
Lv.2   多项目并行
CLAUDE.md 仪表盘 + 记忆索引按需加载 → 旅游期间手机远程推进 Day 16–22
Lv.3   多 Agent 协作
专业化子 Agent + 调度器 + 写审分离 Day 28–30
理论给了方向，实践给了分寸。蓝图可以一天画完，让蓝图变成本能需要 80 天的犯错。
06
INSIGHTS

10 条反直觉认知

上篇 · 1–5

01
最好的 Agent 方案可能不用 Agent。
Echo-Scheduler 从"Agent 巡逻（30分钟响应）"改为"Python 协程（30秒轮询）"，成本归零。
02
审查的 ROI 高于开发。
42 个 P0 如果在线上被发现，修复成本是审计时的 10 倍。
03
文件小一点 > 代码好一点。
800 行完美代码不如 4 x 200 行普通代码——AI 能理解后者但理解不了前者。
04
"为什么这样决定"比"决定了什么"重要。
知道 why 能在新场景做一致判断；只知道 what，换场景就矛盾。
05
重复是信号，不是噪音。
出现两次 = 需要系统性方案，而非两次临时修复。
06
INSIGHTS

10 条反直觉认知

下篇 · 6–10

06
"先做完再审"不如"边做边审"。
AutoMater 先到 v35 再回头审，God File 已经很难拆了。
07
"新建文件夹"是最昂贵的操作。
同一想法 5 个文件夹，每次从零开始。引入 Git 后变成 revert——经验不再丢失。
08
"必须记得执行"的步骤一定会被遗忘。
初代记忆系统设计了 8 步 shutdown 流程，结果 scratchpad 里留着 3 条未合并的 pending_items。改为 write-through 即时持久化后问题消失。
09
自动化部署是效率的分水岭。
Day 1 跑通时不觉得重要，旅游时才意识到它是一切的地基。工作流的可靠性决定了人的自由度。
10
设计文档不等于产品。
1.1MB 完美设计 + 0 行实现 = 最舒适的幻觉。没有实现和验证的闭环，设计只是精美的空气。
07
DATA

数据总览

80 天的量化成果

80
天
20+
项目
2534
Git 提交
9016
测试
228+
审查轮次
500+
审计问题
92
可复用技能
v5.1
记忆系统

最大 God File

2376 行 （已拆分）

审查最密集项目

70 轮 NovelForge

工具越强大，纪律越重要。

Vibe Coding 不是"让 AI 干活人来躺"——它是一种需要更高密度思考的工作方式。你省下的是打字时间，增加的是决策密度和验证密度。

纪律 → 用约定和检查替代信任
复用 → 出现两次就沉淀，出现三次就自动化
验证 → AI 的输出是草稿，永远需要一道外部验证

有纪律的 Vibe Coding 可以让一个人做到过去一个小团队的产出。
没有纪律的 Vibe Coding 只会快速制造一堆看起来能跑但经不起推敲的代码。

区别不在于 AI 的能力，而在于人类是否建立了让 AI 能力可靠释放的框架。

BY TIM · 80 DAYS · 2534 COMMITS
← → 或滚轮翻页