1. 这三个工具到底是在解决什么问题说实话我第一次看到“Spec Kit”“OpenSpec”“Superpowers”这三个名字放在一起时第一反应是“又有人在造新轮子了”。但如果你近期和我一样被“先写接口文档还是先写代码”“前端等的接口和后端实现完全对不上”“联调三天争吵两天”这些破事折磨过就会明白这类工具为什么突然扎堆出现。它们瞄准的是同一个问题让规范和代码不再脱节。1.1 规范驱动开发到底是个什么玩意先讲个背景。传统开发流程里接口约定通常靠三种方式流传需求文档里的一段文字、某个能人脑子里的记忆、以及聊天群里被刷走的消息。等到联调的时候前端说“你这里返回的不是我文档里那个字段”后端说“我文档更新了忘了发你”两边就开始翻聊天记录。问题本质上不是“谁的错”而是“接口约定没有任何机器可校验的载体”。所以这几年开始流行一种做法把接口规范、变更记录、评审结论都写成结构化文件放到代码仓库里让CI、生成脚本、Mock服务都能直接读取这份文件。这个玩法有个名字叫“规范驱动开发”。它希望达到的效果是改需求先改规范文件改完规范文件就自动生成文档、Mock数据、客户端类型代码只需要照着规范去落地。我自己的理解更朴素一点规范驱动开发不是让你多写几份文档而是把“我说了什么”变成“我留下了什么”。只要能留下一个可执行、可检查、可追溯的产物就算入了门。1.2 Spec Kit更像一条生成流水线Spec Kit是我最先试的。它的定位非常明确你给它一份OpenAPI或Schema定义它帮你生成接口文档、Mock服务、客户端SDK、甚至服务端骨架。本质上它是一条“规范到代码”的流水线适合那种“我已经知道接口长什么样只想快点把前后端跑起来”的场景。刚开始用会觉得特别爽。你把一个订单接口的YAML写出来跑一条命令Mock服务起来了TypeScript类型也生成好了前端可以立刻开始写页面。这种“所见即所得”的体验非常上头。但用了一周以后你会发现它的能力强弱完全取决于它支持的模板和插件。你要生成的东西一旦偏离了工具预设的模板就会非常痛苦。比如我们当时有个接口需要返回分页信息工具默认生成的类型里没有total字段我得去改它自动生成的模板代码改完以后下次再生成就直接把你覆盖了。换句话说Spec Kit解决的是“生成”问题它不解决“写规范的人怎么达成共识”的问题。如果你需要的只是快点产出代码它很好用。如果你想让团队围绕规范进行评审、讨论、决策它给不了太多帮助。1.3 OpenSpec更像一种团队协作约定OpenSpec走的是另一条路。它不关注怎么生成代码而是规定了一套“需求变更该怎么写”的文件结构。你在项目里建一个specs目录每个需求对应一个子目录里面放背景说明、决策记录、接口变更、评审记录。这套结构有点像是把RFC、ADR、接口文档揉在一起。我一开始觉得OpenSpec是最接近“规范驱动”理念的它把“写规范”这个动作变得有仪式感强迫团队在动手写代码之前先想清楚“为什么要做”“影响哪些模块”“接口怎么变”。它的目录结构本身就在引导你理清思路这一点我很喜欢。但问题也很明显OpenSpec定义了“规范该怎么长”却没有给出“规范怎么被执行”。它不会帮你校验规范文件写得好不好也不会自动生成Mock和文档脚本更不会强制你“规范变更后必须同步更新代码”。它更像是一套写作规范和流程模板所有机器执行的部分都得你自己补。也就是说OpenSpec给了你一个空壳目录真正的血肉要团队自己长。1.4 Superpowers更像一个流程增强外挂Superpowers这个工具如果你只看名字会以为它是什么提高生产力的黑科技但实际体验下来它更像一个挂在现有流程上的“流程提醒器”。它可以在你提交代码变更时检查你改了接口定义但没改对应文档你更新了Schema但没生成Mock你添加了字段但没跑校验。它的设计逻辑很聪明不逼你改变工作方式而是在你现有的工作流上叠加自动检查。团队里有人经常忘了更新接口文档它会在PR阶段直接拦下来告诉你“别急着合还缺一个Mock文件”。从项目管理角度来看这是一种非常务实的设计。但是我用了一段时间之后总觉得它缺了点什么。它不断提醒你要做这个做那个却不告诉你“规范本身怎么写才是对的”。你可以在一个完全错误的接口定义之上循环补齐所有流程产物最后产出一整套错误的代码。它优化的是流程执行效率不是规范的制定质量。2. 我的实测过程同一需求跑了三遍光看文档和宣传是分不出好坏的所以我当时做了一个决定拿一个真实需求分别用三套工具完整走一遍。这个模拟需求不是什么高深场景就是一个订单查询接口的改造。2.1 我准备的一个模拟需求需求是这样的现有订单查询接口 GET /api/v1/orders/{id} 只返回基础字段现在要支持分页查询订单列表新增 GET /api/v1/orders支持page、pageSize、sortBy、sortOrder四个查询参数响应体里要有total字段权限从普通用户改到需要管理员权限。另外每个订单要新增一个refundStatus字段。这个需求不复杂但刚好覆盖了接口新增、字段修改、权限变更三种场景。我用三个工具分别建了三个试验分支在同一个代码仓库里跑流程最后对比一下哪个“能真正帮我省事”。测试环境方面项目本身是Node.js TypeScript已经有一份OpenAPI 3.1文件团队四个人协作。我没有引入任何额外平台就在本地命令行和仓库的CI配置里来回折腾。2.2 用Spec Kit跑通“设计到Mock”在试验分支里我先按Spec Kit的文档初始化了规范目录把OpenAPI文件丢进它约定好的位置。接着跑了它的脚手架命令spec-kit scaffold api/order.yaml spec-kit generate client --lang typescript --output src/types/order.ts spec-kit generate mock --output mock/order.ts第一次跑完文件确实都出来了TypeScript类型定义、Mock服务、OpenAPI文档站点。前端拿着Mock接口直接开发这种现象级的速度让我一度觉得这次选型已经结束了。真正开始改需求时就有点难受。比如新增refundStatus字段我改完order.yaml重新跑生成命令发现生成的TypeScript类型里refundStatus是可选还是必填完全取决于我在Schema里怎么写required。这倒没啥问题是我想让Mock服务每次都模拟一种固定返回结果发现Mock模板是工具预设的我只能写死某个状态。你把Mock模板改了吧下次重新生成又会覆盖掉。最后我只能放弃自动生成Mock模板自己去写一个独立Mock服务。跑完一遍后的感受工具本身没有大错但它把“规范”当作一种可以被消耗的原料——生成完代码就完事了。当代码和规范发生了偏差工具并不会主动提醒你一切都靠人自觉。2.3 用OpenSpec定义“变更计划”第二个分支我试OpenSpec。按照它的规范我创建了一个需求目录里面的结构是specs/ 2025-03-order-query/ proposal.md decisions/ 001-refund-status.md 002-permission-change.md api/ order-openapi.yaml review/ meeting-notes.mdproposal.md的开头有一段YAML frontmatter包含status、author、reviewers、created等字段。正文部分依次写背景、目标、非目标、方案对比、最终决策。这一套写下来的体验其实相当顺畅尤其是我写着写着发现自己必须要把“为什么需要refundStatus”这件事说清楚才能往下走。你被迫去思考这个字段的真实使用场景而不是先在代码里加一个字段再说。这个“先想后写”的约束非常有价值。但我很快遇到一个现实问题写完这些以后接下来呢OpenSpec没有提供脚本把openapi.yaml转成Mock没有自动生成代码的逻辑也没有校验proposal里status字段状态能不能跳转的工具。文档写得再规范代码还得我自己一行一行改。它更适合用来表达“我们达成了什么共识”而不是“这套共识如何自动驱动后续开发”。用OpenSpec写的文档后来被团队拿去做评审记录效果很好。但如果你指望靠它减少联调扯皮那恐怕要失望因为它的能力边界在“描述”而不是“执行”。2.4 用Superpowers接管“流程提醒”第三个分支我用Superpowers。它的接入方式比我预想中简单很多只要在仓库里启用它的检查钩子它会在提交代码时自动识别你改动的文件superpowers check --staged它会输出一串检查结果比如“order-openapi.yaml已更新但mock文件未更新”“订单模块的接口文档已过期”。你根据提示补上对应文件后检查才能通过。这套机制放到团队场景里是有效果的。我们之前经历过“接口文档忘记更新前端按旧文档开发最后整个模块返工”的事情Superpowers至少可以从流程上拦截这种失误。但它给我最大的困惑是它太依赖“团队已经有一份规范基线”了。如果你的接口定义本身就很烂它检查出来的结果依然会通过因为它只关心“文件在不在”“有没有更新”不关心“改得对不对”。后来我还试过把Superpowers和Spec Kit同时用发现两者完全不互补。规范文件更新后Superpowers会要求你重新生成Mock而Spec Kit生成的Mock又被Superpowers判断为“旧的”“未见过的”两边还要做额外适配。工具多了以后流程并没有变轻松反而多了一堆“为了过检查而去跑的仪式”。这也是促使我认真思考“自己选一套组合还是干脆自建”的直接原因。2.5 三者的横向对比用同一需求跑完三套流程之后我整理了一张表把选择工具时需要关心的几个维度放进去对比维度Spec KitOpenSpecSuperpowers上手成本低跑完脚手架就能用中需要理解目录规范中需要配置检查钩子核心聚焦点规范到代码的生成规范内容的组织与评审规范变更后的流程检查代码生成能力强但模板定制成本高无需要自己写脚本无不关心生成规范校验能力弱只校验语法无只定义格式弱只检查文件更新状态流程约束力无有依赖团队自律强自动拦截团队适配度适合快速出活的小团队适合爱写文档的团队适合已有规范但执行力差的团队这张表做完之后我心里差不多有答案了这三套工具都不是“错的”但它们各自只解决了规范驱动开发的一个侧面。Spec Kit解决了生产效率OpenSpec解决了思维表达Superpowers解决了执行纪律。而我真正需要的是一个把三者合起来但我自己可控的东西。3. 为什么我用完三套以后决定自己搭3.1 最大的问题迁移成本和锁定效应我本来想着要不要为了省事挑一个最接近需求的方案直接用。但仔细看下来不管选哪一套都要给团队带来一笔不小的“迁移成本”。就拿Spec Kit举例。你把代码生成逻辑完全交给它以后项目结构会很快被它预设的模板占领。哪天你发现模板不满足业务、想要微调就得去读它内部怎么组织代码这种投入是隐形的。OpenSpec相对好一点它只定义规范文件怎么写不碰代码生成但它的目录结构一旦固定以后团队所有的新需求都要按它的格式来。如果某天你想把某个变更流程改一下就不是改一个配置那么简单而是要重新培养团队习惯。Superpowers的锁定感最弱因为它本质上就是个检查钩子停用很简单。但你一旦依赖了它的提醒再去切换到其他流程时你会发现团队已经习惯“被机器提醒”而不是自己盯着规范。这些都还不算最要命的。最要命的是工具生态越完善团队反而越远离“理解规范”这件事本身。大家只知道要跑某条命令、要填某个字段却不知道这个字段背后的取舍是什么。规范变成了流水线上一个需要被喂进去的零件而不是大家讨论出来的共识。这种情况跑久了工具会让问题变得更隐蔽。3.2 规范的本质是沟通不是流水线我花了很多天去复盘那次选型最后得到一句话规范的本质是“人与人之间的沟通契约”不是“喂给机器的生产原料”。三套工具多少都有点把规范当作生产原料的倾向。Spec Kit要的是能被解析的SchemaOpenSpec要的是符合标准结构的提案文件Superpowers要的是可对比的文件差异。机器视角没问题但团队协作最难的、最需要花时间的是“让所有人对同一个字段的含义产生一致理解”。这部分恰恰是三套工具最不关心的。它们默认你已经想清楚了需求所以只帮你做后面的事情。但实际上大部分项目出问题都出在前面产品说不清要什么前端和后端对“状态”的理解不一样测试不知道哪些异常场景要覆盖。一个真正的规范工具应该在这些模糊地带帮你收敛共识而不是急着生成代码。我决定自己搭一套就是想做一个“让团队先把事情聊清楚再让机器自动干活”的组合流程。工具本身不复杂关键是约束大家用“写规范”的方式来做设计和评审。3.3 自己搭不等于造轮子而是做“定制胶水层”不少朋友听说我要自己搭第一反应是“别重复造轮子”。但我想说明白我没有从零设计一套规范语言也没有写一个代码生成引擎。我做的事情是在OpenAPI、YAML、Markdown这些已经被广泛使用的格式之上定义了一套“哪些字段必须填”“文件怎么放”“改了规范后必须更新哪些内容”的规则再配上一个小小的校验脚本。打个比方我不需要重新发明汽车我只需要在自己的车子里固定好“座椅角度怎么调”“安全带提醒怎么响”“仪表盘显示哪些信息”这些规则。底层工具全部用现成的我要管的是它们之间的胶水层。所以这套方案的核心其实是几个简单的约定而不是多么复杂的系统。正因为简单团队愿意遵守工具坏了也容易修。这是我从三套工具身上学到的最大教训再强大的工具如果它的运行假设和你的团队习惯不一致就一定会被抛弃。3.4 什么情况下不建议自己搭我也得泼一盆冷水。自建方案适合有一定协作规模、规范要长期维护的团队但不是所有团队都需要这么搞。如果你是一个三人左右的项目组要赶一个短周期项目那就直接用Spec Kit赶紧把代码跑起来比什么都强。如果你的团队本来就没什么写文档的习惯你扔一套自建规范进去只会让效率更低还不如先靠Superpowers这样的工具管住基本检查。再比如团队里没有一个人愿意维护校验脚本一旦脚本出了bug没人管这套东西就会变成摆设比不用还糟糕。我自己之所以能自建成功是因为当时团队里有两三个人对“规范驱动”这件事本身感兴趣愿意一起写规则、调脚本。没有这种维护意愿任何自建方案都是坑。4. 我搭的这套轻量方案到底长什么样说完了来龙去脉下面直接上干货。我搭的这套东西不高端但每一项都在解决前面提到的具体痛点。它由三部分组成目录结构约定、规范文件结构要求、校验脚本和CI门禁。4.1 目录结构设计目录结构是整个方案的基础它规定了所有规范文件的存放位置和层级关系。我最终定的结构长这样specs/ README.md api/ order/ order-service.yaml order-service.mocks.yaml user/ user-service.yaml decisions/ 001-refund-status.md 002-admin-permission.md templates/ change-request/ proposal.md openapi.yaml scripts/ validate-specs.js generate-types.js archive/ 2024-09-old-order-api/根目录的README只写三件事规范文件如何提交、状态流转规则是什么、遇到争议找谁。api目录存放接口定义一个服务一个子目录。decisions目录记录重要技术决策用编号开头排序。templates目录是给新建需求用的模板scripts目录放校验和生成脚本archive目录负责归档已经废弃的规范。为什么这么分因为每个目录承担一个独立职责新成员入职只需要看README就能理解整个流程。旧规范挪到archive而不是直接删除保证历史可追溯。4.2 规范文件的结构强制每个新需求必须在templates/change-request里复制出一个新目录然后按模板填写。proposal.md开头的YAML frontmatter长这样--- status: draft title: 订单接口新增分页查询 owner: backend-user reviewers: - frontend-user - product-user version: 1.0.0 created: 2025-03-02 updated: 2025-03-05 decisions: - 001-refund-status - 002-admin-permission ---为什么用YAML不用JSON两个原因。第一YAML支持注释我可以在模板里写“owner请填后端负责人reviewers建议至少填一个前端”这种说明放在JSON里会很奇怪。第二YAML frontmatter直接嵌在Markdown文件头部既不破坏文档的阅读体验又方便脚本提取字段。一个文件同时承载“给人看的内容”和“给机器读的元信息”这是这套方案里我最满意的设计之一。正文部分我要求必须写清楚四个段落背景这个需求为什么存在、目标验收标准是什么、方案接口变更点和决策依据、影响哪些服务受影响是否存在破坏性变更。写不清楚这四个部分这个提案就不允许进入评审。4.3 校验脚本让规范变成可执行的东西光有文件结构还不够得让机器检查它合不合规。我用一个Node脚本做这件事没有引入任何重型框架因为校验逻辑并不复杂。核心代码大概长这样const matter require(gray-matter); const fs require(fs); const path require(path); const ALLOWED_STATUS [draft, review, approved, deprecated]; const REQUIRED_FIELDS [status, title, owner, version, created]; function validateProposal(filePath) { const raw fs.readFileSync(filePath, utf8); const { data } matter(raw); const missing REQUIRED_FIELDS.filter((field) !data[field]); if (missing.length 0) { throw new Error(${filePath}: 缺少必填字段 ${missing.join(, )}); } if (!ALLOWED_STATUS.includes(data.status)) { throw new Error(${filePath}: status 非法期望 ${ALLOWED_STATUS.join(|)}); } if (data.status approved (!data.reviewers || data.reviewers.length 2)) { throw new Error(${filePath}: approved 状态至少需要 2 个 reviewer); } }这只是简化版我实际还加了说明当一个提案从review流转到approved时除了检查reviewer数量还会自动关联对应的OpenAPI文件并校验其中是否存在version字段。状态机是为了防止有人跳过评审直接写approved。4.4 生成器和CI门禁校验脚本只能保证“规范文件本身合格”但规范要真正驱动开发还得靠生成器和门禁。我写了另一个脚本从所有status为approved的OpenAPI文件中提取路径和Schema生成一份JSON前端可以直接用这份JSON去推导TypeScript类型和Mock数据。node scripts/generate-types.js \ --input specs/api \ --output build/generated/types.ts node scripts/generate-mocks.js \ --input specs/api \ --output mock/generatedCI里面做了三道门禁。第一只要PR改动了specs目录下的任意文件就必须附带运行校验脚本的结果。第二如果某个OpenAPI文件的接口路径发生变化但Mock文件没有跟着变CI直接失败。第三proposal.md里如果status从draft改成了review那么该PR必须至少有一个reviewer的评论确认否则不允许合并。这套门禁的价值在于它把“规范有没有被遵守”这个抽象问题变成了“CI是不是绿”这种明确问题。团队不需要每天提醒彼此机器直接挡在最后一步。5. 落地实录团队用了两个月后的变化从第一版目录结构到团队大多数人习惯这套流程总共花了大概两个月。这两个月里有明显的阻力期也有让我觉得“这一切值得”的时刻。5.1 前两周阻力最大的时候刚开始推行时团队里最响的声音是“这也太麻烦了吧”。一个简单的加字段需求以前直接改代码就行现在倒好得先建目录、填frontmatter、写背景、给评审意见旁边还得再准备一份OpenAPI改动和Mock更新。有人甚至直接对我说这不就是把简单的活变复杂了吗。我当时的解决办法不是长篇大论讲道理而是做了一件很具体的事把模板文件做到极简让新需求从“复制模板到填完字段”不超过十五分钟。模板里每个字段边上都写了注释例如“owner请填后端接口负责人”“reviewers至少填一位前端和一位产品经理”。这样就不用靠记忆照着填就行。我还开了一次十五分钟的短会只讲了两个问题这套流程到底在防什么错以及填owner不是为了追责。我举了个例子如果订单字段的命名有歧义以前你只能翻聊天记录找是谁定的有了owner字段你知道该找谁确认省下的是几个小时的无头苍蝇时间。讲完这个例子我能明显感觉到大家对流程的抵触情绪降了一些。5.2 带来的实际收益到了第五周收益开始变得具体。第一个变化是联调会议的次数明显变少。以前一个月至少有十几次联调会其中一半时间都花在对接口字段定义的理解偏差上。现在前端在开发前会先去看specs目录里的接口定义有疑问直接在proposal的评论区提出来后端会顺手改掉OpenAPI文件而不是口头回答完就了事。联调会从每周三次降到每周一次。第二个变化是接口变更导致的返工明显减少。以前后端改了字段类型前端可能过了两天才知道等开始联调才发现类型对不上整个页面逻辑全部重写。现在只要改了接口定义CI就会卡住并要求Mock同步更新前端在改代码之前就会看到新的Mock返回值能第一时间发现自己依赖的字段变了。我们内部统计过光这一项就至少砍掉了三分之一的前后端返工。第三个变化我一开始没想到新产品需求从提出到设计确认的时间变短了。以前开会讨论讲着讲着就偏到“某个按钮放左边还是右边”这种话题。现在有了规范模板大家被引导着先对齐背景和目标如果连“这个需求要解决什么问题”都写不出来大家都觉得不应该继续往下讨论细节。这个“结构化讨论”的副作用甚至比工具本身带来的效率提升更有价值。5.3 踩过的两个大坑第一个坑发生在第三周。我当时把校验规则写得太死要求所有proposal文件的description字段必须大于30个字结果有好几次团队正常改个文案也被CI拦住。后来我把这类“主观性校验”全部去掉了只保留结构性校验比如字段是否存在、状态是否合法、reviewer数量够不够。内容好不好这种事应该由人来判断机器只负责格式完整和信息齐全。第二个坑是规范文件本身膨胀得太快。一个模块一个接口文件刚开始还清晰但当一个接口迭代了四五个版本同一个文件里堆了各种deprecated字段看着就头疼。后来我和团队定了新规则每个新需求用日期目录隔离旧版本的接口定义不做原地修改而是通过新文件覆盖旧文件并把旧文件移到archive。虽然文件数量变多了但搜索和回溯反而更容易。6. 常见问题与排查速查聊到这儿我把平时收集到的高频问题整理成了一张速查表希望对想参考这套方案的人有点用。常见问题可能原因解决办法校验脚本提示“缺少owner”新成员没看模板注释漏填frontmatter在模板注释里写示例再配合README指路status跳转不合法有人把draft直接改成approved跳过了review保留状态机校验不允许跳级改了OpenAPI但Mock没同步只改了接口定义文件没跑生成脚本CI门禁检查生成物变更不通过不允许合并规范文件太多太乱所有需求堆在同一目录用日期加模块路径隔离定期归档旧规范前端说“接口文档更新了但我没收到”文档更新靠口头通知让生成脚本每次变更后自动生成通知摘要挂在群里或看板上不知道一个已废弃的接口为什么还在旧规范直接删掉了统一移入archive目录并在README写明归档规则校验脚本本身出错自己写的脚本有bug给脚本写测试用例用少量模拟规范文件验证行为6.1 校验脚本误报字段缺失这类问题最常见。原因基本两种一是模板字段名写错了比如把owner写成了author二是新需求确实没有某个字段比如一个纯内部工具接口不需要reviewers。我的建议是脚本里把必填字段分成“硬必填”和“按条件必填”两档。硬必填永远不能缺按条件必填只在某个状态或目录下校验。不要把所有校验都做成硬性的否则团队会被细节逼疯。6.2 接口字段格式变了但生成器没更新这类问题往往出现在前端已经改了代码后端临时改字段名但没有重新跑生成脚本。后来我在generate-types脚本里加了一段输出会在跑完后打印“影响xxx.ts”“影响的文件列表”。前端看到输出就知道自己有没有收到影响。如果生成脚本跑完以后提示“无变化”但代码里明明改了接口那就要检查是不是规范文件没被正确读取。6.3 规范变更和代码变更被拆在两个PR里当时最让我头疼的一个场景是有人先提交了规范文件等合并了才去改代码。中间隔了两天Mock和接口文档都显示“新版”但代码还是旧版前端以为能用实际一调就挂。我们的处理方式是在CI门禁里增加一条提示如果某个规范文件状态为approved但对应的Mock文件最近三天没有更新CI会在评论里提醒“这个规范可能已经被实现或已被放弃请确认”。6.4 要不要搬现成工具还是继续自己维护这个问题我被人问过很多次。我的判断标准只有一条如果有一天我这个维护者休假一个月这套流程还能不能继续跑。如果脚本里坑很多只有你一个人会修那就得考虑要么简化流程要么换回成熟工具。我现在维护的这套方案之所以能存续是因为脚本所有人都能看懂需要的Node依赖也少。如果你发现自己写的脚本越来越“聪明”、越来越像一个小型框架那我建议你停下来回到成熟工具上去。工具的复杂度应该匹配团队维护能力否则就是给自己造了个围城。最后分享一个小习惯折腾完这一圈我最大的收获不是自建了某个系统而是一个特别简单、看起来甚至有点“形式主义”的习惯每次有新需求我会先在specs/templates/change-request文件夹里复制一个新目录出来把标题、背景、目标这三行先填上。这个动作只需要两三分钟但它强迫我先把“我们要做一件什么事”写在纸上而不是急着打开代码编辑器。很多需求就是在这个动作里被发现的——要么是背景写不圆要么是目标含糊到连自己都看不下去于是要么去找人对齐要么直接把需求砍掉。工具换了若干个框架起起落落最后留下来的不是哪套脚本也不是哪个目录结构而是这个“先写清楚再动手”的动手习惯。这套东西你可以不用照着搭但如果你现在经常被接口变更、前后端扯皮、文档过期这些事折磨我建议你至少先试两周建一个specs文件夹放一个模板文件每次需求变更都先填三行字。两周后你会回来谢我的。 
长河君 · 2026/10/12 20:09:01 · 阅读 1.2k 从规范驱动到代码生成：接口协作工具的选型与实践
1. 这三个工具到底是在解决什么问题说实话我第一次看到“Spec Kit”“OpenSpec”“Superpowers”这三个名字放在一起时第一反应是“又有人在造新轮子了”。但如果你近期和我一样被“先写接口文档还是先写代码”“前端等的接口和后端实现完全对不上”“联调三天争吵两天”这些破事折磨过就会明白这类工具为什么突然扎堆出现。它们瞄准的是同一个问题让规范和代码不再脱节。1.1 规范驱动开发到底是个什么玩意先讲个背景。传统开发流程里接口约定通常靠三种方式流传需求文档里的一段文字、某个能人脑子里的记忆、以及聊天群里被刷走的消息。等到联调的时候前端说“你这里返回的不是我文档里那个字段”后端说“我文档更新了忘了发你”两边就开始翻聊天记录。问题本质上不是“谁的错”而是“接口约定没有任何机器可校验的载体”。所以这几年开始流行一种做法把接口规范、变更记录、评审结论都写成结构化文件放到代码仓库里让CI、生成脚本、Mock服务都能直接读取这份文件。这个玩法有个名字叫“规范驱动开发”。它希望达到的效果是改需求先改规范文件改完规范文件就自动生成文档、Mock数据、客户端类型代码只需要照着规范去落地。我自己的理解更朴素一点规范驱动开发不是让你多写几份文档而是把“我说了什么”变成“我留下了什么”。只要能留下一个可执行、可检查、可追溯的产物就算入了门。1.2 Spec Kit更像一条生成流水线Spec Kit是我最先试的。它的定位非常明确你给它一份OpenAPI或Schema定义它帮你生成接口文档、Mock服务、客户端SDK、甚至服务端骨架。本质上它是一条“规范到代码”的流水线适合那种“我已经知道接口长什么样只想快点把前后端跑起来”的场景。刚开始用会觉得特别爽。你把一个订单接口的YAML写出来跑一条命令Mock服务起来了TypeScript类型也生成好了前端可以立刻开始写页面。这种“所见即所得”的体验非常上头。但用了一周以后你会发现它的能力强弱完全取决于它支持的模板和插件。你要生成的东西一旦偏离了工具预设的模板就会非常痛苦。比如我们当时有个接口需要返回分页信息工具默认生成的类型里没有total字段我得去改它自动生成的模板代码改完以后下次再生成就直接把你覆盖了。换句话说Spec Kit解决的是“生成”问题它不解决“写规范的人怎么达成共识”的问题。如果你需要的只是快点产出代码它很好用。如果你想让团队围绕规范进行评审、讨论、决策它给不了太多帮助。1.3 OpenSpec更像一种团队协作约定OpenSpec走的是另一条路。它不关注怎么生成代码而是规定了一套“需求变更该怎么写”的文件结构。你在项目里建一个specs目录每个需求对应一个子目录里面放背景说明、决策记录、接口变更、评审记录。这套结构有点像是把RFC、ADR、接口文档揉在一起。我一开始觉得OpenSpec是最接近“规范驱动”理念的它把“写规范”这个动作变得有仪式感强迫团队在动手写代码之前先想清楚“为什么要做”“影响哪些模块”“接口怎么变”。它的目录结构本身就在引导你理清思路这一点我很喜欢。但问题也很明显OpenSpec定义了“规范该怎么长”却没有给出“规范怎么被执行”。它不会帮你校验规范文件写得好不好也不会自动生成Mock和文档脚本更不会强制你“规范变更后必须同步更新代码”。它更像是一套写作规范和流程模板所有机器执行的部分都得你自己补。也就是说OpenSpec给了你一个空壳目录真正的血肉要团队自己长。1.4 Superpowers更像一个流程增强外挂Superpowers这个工具如果你只看名字会以为它是什么提高生产力的黑科技但实际体验下来它更像一个挂在现有流程上的“流程提醒器”。它可以在你提交代码变更时检查你改了接口定义但没改对应文档你更新了Schema但没生成Mock你添加了字段但没跑校验。它的设计逻辑很聪明不逼你改变工作方式而是在你现有的工作流上叠加自动检查。团队里有人经常忘了更新接口文档它会在PR阶段直接拦下来告诉你“别急着合还缺一个Mock文件”。从项目管理角度来看这是一种非常务实的设计。但是我用了一段时间之后总觉得它缺了点什么。它不断提醒你要做这个做那个却不告诉你“规范本身怎么写才是对的”。你可以在一个完全错误的接口定义之上循环补齐所有流程产物最后产出一整套错误的代码。它优化的是流程执行效率不是规范的制定质量。2. 我的实测过程同一需求跑了三遍光看文档和宣传是分不出好坏的所以我当时做了一个决定拿一个真实需求分别用三套工具完整走一遍。这个模拟需求不是什么高深场景就是一个订单查询接口的改造。2.1 我准备的一个模拟需求需求是这样的现有订单查询接口 GET /api/v1/orders/{id} 只返回基础字段现在要支持分页查询订单列表新增 GET /api/v1/orders支持page、pageSize、sortBy、sortOrder四个查询参数响应体里要有total字段权限从普通用户改到需要管理员权限。另外每个订单要新增一个refundStatus字段。这个需求不复杂但刚好覆盖了接口新增、字段修改、权限变更三种场景。我用三个工具分别建了三个试验分支在同一个代码仓库里跑流程最后对比一下哪个“能真正帮我省事”。测试环境方面项目本身是Node.js TypeScript已经有一份OpenAPI 3.1文件团队四个人协作。我没有引入任何额外平台就在本地命令行和仓库的CI配置里来回折腾。2.2 用Spec Kit跑通“设计到Mock”在试验分支里我先按Spec Kit的文档初始化了规范目录把OpenAPI文件丢进它约定好的位置。接着跑了它的脚手架命令spec-kit scaffold api/order.yaml spec-kit generate client --lang typescript --output src/types/order.ts spec-kit generate mock --output mock/order.ts第一次跑完文件确实都出来了TypeScript类型定义、Mock服务、OpenAPI文档站点。前端拿着Mock接口直接开发这种现象级的速度让我一度觉得这次选型已经结束了。真正开始改需求时就有点难受。比如新增refundStatus字段我改完order.yaml重新跑生成命令发现生成的TypeScript类型里refundStatus是可选还是必填完全取决于我在Schema里怎么写required。这倒没啥问题是我想让Mock服务每次都模拟一种固定返回结果发现Mock模板是工具预设的我只能写死某个状态。你把Mock模板改了吧下次重新生成又会覆盖掉。最后我只能放弃自动生成Mock模板自己去写一个独立Mock服务。跑完一遍后的感受工具本身没有大错但它把“规范”当作一种可以被消耗的原料——生成完代码就完事了。当代码和规范发生了偏差工具并不会主动提醒你一切都靠人自觉。2.3 用OpenSpec定义“变更计划”第二个分支我试OpenSpec。按照它的规范我创建了一个需求目录里面的结构是specs/ 2025-03-order-query/ proposal.md decisions/ 001-refund-status.md 002-permission-change.md api/ order-openapi.yaml review/ meeting-notes.mdproposal.md的开头有一段YAML frontmatter包含status、author、reviewers、created等字段。正文部分依次写背景、目标、非目标、方案对比、最终决策。这一套写下来的体验其实相当顺畅尤其是我写着写着发现自己必须要把“为什么需要refundStatus”这件事说清楚才能往下走。你被迫去思考这个字段的真实使用场景而不是先在代码里加一个字段再说。这个“先想后写”的约束非常有价值。但我很快遇到一个现实问题写完这些以后接下来呢OpenSpec没有提供脚本把openapi.yaml转成Mock没有自动生成代码的逻辑也没有校验proposal里status字段状态能不能跳转的工具。文档写得再规范代码还得我自己一行一行改。它更适合用来表达“我们达成了什么共识”而不是“这套共识如何自动驱动后续开发”。用OpenSpec写的文档后来被团队拿去做评审记录效果很好。但如果你指望靠它减少联调扯皮那恐怕要失望因为它的能力边界在“描述”而不是“执行”。2.4 用Superpowers接管“流程提醒”第三个分支我用Superpowers。它的接入方式比我预想中简单很多只要在仓库里启用它的检查钩子它会在提交代码时自动识别你改动的文件superpowers check --staged它会输出一串检查结果比如“order-openapi.yaml已更新但mock文件未更新”“订单模块的接口文档已过期”。你根据提示补上对应文件后检查才能通过。这套机制放到团队场景里是有效果的。我们之前经历过“接口文档忘记更新前端按旧文档开发最后整个模块返工”的事情Superpowers至少可以从流程上拦截这种失误。但它给我最大的困惑是它太依赖“团队已经有一份规范基线”了。如果你的接口定义本身就很烂它检查出来的结果依然会通过因为它只关心“文件在不在”“有没有更新”不关心“改得对不对”。后来我还试过把Superpowers和Spec Kit同时用发现两者完全不互补。规范文件更新后Superpowers会要求你重新生成Mock而Spec Kit生成的Mock又被Superpowers判断为“旧的”“未见过的”两边还要做额外适配。工具多了以后流程并没有变轻松反而多了一堆“为了过检查而去跑的仪式”。这也是促使我认真思考“自己选一套组合还是干脆自建”的直接原因。2.5 三者的横向对比用同一需求跑完三套流程之后我整理了一张表把选择工具时需要关心的几个维度放进去对比维度Spec KitOpenSpecSuperpowers上手成本低跑完脚手架就能用中需要理解目录规范中需要配置检查钩子核心聚焦点规范到代码的生成规范内容的组织与评审规范变更后的流程检查代码生成能力强但模板定制成本高无需要自己写脚本无不关心生成规范校验能力弱只校验语法无只定义格式弱只检查文件更新状态流程约束力无有依赖团队自律强自动拦截团队适配度适合快速出活的小团队适合爱写文档的团队适合已有规范但执行力差的团队这张表做完之后我心里差不多有答案了这三套工具都不是“错的”但它们各自只解决了规范驱动开发的一个侧面。Spec Kit解决了生产效率OpenSpec解决了思维表达Superpowers解决了执行纪律。而我真正需要的是一个把三者合起来但我自己可控的东西。3. 为什么我用完三套以后决定自己搭3.1 最大的问题迁移成本和锁定效应我本来想着要不要为了省事挑一个最接近需求的方案直接用。但仔细看下来不管选哪一套都要给团队带来一笔不小的“迁移成本”。就拿Spec Kit举例。你把代码生成逻辑完全交给它以后项目结构会很快被它预设的模板占领。哪天你发现模板不满足业务、想要微调就得去读它内部怎么组织代码这种投入是隐形的。OpenSpec相对好一点它只定义规范文件怎么写不碰代码生成但它的目录结构一旦固定以后团队所有的新需求都要按它的格式来。如果某天你想把某个变更流程改一下就不是改一个配置那么简单而是要重新培养团队习惯。Superpowers的锁定感最弱因为它本质上就是个检查钩子停用很简单。但你一旦依赖了它的提醒再去切换到其他流程时你会发现团队已经习惯“被机器提醒”而不是自己盯着规范。这些都还不算最要命的。最要命的是工具生态越完善团队反而越远离“理解规范”这件事本身。大家只知道要跑某条命令、要填某个字段却不知道这个字段背后的取舍是什么。规范变成了流水线上一个需要被喂进去的零件而不是大家讨论出来的共识。这种情况跑久了工具会让问题变得更隐蔽。3.2 规范的本质是沟通不是流水线我花了很多天去复盘那次选型最后得到一句话规范的本质是“人与人之间的沟通契约”不是“喂给机器的生产原料”。三套工具多少都有点把规范当作生产原料的倾向。Spec Kit要的是能被解析的SchemaOpenSpec要的是符合标准结构的提案文件Superpowers要的是可对比的文件差异。机器视角没问题但团队协作最难的、最需要花时间的是“让所有人对同一个字段的含义产生一致理解”。这部分恰恰是三套工具最不关心的。它们默认你已经想清楚了需求所以只帮你做后面的事情。但实际上大部分项目出问题都出在前面产品说不清要什么前端和后端对“状态”的理解不一样测试不知道哪些异常场景要覆盖。一个真正的规范工具应该在这些模糊地带帮你收敛共识而不是急着生成代码。我决定自己搭一套就是想做一个“让团队先把事情聊清楚再让机器自动干活”的组合流程。工具本身不复杂关键是约束大家用“写规范”的方式来做设计和评审。3.3 自己搭不等于造轮子而是做“定制胶水层”不少朋友听说我要自己搭第一反应是“别重复造轮子”。但我想说明白我没有从零设计一套规范语言也没有写一个代码生成引擎。我做的事情是在OpenAPI、YAML、Markdown这些已经被广泛使用的格式之上定义了一套“哪些字段必须填”“文件怎么放”“改了规范后必须更新哪些内容”的规则再配上一个小小的校验脚本。打个比方我不需要重新发明汽车我只需要在自己的车子里固定好“座椅角度怎么调”“安全带提醒怎么响”“仪表盘显示哪些信息”这些规则。底层工具全部用现成的我要管的是它们之间的胶水层。所以这套方案的核心其实是几个简单的约定而不是多么复杂的系统。正因为简单团队愿意遵守工具坏了也容易修。这是我从三套工具身上学到的最大教训再强大的工具如果它的运行假设和你的团队习惯不一致就一定会被抛弃。3.4 什么情况下不建议自己搭我也得泼一盆冷水。自建方案适合有一定协作规模、规范要长期维护的团队但不是所有团队都需要这么搞。如果你是一个三人左右的项目组要赶一个短周期项目那就直接用Spec Kit赶紧把代码跑起来比什么都强。如果你的团队本来就没什么写文档的习惯你扔一套自建规范进去只会让效率更低还不如先靠Superpowers这样的工具管住基本检查。再比如团队里没有一个人愿意维护校验脚本一旦脚本出了bug没人管这套东西就会变成摆设比不用还糟糕。我自己之所以能自建成功是因为当时团队里有两三个人对“规范驱动”这件事本身感兴趣愿意一起写规则、调脚本。没有这种维护意愿任何自建方案都是坑。4. 我搭的这套轻量方案到底长什么样说完了来龙去脉下面直接上干货。我搭的这套东西不高端但每一项都在解决前面提到的具体痛点。它由三部分组成目录结构约定、规范文件结构要求、校验脚本和CI门禁。4.1 目录结构设计目录结构是整个方案的基础它规定了所有规范文件的存放位置和层级关系。我最终定的结构长这样specs/ README.md api/ order/ order-service.yaml order-service.mocks.yaml user/ user-service.yaml decisions/ 001-refund-status.md 002-admin-permission.md templates/ change-request/ proposal.md openapi.yaml scripts/ validate-specs.js generate-types.js archive/ 2024-09-old-order-api/根目录的README只写三件事规范文件如何提交、状态流转规则是什么、遇到争议找谁。api目录存放接口定义一个服务一个子目录。decisions目录记录重要技术决策用编号开头排序。templates目录是给新建需求用的模板scripts目录放校验和生成脚本archive目录负责归档已经废弃的规范。为什么这么分因为每个目录承担一个独立职责新成员入职只需要看README就能理解整个流程。旧规范挪到archive而不是直接删除保证历史可追溯。4.2 规范文件的结构强制每个新需求必须在templates/change-request里复制出一个新目录然后按模板填写。proposal.md开头的YAML frontmatter长这样--- status: draft title: 订单接口新增分页查询 owner: backend-user reviewers: - frontend-user - product-user version: 1.0.0 created: 2025-03-02 updated: 2025-03-05 decisions: - 001-refund-status - 002-admin-permission ---为什么用YAML不用JSON两个原因。第一YAML支持注释我可以在模板里写“owner请填后端负责人reviewers建议至少填一个前端”这种说明放在JSON里会很奇怪。第二YAML frontmatter直接嵌在Markdown文件头部既不破坏文档的阅读体验又方便脚本提取字段。一个文件同时承载“给人看的内容”和“给机器读的元信息”这是这套方案里我最满意的设计之一。正文部分我要求必须写清楚四个段落背景这个需求为什么存在、目标验收标准是什么、方案接口变更点和决策依据、影响哪些服务受影响是否存在破坏性变更。写不清楚这四个部分这个提案就不允许进入评审。4.3 校验脚本让规范变成可执行的东西光有文件结构还不够得让机器检查它合不合规。我用一个Node脚本做这件事没有引入任何重型框架因为校验逻辑并不复杂。核心代码大概长这样const matter require(gray-matter); const fs require(fs); const path require(path); const ALLOWED_STATUS [draft, review, approved, deprecated]; const REQUIRED_FIELDS [status, title, owner, version, created]; function validateProposal(filePath) { const raw fs.readFileSync(filePath, utf8); const { data } matter(raw); const missing REQUIRED_FIELDS.filter((field) !data[field]); if (missing.length 0) { throw new Error(${filePath}: 缺少必填字段 ${missing.join(, )}); } if (!ALLOWED_STATUS.includes(data.status)) { throw new Error(${filePath}: status 非法期望 ${ALLOWED_STATUS.join(|)}); } if (data.status approved (!data.reviewers || data.reviewers.length 2)) { throw new Error(${filePath}: approved 状态至少需要 2 个 reviewer); } }这只是简化版我实际还加了说明当一个提案从review流转到approved时除了检查reviewer数量还会自动关联对应的OpenAPI文件并校验其中是否存在version字段。状态机是为了防止有人跳过评审直接写approved。4.4 生成器和CI门禁校验脚本只能保证“规范文件本身合格”但规范要真正驱动开发还得靠生成器和门禁。我写了另一个脚本从所有status为approved的OpenAPI文件中提取路径和Schema生成一份JSON前端可以直接用这份JSON去推导TypeScript类型和Mock数据。node scripts/generate-types.js \ --input specs/api \ --output build/generated/types.ts node scripts/generate-mocks.js \ --input specs/api \ --output mock/generatedCI里面做了三道门禁。第一只要PR改动了specs目录下的任意文件就必须附带运行校验脚本的结果。第二如果某个OpenAPI文件的接口路径发生变化但Mock文件没有跟着变CI直接失败。第三proposal.md里如果status从draft改成了review那么该PR必须至少有一个reviewer的评论确认否则不允许合并。这套门禁的价值在于它把“规范有没有被遵守”这个抽象问题变成了“CI是不是绿”这种明确问题。团队不需要每天提醒彼此机器直接挡在最后一步。5. 落地实录团队用了两个月后的变化从第一版目录结构到团队大多数人习惯这套流程总共花了大概两个月。这两个月里有明显的阻力期也有让我觉得“这一切值得”的时刻。5.1 前两周阻力最大的时候刚开始推行时团队里最响的声音是“这也太麻烦了吧”。一个简单的加字段需求以前直接改代码就行现在倒好得先建目录、填frontmatter、写背景、给评审意见旁边还得再准备一份OpenAPI改动和Mock更新。有人甚至直接对我说这不就是把简单的活变复杂了吗。我当时的解决办法不是长篇大论讲道理而是做了一件很具体的事把模板文件做到极简让新需求从“复制模板到填完字段”不超过十五分钟。模板里每个字段边上都写了注释例如“owner请填后端接口负责人”“reviewers至少填一位前端和一位产品经理”。这样就不用靠记忆照着填就行。我还开了一次十五分钟的短会只讲了两个问题这套流程到底在防什么错以及填owner不是为了追责。我举了个例子如果订单字段的命名有歧义以前你只能翻聊天记录找是谁定的有了owner字段你知道该找谁确认省下的是几个小时的无头苍蝇时间。讲完这个例子我能明显感觉到大家对流程的抵触情绪降了一些。5.2 带来的实际收益到了第五周收益开始变得具体。第一个变化是联调会议的次数明显变少。以前一个月至少有十几次联调会其中一半时间都花在对接口字段定义的理解偏差上。现在前端在开发前会先去看specs目录里的接口定义有疑问直接在proposal的评论区提出来后端会顺手改掉OpenAPI文件而不是口头回答完就了事。联调会从每周三次降到每周一次。第二个变化是接口变更导致的返工明显减少。以前后端改了字段类型前端可能过了两天才知道等开始联调才发现类型对不上整个页面逻辑全部重写。现在只要改了接口定义CI就会卡住并要求Mock同步更新前端在改代码之前就会看到新的Mock返回值能第一时间发现自己依赖的字段变了。我们内部统计过光这一项就至少砍掉了三分之一的前后端返工。第三个变化我一开始没想到新产品需求从提出到设计确认的时间变短了。以前开会讨论讲着讲着就偏到“某个按钮放左边还是右边”这种话题。现在有了规范模板大家被引导着先对齐背景和目标如果连“这个需求要解决什么问题”都写不出来大家都觉得不应该继续往下讨论细节。这个“结构化讨论”的副作用甚至比工具本身带来的效率提升更有价值。5.3 踩过的两个大坑第一个坑发生在第三周。我当时把校验规则写得太死要求所有proposal文件的description字段必须大于30个字结果有好几次团队正常改个文案也被CI拦住。后来我把这类“主观性校验”全部去掉了只保留结构性校验比如字段是否存在、状态是否合法、reviewer数量够不够。内容好不好这种事应该由人来判断机器只负责格式完整和信息齐全。第二个坑是规范文件本身膨胀得太快。一个模块一个接口文件刚开始还清晰但当一个接口迭代了四五个版本同一个文件里堆了各种deprecated字段看着就头疼。后来我和团队定了新规则每个新需求用日期目录隔离旧版本的接口定义不做原地修改而是通过新文件覆盖旧文件并把旧文件移到archive。虽然文件数量变多了但搜索和回溯反而更容易。6. 常见问题与排查速查聊到这儿我把平时收集到的高频问题整理成了一张速查表希望对想参考这套方案的人有点用。常见问题可能原因解决办法校验脚本提示“缺少owner”新成员没看模板注释漏填frontmatter在模板注释里写示例再配合README指路status跳转不合法有人把draft直接改成approved跳过了review保留状态机校验不允许跳级改了OpenAPI但Mock没同步只改了接口定义文件没跑生成脚本CI门禁检查生成物变更不通过不允许合并规范文件太多太乱所有需求堆在同一目录用日期加模块路径隔离定期归档旧规范前端说“接口文档更新了但我没收到”文档更新靠口头通知让生成脚本每次变更后自动生成通知摘要挂在群里或看板上不知道一个已废弃的接口为什么还在旧规范直接删掉了统一移入archive目录并在README写明归档规则校验脚本本身出错自己写的脚本有bug给脚本写测试用例用少量模拟规范文件验证行为6.1 校验脚本误报字段缺失这类问题最常见。原因基本两种一是模板字段名写错了比如把owner写成了author二是新需求确实没有某个字段比如一个纯内部工具接口不需要reviewers。我的建议是脚本里把必填字段分成“硬必填”和“按条件必填”两档。硬必填永远不能缺按条件必填只在某个状态或目录下校验。不要把所有校验都做成硬性的否则团队会被细节逼疯。6.2 接口字段格式变了但生成器没更新这类问题往往出现在前端已经改了代码后端临时改字段名但没有重新跑生成脚本。后来我在generate-types脚本里加了一段输出会在跑完后打印“影响xxx.ts”“影响的文件列表”。前端看到输出就知道自己有没有收到影响。如果生成脚本跑完以后提示“无变化”但代码里明明改了接口那就要检查是不是规范文件没被正确读取。6.3 规范变更和代码变更被拆在两个PR里当时最让我头疼的一个场景是有人先提交了规范文件等合并了才去改代码。中间隔了两天Mock和接口文档都显示“新版”但代码还是旧版前端以为能用实际一调就挂。我们的处理方式是在CI门禁里增加一条提示如果某个规范文件状态为approved但对应的Mock文件最近三天没有更新CI会在评论里提醒“这个规范可能已经被实现或已被放弃请确认”。6.4 要不要搬现成工具还是继续自己维护这个问题我被人问过很多次。我的判断标准只有一条如果有一天我这个维护者休假一个月这套流程还能不能继续跑。如果脚本里坑很多只有你一个人会修那就得考虑要么简化流程要么换回成熟工具。我现在维护的这套方案之所以能存续是因为脚本所有人都能看懂需要的Node依赖也少。如果你发现自己写的脚本越来越“聪明”、越来越像一个小型框架那我建议你停下来回到成熟工具上去。工具的复杂度应该匹配团队维护能力否则就是给自己造了个围城。最后分享一个小习惯折腾完这一圈我最大的收获不是自建了某个系统而是一个特别简单、看起来甚至有点“形式主义”的习惯每次有新需求我会先在specs/templates/change-request文件夹里复制一个新目录出来把标题、背景、目标这三行先填上。这个动作只需要两三分钟但它强迫我先把“我们要做一件什么事”写在纸上而不是急着打开代码编辑器。很多需求就是在这个动作里被发现的——要么是背景写不圆要么是目标含糊到连自己都看不下去于是要么去找人对齐要么直接把需求砍掉。工具换了若干个框架起起落落最后留下来的不是哪套脚本也不是哪个目录结构而是这个“先写清楚再动手”的动手习惯。这套东西你可以不用照着搭但如果你现在经常被接口变更、前后端扯皮、文档过期这些事折磨我建议你至少先试两周建一个specs文件夹放一个模板文件每次需求变更都先填三行字。两周后你会回来谢我的。