阅读英文技术文章时你是不是也经历过复制段落 → 丢进翻译工具 → 格式乱掉 → 再粘回笔记软件 → 手动排版。折腾半天真正阅读的时间还没排版多。我最近用 Vibe Coding SDDSpecification-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.mdAI 在写 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 弹窗有尺寸限制没办法真正撑满。我没有急着改代码而是先 ResearchChrome 插件的 popup 页面是否可以做成侧边栏答案是可以但不是通过 popup而是 Chrome 的Side Panel APIChrome 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 四个文档逐项确认再动手写代码。你会发现慢就是快少就是多。