规格管理工具实测与自建方案：从文档混乱到自动化校验

1. 为什么会盯上规格工具这条赛道先讲个我自己的翻车现场。去年在某团队做一套跨平台业务系统代码还没写几行光是对需求就吵了三轮。产品说这个流程要支持灰度开关开发说设计文档里根本没提这个状态位测试拿着旧版用例对不上新版行为。最后大家停下来翻了半天聊天记录发现不是谁记错了而是根本没有人把当前生效的规格固定下来。每个人头脑里都有一份自己的规格哪有不乱的。那次以后我开始认真看规格管理这件事。所谓规格文件就是需求、接口行为、状态机、字段约束这些东西的结构化文字记录。以前大家用Word写PRD用Wiki写方案用企业IM发补充说明本质上都是规格的载体只是它们天然分散、版本混乱、没有校验机制。后来行业里慢慢出现了一批专门做规格的工具主打把规格文件变成本地Markdown、变成代码库的一部分、变成可以被git追踪和自动检查的东西。我盯上Spec Kit、OpenSpec、Superpowers这三个就是因为它们各自代表了一套处理规格的思路谁都不是简单的文档插件而是想重新定义团队怎么写作规格。如果你正被文档写了没人看、改了没人知道、和代码对不上这类问题困扰这篇文章值得读完。我会把三个工具的实际用法、各自的特点、我遇到的坑以及最后为什么放弃它们自己组装了一套方案全部摊开来讲。适合还在选型阶段、或者已经被规格混乱磨到崩溃的开发者读。2. 三款工具到底各自强在哪2.1 Spec Kit把规范钉进模板Spec Kit定位很直白它是一套结构化的规格文档模板体系主要帮助团队用统一的Markdown结构去写规格。它的核心爆发点在于模板即契约这个思路把一份规格拆成背景、目标、非目标、设计决策、API变更、验收标准等多个固定区块要求写的人按区块填内容不允许自由发挥。我用下来的感受是它对规格里面应该写什么这件事做了非常好的底线约束。以前让开发写设计文档经常写成一团混着背景和结论的散文读的人要自己提炼重点。被Spec Kit模板一卡至少每一份spec出来都有背景区、决策区、验收区扫一眼就知道该看哪里。它对Markdown本身没有侵入性就是一堆模板文件加上配套的CLI脚手架spec-kit new一下就能生成标准目录。但它的短板也很明显。首先是模板的区块是固定的遇到一些特殊类型规格比如数据迁移方案或者前端埋点规范硬套这个模板非常拧巴。其次是它只管写的时候长这样没有提供规格之间如何互相引用、如何标记废弃、如何和代码提交关联这些更往深走一层的能力。如果你团队的问题是文档完全没结构它能快速救火。如果团队已经有结构、缺的是变更追踪和自动化检查它就帮不上太多忙了。2.2 OpenSpec把规格变成可追踪的变更流OpenSpec是另一种思路它把规格当成代码来管理。字面意思上就是把每一份规格放到一个带状态的目录里通过提案proposal的方式发起变更经过评审后合入基线。目录里的每一个规格都可以独立演进每个变更都有前后对比整个规格库就像git管理源码一样commit历史成了规格的演化记录。我比较喜欢它的一个设计是可追踪性优先。团队里一旦出现当初不是这么说的这种话在OpenSpec模式下是可以直接查历史的翻出当时的提案diff谁在哪个时间点改了哪一行一目了然。它在协作流上和代码评审完全同构不需要额外学习一套复杂流程就按pull request那个方式来玩就行评审人看的就是规格diff和看代码diff的体验高度一致。不过它的成本也摆在那。OpenSpec要求团队每个人都养成改需求先改spec再通过变更流程合入的纪律等于把文档工作从创作模式改成了工程模式。对习惯了想到哪写到哪的团队这刚开始会相当阵痛。而且它比较偏向spec本身的版本管理真正下游的使用场景比如从spec自动生成接口桩、自动生成测试用例、自动生成验收清单它没有深入做需要自己接。2.3 Superpowers自动化最强但生态封闭Superpowers在三者里是最重的一个。它不只是管规格文件而是把规格作为输入自动生成后续的一串东西。用它定义一份模块规格之后能基于预设的生成器产出项目结构、接口定义、甚至部分样板代码。从这个角度看它更像一个规格驱动的低代码引擎。在演示里它确实挺唬人改一行规格描述下游的接口文档、参数模型、mock数据全都能跟着变。我一度觉得这种全链路自动化的体验就是终局省掉了大量人工同步文档的时间。但实际推下去发现它和特定框架、特定目录风格绑定很死生成器的行为要想深度定制得先啃透它的内部规则约定这个学习成本不低。更麻烦的是一旦生成链路出了偏差排查问题要在spec文件、生成配置、模板文件之间来回跳比直接改代码还费劲。所以我把Superpowers定位成全能但封闭。适合一个愿接受特定范式的团队愿意把整个工程都建立在它之上深度拥抱它的生态。但如果你想它只是安静地帮你管规格、同时不绑架其他技术栈选择那它反而会成为负担。2.4 横向对比一张表看清定位差我把三款工具放在同一个坐标系里对比一下这样大家选型时不用纠结表面功能先看自己缺的是哪一层维度Spec KitOpenSpecSuperpowers核心侧重模板化写作规格的版本与变更管理规格驱动的自动生成上手门槛低中偏高对团队纪律要求低仅约束写作结构高强制走变更流程中高需要遵循约定协作方式分散编辑、手动同步类代码评审全程可追踪集中配置、批量生成扩展深度弱仅有模板中变更追踪很强强但绑定生态最适用场景文档格式混乱的团队需求变更频繁、需要追责审计愿意重塑整个工程方式的团队主要风险模板僵化推进阻力大技术栈绑定深后期难以脱身看完这张表你应该能感觉到这三者其实不在同一个赛道上它们分别解决了规格问题的不同层次一个是写作规范一个是变更流程一个是自动化生产。我当时想的是能不能把它们三个的优点合到一起用统一的Markdown目录管理规格每一次变更可追踪可评审下游还能自动生成一些辅助产物。这听起来很理想实际操作起来却撞上了一堆墙。3. 它们解决不了的核心痛点3.1 摩擦成本比功能缺点更致命工具选型有一个特别容易被忽略的指标日常使用的摩擦成本。一款工具哪怕功能再强如果让一个普通开发每天多花两分钟做额外动作这个团队最终一定会悄悄放弃它。我在三个工具里都遇到了不同的摩擦点。Spec Kit的问题是引导性不足。它给了模板框架但没有提供检查机制写完一份spec不规范也没人提醒时间一长模板就变形了项目里会出现三种风格并存的状况。OpenSpec的问题在于流程刚性每一次小修改也要走完整的提案、评审、合入流程改一个字段描述都要这么来一遍很多开发会觉得这点破事也值得开个变更最终导致流程绕开。Superpowers的摩擦就更直接了任何自定义都要研究它的配置语法出了问题还不好调试人很容易在它上面耗尽耐心。我自己感受最深的结论是工具在功能完美和阻力最小之间做选择时除非你的团队纪律性极强否则阻力最小几乎总是更重要。规格工具是要全员每天都用的不是只有架构师偶尔碰一下的玩具任何让人觉得麻烦的设计都会被实际工作流淘汰。3.2 模板标准化和团队习惯脱节现成工具的另一层痛点是模板是别人定义的它反映了别人的思考习惯不一定适配你的团队。比如我们团队有一部分规格是给运营看的需要非常啰嗦地带业务背景另一部分是给后端开发的需要冷冰冰的字段约束和边界说明。如果硬要套同一个模板要么运营觉得文档不说人话要么开发觉得废话太多。Spec Kit让我意识到模板标准化本身是双刃剑。标准化确实解决了没有结构的问题但它解决不了结构不匹配的问题。团队内部每个角色对规格的消费方式完全不同一套标准打天下意味着要么大家迁就模板要么各自在模板外补充私人笔记后者又会造成信息分散。这就是为什么我发现需要一套既能统一骨架、又允许按文档类型扩展区块的方案而这种半标准的诉求在现有工具里找不到。3.3 生成链路的黑盒与新老工具撕咬用Superpowers的时候我还遇到一个更头疼的问题就是生成链路的黑盒化。当你点一下生成几十个文件哗啦啦地冒出来一开始觉得特别爽。但是过了一个月你改了一个spec里的字段描述重新生成之后发现某个文件里的逻辑变了而你不记得那个文件的逻辑是从哪里来的因为生成规则太复杂了你根本没法在脑子里维护那张影响关系图。另一个大问题是新老工具的衔接。团队里已经有一堆存量文档、已经跑着的接口文档平台、已经习惯的Wiki流程新工具不是在一个空白世界上跑而是要在旧世界里插一脚。OpenSpec这种把规格当作唯一真相源的做法在理念上很先进但现实是存量文档还躺在旧平台里两边并存必然导致有人更新这边有人更新那边最后反而制造了新的不一致来源。我当时认清了一件事规格工具的本质是一个系统工程它要和现有的git工作流、代码生成、接口平台、需求管理工具全部缝合起来任何一个环节出现缝合不严整个链条都会漏气。4. 我自己搭的那套东西是怎么设计的4.1 一开始的思路最小可行契约在放弃现成工具之后我没有马上去写一个大型框架而是先定义了我们团队真正不能妥协的几条底线。首先规格必须存在git仓库里和代码同库这样提交记录天然就是变更历史。其次规格文件必须有统一的前置元信息包括状态、负责人、关联模块、版本号。第三要有自动校验格式不对的spec提交直接拦在CI里。第四要能从spec生成两类辅助产物一个是接口桩代码一个是需求追踪清单。我把这套方案取名叫最小可行契约核心思想就是我只管规格的骨架和流转机制不在写作体验上发明新轮子。每个人依然是写Markdown但是有固定区块、有元信息、有校验脚本一旦提交到主分支就有后续动作自动发生。这样做的好处是既不会强迫所有人改变写作习惯又通过自动化把纪律给兜住了。4.2 目录结构与文件契约目录设计我参考了模块化拆分思路每个业务域一个目录每个域内包含当前基线规格和待评审变更分开存放。实际结构是这样的specs/ module-a/ current/ 001-service-contract.md 002-data-model.md proposals/ 20240501-add-billing-status.md module-b/ current/ 001-event-spec.mdcurrent目录下放的就是当前生效的规格每个文件有自己稳定的编号和标题。proposals目录下放变更提案文件名以日期开头天然排序提案一旦被接受并合入就把对应内容更新到current的规格文件里提案文件本身保留作为历史记录。每个规格文件的头部我用YAML frontmatter统一承载元信息--- id: 001 title: 服务契约 module: module-a status: active owner: backend-team last-reviewed: 2024-04-20 ---status字段有四个可选值active、deprecated、draft、reviewing。这个字段是整个流转机制的核心reviewing状态的规格不允许出现在最终生成的任何文档里deprecated状态的规格会在代码生成阶段触发告警日志。一切自动化都以status为前提而不是靠人工判断这份文档还能不能用。4.3 自研校验的CLI不让规范变摆设光有目录和模板是不够的人是会懒的所以必须把规范变成机器强制执行的约束。我用Go写了一个轻量CLI名字就叫spec-check集成到CI流水线里。它做了三件事检查YAML头字段是否齐全、检查编号是否重复、检查当前目录下的文件是否都处于active状态。校验逻辑其实不复杂但有一个点我想提醒大家不要在CLI里塞太多规则。我一开始加了十几条检查项包括标题长度、标签数量、关键词合法性结果团队成员怨声载道因为提交前反复被拦。后来我把校验精简到三条绝对底线其他建议性规则降级为警告而非报错。这个取舍非常重要工具的使命是兜底不是当警察。CLI的核心逻辑片段大致是这样spec-check --review-warnings # 输出示例 # ✓ 001-service-contract.md frontmatter ok # ✓ 002-data-model.md status active # ⚠ 003-old-spec.md deprecated but still in current/警告不阻断CI错误才阻断。这样的设计让团队感觉到的是帮助而不是阻碍规范性逐渐变成了肌肉记忆而不是每次提交前的负担。4.4 自动生成两个副产品稳定了规格结构之后我开始接自动生成。优先做的是接口桩生成。我们的接口契约文件里用特定代码块声明API端点和请求响应结构CI里跑一个解析脚本把契约转成Python和Java的接口桩代码直接输出到对应服务的stub目录。开发拿到的是一个可编译的空壳实现字段名和类型都是从spec来的天然和文档一致。第二个副产品是需求追踪清单。每个规格文件的验收标准区块里都有可编号的验收条目脚本会把当前所有active状态的规格里所有待验收条目汇总到一份清单测试同学直接拿这个清单去映射测试用例跑完勾选结果。做这个功能之后测试和开发的对接效率明显提升因为验收标准不用翻文档了机器帮你汇总成一张表了而且来源永远是当前的active规格。5. 踩过的坑和故障现场5.1 自动生成文件污染PR自建方案遇到的第一个坑来自自动生成。因为生成的桩文件是跑脚本直接产出并写到仓库里的结果每次跑完重新生成都会产生大量diff代码评审里充满了一堆没有意义的更新生成文件提交。这个问题的本质是生成产物不该和手写代码混在一个提交流里。我的解决办法是调整目录策略生成产物单独进一个目录并且用.gitattributes标记为generated。代码评审时默认折叠生成目录的diff只有真正手写的代码变动才会出现在评审界面上。生成产物不参与手写代码的review但保留在仓库里以便编译和测试直接引用。这个策略大家如果有类似场景可以直接照抄省掉很多评审噪音。5.2 存量文档迁移的断舍离把旧文档往新目录结构迁移的时候我犯了一个典型错误想把所有历史文档都搬进来结果迁移过程极其痛苦。很多旧文档根本没有元信息当时定的状态也不准确搬到一半发现大量文档其实已经废弃只是没人敢删。后来我换了个思路所有存量文档默认归入legacy目录不进新规格体系只有真正还在被引用的文档才手动升级到新目录。这个默认不迁移的策略让整个系统落地快了很多也避免了新工具和旧历史死磕。这件事给我的经验是规格工具的引入本质上是一次信息架构的重新整理不是搬运。不要试图把历史垃圾搬进新房子要在新房里只放真正有价值的资产。5.3 校验脚本变成大型项目我在做CLI时踩的第三个坑也很典型就是功能越加越多最终不可维护。起初只想做校验后来想让它直接调接口出mock再后来想让它支持交互式提案创建每次加需求都想放在这个CLI里最后代码膨胀到三四个模块bug率直线上升。后来我砍掉了CLI里和校验无关的功能把其他能力拆成独立的独立工具让CLI只做一件事并且做好。这里有一个血泪教训自建工具最怕的不是功能不足而是做得太重。做出一个只有自己会用的复杂工具比写一个朴素好用的脚本失败得多。保持小而专是自建方案的底线。5.4 常见问题速查表问题症状排查方向我的解法规格文件状态混乱同一文件出现多个status标记检查YAML格式是否多空格统一用脚本检测违规即报错生成的接口桩和手写逻辑冲突编译不过或运行时报错确认是否手工修改了generated文件生成目录设为只读约定修改需复制到srcCI中规格校验时好时坏同一提交偶尔拦偶尔过检查是否有跳过校验的逃逸路径禁用跳过必须全量校验提案合入后基线不同步current目录和proposal内容不一致检查合入流程是否仅存档未更新基线合入即更新基线文件同时保留提案团队有人绕开spec直接改代码接口和文档开始漂移代码评审时未强制检查spec让CI比对代码变更与相关spec状态不匹配则告警6. 留给你的选型建议6.1 什么情况老实选现成工具我虽然最后自己搭了一套但我还是想跟所有人说自建不是默认选项绝大多数团队老老实实用现成工具反而更好。如果你的团队规模不大规格文件数量不多市面上任何一个工具只要能坚持用下去效果都远好于继续用wiki和IM来管理需求。选型只看一个指标这个工具用多久能让团队最自然地养成写规格的习惯。Spec Kit适合完全没结构的团队OpenSpec适合变更频繁且需要审计追踪的团队Superpowers适合愿意深度绑定生态的工程团队。6.2 什么情况适合走自建路线真正适合自建的信号是你对现成工具的每一个都认可某个部分但没有任何一个能覆盖你全部关键路径。并且你团队有工程能力去维护脚本和CI流程。最关键的是你愿意且有能力持续投入维护。规格工具不是一次性项目它随着团队规模变化需要不断调整如果你建设完就不想再碰它那还是买现成的吧。另外一个重要的前置条件是团队核心成员必须对这自建路线有真实认同。如果只是架构师拍板决定其他成员被动接受那再好的自建方案也活不过三个月。我在推进自建方案前和团队成员逐一聊了一遍把为什么要自建和现在的工具有什么问题摊开来讨论过大家认可之后推进阻力小了很多。6.3 关于自己搭的一些底线判断以我踩过的坑来看自己搭规格系统有几个底线建议。第一规格文件永远保存在仓库里和代码同生命周期这是所有追踪和自动化的根基。第二自动化要做但只做能节省别人时间的部分不要做只有自己看得懂的炫技功能。第三任何规则都必须有机器检查兜底人记不住的规则等于没有规则。第四保持简单宁可多个小脚本各干一件事也不要一个大工具包揽所有功能。我个人实际使用中的体会是规格管理这件事真正难的不是技术而是让团队愿意持续维护一套文字版的事实。工具选型永远没有万能解适合团队节奏的才是好工具。如果你现在正在三个工具之间纠结先别急着比功能回去看一眼你团队最痛的那个问题是什么然后选一个恰好能撞上那个痛点的方案哪怕它其他方面弱一点。现在这套自建方案在我们的日常协作里跑了四个多月最大的变化是所有人对当前规格是什么这件事不再有疑虑了。以后如果这个思路还可以往下扩展我可能会在规格文件里增加更多可执行验证条目比如从验收标准直接生成冒烟测试然后把需求和缺陷管理平台的ID也纳进来。到那时或许又会有新的工具出现到时候再迭代也不迟。