告别 Vibe Coding！SDD 规范驱动开发实战：从文档到代码的 AI 开发新范式

本文基于实际项目 md-wx-chrome-extensions（浏览器翻译插件），完整演示 SDD（Spec-Driven Development，规范驱动开发）的落地流程。

---

一、Vibe Coding 的痛：第一天起飞，第二天返工

Vibe Coding（氛围编程）很上头------打开 Claude Code、Cursor 这些 AI Agent，对着聊天窗口疯狂下任务：

"帮我做一个用户认证系统"

AI 噼里啪啦输出 2000 行代码，看上去跑得起来，心里美滋滋。

然后噩梦开始了：

• 用的什么框架？NestJS？Express？Python？Java？------AI 猜了一个
• 数据库用什么？------AI 又猜了一个
• 第一天效率拉满，第二天发现要返工
• 第一个月陷入自我怀疑：AI 能力明明超强，为什么翻车了？

答案很简单：我们给大模型的上下文不够。

聊天窗口一关，会话历史没了。AI 没有持久化的记忆，只能靠猜。每一轮失败都在消耗时间和词元。

---

二、SDD：规范驱动开发------先写文档，再写代码

Stephen Covey 在《高效人士的 7 个习惯》中提出：以终为始。

优秀老板做事情会经历两次创造：

1. 第一次创造（心智创造）：在大脑中设计好，用文档落地
2. 第二次创造（物理创造）：根据规范，驱动 AI 写代码

不画蓝图就不盖房，不写商业计划书就不创业。

SDD（Spec-Driven Development） 就是把这个理念搬到 AI 开发中：

做什么 → 为什么做 → 怎么做 → 如何一步步做

当代码生成成本越来越低，真正稀缺的是清晰、可执行、可验证的意图。

---

三、SDD 包含哪些文档？

文档	职责	角色
proposal.md	需求定义：系统是什么样，满足什么需求	产品经理
design.md	技术架构：怎么实现，技术选型	架构师
task.md	任务拆解：先干什么，再干什么，什么可以并行	项目经理

三份规范完成第一次创造 （工作内容），代码是第二次创造（Agent 执行）。

Vibe Coding 的问题在于：跳过了第一次创造，直接进入第二次创造。

聊天窗口诱惑我们直接开干，SDD 坚持------所有伟大事物都要经历两次创造。

---

四、实战：md-wx-chrome-extensions 浏览器插件

4.1 项目是什么

一个浏览器插件，核心功能：

• 一键提取英文网页的核心内容
• 调用 AI 模型翻译成中文
• Markdown 格式呈现翻译结果
• 一键复制，方便粘贴到公众号

目标用户：大网红、公众号作者（md-wx = markdown + 微信）

---

4.2 第一步：需求分析（proposal.md）

清晰的定义我们要做什么。

不是直接开写代码，而是先花时间编写并验证需求。

核心功能拆解：

1. 网页内容提取------难点：如何只要正文，去掉广告、导航栏？
2. AI 翻译------模型可配置（DeepSeek、Qwen、OpenAI 兼容接口）
3. Markdown 渲染------使用 npm marked（通用方案）
4. 流式输出------翻译过程实时显示
5. 一键复制------复制到剪贴板

明确不做什么：

• 不是新建项目，需要先阅读已有代码
• 不做全文缓存（成本太高）
• 不做多语言互译（只做英→中）

文档的好处：可共享、可记录。Vibe Coding 一关窗口可能就没了。

---

4.3 第二步：技术框架设计（design.md）

直接关系到项目的成败。一个正确的技术选型，能让后续开发事半功倍。

技术难点攻关：

难点	解决方案
网页只要内容？	上网搜方案，LLM 工具和分析能力很强
AI 模型切换？	强调 OpenAI 兼容方式，切换 Qwen 等无缝
微信格式？	生成 wx markdown 格式

技术栈选型：

• Chrome Extension Manifest V3
• 前端：React + TypeScript
• AI 调用：OpenAI 兼容接口（DeepSeek / Qwen 可切换）
• Markdown 渲染：marked.js
• 流式输出：SSE（Server-Sent Events）

---

4.4 第三步：任务拆解（task.md）

1. 项目初始化 + Git 仓库
2. Chrome Extension 基础框架
3. 网页内容提取模块
4. AI 翻译模块（流式输出）
5. Markdown 渲染 + 复制功能
6. 集成测试 + 发布

什么可以并行？------网页提取和 AI 翻译可以并行开发。

---

五、Git 版本控制：Vibe Coding 的安全网

AI 生成的代码，必须即时版本控制。

出现幻觉怎么办？

情况一：没到暂存区（没 git add）

git restore .

直接丢弃这次修改。

情况二：到了暂存区，没提交

git restore --staged .   # 先移出暂存区
git restore .            # 再丢弃修改

情况三：已经提交了

git reset --hard HEAD^

彻底回退到上一次提交。

养成习惯：每完成一个功能 → git add → git commit。

Git 是 Vibe Coding 的安全网，崩了随时回退。

---

六、管理 AI 会话：上下文是关键

每次开发新功能，开启新的对话，新的上下文。

为什么？

• 旧会话的上下文太杂，AI 会混淆
• 新会话 + 完整的 SDD 文档 = 精准的输出

SDD 文档就是 AI 的持久化记忆，比聊天窗口靠谱得多。

---

七、SDD 的核心理念

对比项	Vibe Coding	SDD
工作方式	埋头就干	先设计，后执行
上下文	聊天窗口（易丢失）	文档（持久化）
可追溯性	差（窗口一关就没了）	强（文档可共享、可记录）
AI 输出质量	靠猜（上下文不足）	精准（文档驱动）
返工成本	高	低

SDD 不是银弹，但它是目前 AI 开发最有效的范式。

---

八、总结

1. Vibe Coding 的问题：上下文缺失 → AI 猜 → 幻觉 → 返工
2. SDD 的解决方案：文档先行，两次创造
3. 三份核心文档 ：proposal.md（做什么）→ design.md（怎么做）→ task.md（分步做）
4. Git 是安全网：每步都 commit，崩了随时回退
5. 上下文管理：新功能开新会话，SDD 文档是持久化记忆

当代码生成成本越来越低，真正稀缺的是清晰、可执行、可验证的意图。

SDD 不是增加工作量，而是把工作做对。AI 时代的工程师价值，不在于调了多少 API，而在于能用工程化思维把 LLM 的能力稳定地产品化。

---

相关项目 ：md-wx-chrome-extensions

技术栈：Chrome Extension · React · TypeScript · DeepSeek API · OpenAI 兼容接口 · marked.js

---

💬 你在 AI 开发中踩过哪些坑？欢迎评论区交流！