告别 Vibe Coding：用 SDD 把一个 Chrome 翻译插件从 0 做到 1

一个真实的实践复盘：如何用「文档先行」的规范驱动开发（SDD），配合 AI Coding Agent，做出一个可验收、可回退、可迭代的浏览器插件，而不是陷入「第一天上头、第二周返工」的泥潭。

一、Vibe Coding 的甜蜜陷阱

每一个声称能带来 10 倍效率提升的工具，都逃不过这个剧本：

• 第一天：效率飙升。对着 AI 说一句「帮我做个用户认证系统」，它哗啦生成 2000 行代码，看起来还能跑。
• 第二周：开始返工。你发现它用的框架不是你想要的、数据层是猜的、边界条件没处理，开始不断追问、补丁摞补丁。
• 第一个月：陷入自我怀疑。上下文丢了、会话历史没了、AI 开始「幻觉」，每一轮失败都在消耗你的等待时间和 token。

这就是 Vibe Coding（氛围编程） 的本质问题------它让我们跳过了第一次创造，直接进入了第二次创造。

两次创造

Stephen Covey 在《高效能人士的七个习惯》里讲过一个原则叫「以终为始」：优秀的人，一件事会经历两次创造。

1. 第一次创造 ------ 心智创造：在动手之前，先在大脑里把这件事「做」一遍，想清楚它是什么样、怎么实现。
2. 第二次创造 ------ 物理创造：照着蓝图，真正把它做出来。

不画蓝图就不盖房，不写商业计划就不创业。写代码也一样------不写规范，就别急着让 AI 写代码。

而 Vibe Coding 的陷阱，恰恰是聊天窗口的即时反馈太诱人，让我们一步跨到了「物理创造」，把「心智创造」这个关键环节整个省掉了。

二、SDD：规范驱动开发

SDD（Spec-Driven Development，规范驱动开发） 就是要把「第一次创造」补回来。

当代码生成成本越来越低，真正稀缺的不再是「能写出代码」，而是清晰、可执行、可验证的意图。这就是 SDD 的核心主张：

文档即是代码，规范驱动开发。

flowchart LR A[Vibe Coding<br/>直接写代码] --> B[上下文缺失<br/>AI 靠猜] B --> C[幻觉 / 返工 / 自我怀疑] D[SDD<br/>文档先行] --> E[proposal 需求] E --> F[design 架构] F --> G[tasks 任务] G --> H[按规范驱动 AI 写代码] H --> I[可验收 / 可回退 / 可迭代]

SDD 把「写文档」从被淡忘的体力活，变成新的、有效的核心工作内容。

SDD 包含哪些文档？（按需加载）

文档	对应角色	回答的问题
proposal.md	产品经理（PRD）	做什么、为什么做、不做什么
design.md	架构师	怎么做、技术选型、目录结构
tasks.md	项目经理	先干什么、后干什么、什么能并行
rules/	团队规范	AI 必须遵守的高层原则

这三份规范完成第一次创造，代码是第二次创造（交给 Agent），然后不停地迭代。

三、实战：Chrome 翻译插件

光讲道理太空，下面用一个真实项目 chrome-extention-en-translation 走一遍完整流程。

3.1 项目是什么

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

• 浏览英文网页时，一键提取文章核心内容；
• 调用可配置的 AI 模型（DeepSeek、Qwen...）翻译；
• 翻译结果以 Markdown 格式呈现；
• 一键复制，方便粘贴到公众号 / 掘金等平台。

MVP 就这四件事，不做什么也明确：不做历史记录、不做账号体系、不做收藏，只本地保存最近一次结果。

3.2 第一步：需求文档 proposal.md

第一步永远是清晰定义「我们要做什么」，而不是直接开写。

• 明确做什么：一键提取 → 转 Markdown → AI 翻译 → 打字机展示 → 下载。
• 明确难点：正文提取是整个插件的关键和难点------如何从任意网站剥离导航/广告/侧边栏，只留下正文？
• 明确输出格式：最终结果严格遵循固定结构（标题 / 作者 / 原文链接 / 正文）。
• 明确不做什么：不提供历史记录、不提供账号体系等。

关于「正文提取」这个难点，正确的做法是先调研、多和 AI 聊几轮、查资料 ，得到可靠方案后，再写进文档。这里我们得到的结论是：用 Mozilla Readability （Firefox 阅读模式同款引擎）提取正文，用 Turndown 转 Markdown。

关键点：需求文档只写「是什么」，不写实现代码。写完即停，交给下一步。

3.3 第二步：技术架构设计 design.md

技术选型直接决定项目成败------选对了事半功倍，选错了陷入泥潭。这一步扮演的是架构师角色。

两个关键技术决策：

1. 翻译接入用 OpenAI 兼容方式 ：用 openai SDK，只改 base_url / api_key / model 三处，就能在 DeepSeek、Qwen 之间自由切换。不绑定任何一家。
2. Markdown 渲染用 md-wx：专为公众号优化的 React Markdown 渲染组件，正好满足「微信 Markdown 格式」的诉求。

同时确定清晰的目录结构 （按 MV3 的 background / content / popup / panel 四个运行时上下文拆分）和编码规范。

3.4 第三步：页面布局 layouts

用 ASCII 字符画出每个页面的草图，按页面分文件。这一步让「界面长什么样」在写代码前就有个样子。

• Popup 入口弹窗：核心只有一个「⚡ 一键翻译」按钮 + 状态 + 设置入口，极简。
• Panel 结果面板：打字机展示译文 + 「下载」「复制」，突出翻译与下载。

┌──────────────────────────────────────────────┐
│ ① 🔤 英文网页翻译                             │
├──────────────────────────────────────────────┤
│ ② 目标页面（当前页标题 / 域名摘要）            │
├──────────────────────────────────────────────┤
│ ③      ┌──────────────────────────┐          │
│        │       ⚡ 一键翻译         │          │
│        └──────────────────────────┘          │
├──────────────────────────────────────────────┤
│ ④ 状态：● 提取中 → 翻译中 → ✅ 完成           │
├──────────────────────────────────────────────┤
│ ⑤ ⚙ 设置（API Key / 模型）                    │
└──────────────────────────────────────────────┘

3.5 第四步：任务拆分 tasks.md

把「第二次创造」拆成一个个单一任务 ，每个任务有明确的范围 和验收标准，让 AI 逐个执行、逐个验收。

阶段 0 工程基础   0.1 初始化构建链 → 0.2 共享类型/消息 → 0.3 存储层
阶段 1 正文提取   1.1 提取管线 → 1.2 元数据与图片处理
阶段 2 AI 翻译    2.1 Qwen 流式 → 2.2 提示词与输出格式
阶段 3 Popup      3.1 骨架 → 3.2 触发状态 → 3.3 设置
阶段 4 Panel      4.1 流式接入 → 4.2 打字机/md-wx → 4.3 下载复制 → 4.4 持久化
阶段 5 联调       5.1 端到端 → 5.2 错误与边界

配合项目规则 rules/project_rules.md 里的「AI 助手任务执行规范」：

• 单一任务原则：每次只执行一个明确编号的任务，完成后等待确认。
• 禁止自动扩展：不基于其他文档自行加戏。
• 验收自检 ：完成后对照 tasks.md 的验收标准自检。

3.6 工程实践：把「可回退」当成安全网

AI 生成的代码，必须即时版本控制------这样出现幻觉时才能追述、回退。

# 没到暂存区：直接丢弃这次修改
git restore .

# 到了暂存区但没提交：先移出暂存区，再丢弃
git restore --staged .
git restore .

# 已经提交了：回退到上一个版本
git reset --hard HEAD^

另一条铁律：管理 AI 会话。新任务开新会话、新上下文，别让上一个任务的脏上下文污染下一个任务。

四、需求迭代：文档和代码一起进化

项目不是写完就完，新需求会不断进来。关键是：先改文档，再改代码，保持两者一致，用 git 跟踪变更。

举个例子，做完第一版后有了个新需求：

当前 popup 是弹窗形式，能不能改成从右侧滑出、高度撑满整页？因为翻译内容可能很长。

正确的姿势不是直接让 AI 改代码，而是：

1. 先调研：Chrome 插件的 popup 能不能这样做？（答案：可以，用 Chrome Side Panel 侧边栏 API。）
2. 改文档 ：把方案更新到 design.md / layouts，让「界面」从 popup 变成侧边栏。
3. 再改代码：按更新后的文档驱动 AI 实现。
4. git 提交：文档和代码的一致性被 git 完整跟踪。

这就是「新需求迭代」的正确节奏------文档和代码生成保持一致，git 可以跟踪。

五、写在最后

SDD 不是什么玄学，它回答的是一组最朴素的问题：

• 做什么（proposal）------不写需求就写代码，等于不画蓝图就盖房。
• 怎么做（design）------一个正确的选型，能让后续事半功倍。
• 按什么顺序做（tasks）------先干什么、后干什么、什么能并行。
• 按什么规矩做（rules）------给 AI 的高层原则，而不是让它自由发挥。

Vibe Coding 的教训是：跳过第一次创造，直接进入第二次创造，死得越快。 SDD 坚持「所有事物都要经过两次创造」------第一次在大脑里（用文档落地），第二次才动手（让 AI 写代码）。

当代码生成越来越便宜，清晰、可执行、可验证的意图，才是真正稀缺、真正值钱的东西。

如果你也在用 AI 写代码，不妨试试：先停下来，把规范写清楚，再让 AI 动手。 你会发现，慢下来，反而更快。