1. 为什么规范驱动开发突然成了绕不开的话题如果你最近半年在开发社区里泡着大概率会反复刷到三个名字Spec Kit、Superpowers、OpenSpec。它们被一些人打包叫作规范驱动开发三剑客听起来像是某个新出的框架组合实际上三者定位差别很大甚至不完全在同一个层面上竞争。我最初接触它们的时候也犯过迷糊——以为都是写文档然后生成代码的工具用了一圈才发现它们解决的是完全不同阶段的问题。先说清楚这篇文章要聊什么。规范驱动开发Specification-Driven Development简称 SDD的核心主张是在让 AI 写代码之前先把要做什么、做到什么程度、边界在哪用结构化规范描述清楚再让工具基于规范去生成、校验、迭代。它和传统的提示词工程最大的区别在于规范是可复用、可版本化、可校验的资产而不是一次性的对话记录。Spec Kit、Superpowers、OpenSpec 就是这条链路上三种不同思路的代表。这篇文章适合三类人看一是已经在用 AI 辅助编码、但被生成结果不稳定、改一处崩三处折磨过的开发者二是团队里负责制定研发流程、正在评估要不要引入规范驱动这套方法的技术负责人三是单纯想搞清楚这三个工具到底谁是谁、该选哪个的观望者。我会把每个工具的核心机制拆开讲把选型判断的依据摆出来再给一套可以照着走的落地路径。全文基于我自己的实测和踩坑不吹不黑该说局限的地方直接说。需要提前说明一点这三个工具都还在快速迭代接口和命令可能隔几周就变。所以我会重点讲设计思路和判断逻辑而不是死记某条命令。命令会过时思路不会。2. 三剑客到底各管哪一段定位拆解2.1 Spec Kit把需求翻译成机器能读的规范Spec Kit 的定位最接近规范本身的生产工具。它的核心思路是提供一套结构化的规范模板和校验机制让你把模糊的需求写成有固定骨架的文档——包含目标、用户故事、验收标准、边界条件、非目标明确不做什么等字段。写完之后工具会检查你的规范是否完整、是否存在自相矛盾、验收标准是否可测试。我实测下来它最有价值的不是生成代码而是逼你把需求想清楚。很多人用 AI 写代码翻车根因不是模型不行而是自己都没想明白要什么。Spec Kit 通过模板强制你把用户点击按钮后应该发生什么这种细节写出来写不出来的地方就是需求黑洞。它的输出物是一份机器可解析的规范文件可以被后续的代码生成环节消费。所以 Spec Kit 更像是上游的规范层它不关心你用什么模型、什么语言只关心规范的质量。2.2 Superpowers给 AI 装上技能包的执行层Superpowers 的定位完全不同。它更像是一套给 AI 编码助手用的技能扩展框架。你可以把它理解成把常见的开发任务比如写一个符合规范的 API 端点重构这段代码并保持行为不变根据规范生成测试用例封装成可复用的技能AI 在执行任务时按需调用这些技能而不是每次从零开始即兴发挥。它的核心价值在于把规范变成可执行的技能。Spec Kit 产出的规范是静态文档Superpowers 则让 AI 能够按照规范去执行具体动作。我自己的体会是Superpowers 解决的是AI 每次生成风格不一致、质量忽高忽低的问题——因为技能包里固化了最佳实践和检查清单AI 每次执行都走同一条路径。它和 Spec Kit 是互补关系Spec Kit 负责写清楚要什么Superpowers 负责按这个要求稳定地做出来。2.3 OpenSpec规范与代码之间的对账工具OpenSpec 关注的是另一个痛点规范和代码会漂移。你三个月前写的规范代码早就改得面目全非但没人更新规范。OpenSpec 的思路是提供一套开放的规范格式和比对机制能够检查当前代码实现是否符合规范描述把规范说的和代码做的之间的差异暴露出来。它有点像规范层面的lint 工具。你定义好规范它帮你扫描代码库告诉你哪些地方偏离了规范、哪些规范条目已经没有对应实现可能是废弃了但没清理、哪些实现没有规范覆盖可能是偷偷加的需求。这三个工具串起来就是一条完整的链路Spec Kit 写规范 → Superpowers 按规范执行 → OpenSpec 校验执行结果是否偏离规范。当然你不一定要三个都用很多团队只用其中一个也能解决核心痛点。工具核心定位解决的核心问题输出物Spec Kit规范生产与校验需求模糊、验收标准不可测结构化规范文件Superpowers技能封装与执行AI 生成质量不稳定、风格漂移可复用技能包 执行结果OpenSpec规范与代码比对规范代码漂移、覆盖盲区差异报告3. Spec Kit 的规范模板字段设计与填写逻辑3.1 为什么模板字段是这么设计的Spec Kit 的规范模板不是随便定的每个字段都对应一类常见的需求缺陷。我把它拆开讲你就能理解为什么不能省字段。目标Goal字段要求用一句话说清楚这个功能要达成什么。听起来简单但很多人写出来的是实现用户登录功能——这是任务不是目标。真正的目标应该是让已注册用户能够通过凭证验证进入系统。区别在于任务描述的是做什么动作目标描述的是达成什么状态。后者才能推导出验收标准。用户故事User Story字段强制你从使用者视角描述场景。格式通常是作为[角色]我希望[行为]以便[价值]。这个字段的价值在于暴露谁在用、为什么用。我见过太多需求写着写着就变成了技术自嗨用户故事能把它拉回来。验收标准Acceptance Criteria是最关键的字段也是最容易写砸的。好的验收标准必须是可测试的——给定什么输入、执行什么操作、期望什么输出。写系统应该快速响应是废的写在 100 并发下 P95 响应时间小于 200ms才是可测的。Spec Kit 会校验你的验收标准里有没有出现快速友好合理这类不可测的形容词有的话会提示你改写。边界条件Edge Cases字段要求列出异常路径。比如用户输入空密码网络中断时提交并发修改同一条记录。这个字段是区分新手和老手的分水岭——新手只写正常流程老手知道 bug 都藏在边界里。非目标Non-Goals字段可能是最被低估的。明确写出这次不做什么能防止范围蔓延。我踩过的坑就是需求没写清楚不做什么开发过程中不断有人加需求最后交付延期一倍。3.2 一份规范从草稿到可用的完整过程我拿一个真实场景走一遍给一个内部工具加批量导出数据功能。第一步先写目标。草稿是加个导出按钮。这不行太模糊。改成让运营人员能够把筛选后的数据列表导出为表格文件用于线下分析。这样角色、行为、价值都有了。第二步写用户故事。作为运营人员我希望在数据列表页选择筛选条件后一键导出以便把数据拉到本地做透视分析。这里暴露了一个关键信息导出的是筛选后的数据不是全量。如果没写这句开发很可能做成全量导出。第三步写验收标准。我列了五条导出文件格式为 CSV 且首行为表头导出内容与当前筛选条件一致单次导出上限 5 万行超出时提示分批导出过程有进度提示导出失败时给出可重试的错误提示。每一条都能测。第四步写边界条件。空结果集导出时应该生成只有表头的文件还是提示无数据筛选条件包含特殊字符时文件名怎么处理导出过程中用户切换页面怎么办这些都得定。第五步写非目标。这次不做定时导出、不做导出模板自定义、不做导出到云存储。写清楚省得后面扯皮。走完这五步你会发现规范文档本身就是一份开发说明书。Spec Kit 的价值就在这里——它不生成代码但它让后续所有环节都有了依据。3.3 实测中发现的三个填写陷阱第一个陷阱验收标准写成实现细节。有人写使用 Redis 缓存查询结果这是实现方案不是验收标准。验收标准应该写重复查询同一条件时响应时间小于 50ms至于用不用缓存、用什么缓存是实现自由。第二个陷阱用户故事写成技术任务。作为开发者我希望重构这个模块——这不是用户故事用户故事的主角必须是使用者不是开发者自己。重构是技术任务应该放在非目标或者单独的技术债清单里。第三个陷阱边界条件写成了异常处理清单。边界条件描述的是什么情况下会发生什么不是代码里要 try-catch 什么。前者是需求后者是实现。提示Spec Kit 的校验只能查格式和明显矛盾查不出需求本身是否合理。规范写完之后一定要拉上真正的使用者过一遍别自己闷头写完就开干。4. Superpowers 的技能封装机制从提示词到可复用资产4.1 技能包和普通提示词的本质区别很多人第一次听说 Superpowers 会想这不就是提示词模板吗我存几个常用的提示词不就行了区别在于约束强度和可组合性。普通提示词是建议性的——你告诉 AI请写一个规范的 APIAI 可能规范也可能不规范。技能包是约束性的——它内置了检查清单和输出格式要求AI 执行完技能后输出必须满足预设的结构否则会被判定为执行失败并重试。更关键的是可组合性。一个生成 API 端点的技能可以调用生成数据校验逻辑的子技能再调用生成单元测试的子技能。这种组合关系是显式定义的不是靠提示词里写顺便把测试也写了这种模糊指令。我实测的感受是技能包把隐性经验变成了显性资产。团队里那个最懂规范的老手他的经验以前只在他脑子里现在可以封装成技能包让 AI 和所有新人都能复用。4.2 一个技能包应该包含哪些部分我拆解了几个用得顺手的技能包发现它们都有相似的结构。触发条件Trigger什么情况下该用这个技能。比如当需要新增一个符合团队 API 规范的端点时。触发条件写得越具体AI 越不容易误用。输入契约Input Contract执行这个技能需要提供什么。比如需要提供端点路径、HTTP 方法、请求体结构、响应体结构、鉴权要求。输入不全会直接报错而不是让 AI 猜。执行步骤Steps分步骤的执行逻辑。这里的关键是每步都有明确的产出而不是笼统的生成代码。比如第一步根据输入契约生成接口定义第二步生成参数校验逻辑第三步生成业务逻辑骨架第四步生成单元测试。检查清单Checklist执行完必须逐项确认的检查点。比如是否处理了空输入是否返回了正确的状态码是否有日志埋点。检查清单是保证质量一致性的核心。输出格式Output Format产出的文件结构、命名规范、代码风格。这部分通常和团队的代码规范绑定。4.3 技能包维护的坑什么时候该拆、什么时候该合我踩过最大的坑是技能包粒度失控。一开始什么都往一个技能包里塞结果一个技能包有二十几个步骤AI 执行到一半就忘了前面的约束。后来我总结出一条经验单个技能包的步骤不要超过七步超过就拆成主技能加子技能。另一个坑是技能包版本管理。技能包改了之后之前用旧版本生成的东西怎么办我的做法是给技能包打版本号规范文件里记录用的是哪个版本的技能包。这样出问题能追溯也能判断是规范的问题还是技能的问题。还有一个反直觉的经验不是所有任务都值得封装成技能。一次性任务、探索性任务、需求还在变的任务封装技能反而增加维护成本。值得封装的是那些高频、稳定、有明确最佳实践的任务。我一般会观察一个任务如果重复做了三次以上且每次做法基本一致才考虑封装。技能包要素作用常见错误触发条件界定适用范围写得太宽导致误用输入契约明确前置依赖允许缺省让 AI 瞎猜执行步骤固化操作路径步骤过多超出 AI 上下文检查清单保证质量一致检查项不可验证输出格式统一产出风格与团队规范脱节5. OpenSpec 的漂移检测让规范和代码不再各说各话5.1 漂移是怎么发生的三种典型场景规范和代码漂移不是某个人偷懒造成的它是流程自然演化的结果。我观察到的漂移主要有三种。第一种是紧急修复型漂移。线上出 bug开发直接改代码修复没时间更新规范。修完就忘了规范停留在旧版本。这种漂移最危险因为规范描述的行为和实际行为不一致后来的人按规范理解代码会完全懵。第二种是渐进演化型漂移。需求慢慢变化代码跟着小步调整每次调整都觉得这点小改动不用更新规范积累半年后发现规范已经和代码差了十万八千里。第三种是规范先行型漂移。规范写得很超前规划了未来三个版本的功能但代码只实现了第一个版本。这种漂移本身不算问题但如果没有标记清楚哪些规范已实现、哪些未实现就会造成混淆。OpenSpec 的价值就是把这三种漂移可视化。它通过解析规范文件和代码库建立映射关系然后报告差异。5.2 漂移检测的三种粒度我实测下来OpenSpec 的检测可以做到三个粒度每个粒度解决不同问题。条目级检测规范里的某一条验收标准在代码里有没有对应的实现和测试。这个粒度最粗但能快速发现规范写了但没做的情况。行为级检测规范描述的行为代码实际执行的行为是否一致。这个粒度需要更深的分析通常要结合测试用例。比如规范说超过 5 万行提示分批代码里是不是真的在 5 万行处做了判断。边界级检测规范列出的边界条件代码里有没有对应的处理。这个粒度最细也最有价值。我见过太多代码只处理了正常流程边界条件全靠应该不会发生。5.3 把漂移检测接进日常流程的实操漂移检测如果只在季度评审时跑一次价值有限。我的做法是把它接进持续集成流程。具体来说在代码合并请求PR阶段就跑一次 OpenSpec 检测如果发现这次改动导致规范与代码偏离就在 PR 里自动评论提示。这样漂移在产生的当下就被发现而不是积累三个月后才暴露。但这里有个坑不是所有漂移都需要立即修复。有些漂移是合理的比如规范过时了代码是对的有些是紧急修复留下的需要补规范。所以检测报告要能区分需要更新代码和需要更新规范两种情况。我的做法是在规范文件里给每条加一个状态标记检测到偏离时如果规范标记为已废弃就提示删规范如果标记为生效中就提示改代码。注意漂移检测的前提是规范和代码之间有可解析的映射关系。如果你的规范写得全是自然语言散文没有结构化的条目和标识符检测工具也无能为力。这也是为什么 Spec Kit 那套结构化模板很重要的原因——它为后续的检测打下了基础。6. 选型判断你的团队到底该从哪个入手6.1 按痛点选而不是按热度选我见过太多团队跟风上工具结果用不起来。选型的正确姿势是先定位痛点再选工具。如果你的痛点是需求总是理解偏差做出来的东西不是想要的那核心问题是规范缺失应该从Spec Kit入手。先把需求写清楚这一步的投入产出比最高。如果你的痛点是AI 生成的代码质量不稳定每次都要大量返工那核心问题是执行环节缺乏约束应该从Superpowers入手。把团队的最佳实践封装成技能包让 AI 按固定路径执行。如果你的痛点是代码和文档对不上新人上手困难老代码不敢改那核心问题是漂移应该从OpenSpec入手。先把现状摸清楚再决定怎么治理。6.2 团队规模与成熟度的影响小团队3 人以下我一般建议只上 Spec Kit。人少沟通成本低规范写清楚基本就够了技能封装和漂移检测的收益不明显反而增加维护负担。中等团队4 到 15 人可以考虑Spec Kit Superpowers。这个规模开始出现每个人做法不一样的问题技能包能统一执行标准。漂移检测可以先用轻量方式比如定期人工比对不急着上工具。大团队15 人以上或者多团队协作三个都值得上。规范层统一需求语言技能层统一执行标准检测层保证长期一致性。但要注意大团队上工具一定要先小范围试点别一上来就全量推否则阻力会很大。6.3 一个务实的落地顺序如果你决定三个都上我建议的顺序是先 Spec Kit再 OpenSpec最后 Superpowers。先上 Spec Kit 是因为规范是基础没有规范后面两个工具都没有输入。而且规范化的收益最快显现——需求写清楚了开发返工率立刻下降。再上 OpenSpec 是因为它能帮你摸清现状。在封装技能之前你得知道当前代码和规范的偏离程度否则你封装的最佳实践可能本身就是错的。最后上 Superpowers 是因为技能封装最耗时而且需要前两步积累的规范和实践作为素材。顺序反了的话你会封装出一堆基于错误实践的技能包越用越乱。团队情况推荐组合理由3 人以下仅 Spec Kit沟通成本低规范足够4-15 人Spec Kit Superpowers需要统一执行标准15 人以上三者全上需要全链路治理遗留系统为主先 OpenSpec先摸清漂移现状7. 三剑客协同的完整工作流从需求到交付7.1 需求阶段Spec Kit 产出规范基线工作流的起点是需求。产品或者业务方提出需求后不直接进入开发而是先用 Spec Kit 的模板把需求结构化。这个阶段的关键角色是需求提出者和技术负责人他们要一起把目标、用户故事、验收标准、边界条件、非目标填完整。我实测下来这个阶段平均要花 1 到 2 小时比传统口头说需求多花时间但能省下后面几倍的返工时间。规范写完后Spec Kit 会做一轮校验把明显的问题不可测的标准、缺失的边界标出来改完才算通过。产出的规范文件进入版本控制成为这个需求的唯一事实来源。后续所有讨论、开发、测试都以它为准不再依赖聊天记录或者口头约定。7.2 开发阶段Superpowers 按规范执行开发阶段AI 助手加载对应的技能包读取规范文件按技能定义的步骤执行。比如生成 API 端点技能会读取规范里的接口定义部分生成代码骨架、校验逻辑、测试用例。这个阶段的关键是技能包和规范的对接。技能包的输入契约要和规范的字段对应上否则 AI 读不懂规范。我的做法是在规范模板里预留技能提示字段标明这个需求适合用哪些技能包处理。开发过程中如果发现规范有问题比如边界条件没考虑到不是直接改代码绕过而是回到规范层修改改完再重新执行。这个纪律很重要否则规范很快就失去权威性。7.3 交付阶段OpenSpec 校验一致性代码写完后在合并请求阶段跑 OpenSpec 检测。它会比对规范条目和代码实现报告三类问题规范有但代码没有漏做、代码有但规范没有偷加、规范和代码行为不一致做错。检测报告作为合并请求的评审依据之一。漏做和做错的必须修复偷加的要么补规范要么删代码。这样保证交付时代码和规范是对齐的。7.4 迭代阶段规范作为变更的锚点需求变更时不是直接改代码而是先改规范。改完规范后重新走一遍执行和检测流程。这样每次变更都有迹可循规范始终反映系统的最新意图。我自己的体会是这套流程跑顺之后最大的变化是沟通成本大幅下降。以前讨论需求要拉一堆人开会现在看规范文件就行以前代码评审靠感觉现在有检测报告作为客观依据。8. 实测踩坑记录那些文档里不会写的问题8.1 规范写太细反而拖慢进度我一开始用 Spec Kit 的时候追求把每个细节都写进规范结果一份规范写了八千字开发看了半天还没开始写代码。后来我调整了策略规范写到验收标准可测就够了实现细节留给开发。判断标准很简单如果一条内容写进规范后不影响验收标准的判定那它就不该进规范。比如用哪个数据库用什么设计模式这些除非有硬性约束否则不该写进规范。8.2 技能包过度封装导致灵活性丧失Superpowers 用了一段时间后我发现有些任务被技能包框死了。技能包规定必须走某个流程但实际场景下那个流程不适用AI 却还是硬走结果产出很别扭。解决办法是给技能包加逃生舱在技能定义里允许在特定条件下跳过某些步骤或者调用替代路径。但逃生舱不能滥用否则技能包就失去约束意义了。我的经验是一个技能包里逃生舱不超过两个。8.3 漂移检测的误报让人麻木OpenSpec 刚接入的时候检测报告里一堆误报——有些是规范表述和代码实现方式不同但行为一致有些是规范里的示例代码和实际代码不同。误报多了之后团队就麻木了真问题也被忽略。治理误报的办法是持续调优检测规则。把确认是误报的模式加入白名单把漏报的模式加入检测规则。这个过程要持续几周直到误报率降到可接受水平我的目标是低于 10%。在误报率降下来之前不要强推检测报告作为硬性门禁否则会引起反感。8.4 三个工具的数据格式不互通这是最现实的坑Spec Kit 产出的规范格式、Superpowers 消费的技能输入格式、OpenSpec 解析的规范格式三者并不完全一致。我一开始以为可以无缝串联实际用起来发现要做格式转换。我的做法是以 Spec Kit 的格式为基准写一层转换脚本把规范转成 Superpowers 能读的输入同时转成 OpenSpec 能解析的结构。这层脚本是必要的胶水别指望工具之间自动兼容。提示在选型评估阶段一定要做一次端到端的串联测试别只看单个工具的功能演示。工具之间的衔接成本往往比工具本身的学习成本还高。9. 关于长期维护的一点个人看法这套东西用下来我最大的感受是规范驱动开发的瓶颈不在工具而在纪律。工具能帮你写规范、执行规范、检测偏离但没法强迫团队真的去用规范。我见过团队买了最好的工具规范文件建了一堆三个月后全部荒废代码该怎样还怎样。能跑起来的团队都有一个共同点把规范当成了交付物的一部分而不是额外负担。代码合并请求里没有规范更新就不给合并需求评审没有规范文档就不进入开发。这种纪律一旦建立工具才真正发挥作用。另一个体会是不要追求一步到位。我见过团队想一次性把三个工具全上、把所有历史代码都补规范结果三个月都没搞完团队怨声载道。务实的做法是选一个正在做的新需求作为试点完整走一遍流程跑通了再逐步扩大范围。历史代码的规范补全优先级放在最后甚至可以不补——把精力放在新代码上让规范覆盖率自然增长。最后说一个容易被忽略的点规范也是要定期清理的。废弃的功能对应的规范要及时删除或标记废弃否则规范库会越来越臃肿检测报告里全是噪音。我一般每个季度做一次规范清理把已废弃的条目归档保持规范库的精简。这件事没人催但不做的话前面所有的投入都会慢慢贬值。