一、规划归规划，执行归执行

用了两年 AI 编程工具，踩过的最深的坑不是代码写错了，而是代码写完了，当初那份规划文档还躺在仓库里吃灰。

这个场景你应该不陌生：花了半小时跟 Claude Code 聊需求，产出一份漂亮的 proposal.md 和 design.md。然后呢？然后你开始写代码，AI 开始帮你写代码，三天后功能上线了。回头一看，当初那份规划文档里的约束——“这个模块要支持水平扩展”“API 响应时间必须控制在 200ms 以内”——代码里一条都没兑现。

不是 AI 不听话，是没人把规划“焊”到执行流里。

规划文档写完的那一刻，它就成了历史文件。执行阶段的 AI 不知道它存在，知道也不会主动去读。你在规划阶段花了 30% 的精力，但这些精力的产出物对后续 70% 的执行阶段毫无约束力。

这就是 AI 编程当前最大的结构性缺陷：规划和执行是断层的。

坦白讲，这个问题不是某个工具的问题，是整个 AI 编程范式的青春期烦恼。2025 年到 2026 年，社区里冒出了两个方向试图解决它：一个是 Spec-Driven Development（SDD），让 AI 先写规格再写代码；另一个是 Test-Driven Development 的 AI 增强版，用测试用例约束 AI 的行为。

这两个方向的代表作，一个叫 OpenSpec，一个叫 Superpowers。都是 GitHub 上的神级项目，OpenSpec 58,522 stars，Superpowers 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 没有给出答案。

再说 Superpowers。

obra（Jesse Vincent）的这个项目是 Claude Code 插件生态的绝对王者。245,221 stars，v6.0.3，2026 年 6 月 18 日还在更新。它的核心是三个铁律：TDD（先写测试再写代码）、SDD 子袋（用专门的 subagent 做规格检查）、Review Gate（代码评审门禁）。执行阶段的每一步都有硬约束，AI 不能跳过测试直接写代码，不能绕过评审直接合并。

Superpowers 的强大之处在于执行纪律。它把“AI 编程的随意性”关进了笼子里。但它的边界同样明显：它的纪律机制需要一个起点——一份已经定义好的任务清单。而这份清单从哪来？Superpowers 不管。

看到问题了没有？

OpenSpec 是火车头，负责制定路线图，但到了站台就熄火了。Superpowers 是铁轨，保证列车按规范行驶，但铁轨不会自己铺到目的地。两个框架各自解决了 AI 编程一半的问题，但中间缺了一个关键的衔接层。

这就是为什么装了 OpenSpec 的人还在抱怨“规划写了白写”，装了 Superpowers 的人也在抱怨“TDD 是好的，但我不知道该测什么”。两个工具都很好，但它们之间没有对话。

三、“焊死”的核心：源码级融合 vs 装两个插件

spec-superflow 做的第一件事，是把两个框架的引擎源码级吸收，而不是外部调用。

这个区别很关键。解释一下。

外部编排模式的意思是：你的工作流脚本调用 OpenSpec CLI 生成规划文档，然后调用 Superpowers 的 skill 执行任务。两个工具各跑各的，通过文件系统交换数据。Comet（rpamis/comet）走的就是这条路——用 YAML 状态机编排 OpenSpec 和 Superpowers 的外部调用，通过 shell guard 脚本做状态检测。

这个方案能用，但有一个致命缺陷：两个工具对彼此的内部状态一无所知。OpenSpec 生成了一份 spec，Superpowers 不知道这份 spec 里有哪些约束条件需要强制执行。Superpowers 执行到一半发现测试失败了，OpenSpec 不知道执行阶段出了什么问题、需不需要回头修改规划文档。

而作为开发者，就成了两个人之间的翻译官。每次状态不对齐，就得手动调停。

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 种状态机状态保证你不会跳过任何一步。

9 个 skill 分别是：

1. workflow-start：入口，检测当前状态，决定下一步
2. need-explorer：需求澄清，确保“要做的事”定义清晰
3. spec-writer：规划文档生成（proposal / specs / design / tasks）
4. contract-builder：核心创新，把规划文档压缩为执行契约
5. build-executor：有纪律的批量执行
6. code-reviewer：执行后代码评审
7. spec-merger：Delta Spec 合并到主 Spec
8. release-archivist：收尾、验证、归档
9. bug-investigator：侧路径，遇到 bug 时触发调查

8 种状态机状态构成了严格的工作流流转：exploring → specifying → bridging → approved-for-build → executing → reviewing → merging → closing。每一步都有前置条件，不满足前置条件就无法进入下一步。

说一下这里的设计哲学。

很多工作流工具的问题是“状态检查太弱”。它们检查“有没有这个文件”，但从不检查“这个文件里的内容有没有真正落实”。spec-superflow 的做法是内容级状态检测——不只是检查 execution-contract.md 存不存在，而是检查它的 SHA256 哈希是否与规划文档的输出一致。如果规划文档更新了但契约没更新，状态机会阻止你进入执行阶段。

这个细节很小，但影响巨大。它解决了一个常见的场景：你规划做好了，契约也签了，但执行前又改了一下规划文档。在传统工作流里，没人会提醒你“契约过期了”。在 spec-superflow 里，状态机会直接报错。

另一个设计亮点是决策点协议（Decision Point，DP）。工作流在 8 个关键节点设置了 DP，AI 不能自己拍板，必须停下来问你的意见。比如 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：规划到执行的契约桥接层

如果要从中选一个最能代表 spec-superflow 设计思想的 skill，会选 contract-builder。

contract-builder 做的事简单描述起来就是：把 proposal、specs、design、tasks 这四个规划文档，压缩成一份 execution-contract.md。这份契约包含三个关键信息：

1. 意图锁（Intent Lock）：用一句话锁定这次变更的核心意图。执行阶段的 AI 做任何决策，都必须对齐这个意图。意图对不上，拒绝执行。
2. 约束清单（Constraint Checklist）：从四个规划文档中提取所有硬性约束——性能指标、兼容性要求、安全规范——变成可验证的检查项。
3. 验收标准（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。

这个过程发现并修复了 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 文件时发现的（ironically，spec-superflow 自己的 spec 文件就很大）。修复方案：增加增量处理逻辑，只重新处理变更的 spec 文件。

这个 dogfooding 案例的价值不在于修了 5 个 bug——任何项目都有 bug。价值在于，这 5 个 bug 中的 3 个（问题一、三、五），在没有 spec-superflow 的情况下很难被发现。因为它们不是功能 bug，而是元层面的问题——文件一致性、token 准确性、状态漂移。传统的测试框架不太会覆盖这类问题，但 spec-superflow 的内容级状态检测和契约校验刚好能捕捉到。

这就是前面说的“自洽”——一个工作流工具能发现自己产生的问题，说明它的反馈回路是闭合的。

七、竞品对比：为什么不是 Comet、QFAI 或 sdd？

2026 年，SDD 工作流赛道爆发式增长，至少 10+ 个开源项目在抢这个方向。简单过一下几个主要竞品，帮你理解 spec-superflow 的定位。

Comet（rpamis/comet）

Comet 是目前最接近 spec-superflow 的竞品。它的思路是：用 YAML 定义工作流状态机，通过 shell guard 脚本编排 OpenSpec 和 Superpowers 的外部调用。支持 29 个平台，npm 包 v0.3.9。

Comet 的优势是灵活——YAML 配置，想怎么编排就怎么编排，29 平台覆盖比 spec-superflow 更广。劣势也很明显：外部编排模式决定了它只能做“表面的状态检查”（文件存在、时间戳），做不了“内容级状态检测”（SHA256 哈希、意图一致性）。而且它需要你先装 OpenSpec 和 Superpowers——Comet 只是胶水。

QFAI

质量优先开发套件，npm 包，覆盖 SDD → ATDD → TDD 全链路。理念很完整，但太重了。它的典型用户画像是有 CI/CD pipeline 的企业团队，需要完整的质量门禁体系。个人开发者或者小团队用 QFAI，光是初始配置就能劝退一半人。

genkovich/sdd

18 个苏格拉底式 skill，12 步工作流。学术气息很浓，每一步都要求 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-superflow@spec-superflow

Cursor / Copilot 用户：

node /path/to/spec-superflow/scripts/install-cursor.mjs

零运行时依赖。不需要先装 OpenSpec，不需要先装 Superpowers——spec-superflow 内置了它们的引擎逻辑。支持 7 个平台：Claude Code、Cursor、Codex、Copilot CLI、Gemini CLI、OpenCode、Trae。

上手流程也很简单：

1. 在项目根目录运行 workflow-start，初始化 .spec-superflow.yaml 和工作流目录
2. need-explorer 引导你澄清需求
3. spec-writer 自动生成 4 个规划文档
4. 你审查确认后，contract-builder 生成执行契约
5. build-executor 分批执行
6. release-archivist 收尾归档

整个流程走下来，一个中等复杂度的需求（比如“给 CLI 增加一个子命令”），从规划到合并大约 40-60 分钟。其中人类的决策时间大约占 15 分钟（主要花在 DP 确认点上），其余时间都是 AI 在执行。

坦白讲，第一次用的学习曲线不算低。9 个 skill，8 个状态机状态，8 个决策点，概念不少。但走完两个完整的变更周期之后，流程就变成肌肉记忆了。现在开新需求的时候，如果不用 workflow-start，会感觉少了点什么。

九、FAQ

Q1：我已经在用 Cursor / Claude Code 了，还需要 spec-superflow 吗？

Cursor 和 Claude Code 解决的是“怎么写代码”的问题。spec-superflow 解决的是“写什么代码、按什么顺序写、写到什么程度算完”的问题。两者是不同层面的工具，前者是编辑器/编码助手，后者是工作流引擎。不冲突，可以叠加使用。

Q2：spec-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-superflow，MIT 协议，一条命令装好。如果在用 Cursor 或者 Copilot，它也支持，安装脚本会自动检测你的环境。

AI 编程的下一个阶段，不是让 AI 写得更快，而是让 AI 写得更稳。SDD 工作流是通往这个目标的必经之路，而 spec-superflow 是目前这条路上走得最远的开源项目之一。