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

黄敬峰 2026-08-20 14 阅读5分钟

本文基于实际项目 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 开发中踩过哪些坑？欢迎评论区交流！