别再让 AI 瞎改了：spec-superflow 完整使用指南

你好，我是码哥。

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

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

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

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

仓库地址在这里，点个 Star 支持一下。https://github.com/MageByte-Zero/spec-superflow

9 个 Skill 与阶段映射全景

9 个 Skill 与阶段映射全景

一、它到底由什么组成

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

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

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

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

8 状态机流转与调试支线

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。

4 工件桥接为执行契约

4 工件桥接为执行契约

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

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

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

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

RBAC 实战 9 Skill 流转

RBAC 实战 9 Skill 流转

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+SDD+Review

执行三重纪律 TDD+SDD+Review

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 用模式检测自动降级。

三模式对比 full/hotfix/tweak

三模式对比 full/hotfix/tweak

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 官方仓库 MageByte-Zero/spec-superflow（v0.9.0），含 README、docs/state-machine、docs/decision-points、docs/artifact-contract 及各 Skill 源码。