spec-superflow开源工作流 解决AI编程代码失控、需求跑偏问题

你肯定遇到过这种场面。你对 AI 说一句「帮我给项目加个权限控制」，它二话不说唰唰改了四十多个文件。改到一半你才发现，它默认做的是 ABAC，而你要的根本是 RBAC。更酸爽的是，proposal 写了、design 画了，合并之后你才意识到行为根本不对，因为实现阶段没人盯着测试，也没人卡 review。

这就是用 AI 写代码最常踩的两个失控点。第一，还没想清楚要做什么，AI 就动手了。第二，规划文档写得明明白白，执行阶段照样跑偏。

我最近在翻 MageByte 开源的 spec-superflow 源码，发现它正好把这两道墙都砌上了。一句话理解它，它是源码级融合 OpenSpec 规划引擎 + Superpowers 执行纪律的 AI 编程工作流插件。说穿了，它在「想清楚」和「做对」之间建了一道硬墙，让 Agent 既不能瞎写，也不能瞎跑。

spec-superflow 已经在 GitHub 开源，MIT 协议。如果你也被 AI 写代码的失控点折磨过，建议直接装上试试，源码就在仓库里，架构、契约模板、状态机都看得见。

仓库地址在这里，点个 Star 支持一下。打开站点

一、它到底由什么组成

spec-superflow 不是给你一个万能 prompt，而是把工作流拆成了 9 个 Skill，每个 Skill 只管一个阶段。你不用记命令，一句话就能启动，剩下的路由交给状态机。

划重点，这 9 个 Skill 不是平铺的，它们被一台 8 状态的状态机串起来。你喊「继续上次的工作流」，它靠内容级判断（比对 proposal 范围 vs 契约意图锁，而不是看文件时间戳）知道你现在卡在哪个阶段，然后把你路由到正确的下一个 Skill。

二、8 状态工作流，每一步都有刹车

spec-superflow 把一次变更的生命周期定义成 8 个显式状态。

exploring → specifying → bridging → approved-for-build → executing → closing
                                          │
                                     ◇ 用户批准 ◇   ← 唯一一次人工介入（DP-3）
                                          │
executing ──[遇到 bug]──→ debugging ──→ 回到 executing
任意非终态 ──→ abandoned（终态，不可再转移）

几个关键约束你得记牢。没有 execution-contract.md 或没被批准，不许实现。需求变了，强制回退到 specifying 或 bridging。遇到 bug，强制走 debugging，不许「随便试试」。这些都不是建议，是护栏，违反就拦截并回退。

坑就在这，很多人以为有了 proposal 就安全了。但提案是给人看的，Agent 执行时根本不会每次都回头翻 proposal。spec-superflow 的解法是，把规划期的成果压缩成一份契约，执行阶段唯一认这份契约，而不是聊天记录。

三、核心创新：contract-builder 这座桥

这是我认为整个项目最值得讲的设计。OpenSpec 擅长规划（proposal / specs / design / tasks），Superpowers 擅长执行纪律（TDD / SDD / 调试 / 审查），但两者之间是断的。文档写得再漂亮，执行照样跑偏，因为缺一层「规划到实现的唯一交接层」。

contract-builder 干的事，就是把 4 份规划工件程序化提取并压缩成一份 execution-contract.md。

契约里最狠的是这几块。意图锁，把「到底要做什么」钉死。范围栅栏，明确不做什么。测试义务，列清楚哪些行为必须先有失败测试。审查门，规定每个 wave 过后必须 review。升级规则，写清楚什么情况必须打回重规划。

而且契约会内容级过期检测。不是看文件修改时间，而是比对 proposal 范围是否溢出契约栅栏、specs 里批准的需求是否改了、design 架构约束是否变了。一旦漂移，自动回退到 contract-builder 重做。DP-3 是硬门禁，用户不批准，build-executor 连启动的资格都没有。

四、实战走一遍：给项目加 RBAC 权限

光讲概念发虚，我们拿「给 API 加一套 RBAC 权限」走一遍全流程。

1. 入口。 你说「帮项目加权限控制」，Agent 调 workflow-start。它先跑 DP-0 设计前确认，问你变更名、意图、已知约束。确认完写进 .spec-superflow.yaml。
2. 探索。 路由到 need-explorer。它一次只问一个问题，不会甩你一堆。它会抛方案对比，比如「RBAC 还是 ABAC？粒度到接口还是到数据行？」并给出推荐。你确认 scope 后，DP-1 需求确认门记录结果。
3. 规格。spec-writer 按 proposal → specs → design → tasks 的顺序，一个一个产出，每个都过 Schema 引擎校验。specs 里每个需求必须可测，用 SHALL / MUST，且至少带一个 #### Scenario: 的 WHEN/THEN。全部产出后 DP-2 工件审查，你点头。
4. 桥接。contract-builder 自动提取 4 工件，压成 execution-contract.md。这里会做需求覆盖率交叉检查，确保每个 SHALL/MUST 都有测试义务、都落进某个批次。然后 DP-3 契约批准，这是全流程唯一一次人工门禁，你批了才许动代码。
5. 执行。build-executor 启动。先跑 ssf isolate 做 git 隔离（在 main 上直接改会被它拦停），再跑 ssf execution plan 保存执行计划，DP-4 让你选 TDD 还是 SDD 模式。每个 wave 实现完，code-reviewer 出 review report，你记一个 pass receipt 才能进下一个 wave 或收口。
6. 收口与同步。 实现完，release-archivist 跑「验证前完成」铁律，没证据不许说完成。DP-6 验证、DP-7 归档确认。最后 spec-merger 把本次的 delta spec 合并回主规范基线，防止规范腐烂。

你看，全程 Agent 没有一次能「自由发挥」。每一次跳跃都有状态机卡着，每一次进实现都有契约卡着，每一个 wave 都有 review receipt 卡着。

五、执行阶段的三重纪律

build-executor 是纪律最密的地方，我单独拎出来说。

TDD 铁律。 没有失败的测试，不许写生产代码。RED（先写测试，看它红）→ GREEN（写最小实现，看它绿）→ REFACTOR（清理，套件保持绿）。任何「先快速实现，测试待会补」的念头，在 spec-superflow 里都算红灯，直接停。

SDD 子代理驱动。 full / hotfix 默认 SDD（Spec-Driven Development）。先在.superpowers/sdd/execution-plan.json保存带依赖和策略的执行计划，再按 wave 派发子代理。每个 wave 先写一份非空的review report，再记pass / fail receipt。只有你显式 override，才能选 inline 或 batch-inline，而且 batch-inline 始终是串行，绝不冒充并行。

Review Gate。 每个依赖 wave 必须有当前pass receipt，依赖 wave 和 closing 才放行。修订计划会让旧 receipt 失效，逼你重新 review。说到底，这就是用机制代替自觉。

六、小变更的捷径：hotfix 与 tweak

大功能走全套没问题，改两行配置也走 9 个 Skill 就太重了。spec-superflow 用模式检测自动降级。

hotfix 走 exploring → bridging → approved-for-build → executing，可以跳过完整规划工件，但仍必须生成一份最小 execution-contract.md 并过 DP-3。tweak 最轻，直接从 exploring 跳到 approved-for-build 动手改，做完轻量收口即可。

七、安装与多平台

spec-superflow 自包含，不需要你单独装 OpenSpec 或 Superpowers，一个插件全包。当前版本 v0.9.0，支持 17 个 AI 编程平台。

Claude Code 走 marketplace

/plugin marketplace add MageByte-Zero/spec-superflow
/plugin install spec-superflow@spec-superflow

Cursor 用官方安装器一行搞定

npx spec-superflow@latest install-cursor

Cline / Kiro / Windsurf / Qwen / Amazon Q / Roo Code / Continue / Pi / Codex / Gemini / GitHub Copilot / WorkBuddy / Trae 等都有对应安装器或入口，完整矩阵见官方 INSTALL.md。装完之后，全局 CLI 叫 ssf：

npm install -g spec-superflow
ssf list        # 列出所有 changes 及状态
ssf doctor      # 健康检查（版本、hooks、skills、文档一致性）
ssf validate .  # 验证工件完整性

小技巧，恢复会话用 继续上次的工作流，不确定状态用 帮我看看现在该干什么，它都会靠内容级检测把你指到正确的 Skill。

八、决策点门禁总览

整条流水线有 8 个决策点（DP-0 到 DP-7），它们是自动化流程里给你保留的最终决策权。Skill 走到门禁必须暂停，等你的明确指令才继续。

讲真，这套机制最反直觉但也最值钱的一点，是它把「人的确认」精确安插在 8 个关键节点，而不是撒手让 Agent 一路冲到合并。你只在 DP-3 真正卡一次代码门，其余大多是信息确认，成本低但护栏实。

九、适用场景与收尾

推荐用，大型功能开发、多人协作、长期维护项目、需要 TDD + Review Gate 的棕地项目。不推荐，一次性脚本、纯咨询问答。

我自己用下来的体感是，spec-superflow 把「想清楚」和「做对」这两件最容易被 AI 跳过的事，变成了不可绕过的工程步骤。它不替你做决定，但确保你每做一个决定，都有记录、有契约、有回退。对动辄改几十个文件的 AI 编程来说，这种克制反而最快。

如果你也在用 AI 写代码，建议先把 workflow-start 这一个入口用熟。剩下的，状态机会替你看着。

以上关于spec-superflow开源工作流 解决AI编程代码失控、需求跑偏问题的文章就介绍到这了，更多相关内容请搜索码云笔记以前的文章或继续浏览下面的相关文章，希望大家以后多多支持码云笔记。