SDD 规范驱动实战：我用 Vibe Coding 开发了一个 AI 网页翻译 Chrome 插件
阅读英文技术文章时，你是不是也经历过：复制段落 → 丢进翻译工具 → 格式乱掉 → 再粘回笔记软件 → 手动排版。折腾半天，真正阅读的时间还没排版多。
我最近用 Vibe Coding + SDD（Specification-Driven Development，规范驱动编程）的方式，开发了一个 Chrome 插件：md-wx-chrome-extensions。它能在英文网页上一键提取正文，调用 AI 模型翻译，然后用 Markdown 格式渲染出来，最后一键复制到公众号编辑器。
这篇文章不是纯理论，而是一次真实项目的完整复盘。你会发现：在 AI 能疯狂产出代码的时代，写清楚需求反而成了最核心的工程能力。
一、SDD 文档先行：四个文档，四道保险
很多人用 AI 写代码，上来就是一句：“帮我写个翻译插件。”然后 AI 哐哐生成一堆代码，跑起来发现：提取的正文全是导航栏和广告，翻译接口写死了 OpenAI，界面还是个半成品。
问题出在哪儿？你没有先写文档。
SDD（规范驱动编程）的核心就是：先让 AI 生成完整的规范文档，充分对齐意图，再动手写代码。在我的项目里，第一步不是敲代码，而是让 AI 依次产出四个文档：
proposal.md → 需求文档：做什么、不做什么 design.md → 技术设计：怎么做、选什么技术 task.md → 任务拆分：按什么顺序做 layout.md → 界面布局：界面长什么样、怎么交互这四个文档就像盖楼前的四张图纸：需求图告诉你盖什么楼，设计图告诉你用什么结构，施工图告诉你先砌哪面墙，装修图告诉你房间怎么布置。图纸齐了，AI 这个施工队才不会乱来。
我通常会这样对 AI 说：
“请先阅读项目背景，然后依次生成 proposal.md、design.md、task.md、layout.md 四个文档。只生成文档，不要写任何代码。等我确认文档无误后再开始编码。”
二、proposal.md：先把“做什么”和“不做什么”说清楚
第一个文档是需求文档，核心就两件事：定义 MVP 和明确边界。
MVP（最小可行性单元）不是把功能做少，而是用最小的成本验证最核心的价值。这个插件的 MVP 就是：
- 提取当前页面的正文
- 调用可配置的 AI 模型翻译
- 以 Markdown 格式渲染
- 一键复制
至于用户系统、翻译历史、多语言互译、收藏夹……统统不做，写进文档的“非目标”部分。
为了让 AI 理解得更准确，我还会在 proposal.md 里写详细的示例。比如翻译返回格式：
- 保留原 Markdown 标题层级（#、##、###）
- 保留代码块、列表、引用等格式
- 翻译成中文，但专有名词保留英文（如 API、Git）
- 不添加额外解释，只输出翻译结果
这些约束写清楚，AI 生成代码时就不会自由发挥。你可能会问：写这么多细节，是不是有点浪费时间？恰恰相反，在文档里多花十分钟，能省下后面和 AI 反复拉扯的十个小时。
还有一个容易忽略的点：如果是在已有项目上迭代，必须让 AI 先阅读现有文档和代码，而不是从零生成。否则它可能会推倒你原来合理的设计，把项目搞成四不像。
三、design.md：技术选型决定项目生死
需求理清之后，第二个文档是技术设计。选型就像选地基，AI 可以帮你盖楼，但楼盖在沙滩上一定会塌。
这个项目我遇到了几个关键技术难点，都在 design.md 里做了充分调研和决策：
1. 正文提取：别自己造轮子
“从任意网页提取正文”听起来简单，实际上非常复杂。不同网站的 HTML 结构千差万别，导航栏、广告、推荐列表全是干扰项。
经过和 AI 多轮讨论，最终选定了 Mozilla 的Readability.js，它就是 Firefox 阅读模式的核心库，专门解决这个问题。只需要把当前页面 DOM 传进去，它就能返回干净的正文内容。
选型启示：遇到通用难题，先找现成的成熟方案，而不是让 AI 从零写一个“看起来能用”的提取器。
2. 模型调用：走 OpenAI 兼容协议
AI 模型如果写死某一家，用户就没法自由切换 DeepSeek、通义千问这些国内模型。现在的 AI 圈，OpenAI 接口几乎成了事实标准，很多模型服务都提供兼容协议。
所以核心设计是：把baseURL、apiKey、model全部做成用户可配置项。用户想用哪个模型，只要填对应的地址和密钥就行。这样插件就从一个“OpenAI 翻译工具”变成了“通用 AI 翻译工具”。
3. Markdown 渲染：选轻量库
翻译结果是 Markdown 格式，渲染成 HTML 需要选择一个解析库。我选了marked，轻量、稳定、通用。为什么不用更重的框架？因为插件界面就那么点大，够用就好，别把项目搞复杂。
这三个选型定下来后，整个项目的技术骨架就清晰了：Readability 负责“提取”，OpenAI 兼容协议负责“翻译”，marked 负责“渲染”。design.md 就是把这些决策和理由记录下来，避免后续开发中 AI 又“灵机一动”换方案。
四、task.md：把设计拆成 AI 可执行的小任务
有了需求和技术设计，还不够。如果你直接对 AI 说“按照 design.md 把插件做出来”，它可能会一次性生成大量代码，结果乱七八糟，出了问题都不知道从哪儿查起。
所以第三个文档是 task.md，把整个开发过程拆解成一系列有序的小任务。每个任务都足够小，小到 AI 可以一次性完成并通过验收。
比如我的 task.md 大概是这样的结构：
- 初始化项目结构：创建 manifest 文件和基础目录
- 实现正文提取模块：集成 Readability.js，编写 content script
- 实现 AI 调用模块：封装 OpenAI 兼容接口，支持流式返回
- 实现 Markdown 渲染模块：集成 marked，处理复制功能
- 搭建基础 UI：根据 layout.md 生成界面
- 联调与测试：串联所有模块，修复问题
每个任务完成后，我会运行测试、检查效果，确认无误后 commit 一次。这样即使后面某一步出错，也能快速定位到是哪个任务引入的问题。
task.md 的价值在于：把一个大目标变成一串小目标，让 AI 每一步都有明确的任务边界，也让你每一步都能验收。
五、layout.md：界面布局也要提前定义
第四个文档是 layout.md，专门描述界面长什么样、交互怎么走。很多人忽视这一步，结果 AI 生成的界面要么丑得没法用，要么交互逻辑混乱。
我的 layout.md 里会包含：
- 整体布局：插件是弹窗还是侧边栏？宽度多少？有哪些区域？
- 组件描述：按钮放哪里？输入框在哪儿？结果展示区怎么滚动？
- 交互流程：用户点击“翻译”后发生什么？加载状态怎么显示？复制按钮的反馈是什么？
- 流式渲染：翻译结果是一段一段出现的，界面如何平滑展示？
这些描述不需要画图，用文字说清楚就行。AI 理解能力很强，只要你描述得足够具体，它就能生成符合预期的界面。
有了 layout.md，AI 在写 UI 代码时就有据可依，不会出现“按钮位置不对”“结果区域太窄”这种反复修改的情况。界面不是玄学，描述清楚，AI 就能画出来。
六、项目准备：把 Git 当成后悔药
四个文档确认后，才开始写代码。但写代码之前，还有一件重要的事：Git 版本控制。
Vibe Coding 最大的风险是什么？AI 生成代码很快，但翻车也很快。有时候它一个“幻觉”，就把你昨天调好的代码改崩了。
所以项目初始化后，我做的第一件事就是初始化 Git 仓库。不是为了装专业，而是因为 AI 生成的是“可验收代码”，你必须随时能验收、能回退。
我给自己总结了三个层次的回退命令：
# 1. 改动还没到暂存区，直接丢弃 git restore . # 2. 改动到了暂存区，但没提交 git restore --staged . git restore . # 3. 已经提交了，回退到上一个版本 git reset --hard HEAD^这三个命令，在 AI 产生幻觉时就是救命的后悔药。AI 生成代码很快，但回滚更快——前提是你有 Git。
另外，管理 AI 会话也很重要。当一个任务聊了太久，上下文已经严重污染时，我会果断开启新会话，把关键结论写进文档，让新会话先读文档再继续。这样比在一个会话里反复纠正 AI 高效得多。
七、迭代实践：从 Popup 到侧边栏
MVP 跑通后，第一个真实需求来了：
当前 popup 页面是弹窗形式，高度有限。翻译后的内容可能很多，能不能做成从右侧打开，高度撑满整个页面？
这个问题很有意思。很多开发者第一反应是调popup.html的高度，但 Chrome 弹窗有尺寸限制，没办法真正撑满。
我没有急着改代码，而是先 Research：Chrome 插件的 popup 页面是否可以做成侧边栏？
答案是可以，但不是通过 popup，而是 Chrome 的Side Panel API（Chrome 114+）。它可以让插件在浏览器右侧打开一个与页面等高的侧边栏，完美满足需求。
于是我先更新文档。按照 SDD 的流程，四个文档都要同步更新：
- proposal.md：增加“侧边栏展示”作为需求变更
- design.md：补充 Side Panel API 的技术方案
- task.md：新增“改造为侧边栏”的任务项
- layout.md：更新界面布局，从弹窗改为右侧面板
文档确认无误后，再让 AI 按照文档修改代码。从 popup 到侧边栏，本质上就是配置调整加页面文件改名，以及样式上的一些适配。用户再也不用在小小的弹窗里看长文翻译了。
文档和代码保持一致，Git 同时跟踪两者的版本。这是 SDD 最容易被忽视的优势：需求怎么变的，代码怎么跟着改的，历史记录里一目了然。
八、复盘与踩坑
整个项目做下来，有几个点值得总结：
1. 四个文档缺一不可
proposal 定义方向，design 决定方案，task 控制节奏，layout 保证体验。少了任何一个，后面都可能返工。文档不是走过场，而是 AI 协作中的“合同”。
2. 管理 AI 会话，别让它“精神分裂”
当你和一个 AI 会话聊了几十个来回，它的上下文会越来越乱，开始忘记前面定下的规范。这时候别硬聊，开个新会话，把四个文档扔给它，让它先读再说。
3. 迭代后记得移除冗余代码
从 popup 改成侧边栏后，原来 popup 相关的样式和逻辑就成了死代码。如果不清理，项目会越来越臃肿，AI 下次读取项目时也可能被冗余代码误导。用完就删，保持项目干净，是对下一个接手者（包括未来的你）最大的善意。
Vibe Coding 的本质不是让 AI 替你写代码，而是让你有精力去思考真正重要的设计。
AI 帮你解决的是“怎么写”，但“写什么”“为什么这么写”永远是你自己的功课。SDD 的四个文档，就是把这门功课做扎实。
写在最后
这个插件从四个文档到侧边栏迭代，全程用 SDD + Vibe Coding 完成。最让我意外的不是 AI 写了多少代码，而是文档真正成了项目的“源代码”——代码可以删了重写，但只要文档在，项目就能一次次被准确重建。
如果你也在用 AI 做开发，不妨试试这个流程：先让 AI 生成 proposal、design、task、layout 四个文档，逐项确认，再动手写代码。你会发现，慢就是快，少就是多。