从 Vibe Coding 到 SDD：让 AI 写代码之前，先把话说清楚
一、先说说那个"第一个月"
用 AI 写代码的人，大概都经历过同一条曲线：
- 第一天：效率起飞。一句"帮我做一个用户认证系统"，2000 行代码哗啦啦出来，还真能跑。
- 第二周：开始返工。改一个需求牵出三个 bug，翻聊天记录发现——当初根本没说清楚要用什么框架。
- 第一个月：自我怀疑。到底是我不会用，还是它不行？
Claude Code、Codex、Cursor、Trae、Copilot，每一家都宣称"10 倍效率提升"。这话不算撒谎，但它默认了一个前提：你得知道自己要什么。
问题恰恰出在这里。回到那句"帮我做一个用户认证系统"——
用什么框架？NestJS 还是 Python 还是 Java？数据先 mock 还是直接接库？Token 存哪儿？密码怎么加密？
你没说，AI 就得猜。猜对了是运气，猜错了是幻觉。而每一轮猜错的代价是双份的：等待生成的时间 + 烧掉的 token。
再叠加上会话本身的脆弱性——上下文窗口有限、历史记录没持久化、窗口一关就什么都没了——你会发现所谓"AI 能力不行"，很多时候是我们喂给它的上下文不够。
Vibe coding（氛围编程）真正的问题，不是它不好用，而是它太好用了：那个聊天输入框一直在诱惑你不停地下任务，让你跳过了最该做的那一步。
二、核心洞见：所有事物都要经过两次创造
史蒂芬·柯维在《高效能人士的七个习惯》里讲过一个原则——以终为始：任何事物都要经过两次创造，一次在头脑中，一次在现实中。
优秀的老板做一件事，一定是先做完第一遍。
- 第一次创造（心智创造） ：停下来，先写规范、设计项目。在动手之前，先在脑子里把这个系统跑一遍，然后用各种文档把它落地。
- 第二次创造（物理创造） ：根据规范，真正驱动 AI 写出代码。
不画蓝图就不盖房，不写商业计划就不创业。可到了写代码这件事上，我们却觉得可以直接开工。
Vibe coding 的病根，就是跳过了第一次创造，直接冲进了第二次创造。
而 SDD（Spec-Driven Development，规范驱动开发）的主张只有一句：先撰写文档，再编写代码。
这里有个认知需要扭转——写文档不是"额外的负担"，而是新的主要工作内容。当 AI 把 coding 这件事的成本压到接近于零，工程师的工作量正在从"写代码"迁移到"写规范"。稀缺的不再是代码，而是清晰、可执行、可验证的意图。
三、SDD 到底要写哪些文档
四份，各司其职：
| 文档 | 回答的问题 | 说明 |
|---|---|---|
| PRD / 需求文档 | 做什么 | 产品经理视角的原始需求 |
| proposal.md | 为什么做 | 心智创造的载体：这个系统应该长什么样、满足什么需求 |
| design.md | 怎么实现 | 技术架构、技术选型 |
| task.md | 如何一步步做 | 先干什么、再干什么、什么可以并行 |
三份规范完成第一次创造（你的工作），代码是第二次创造（Agent 的工作），然后不停迭代。
工程界已经有了成型的框架，比如 Spec-Kit，可以直接拿来用。
四、实战：一个浏览器插件是怎么"先写文档"的
光讲理论容易飘，看一个真实的小项目：md-wx-chrome-extensions。
它要解决什么：浏览英文网页时，一键提取文章核心内容 → 调用 AI 模型翻译 → 以 Markdown 格式呈现 → 一键复制。
目标用户很具体：那些需要把英文素材搬到公众号的大网红/内容创作者。所以输出格式不是通用 Markdown，而是微信公众号排版友好的 Markdown。
第 1 步：需求分析，而不是需求罗列
分两小步：
- 清晰定义我们要做什么
- 分析和调研——这一步最容易被跳过
比如"一键提取文章核心内容"这个功能，听起来一句话，实际是整个项目的技术难点：网页结构千奇百怪，广告、导航、评论区混在一起，怎么准确抓出正文？
这时候不要自己硬想，也不要直接让 AI 写代码。去和 Claude Code 聊，去用对应的 Skill 聊，多聊几轮，把方案聊出来。LLM 的工具调用和分析能力很强，让它上网搜、让它对比方案——这是普通人快速长出架构师认知的最短路径。
调研的产出是一系列已经决策过的结论：
- AI 模型可配置（DeepSeek / Qwen / ...）
- Markdown 渲染用 npm 的
marked（通用、成熟） - 界面：按钮 + 流式布局
第 2 步：写 proposal 时的几条纪律
这几点是实操中最容易踩坑的地方：
- 明确 MVP（最小可行性单元） 。别一上来就想做全功能，先定义"最小能用"的那个版本。
- 给详细的举例。抽象描述 AI 会自由发挥，具体例子才是约束。
- 指定返回格式。
- 明确告诉它：只生成文档，其他的什么都不要做。 否则你会发现文档还没定稿，它已经把代码写了一半。
- 写清楚"不做什么" 。边界比功能更重要。
- 如果不是新项目，先让它读代码。
写完不算完，还要花时间验证需求。这一步不能走过场——它是程序开发的必备关键流程，不是形式主义。
文档的另一重价值在于：可记录、可共享。Vibe coding 一关窗口可能就全没了，文档不会。
第 3 步：项目准备——版本控制是安全网
创建项目的同时创建 Git 仓库。这在 AI 时代的重要性被放大了：
AI 生成的代码，只要验收通过就立即提交。 这样 vibe coding 才是可追溯、可回退的。
当 AI 出现幻觉、代码跑偏时，按状态分三种回退方式：
# 情况一：还没到暂存区 —— 直接丢弃修改
git restore .
# 情况二：到了暂存区，还没提交 —— 先移出暂存区，再丢弃
git restore --staged .
git restore .
# 情况三：已经提交了 —— 回退到上一个提交
git reset --hard HEAD^
有了这张网，你才敢放手让 AI 干活。
第 4 步：管理 AI 会话
一个简单但关键的习惯：新任务，就开新会话、新上下文。
上下文不是越多越好。前面几十轮讨论需求的对话，在写代码阶段全是噪音。文档已经把该沉淀的都沉淀了，新会话直接喂文档就够了。
第 5 步：技术架构设计
技术选型直接关系项目成败。选对了事半功倍，选错了陷入泥潭。
这个插件的两个关键决策：
- 强调 OpenAI 兼容的调用方式 —— 一套接口，后面想切 Qwen、切别的模型，改配置就行，不用重写。
- 输出格式锁定微信 Markdown —— 从用户场景倒推格式，而不是先做个通用方案再想办法适配。
这两条都不是代码问题，是在写第一行代码之前就必须想清楚的问题。
五、几点总结
- Vibe coding 已经过去了。 不是说它没用，而是它只能作为第二次创造的执行手段，不能作为整个开发流程。
- SDD 不是选修课，是必选项。 它是新的主要工作内容，不是写代码之外的负担。
- 调研阶段多花的时间，会在实现阶段十倍还回来。 尤其是技术难点，先和 AI 聊透方案，再让它动手。
- 写规范时要给约束：MVP 范围、详细举例、返回格式、"不做什么"、"只写文档不写代码"。
- Git 提交要密。AI 生成 → 验收 → 立即提交，这是你敢放手的前提。
- 会话要勤换。文档是持久化的上下文，聊天记录不是。
结语
当代码生成的成本无限趋近于零，真正稀缺的东西浮出水面了——
清晰、可执行、可验证的意图。
SDD 借鉴的其实是建造业和商业里几百年的老智慧：不画蓝图不盖房，不写计划不创业。它不是什么新发明，只是在 AI 把执行成本打到地板之后，设计的价值第一次变得如此显眼。
停下来，先把话说清楚。这是现在最划算的投资。
