被 Vibe Coding 反噬之后，我老老实实地回去写文档了

事情要从我想做的那个浏览器插件说起

那段时间我脑子里一直有个想法：做个浏览器插件，在英文网页上点一下，自动把文章正文提出来，丢给 AI 翻译成中文，渲染成 Markdown，再一键复制------目标用户是做公众号的那帮朋友，英文版块直接搬成中文版。

我在对话框里敲了一句"帮我做一个浏览器插件，能提取网页正文、调用 AI 翻译、导出 Markdown"，然后 AI 唰唰吐了几千行代码。

说实话，第一天是真的上头。插件居然装到 Chrome 里跑起来了，demo 页面上翻译结果像模像样。我当时觉得"十倍效率提升"真不是吹的。

然后第二周，开始返工。

"提取正文"这个功能在各种网站上花式翻车：导航栏被当成正文、广告混进翻译里、分页文章只抓到第一页。我让 AI 修，修了 A 坏了 B。更崩的是，新开会话之后它完全不记得之前的决策------为什么选这个方案、哪个文件改过、为什么改，全没了。它只能猜，猜错就是幻觉，每一轮返工都在烧我的时间和 token。

真正让我停下来的是一个差点崩盘的晚上：AI 一次"优化"把整个提取逻辑改挂了，我看着满屏报错，脑子里只有一个念头------上一个能跑的版本，我好像没提交。

问题到底出在哪

后来我才想明白，AI 没毛病，是我的用法有问题：我跳过了"想清楚"这一步，直接让它"干出来"。

这就像盖房子不画图纸，工人手快不是什么好事，墙砌得越快，等发现卧室没留门的时候就越绝望。《高效能人士的七个习惯》里讲"以终为始"，说任何事物都要经历两次创造：第一次是心智创造，在脑子里把它设计出来；第二次才是物理创造，真刀真枪盖出来。

Vibe Coding 的病根，就是被聊天窗口诱惑着，跳过第一次创造，直接冲进第二次。

Spec-Driven Development（规范驱动开发，简称 SDD）干的事说穿了就一句话：先把脑子里的设计落成文档，再让文档驱动 AI 写代码。 当写代码的成本越来越低，真正稀缺的不是会写代码的 AI，而是一份清晰、可执行、可验证的意图。

文档不用多，按需来，核心就三份：

proposal.md：要做什么、为什么做，边界在哪
design.md：怎么实现，技术架构和选型
task.md：先干什么后干什么，哪些能并行

拿我的插件真走一遍

先把 MVP 抠到最小

重新开工，我没让 AI 写一行代码，先写 proposal.md，逼自己把需求抠到最小可行单元：

markdown 复制代码

## 要做什么
在英文博客页面一键完成：
提取正文 → 调 AI 翻译成中文 → Markdown 渲染 → 一键复制

## 不做什么
- 不做收藏夹、历史记录
- 不做账号系统
- 不做中英以外的语种
- 不做整页翻译，只翻正文

"不做什么"这栏特别重要，它是用来拦 AI、也拦我自己的。没这栏，AI 会热情地给你加上登录、云同步、深色模式......最后做出来一个谁都不需要的东西。

技术难点要摊开写，不能糊弄

然后是 design.md，把难点一条条摊在桌面上：

markdown 复制代码

## 技术难点
1. 正文提取：网页结构千奇百怪，先调研 Readability 类方案
2. AI 接入：统一走 OpenAI 兼容格式，deepseek、qwen 只改配置
3. Markdown 渲染：用 npm 的 marked
4. 输出格式要适配微信公众号（标题、引用、代码块样式）

比如"AI 模型可配置"这条，写下来之后选型就顺了：不绑死任何一家，全按 OpenAI 的接口格式对接，想换模型只改 baseURL 和 key。这种决策在聊天里随口就定了，没文档的话，三个会话后保证忘得一干二净。

写文档不是写给同事看的，是喂给 AI 的上下文。会话一关上下文就清零，但文件还在。新会话开场不用重新解释项目，一句"先读 proposal.md 和 design.md"，它就全想起来了。

真正的后悔药：小步提交

文档解决了"想清楚"的问题，但 AI 写代码照样会幻觉。另一条铁律我是拿血泪换来的：AI 生成的代码，跑通一个可验收的版本，立刻提交。 有版本兜着底，它幻觉它的，我随时能退。

那天晚上之后，我把"改坏了怎么退"练得特别熟。改动出问题，分三种情况，对号入座：

shell 复制代码

# 情况 1：改了文件，还没 git add ------ 直接丢弃工作区修改
git restore .

# 情况 2：已经 git add 进了暂存区，但还没 commit
# 先把改动移出暂存区，再丢弃。别问我为什么知道，试了三次
git restore --staged .
git restore .

# 情况 3：已经 commit 了 ------ 硬回退到上一个提交
git reset --hard HEAD^

情况 2 坑了我最久。我原以为 git restore . 是万能的，结果暂存区里那份坏代码纹丝不动，回头 AI 还基于它继续改，错上加错。后来才搞明白：工作区和暂存区是两层，得一层层往外退。

实际跑一遍长这样：

shell 复制代码

$ git status
On branch main
Changes not staged for commit:
  modified:   src/extractor.js

$ git restore .
$ git status
On branch main
nothing to commit, working tree clean

git reset --hard HEAD^ 会把当前提交之后的改动全扔掉，敲回车前先 git status 看一眼，确认那些改动你真的不要了。

有了频繁提交的习惯，心态完全不一样了。以前是"AI 你可千万别给我改坏了"，现在是"随便改，改坏了一条命令回到能跑的版本"。这大概就是版本控制给 Vibe Coding 上的保险。

再往深想一层：文档治的到底是什么病

用了一段时间我意识到，SDD 治的不是"AI 写代码不行"，是上下文丢失。

聊天记录不是持久的，窗口一关、会话一长，早期的决策就被挤出上下文了。而"一键提取文章核心内容"这种话，敲下来只要十秒，真要落成可执行的规范，你得回答一堆问题：什么算核心内容？导航菜单要不要？评论区呢？分页文章怎么办？

这些问题你不回答，AI 就只能猜。你把答案写进文档，它每一轮都读得到，猜的空间就没了。所以写文档这个动作本身，就是在替未来的每一次对话把上下文存档------顺便还能逼自己把事情想明白，属于买一送一。

最后说点实在的

走完这一遍，最值钱的三个体会：

一是万事真的有两次创造，动手前让脑子里那遍先发生，哪怕只花半小时；二是文档不是应付检查的交付物，它是 AI 的上下文存档，写给它看，也顺便治自己的糊涂；三是小步提交是后悔药，没有频繁 commit 兜底，让 AI 改代码跟裸奔没区别。

不过这玩意儿也不是万能的。你要是周末花两小时写个一次性脚本、用完就扔，那真别搞三份文档，那是给自己加戏。问题规模小到脑子装得下、会话不会断，流程就是负担。SDD 真正适合的，是那种要跨好几个会话、有明确技术难点、还打算长期迭代的项目------比如我这个到现在还在改的翻译插件。

对了，如果你也被 AI 的幻觉坑过，或者对 git 那两层区域有不一样的理解，搞懂了记得回来留个言，我也想看看你是怎么从坑里爬出来的。