OpenSpec 是一头猛虎它有完整的规划方法论58,000 多个 star 是社区对它的认可。Superpowers 是一双铁翼245,000 多个 star 证明了执行纪律是 AI 编程的刚需。但如果你只是把它们放在同一个项目里你得到的是「一头老虎 一双翅膀」而不是「一头会飞的老虎」。我是码哥今天给大家分享一个在 Github 很有特色的一个工作流 spec-superflow。我们知道 OpenSpecGitHub 58k stars管规划Superpowers245k stars管执行但装了两个插件不等于有了工作流。spec-superflow把两个神级框架的引擎源码级融合独创contract-builder契约桥接层让AI编程从碰运气变成可预测。https://github.com/MageByte-Zero/spec-superflow 推荐大家安装使用点个Star。这几天体验下来太爽了既有初恋的美好还有知心姐姐的风韵一、规划归规划执行归执行我用了两年 AI 编程工具踩过的最深的坑不是代码写错了而是代码写完了规划文档还躺在仓库里吃灰。这个场景你应该不陌生花了半小时跟 Claude Code 聊需求产出一份漂亮的proposal.md和design.md。然后呢然后你开始写代码AI 开始帮你写代码三天后功能上线了。回头一看当初那份规划文档里的约束「这个模块要支持水平扩展」「API 响应时间必须控制在 200ms 以内」代码里一条都没兑现。不是 AI 不听话是没人把规划「焊」到执行流里。规划文档写完的那一刻它就成了历史文件。执行阶段的 AI 不知道它存在知道也不会主动去读。你在规划阶段花了 30% 的精力但这些精力的产出物对后续 70% 的执行阶段毫无约束力。这就是 AI 编程当前最大的结构性缺陷规划和执行是断层的。AI 编程的规划-执行断层问题坦白讲这个问题不是某个工具的问题是整个 AI 编程范式的青春期烦恼。2025 年到 2026 年社区里冒出了两个方向试图解决它一个是 Spec-Driven DevelopmentSDD让 AI 先写规格再写代码另一个是 Test-Driven Development 的 AI 增强版用测试用例约束 AI 的行为。这两个方向的代表作一个叫 OpenSpec一个叫 Superpowers。都是 GitHub 上的神级项目OpenSpec 58,522 starsSuperpowers 245,221 stars。一个管「写什么」一个管「怎么写」。理论上你装了两个插件就既有规划又有执行纪律了。实际上两个插件之间没有衔接层。规划文档写完了执行阶段不会自动读取。你还是在手动搬运。这就是 spec-superflow 要解决的问题。它不是一个新框架而是把 OpenSpec 和 Superpowers 的引擎吸收重构做成了一个自洽的、有契约桥接层的 9-skill 工作流。用一个比喻来说OpenSpec 是猛虎Superpowers 是双翼但如果你只是把老虎和翅膀放在同一个笼子里它们不会自动组合成一头会飞的老虎。spec-superflow 做的事就是把翅膀焊在老虎身上。二、两个神级框架各管一半先说 OpenSpec。Fission-AI 在 2025 年 8 月开源的这个项目核心思想很简单让 AI 在写代码之前先写一份可验证的规格说明。它的工作流是 proposal提案→ specs规格→ design设计→ tasks任务拆解四个 artifact 构成一个完整的规划链。每个 artifact 有严格的格式约束确保规划不是随便写写而是有结构的、可追溯的。58,522 个 star 不是白来的。OpenSpec 做到了两件很难的事第一它让规划文档从「给人看的」变成了「给 AI 看的」格式化的 Delta Spec 既有人类可读性又有机器可解析性第二它把规划流程标准化了不需要每次从头设计文档结构。但 OpenSpec 有一个天生的边界它只负责「写什么」不负责「怎么写」。规划做完之后执行阶段该怎么做它不管。你拿到 tasks.md然后呢手动逐个执行还是让 AI 自由发挥OpenSpec 没有给出答案。OpenSpec 工作流示意再说 Superpowers。obraJesse Vincent的这个项目是 Claude Code 插件生态的绝对王者。245,221 starsv6.0.32026 年 6 月 18 日还在更新。它的核心是三个铁律TDD先写测试再写代码、SDD 子代理用专门的 subagent 做规格检查、Review Gate代码评审门禁。执行阶段的每一步都有硬约束AI 不能跳过测试直接写代码不能绕过评审直接合并。Superpowers 的强大之处在于执行纪律。它把「AI 编程的随意性」关进了笼子里。但它的边界同样明显它的纪律机制需要一个起点一份已经定义好的任务清单。而这份清单从哪来Superpowers 不管。看到问题了没有OpenSpec 是火车头负责制定路线图但到了站台就熄火了。Superpowers 是铁轨保证列车按规范行驶但铁轨不会自己铺到目的地。两个框架各自解决了 AI 编程一半的问题但中间缺了一个关键的衔接层。OpenSpec Superpowers 能力矩阵这就是为什么装了 OpenSpec 的人还在抱怨「规划写了白写」装了 Superpowers 的人也在抱怨「TDD 是好的但我不知道该测什么」。两个工具都很好但它们之间没有对话。三、「焊死」的核心源码级融合 vs 装两个插件spec-superflow 做的第一件事是把两个框架的引擎源码级吸收而不是外部调用。这个区别很关键。让我解释一下。外部编排模式的意思是你的工作流脚本调用 OpenSpec CLI 生成规划文档然后调用 Superpowers 的 skill 执行任务。两个工具各跑各的通过文件系统交换数据。Cometrpamis/comet走的就是这条路用 YAML 状态机编排 OpenSpec 和 Superpowers 的外部调用通过 shell guard 脚本做状态检测。这个方案能用但有一个致命缺陷两个工具对彼此的内部状态一无所知。OpenSpec 生成了一份 specSuperpowers 不知道这份 spec 里有哪些约束条件需要强制执行。Superpowers 执行到一半发现测试失败了OpenSpec 不知道执行阶段出了什么问题、需不需要回头修改规划文档。而你作为开发者就成了两个人之间的翻译官。每次状态不对齐你就得手动调停。源码级融合 vs 外部编排对比spec-superflow 走的是另一条路源码级融合。它不是调用 OpenSpec 的 CLI而是把 OpenSpec 的规划逻辑吸收进自己的 skill 体系不是调用 Superpowers 的 skill而是把 Superpowers 的执行纪律内化成自己的状态机。这样做的结果是所有 9 个 skill 共享同一套状态机任何一个 skill 都知道工作流当前处于哪个阶段、上一个阶段产出了什么、下一个阶段需要什么约束条件。状态不是写在文件系统里的而是内建于工作流引擎的。用技术术语说外部编排是「控制反转」源码级融合是「引擎内聚」。前者灵活但松散后者紧致但自洽。对于 AI 编程工作流来说自洽比灵活更重要。因为 AI 本身就有足够的灵活性你不需要再给它松松绑你需要的是给它加约束。这就是「焊死」的含义。不是物理意义上的焊接而是架构层面的内聚把 OpenSpec 的规划能力和 Superpowers 的执行纪律重构为一个不可分割的整体。四、9 个 skill 8 状态机一个自洽的工作流引擎spec-superflow 的架构可以用一句话概括9 个 skill 对应 9 个工作流阶段8 种状态机状态保证你不会跳过任何一步。spec-superflow 整体架构9 个 skill 分别是workflow-start入口检测当前状态决定下一步need-explorer需求澄清确保「要做的事」定义清晰spec-writer规划文档生成proposal / specs / design / taskscontract-builder核心创新把规划文档压缩为执行契约build-executor有纪律的批量执行code-reviewer执行后代码评审spec-mergerDelta Spec 合并到主 Specrelease-archivist收尾、验证、归档bug-investigator侧路径遇到 bug 时触发调查8 种状态机状态构成了严格的工作流流转exploring → specifying → bridging → approved-for-build → executing → reviewing → merging → closing。每一步都有前置条件不满足前置条件就无法进入下一步。说一下这里的设计哲学。很多工作流工具的问题是「状态检查太弱」。它们检查「有没有这个文件」但从不检查「这个文件里的内容有没有真正落实」。spec-superflow 的做法是内容级状态检测不只是检查execution-contract.md存不存在而是检查它的 SHA256 哈希是否与规划文档的输出一致。如果规划文档更新了但契约没更新状态机会阻止你进入执行阶段。这个细节很小但影响巨大。它解决了一个常见的场景你规划做好了契约也签了但执行前又改了一下规划文档。在传统工作流里没人会提醒你「契约过期了」。在 spec-superflow 里状态机会直接报错。状态机全流转图另一个设计亮点是决策点协议Decision PointDP。工作流在 8 个关键节点设置了 DPAI 不能自己拍板必须停下来问你的意见。比如 DP-0 用户确认门禁在 need-explorer 阶段结束后AI 必须把需求理解结果呈现给你你确认了才能进入 spec-writer。这个设计专门防范 AI 「自以为理解了需求但实际上跑偏了」的经典问题。8 个 DP 分布在DP-0需求确认need-explorer 后DP-1提案确认proposal 生成后DP-2规格确认specs 生成后DP-3设计确认design 生成后DP-4任务确认tasks 生成后DP-5契约确认contract-builder 后DP-6批次确认每批执行前后DP-7收尾确认release-archivist 后有人可能会觉得 8 个确认点太多了。但我的使用体验是这 8 个点恰好是 AI 编程最需要人类判断力的地方。把判断力用在刀刃上而不是让 AI 在无关紧要的地方反复问「要不要继续」。五、contract-builder规划到执行的契约桥接层如果要我从 9 个 skill 里选一个最能代表 spec-superflow 设计思想的我会选 contract-builder。contract-builder 契约桥接层工作流程contract-builder 做的事很简单描述起来把 proposal、specs、design、tasks 这四个规划文档压缩成一份execution-contract.md。这份契约包含三个关键信息意图锁Intent Lock用一句话锁定这次变更的核心意图。执行阶段的 AI 做任何决策都必须对齐这个意图。意图对不上拒绝执行。约束清单Constraint Checklist从四个规划文档中提取所有硬性约束性能指标、兼容性要求、安全规范变成可验证的检查项。验收标准Acceptance Criteria每个 task 的完成标准不只是「代码写完了」而是「代码写完了且通过了这些验证」。最精彩的地方在于contract-builder 在生成契约的同时会计算 SHA256 哈希把哈希写入契约文件。执行阶段启动前状态机会重新计算规划文档的哈希如果和契约中的哈希不一致说明规划文档在契约签署后被修改了执行阶段被自动锁定。这解决了一个非常实际的问题你以为自己在按规划写代码但规划其实悄悄变了。可能是你手动改了一个 spec 文件可能是 AI 在某个对话里「优化」了一下 design。不管原因是什么结果都一样你执行的规划和你当初签的规划不是同一份。意图锁是另一个杀手级设计。我举个真实例子在用 spec-superflow 做 v0.8.7 的一个补丁时执行阶段的 AI 在执行中途建议「这个地方不如顺便重构一下把配置项统一管理」。听起来是个好建议对吧但 contract-builder 里的意图锁写的是「修复 3 个边界条件 bug不改变现有 API 签名」。AI 的建议被意图锁拦截了重构不在本次变更的意图范围内。如果没有意图锁这个「顺手重构」可能就做了。然后呢然后回归测试炸了因为统一配置项的改动波及了 7 个文件。你就得花一个下午排查问题。这就是 contract-builder 的核心价值它不是阻止 AI 提建议而是确保建议不偏离本次变更的意图。范围蔓延scope creep是人类开发者和 AI 开发者的通病contract-builder 是给两者同时上的紧箍咒。六、用 spec-superflow 审计 spec-superflow说再多设计理念不如看一个真实案例。最好的案例就是 spec-superflow 自己。v0.8.7 的开发流程我全程用 spec-superflow 管理。就是说我用这个工作流来审计和改进这个工作流本身。典型的 dogfooding。dogfooding 案例流程这个过程发现并修复了 5 个关键问题问题一技能描述文件中的 token 估算偏差。在 v0.8.6 中某些 skill 描述文件声明的 token 使用量与实测偏差超过 40%。这个问题是被 code-reviewer 在执行后评审中发现的它检查了 skill 描述文件的声明值与实际注入上下文的 token 计数。根因是 skill 描述文件更新后没有同步更新 token 估算字段。修复方案在 contract-builder 的约束清单中增加「token 估算一致性」检查项。问题二tweak 模式下的死锁。在执行阶段如果用户在 tweak 模式下输入与当前 batch 意图不一致的指令state machine 会进入一个既无法继续也无法回滚的状态。这个问题是我在 dogfooding 中发现的我在执行 batch-3 的时候手贱改了一行无关代码触发 tweak 检测但错误处理路径没有覆盖这个场景。bug-investigator 介入后定位到状态转换逻辑缺少一个「用户输入冲突」分支。问题三状态文件与规划文档的同步漂移。这是内容级状态检测反向发现的问题。contract-builder 的 SHA256 校验正确地检测到了状态不一致但错误信息只说「哈希不匹配」没有告诉用户哪个文件变了、变了什么。修复方案增加 diff 摘要输出让用户一眼看到「design.md 第 42 行的约束条件被修改了」。问题四多平台安装脚本的 shell 兼容性。spec-superflow 声称支持 7 个平台但在 Zsh 和 Fish shell 下的安装脚本有兼容性问题。这是 release-archivist 的跨平台验证矩阵发现的。修复方案增加 shell 检测逻辑和对应的语法适配。问题五contract-builder 对大 spec 文件的性能问题。当 specs 目录下有超过 5 个文件或单个文件超过 2000 行时contract-builder 的提取和压缩耗时超过 30 秒。这个性能瓶颈是在审计 spec-superflow 自身的 spec 文件时发现的ironicallyspec-superflow 自己的 spec 文件就很大。修复方案增加增量处理逻辑只重新处理变更的 spec 文件。这个 dogfooding 案例的价值不在于修了 5 个 bug任何项目都有 bug。价值在于这 5 个 bug 中的 3 个问题一、三、五在没有 spec-superflow 的情况下很难被发现。因为它们不是功能 bug而是元层面的问题文件一致性、token 准确性、状态漂移。传统的测试框架不太会覆盖这类问题但 spec-superflow 的内容级状态检测和契约校验刚好能捕捉到。这就是我说的「自洽」。一个工作流工具能发现自己产生的问题说明它的反馈回路是闭合的。七、竞品对比为什么不是 Comet、QFAI 或 sdd2026 年SDD 工作流赛道爆发式增长至少 10 个开源项目在抢这个方向。简单过一下几个主要竞品帮你理解 spec-superflow 的定位。Cometrpamis/cometComet 是目前最接近 spec-superflow 的竞品。它的思路是用 YAML 定义工作流状态机通过 shell guard 脚本编排 OpenSpec 和 Superpowers 的外部调用。支持 29 个平台npm 包 v0.3.9。Comet 的优势是灵活YAML 配置想怎么编排就怎么编排29 平台覆盖比 spec-superflow 更广。劣势也很明显外部编排模式决定了它只能做「表面的状态检查」文件存在、时间戳做不了「内容级状态检测」SHA256 哈希、意图一致性。而且它需要你先装 OpenSpec 和 SuperpowersComet 只是胶水。QFAI质量优先开发套件npm 包覆盖 SDD → ATDD → TDD 全链路。理念很完整但太重了。它的典型用户画像是有 CI/CD pipeline 的企业团队需要完整的质量门禁体系。个人开发者或者小团队用 QFAI光是初始配置就能劝退一半人。genkovich/sdd18 个苏格拉底式 skill12 步工作流。学术气息很浓每一步都要求 AI 用提问引导你思考。适合喜欢深度思考的开发者但步骤太多12 步走完一个变更周期对于中小需求来说太重了。竞品功能对比表spec-superflow 和它们的最本质区别在于哲学层面Comet 是「胶水哲学」用外部编排把已有工具粘起来QFAI 是「全栈哲学」自己造一套完整的质量体系sdd 是「学院哲学」用苏格拉底式对话引导人思考spec-superflow 是「融合哲学」吸收神级框架的引擎重构为自洽的整体没有哪个哲学绝对正确。但如果你是一个每天和 AI 打交道的工程师你大概率会更喜欢「融合哲学」你不需要再维护一套 YAML 配置文件Comet不需要学习一套完整的企业级质量方法论QFAI不需要走 12 步才能完成一个小需求sdd。你只需要一条安装命令然后按工作流走就行。另一个实际的区别中文支持。spec-superflow 是目前唯一一个支持中英双语的 SDD 工作流工具。对于中文开发者来说这个差别是实质性的规划文档、执行契约、评审意见全都可以用中文写。其他竞品都是纯英文。八、安装和上手Claude Code 用户一条命令安装/plugin marketplace add MageByte-Zero/spec-superflow /plugin install spec-superflowspec-superflowCursor / Copilot 用户node /path/to/spec-superflow/scripts/install-cursor.mjs零运行时依赖。不需要先装 OpenSpec不需要先装 Superpowersspec-superflow 内置了它们的引擎逻辑。支持 7 个平台Claude Code、Cursor、Codex、Copilot CLI、Gemini CLI、OpenCode、Trae。上手流程也很简单在项目根目录运行workflow-start初始化.spec-superflow.yaml和工作流目录need-explorer引导你澄清需求spec-writer自动生成 4 个规划文档你审查确认后contract-builder生成执行契约build-executor分批执行release-archivist收尾归档整个流程走下来一个中等复杂度的需求比如「给 CLI 增加一个子命令」从规划到合并大约 40-60 分钟。其中人类的决策时间大约占 15 分钟主要花在 DP 确认点上其余时间都是 AI 在执行。坦白讲第一次用的学习曲线不算低。9 个 skill8 个状态机状态8 个决策点概念不少。但走完两个完整的变更周期之后流程就变成肌肉记忆了。我现在开新需求的时候如果不用workflow-start会感觉少了点什么。九、FAQQ1我已经在用 Cursor / Claude Code 了还需要 spec-superflow 吗Cursor 和 Claude Code 解决的是「怎么写代码」的问题。spec-superflow 解决的是「写什么代码、按什么顺序写、写到什么程度算完」的问题。两者是不同层面的工具前者是编辑器/编码助手后者是工作流引擎。不冲突可以叠加使用。Q2spec-superflow 和直接用 GitHub Copilot Workspace 有什么区别Copilot Workspace 有类似的结构化规划功能spec → plan → tasks → code但它的规划逻辑是黑盒的你没法自定义工作流阶段或决策点。spec-superflow 是完全透明的状态机你可以看到每一步的前置条件和状态转换。而且 spec-superflow 跨平台不绑定任何单一 AI 编码工具。Q3小项目值得用吗个人 side project 呢看需求复杂度。如果一个需求你脑子里就能完全 hold 住比如改个配置、修个文案不需要走完整工作流。但如果一个需求需要 3 个以上的文件修改、涉及多个模块、或者你对方案还不够确定走一遍 spec-superflow 是值的它能帮你把不确定的部分提前暴露出来而不是写到一半才发现想错了。我自己的经验是超过 2 小时的需求走工作流小于 30 分钟的需求直接写。中间地带看心情。Q4和公司内部的 CI/CD pipeline 怎么集成execution-contract.md 可以被 CI 系统读取。你可以在 CI 里加一个检查步骤验证代码变更是否与 execution-contract.md 的验收标准一致。contract-builder 生成的约束清单本身就是结构化的解析起来很方便。Q5性能开销大吗状态检测和 SHA256 校验的时间开销基本可以忽略毫秒级。contract-builder 对大型 spec 文件的处理时间在 v0.8.7 中已优化到 5 秒以内之前是 30 秒就是 dogfooding 发现的问题五。对于日常使用性能完全不是瓶颈。十、猛虎添翼不装就落后了写到这里我想回到标题那个比喻。OpenSpec 是一头猛虎它有完整的规划方法论58,000 多个 star 是社区对它的认可。Superpowers 是一双铁翼245,000 多个 star 证明了执行纪律是 AI 编程的刚需。但如果你只是把它们放在同一个项目里你得到的是「一头老虎 一双翅膀」而不是「一头会飞的老虎」。spec-superflow 做的事就是完成那个「添」的动作。不是把已有的东西堆在一起而是用源码级融合 契约桥接层 内容级状态机做出一个真正自洽的工作流引擎。198 个 star 不算多但每个 star 背后都有一个被 AI 编程的随意性折磨过的开发者。这个赛道在 2026 年爆发不是偶然的当 AI 写代码的速度越来越快我们对它的质量要求也应该越来越高。快而不稳等于白快。我在 v0.8.7 的 dogfooding 中切身体会到了这个工作流的力量不是因为它帮我写出了更漂亮的代码而是因为它帮我避免了 5 个在传统工作流下大概率会被漏掉的元层面问题。这些问题的共同点是它们都不在「代码写没写对」的检查范围内而在「事情做没做对」的检查范围内。如果你想试一下GitHub 搜MageByte-Zero/spec-superflowMIT 协议一条命令装好。如果你在用 Cursor 或者 Copilot它也支持安装脚本会自动检测你的环境。AI 编程的下一个阶段不是让 AI 写得更快而是让 AI 写得更稳。SDD 工作流是通往这个目标的必经之路而 spec-superflow 是目前这条路上走得最远的开源项目之一。
设计与STM32实现指南)
