1. 起因一个重复了无数次的排版痛点和一次方法论转向这个月我把一个积压了很久的零散脚本正式做成了一款排版类的 npm 包。整个过程最让我意外的不是包本身而是它的生产方式我没有像以前那样打开编辑器就开写而是先花了大半天整理规格文档再让 AI 在规格约束下实现最后测试全绿、包发布上线。这套流程就是 SDDSpec-Driven Development规格驱动开发配合 AI 协作的完整闭环也是我目前用得最顺的一种开发节奏。先说说痛点从哪来。我平时要写技术文章、整理项目文档内容经常是从各种渠道粘贴进来的——聊天记录、PDF 复制、别人发来的文本片段。这个场景大家应该不陌生中英文之间没空格、直引号和弯引号混用、全角半角标点乱成一团。以前我的处理方式是打开编辑器临时写一段正则替换脚本。问题是这种脚本我前前后后写过至少五次每次换环境就找不到了而且不同来源的文本总能在替换链路里翻出新问题。某天我又一次在新项目里重新发明排版脚本时突然觉得不对劲明明是一个边界清晰、规则稳定的文本处理需求为什么每次都要从零开始随手列一下就有中英文间距、中文数字间距、引号转换、标点规范化、Markdown 内容保护……如果把这些规则统一成一份规格再让规格变成可执行的测试最后封装成 npm 包发布是不是就能彻底终结这种重复劳动恰好那阵子我在研究 ThoughtWorks 杰出工程师 Birgitta Böckeler 提出的 SDD 三级分类框架她的观点正好戳中我的疑问当 AI agent 开始参与写代码规格文档就不再只是给人看的说明书而是约束 AI 行为的边界和合同。顺着这个思路我决定拿这个排版包当试验田完整走一遍 SDD 六步实践。这篇就把我从需求拆解、规格编写、AI 实现到 npm 发布的全过程拆开讲包括踩过的坑和后来验证过有效的做法。无论你是想优化和 AI 的协作方式还是准备发布自己的第一个 npm 包都值得往下看看。2. SDD 三级分类框架为什么我要把规格写成可执行合同在讲具体步骤之前有必要先交代一下 SDD 的分类逻辑因为很多人第一次听到规格驱动开发都会误解这不就是先写文档再写代码吗传统瀑布流也这么干啊。区别恰恰藏在规格的消费方式里。Birgitta Böckeler 的三级分类框架把 SDD 按规格的用途切成了三层级别规格形态主要消费对象典型问题L1描述性文档人类阅读写的人和写代码的人理解不一致L2可执行测试测试框架用例覆盖不全规格和测试脱节L3生成上下文AI 模型上下文过载模型抓不住重点L1 就是我们最熟悉的场景产品经理写 PRD开发照着实现。规格在这里只是参考代码写成什么样主要看开发的理解水平和心情。传统软件工程里大量的返工都发生在这层——文档说加空格开发理解成所有地方都加空格测试又没跟上问题直到上线才暴露。L2 稍微进了一步规格里的每一条规则都要变成可执行的测试。还是加空格这条需求L2 会要求你写清楚什么情况下加、什么情况下不加并且把每个不加的场景都固化成测试用例。这层已经能把大部分理解偏差拦截在编码阶段。L3 是 SDD 和 AI 结合后新长出来的能力规格文档不再只给人看而是直接作为上下文喂给 AI 模型让代码生成行为从一开始就被规格锚定。这层的核心价值在于AI 生成的代码如果跑偏了你不需要靠感觉去猜哪出了问题只需要回到规格逐条对照——是规则写得含糊还是模型执行偏差。我第一次走完这套流程后最大的感触是L1 到 L3 不是递进关系而是互补关系。排版包这种规则密集型的小工具最怕的就是规则含糊。所以我采用了 L2 L3 混合的策略规格文档同时服务两个对象——人类 reviewer 和 AI 模型而验收标准全部转成 Vitest 测试用例。规格不是写完了就锁进抽屉它贯穿了从编码到发布的每一个环节。后面你会发现所有让我头疼的 AI 翻车最后都能追溯到规格里某个没说清楚的地方。3. 六步实践从一句抱怨到验收测试全绿接下来是重头戏我把这次开发走的六步完整复盘一遍每一步都附上实际产出的样子。这套六步法不是我发明的是我结合 SDD 的实践指南和实际项目经验调整出来的对工具类、库类项目尤其适用。3.1 第一步把模糊的抱怨翻译成用户故事我最初的抱怨是粘贴进来的文本排版乱得没法用。这句话当需求完全不合格因为它没有边界。我把它重写成了正式的用户故事作为一个经常撰写技术文档的人我希望粘贴进来的混合文本能被自动规范化排版包括中英文间距、标点转换和引号修正这样我就不需要手动逐处修改。用户故事的价值在于它强制你交代三件事使用者是谁、期望什么行为、解决什么问题。写完角色和目的之后自然就会追问一个关键问题自动规范化到底包含哪些规则这就引出了第二步。3.2 第二步穷举规则和反例规则收集阶段是最费时的但也是整个 SDD 流程里回报率最高的一步。我花了一下午把脑子里积累的排版规则全部倒出来然后逐条补上反例。所谓反例就是这条规则不应该生效的场景。规则正向示例反例/例外中英文之间加空格我用JavaScript三年 → 我用 JavaScript 三年行内代码、代码块、URL中文与数字之间加空格共3个文件 → 共 3 个文件百分比 50%、版本号 v1.2.3直引号转中文弯引号他说你好 → 他说“你好”英文撇号 dont、代码字符串半角逗号句号转全角你好,世界. → 你好世界。代码、URL 内部保持原样清理连续空格你好 世界 → 你好 世界代码块内缩进不得改动括号前后不加空格(重要) 保持原样中英文括号混用时可替换这一步特别重要的一个原则是反例和正向规则同等重要。比如中文和英文之间加空格这条如果不写清楚行内代码、URL 排除AI 第一版实现一定会把代码里的内容也改了。3.3 第三步编写规格文档规则收集完之后我把它整理成一份结构化的规格文档。文档结构大概是这样的项目背景与目标输入输出定义输入任意字符串输出排版后的字符串规则表上面的表格直接搬进去边界条件清单空字符串、纯英文、纯中文、全角英文、Emoji 混合验收标准每条规则对应一条可验证的描述这份文档有两份读者我自己和 AI。所以语言必须无歧义。比如说中文这个表述我在规格里明确限定为 Unicode 中文字符范围同时把扩展区、生僻字、中文标点都列了出来。AI 不需要理解什么叫中文它只需要知道判断标准是什么。3.4 第四步把规格转成测试用例规格文档定稿后我做的第一件事不是写实现而是写测试。这里用 Vitest原因很简单它跑得快断言语法和 Jest 基本一致而且零配置就能用。我按照规格里的每一条规则逐条转成测试用例import { describe, expect, it } from vitest; import { typeset } from ../src; describe(中英文间距规则, () { it(在中文和英文之间插入空格, () { expect(typeset(我用JavaScript三年)).toBe(我用 JavaScript 三年); }); it(不处理行内代码中的内容, () { expect(typeset(运行 npm install 安装依赖)).toBe(运行 npm install 安装依赖); }); it(不拆分版本号, () { expect(typeset(发布v1.2.3版本)).toBe(发布 v1.2.3 版本); }); }); describe(引号转换规则, () { it(直引号转换成中文弯引号, () { expect(typeset(他说你好)).toBe(他说“你好”); }); it(保留英文缩写中的撇号, () { expect(typeset(Dont worry)).toBe(Dont worry); }); });写测试的过程其实就是把规格逐条翻译成机器可验证的断言。如果你发现某条规则没法写成测试八成是规则本身定义得不够清晰——这是规格和实现之间的一个绝佳校准点。3.5 第五步让 AI 在规格约束下实现测试就位后我把规格文档连同测试文件一起作为上下文喂给 AI让它实现src/index.ts。这一版的策略是先让 AI 打全量我再根据测试结果决定怎么收敛。结果当然不可能一次过——第一次跑测试十几个用例挂了将近一半。但这正是 SDD 流程的价值失败信息精确地告诉 AI 和我是哪条规则没实现对而不是一句笼统的代码有问题。我把失败信息原样回传给 AI让它基于测试反馈做第二轮修复。如此循环大概三轮后测试从一片红变成了全绿。这个红绿循环是 SDD 和 AI 协作最核心的机制AI 可以自由选择实现方式但验收标准是固定的跑不跑得过测试是客观事实不用争论。3.6 第六步Review、补坑、发布测试全绿不等于事情结束。我自己做了一轮人工 review重点看那些测试没有覆盖的犄角旮旯——比如超长文本的性能、并发调用会不会出现状态污染。这个阶段我还补了发布配置、类型声明和 README然后才走 npm 发布流程。这部分细节比较多我放到第五章节专门讲。4. AI 编码阶段三种协作模式与真实翻车现场规格和测试就位之后AI 具体怎么用我试出了三种协作模式各有各的适用场景也各有各的坑。4.1 模式一规格文档直接投喂一次性生成这是最省事的方式把规格文档全文 测试文件 现有项目结构一起丢给 AI让它从头生成实现。优点是快缺点是失控风险高。我第一次这么干的时候AI 确实交出了能跑的代码但等我细看发现它在处理 Markdown 代码块时用的保护策略是分割后分别处理分割逻辑本身又有漏洞遇到嵌套反引号就直接懵了。这类问题在测试用例里没覆盖到测试全绿也不代表实现质量过关。4.2 模式二测试先行AI 只负责让测试变绿这个模式我后来用得最多。核心思想是我完全不描述实现思路只把测试文件丢给 AI告诉它实现一个能让这些测试全部通过的模块实现方式你自由发挥。优点很明显AI 的自由度最大而且测试本身就是清晰的验收信号。但这里有个隐藏前提——测试用例必须写得足够好。如果测试只覆盖了正常路径AI 就会用最偷懒的方式糊弄过去。所以模式二必须搭配 review不能真的当甩手掌柜。4.3 模式三人审机改逐轮收敛模式三是前两种的兜底方案。当 AI 给出的实现方案有明显设计问题时我不直接说重写而是把问题描述清楚让 AI 在原有基础上修改。比如你当前实现里对代码块的保护逻辑会在嵌套反引号场景下失效请改用先提取再还原的策略这种反馈方式比你写错了有效得多。这里有个重要的沟通技巧给 AI 的反馈要让它是可执行的。模糊的批评只会得到模糊的修改精确的问题描述才能换来精确的修复。4.4 三个真实翻车现场翻车现场一版本号被拆散。AI 第一版的正则没把v1.2.3这种版本号纳入例外结果排版之后变成v 1.2.3整篇文章的版本号全毁了。这个反例幸好提前写进了规格测试一跑就暴露了。翻车现场二Markdown 代码块保护失效。AI 实现了行内代码的保护但对 围栏代码块没有处理导致代码块里的注释也被加了空格。这种问题靠单测不好覆盖我是靠人工 review 抓出来的。翻车现场三性能上出了幺蛾子。AI 用的是逐字符遍历加字符串拼接处理几千字的文本没问题但喂给它一份几万字的文档时明显感觉到卡顿。后来把实现改成了基于正则的全局替换 分段处理性能才恢复正常。这三个翻车案例给我的共同教训是AI 生成代码的平均质量在提高但它对异常路径的想象力依然有限。规格文档覆盖得越细AI 的发挥空间被约束得越紧最终产物就越可靠。5. 发布 npm 包从本地验证到 registry 上线的完整链路测试全绿只是开发阶段的终点真正的考验在发布环节。这次我踩了不少坑有些是 npm 发布的基础问题有些是新版 Node 环境特有的统一记录一下。5.1 发布前的本地验证npm link 和 npm pack正式发布之前我建议无论如何都要先在本地验证一遍。最直接的方式是npm link把当前目录的包链接到全局再在测试项目里npm link 包名。这样改完源码测试项目立刻就能用上最新版本。还有一个容易被忽略的命令是npm pack --dry-run。它会列出打包后将要发布的所有文件相当于发布前的预览。我第一次跑的时候吓了一跳——node_modules没被排除不说连测试文件和.ts源码都混进了包里。后来在package.json里加了files字段只保留构建产物和声明文件{ files: [dist, README.md, LICENSE] }5.2 package.json 里最容易漏的三个字段第一个是types。用 TypeScript 写的库如果不配类型声明路径使用方在 TS 项目里会得到一个巨大的any直接废掉类型提示。第二个是exports字段它比main更精确地控制了包入口能同时区分import和require两种使用方式。第三个是sideEffects: false方便使用方做 tree-shaking。这三个字段不加包的体验会差一个档次。构建方面我用tsc输出产物到dist目录同时在package.json里把main指向dist/index.cjs、module指向dist/index.mjs。如果你只用纯 JavaScript构建步骤可以省掉但类型声明建议还是留着——现在 npm 上没类型声明的库使用者抱怨率极高。5.3 发布命令与常见报错发布本身不复杂登录 npm 账号、npm publish但操作过程中我接连遇到两个报错。第一个是 Windows 环境下 PowerShell 禁止运行npm.ps1脚本报错信息是npm : 无法加载文件 ... 因为在此系统上禁止运行脚本。这不是 npm 的问题是 PowerShell 执行策略默认限制。解决办法是在管理员终端里执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned然后重开终端即可。第二个是证书过期报错形如npm err! code cert_has_expired。这个通常是因为 registry 配置指向了某个老旧的镜像地址证书已过期失效。解决办法是检查.npmrc里的 registry 配置重置为官方源或维护正常的新镜像地址再重新执行安装或发布。这两个问题都很基础但如果你第一次接触 npm遇到报错的第一反应别急着搜堆栈先检查执行策略和 registry 配置能省下不少时间。5.4 发布后的自检发布成功后我做的第一件事是npm view 包名确认版本号、描述、入口文件都对。接着开一个全新的临时目录npm install刚发布的包写一小段验证脚本跑一遍核心功能。这一步能同时验证包在用户视角下的安装体验和运行体验比在开发目录里自我感觉良好靠谱得多。6. 收益与边界SDD 不是什么万能灵药走完整个流程我最想分享的是对 SDD 适用边界的认识。这个方法对我这次排版包项目非常有效但它有明确的前提。首先是适合的场景特征规则密集、边界清晰、验收标准容易量化。排版、校验、格式化、数据转换这类工具型需求天生就是 SDD 的主场。因为它们的行为可以拆成一条条明确的 if-else每条规则都能写进测试AI 实现起来也不容易跑偏。其次凡是探索性质的任务SDD 就会显得笨重。比如设计一个交互复杂的界面或者规划一个大型系统的架构你根本没法在动手前把规则写清楚。这种时候硬套 SDD只会得到一份假大空的规格文档对实际开发毫无指导意义。我自己现在的做法是探索型任务继续用接近 vibe coding 的方式快速试错一旦需求收敛、规则清晰再切换到 SDD 流程让 AI 在规格约束下完成实施。两者不是替代关系而是接力关系。最后说一点个人体会。以前我总觉得写文档是负担尤其是写那种写完就没人看的规格文档。但 SDD 改变了我对文档的定位规格不是写给流程看的它是你和 AI 之间的协作协议。协议写得越清楚AI 的执行偏差就越小你 review 的工作量反而降下来了。这次做排版 npm 包真正写代码的时间占比不足四成剩下的时间全花在规则梳理、测试编写和发布验证上。但正是这些不写代码的环节决定了这个包最终能不能稳定、耐用、值得别人安装依赖。如果你也想尝试这套流程我建议从一个小而规则清晰的项目开始比如一个日期格式化工具、一个 Markdown 标题提取器或者像我一样的文本排版器。把规格写细把测试写全再让 AI 上场。你会感受到一种和之前完全不同的开发节奏不是追着 bug 跑而是让代码向规格收敛。
1. 起因一个重复了无数次的排版痛点和一次方法论转向这个月我把一个积压了很久的零散脚本正式做成了一款排版类的 npm 包。整个过程最让我意外的不是包本身而是它的生产方式我没有像以前那样打开编辑器就开写而是先花了大半天整理规格文档再让 AI 在规格约束下实现最后测试全绿、包发布上线。这套流程就是 SDDSpec-Driven Development规格驱动开发配合 AI 协作的完整闭环也是我目前用得最顺的一种开发节奏。先说说痛点从哪来。我平时要写技术文章、整理项目文档内容经常是从各种渠道粘贴进来的——聊天记录、PDF 复制、别人发来的文本片段。这个场景大家应该不陌生中英文之间没空格、直引号和弯引号混用、全角半角标点乱成一团。以前我的处理方式是打开编辑器临时写一段正则替换脚本。问题是这种脚本我前前后后写过至少五次每次换环境就找不到了而且不同来源的文本总能在替换链路里翻出新问题。某天我又一次在新项目里重新发明排版脚本时突然觉得不对劲明明是一个边界清晰、规则稳定的文本处理需求为什么每次都要从零开始随手列一下就有中英文间距、中文数字间距、引号转换、标点规范化、Markdown 内容保护……如果把这些规则统一成一份规格再让规格变成可执行的测试最后封装成 npm 包发布是不是就能彻底终结这种重复劳动恰好那阵子我在研究 ThoughtWorks 杰出工程师 Birgitta Böckeler 提出的 SDD 三级分类框架她的观点正好戳中我的疑问当 AI agent 开始参与写代码规格文档就不再只是给人看的说明书而是约束 AI 行为的边界和合同。顺着这个思路我决定拿这个排版包当试验田完整走一遍 SDD 六步实践。这篇就把我从需求拆解、规格编写、AI 实现到 npm 发布的全过程拆开讲包括踩过的坑和后来验证过有效的做法。无论你是想优化和 AI 的协作方式还是准备发布自己的第一个 npm 包都值得往下看看。2. SDD 三级分类框架为什么我要把规格写成可执行合同在讲具体步骤之前有必要先交代一下 SDD 的分类逻辑因为很多人第一次听到规格驱动开发都会误解这不就是先写文档再写代码吗传统瀑布流也这么干啊。区别恰恰藏在规格的消费方式里。Birgitta Böckeler 的三级分类框架把 SDD 按规格的用途切成了三层级别规格形态主要消费对象典型问题L1描述性文档人类阅读写的人和写代码的人理解不一致L2可执行测试测试框架用例覆盖不全规格和测试脱节L3生成上下文AI 模型上下文过载模型抓不住重点L1 就是我们最熟悉的场景产品经理写 PRD开发照着实现。规格在这里只是参考代码写成什么样主要看开发的理解水平和心情。传统软件工程里大量的返工都发生在这层——文档说加空格开发理解成所有地方都加空格测试又没跟上问题直到上线才暴露。L2 稍微进了一步规格里的每一条规则都要变成可执行的测试。还是加空格这条需求L2 会要求你写清楚什么情况下加、什么情况下不加并且把每个不加的场景都固化成测试用例。这层已经能把大部分理解偏差拦截在编码阶段。L3 是 SDD 和 AI 结合后新长出来的能力规格文档不再只给人看而是直接作为上下文喂给 AI 模型让代码生成行为从一开始就被规格锚定。这层的核心价值在于AI 生成的代码如果跑偏了你不需要靠感觉去猜哪出了问题只需要回到规格逐条对照——是规则写得含糊还是模型执行偏差。我第一次走完这套流程后最大的感触是L1 到 L3 不是递进关系而是互补关系。排版包这种规则密集型的小工具最怕的就是规则含糊。所以我采用了 L2 L3 混合的策略规格文档同时服务两个对象——人类 reviewer 和 AI 模型而验收标准全部转成 Vitest 测试用例。规格不是写完了就锁进抽屉它贯穿了从编码到发布的每一个环节。后面你会发现所有让我头疼的 AI 翻车最后都能追溯到规格里某个没说清楚的地方。3. 六步实践从一句抱怨到验收测试全绿接下来是重头戏我把这次开发走的六步完整复盘一遍每一步都附上实际产出的样子。这套六步法不是我发明的是我结合 SDD 的实践指南和实际项目经验调整出来的对工具类、库类项目尤其适用。3.1 第一步把模糊的抱怨翻译成用户故事我最初的抱怨是粘贴进来的文本排版乱得没法用。这句话当需求完全不合格因为它没有边界。我把它重写成了正式的用户故事作为一个经常撰写技术文档的人我希望粘贴进来的混合文本能被自动规范化排版包括中英文间距、标点转换和引号修正这样我就不需要手动逐处修改。用户故事的价值在于它强制你交代三件事使用者是谁、期望什么行为、解决什么问题。写完角色和目的之后自然就会追问一个关键问题自动规范化到底包含哪些规则这就引出了第二步。3.2 第二步穷举规则和反例规则收集阶段是最费时的但也是整个 SDD 流程里回报率最高的一步。我花了一下午把脑子里积累的排版规则全部倒出来然后逐条补上反例。所谓反例就是这条规则不应该生效的场景。规则正向示例反例/例外中英文之间加空格我用JavaScript三年 → 我用 JavaScript 三年行内代码、代码块、URL中文与数字之间加空格共3个文件 → 共 3 个文件百分比 50%、版本号 v1.2.3直引号转中文弯引号他说你好 → 他说“你好”英文撇号 dont、代码字符串半角逗号句号转全角你好,世界. → 你好世界。代码、URL 内部保持原样清理连续空格你好 世界 → 你好 世界代码块内缩进不得改动括号前后不加空格(重要) 保持原样中英文括号混用时可替换这一步特别重要的一个原则是反例和正向规则同等重要。比如中文和英文之间加空格这条如果不写清楚行内代码、URL 排除AI 第一版实现一定会把代码里的内容也改了。3.3 第三步编写规格文档规则收集完之后我把它整理成一份结构化的规格文档。文档结构大概是这样的项目背景与目标输入输出定义输入任意字符串输出排版后的字符串规则表上面的表格直接搬进去边界条件清单空字符串、纯英文、纯中文、全角英文、Emoji 混合验收标准每条规则对应一条可验证的描述这份文档有两份读者我自己和 AI。所以语言必须无歧义。比如说中文这个表述我在规格里明确限定为 Unicode 中文字符范围同时把扩展区、生僻字、中文标点都列了出来。AI 不需要理解什么叫中文它只需要知道判断标准是什么。3.4 第四步把规格转成测试用例规格文档定稿后我做的第一件事不是写实现而是写测试。这里用 Vitest原因很简单它跑得快断言语法和 Jest 基本一致而且零配置就能用。我按照规格里的每一条规则逐条转成测试用例import { describe, expect, it } from vitest; import { typeset } from ../src; describe(中英文间距规则, () { it(在中文和英文之间插入空格, () { expect(typeset(我用JavaScript三年)).toBe(我用 JavaScript 三年); }); it(不处理行内代码中的内容, () { expect(typeset(运行 npm install 安装依赖)).toBe(运行 npm install 安装依赖); }); it(不拆分版本号, () { expect(typeset(发布v1.2.3版本)).toBe(发布 v1.2.3 版本); }); }); describe(引号转换规则, () { it(直引号转换成中文弯引号, () { expect(typeset(他说你好)).toBe(他说“你好”); }); it(保留英文缩写中的撇号, () { expect(typeset(Dont worry)).toBe(Dont worry); }); });写测试的过程其实就是把规格逐条翻译成机器可验证的断言。如果你发现某条规则没法写成测试八成是规则本身定义得不够清晰——这是规格和实现之间的一个绝佳校准点。3.5 第五步让 AI 在规格约束下实现测试就位后我把规格文档连同测试文件一起作为上下文喂给 AI让它实现src/index.ts。这一版的策略是先让 AI 打全量我再根据测试结果决定怎么收敛。结果当然不可能一次过——第一次跑测试十几个用例挂了将近一半。但这正是 SDD 流程的价值失败信息精确地告诉 AI 和我是哪条规则没实现对而不是一句笼统的代码有问题。我把失败信息原样回传给 AI让它基于测试反馈做第二轮修复。如此循环大概三轮后测试从一片红变成了全绿。这个红绿循环是 SDD 和 AI 协作最核心的机制AI 可以自由选择实现方式但验收标准是固定的跑不跑得过测试是客观事实不用争论。3.6 第六步Review、补坑、发布测试全绿不等于事情结束。我自己做了一轮人工 review重点看那些测试没有覆盖的犄角旮旯——比如超长文本的性能、并发调用会不会出现状态污染。这个阶段我还补了发布配置、类型声明和 README然后才走 npm 发布流程。这部分细节比较多我放到第五章节专门讲。4. AI 编码阶段三种协作模式与真实翻车现场规格和测试就位之后AI 具体怎么用我试出了三种协作模式各有各的适用场景也各有各的坑。4.1 模式一规格文档直接投喂一次性生成这是最省事的方式把规格文档全文 测试文件 现有项目结构一起丢给 AI让它从头生成实现。优点是快缺点是失控风险高。我第一次这么干的时候AI 确实交出了能跑的代码但等我细看发现它在处理 Markdown 代码块时用的保护策略是分割后分别处理分割逻辑本身又有漏洞遇到嵌套反引号就直接懵了。这类问题在测试用例里没覆盖到测试全绿也不代表实现质量过关。4.2 模式二测试先行AI 只负责让测试变绿这个模式我后来用得最多。核心思想是我完全不描述实现思路只把测试文件丢给 AI告诉它实现一个能让这些测试全部通过的模块实现方式你自由发挥。优点很明显AI 的自由度最大而且测试本身就是清晰的验收信号。但这里有个隐藏前提——测试用例必须写得足够好。如果测试只覆盖了正常路径AI 就会用最偷懒的方式糊弄过去。所以模式二必须搭配 review不能真的当甩手掌柜。4.3 模式三人审机改逐轮收敛模式三是前两种的兜底方案。当 AI 给出的实现方案有明显设计问题时我不直接说重写而是把问题描述清楚让 AI 在原有基础上修改。比如你当前实现里对代码块的保护逻辑会在嵌套反引号场景下失效请改用先提取再还原的策略这种反馈方式比你写错了有效得多。这里有个重要的沟通技巧给 AI 的反馈要让它是可执行的。模糊的批评只会得到模糊的修改精确的问题描述才能换来精确的修复。4.4 三个真实翻车现场翻车现场一版本号被拆散。AI 第一版的正则没把v1.2.3这种版本号纳入例外结果排版之后变成v 1.2.3整篇文章的版本号全毁了。这个反例幸好提前写进了规格测试一跑就暴露了。翻车现场二Markdown 代码块保护失效。AI 实现了行内代码的保护但对 围栏代码块没有处理导致代码块里的注释也被加了空格。这种问题靠单测不好覆盖我是靠人工 review 抓出来的。翻车现场三性能上出了幺蛾子。AI 用的是逐字符遍历加字符串拼接处理几千字的文本没问题但喂给它一份几万字的文档时明显感觉到卡顿。后来把实现改成了基于正则的全局替换 分段处理性能才恢复正常。这三个翻车案例给我的共同教训是AI 生成代码的平均质量在提高但它对异常路径的想象力依然有限。规格文档覆盖得越细AI 的发挥空间被约束得越紧最终产物就越可靠。5. 发布 npm 包从本地验证到 registry 上线的完整链路测试全绿只是开发阶段的终点真正的考验在发布环节。这次我踩了不少坑有些是 npm 发布的基础问题有些是新版 Node 环境特有的统一记录一下。5.1 发布前的本地验证npm link 和 npm pack正式发布之前我建议无论如何都要先在本地验证一遍。最直接的方式是npm link把当前目录的包链接到全局再在测试项目里npm link 包名。这样改完源码测试项目立刻就能用上最新版本。还有一个容易被忽略的命令是npm pack --dry-run。它会列出打包后将要发布的所有文件相当于发布前的预览。我第一次跑的时候吓了一跳——node_modules没被排除不说连测试文件和.ts源码都混进了包里。后来在package.json里加了files字段只保留构建产物和声明文件{ files: [dist, README.md, LICENSE] }5.2 package.json 里最容易漏的三个字段第一个是types。用 TypeScript 写的库如果不配类型声明路径使用方在 TS 项目里会得到一个巨大的any直接废掉类型提示。第二个是exports字段它比main更精确地控制了包入口能同时区分import和require两种使用方式。第三个是sideEffects: false方便使用方做 tree-shaking。这三个字段不加包的体验会差一个档次。构建方面我用tsc输出产物到dist目录同时在package.json里把main指向dist/index.cjs、module指向dist/index.mjs。如果你只用纯 JavaScript构建步骤可以省掉但类型声明建议还是留着——现在 npm 上没类型声明的库使用者抱怨率极高。5.3 发布命令与常见报错发布本身不复杂登录 npm 账号、npm publish但操作过程中我接连遇到两个报错。第一个是 Windows 环境下 PowerShell 禁止运行npm.ps1脚本报错信息是npm : 无法加载文件 ... 因为在此系统上禁止运行脚本。这不是 npm 的问题是 PowerShell 执行策略默认限制。解决办法是在管理员终端里执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned然后重开终端即可。第二个是证书过期报错形如npm err! code cert_has_expired。这个通常是因为 registry 配置指向了某个老旧的镜像地址证书已过期失效。解决办法是检查.npmrc里的 registry 配置重置为官方源或维护正常的新镜像地址再重新执行安装或发布。这两个问题都很基础但如果你第一次接触 npm遇到报错的第一反应别急着搜堆栈先检查执行策略和 registry 配置能省下不少时间。5.4 发布后的自检发布成功后我做的第一件事是npm view 包名确认版本号、描述、入口文件都对。接着开一个全新的临时目录npm install刚发布的包写一小段验证脚本跑一遍核心功能。这一步能同时验证包在用户视角下的安装体验和运行体验比在开发目录里自我感觉良好靠谱得多。6. 收益与边界SDD 不是什么万能灵药走完整个流程我最想分享的是对 SDD 适用边界的认识。这个方法对我这次排版包项目非常有效但它有明确的前提。首先是适合的场景特征规则密集、边界清晰、验收标准容易量化。排版、校验、格式化、数据转换这类工具型需求天生就是 SDD 的主场。因为它们的行为可以拆成一条条明确的 if-else每条规则都能写进测试AI 实现起来也不容易跑偏。其次凡是探索性质的任务SDD 就会显得笨重。比如设计一个交互复杂的界面或者规划一个大型系统的架构你根本没法在动手前把规则写清楚。这种时候硬套 SDD只会得到一份假大空的规格文档对实际开发毫无指导意义。我自己现在的做法是探索型任务继续用接近 vibe coding 的方式快速试错一旦需求收敛、规则清晰再切换到 SDD 流程让 AI 在规格约束下完成实施。两者不是替代关系而是接力关系。最后说一点个人体会。以前我总觉得写文档是负担尤其是写那种写完就没人看的规格文档。但 SDD 改变了我对文档的定位规格不是写给流程看的它是你和 AI 之间的协作协议。协议写得越清楚AI 的执行偏差就越小你 review 的工作量反而降下来了。这次做排版 npm 包真正写代码的时间占比不足四成剩下的时间全花在规则梳理、测试编写和发布验证上。但正是这些不写代码的环节决定了这个包最终能不能稳定、耐用、值得别人安装依赖。如果你也想尝试这套流程我建议从一个小而规则清晰的项目开始比如一个日期格式化工具、一个 Markdown 标题提取器或者像我一样的文本排版器。把规格写细把测试写全再让 AI 上场。你会感受到一种和之前完全不同的开发节奏不是追着 bug 跑而是让代码向规格收敛。
