从 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 出现幻觉、代码跑偏时，按状态分三种回退方式：

perl 复制代码

# 情况一：还没到暂存区 ------ 直接丢弃修改
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 把执行成本打到地板之后，设计的价值第一次变得如此显眼。

停下来，先把话说清楚。这是现在最划算的投资。