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

spec-superflow 已经在 GitHub 开源MIT 协议。如果你也被 AI 写代码的失控点折磨过建议直接装上试试源码就在仓库里架构、契约模板、状态机都看得见。你肯定遇到过这种场面。你对 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-superflow9 个 Skill 与阶段映射全景一、它到底由什么组成spec-superflow 不是给你一个万能 prompt而是把工作流拆成了 9 个 Skill每个 Skill 只管一个阶段。你不用记命令一句话就能启动剩下的路由交给状态机。#Skill阶段职责1workflow-start入口内容级状态检测、8 状态路由、阻止非法跳转2need-explorer探索一次一问 方案对比 推荐3spec-writer规格产出 proposal / specs / design / tasksSchema 引擎实时验证4contract-builder桥接解析引擎自动提取 4 工件压缩为execution-contract.md5build-executor执行TDD 铁律 SDD 子代理驱动 Review Gate6bug-investigator调试4 阶段根因分析3 次以上修复失败就质疑架构7code-reviewer审查结构化审查三级问题分级8release-archivist收口验证前完成铁律 归档 风险总结9spec-merger同步Delta Spec 智能合并回主规范划重点这 9 个 Skill 不是平铺的它们被一台 8 状态的状态机串起来。你喊「继续上次的工作流」它靠内容级判断比对 proposal 范围 vs 契约意图锁而不是看文件时间戳知道你现在卡在哪个阶段然后把你路由到正确的下一个 Skill。二、8 状态工作流每一步都有刹车spec-superflow 把一次变更的生命周期定义成 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 / tasksSuperpowers 擅长执行纪律TDD / SDD / 调试 / 审查但两者之间是断的。文档写得再漂亮执行照样跑偏因为缺一层「规划到实现的唯一交接层」。contract-builder 干的事就是把 4 份规划工件程序化提取并压缩成一份execution-contract.md。4 工件桥接为执行契约来源工件提取成契约里的什么proposal.md意图锁问题 范围栅栏specs/已批准需求、场景、测试义务design.md架构、接口、依赖约束tasks.md执行批次、完成定义、审查时机契约里最狠的是这几块。意图锁把「到底要做什么」钉死。范围栅栏明确不做什么。测试义务列清楚哪些行为必须先有失败测试。审查门规定每个 wave 过后必须 review。升级规则写清楚什么情况必须打回重规划。而且契约会内容级过期检测。不是看文件修改时间而是比对 proposal 范围是否溢出契约栅栏、specs 里批准的需求是否改了、design 架构约束是否变了。一旦漂移自动回退到 contract-builder 重做。DP-3 是硬门禁用户不批准build-executor 连启动的资格都没有。四、实战走一遍给项目加 RBAC 权限光讲概念发虚我们拿「给 API 加一套 RBAC 权限」走一遍全流程。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你记一个passreceipt 才能进下一个 wave 或收口。6. 收口与同步。实现完release-archivist跑「验证前完成」铁律没证据不许说完成。DP-6 验证、DP-7 归档确认。最后spec-merger把本次的 delta spec 合并回主规范基线防止规范腐烂。你看全程 Agent 没有一次能「自由发挥」。每一次跳跃都有状态机卡着每一次进实现都有契约卡着每一个 wave 都有 review receipt 卡着。五、执行阶段的三重纪律build-executor 是纪律最密的地方我单独拎出来说。执行三重纪律 TDDSDDReviewTDD 铁律。没有失败的测试不许写生产代码。RED先写测试看它红→ GREEN写最小实现看它绿→ REFACTOR清理套件保持绿。任何「先快速实现测试待会补」的念头在 spec-superflow 里都算红灯直接停。SDD 子代理驱动。full / hotfix 默认 SDDSpec-Driven Development。先在.superpowers/sdd/execution-plan.json保存带依赖和策略的执行计划再按 wave 派发子代理。每个 wave 先写一份非空的 review report再记pass/failreceipt。只有你显式 override才能选 inline 或 batch-inline而且 batch-inline 始终是串行绝不冒充并行。Review Gate。每个依赖 wave 必须有当前passreceipt依赖 wave 和 closing 才放行。修订计划会让旧 receipt 失效逼你重新 review。说到底这就是用机制代替自觉。六、小变更的捷径hotfix 与 tweak大功能走全套没问题改两行配置也走 9 个 Skill 就太重了。spec-superflow 用模式检测自动降级。三模式对比 full/hotfix/tweak模式文件数完整规划工件DP-3 契约execution planfull任意需要 proposal/specs/design/tasks需要需要默认 SDDhotfix≤2 文件可跳过但需一份最小契约需要需要tweak≤4 文件纯配置/文档直接编辑不需要不需要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-superflowspec-superflowCursor 用官方安装器一行搞定npx spec-superflowlatest install-cursorCline / Kiro / Windsurf / Qwen / Amazon Q / Roo Code / Continue / Pi / Codex / Gemini / GitHub Copilot / WorkBuddy / Trae 等都有对应安装器或入口完整矩阵见官方INSTALL.md。装完之后全局 CLI 叫ssfnpm install -g spec-superflow ssf list # 列出所有 changes 及状态 ssf doctor # 健康检查版本、hooks、skills、文档一致性 ssf validate . # 验证工件完整性小技巧恢复会话用继续上次的工作流不确定状态用帮我看看现在该干什么它都会靠内容级检测把你指到正确的 Skill。八、决策点门禁总览整条流水线有 8 个决策点DP-0 到 DP-7它们是自动化流程里给你保留的最终决策权。Skill 走到门禁必须暂停等你的明确指令才继续。编号名称关联 Skill阶段DP-0设计前确认workflow-start入口DP-1需求确认need-explorer探索DP-2工件审查spec-writer规划DP-3契约批准硬门禁contract-builder桥接DP-4执行模式选择build-executor执行DP-5调试升级bug-investigator执行DP-6验证失败release-archivist收尾DP-7归档确认release-archivist收尾讲真这套机制最反直觉但也最值钱的一点是它把「人的确认」精确安插在 8 个关键节点而不是撒手让 Agent 一路冲到合并。你只在 DP-3 真正卡一次代码门其余大多是信息确认成本低但护栏实。九、适用场景与收尾推荐用大型功能开发、多人协作、长期维护项目、需要 TDD Review Gate 的棕地项目。不推荐一次性脚本、纯咨询问答。我自己用下来的体感是spec-superflow 把「想清楚」和「做对」这两件最容易被 AI 跳过的事变成了不可绕过的工程步骤。它不替你做决定但确保你每做一个决定都有记录、有契约、有回退。对动辄改几十个文件的 AI 编程来说这种克制反而最快。如果你也在用 AI 写代码建议先把workflow-start这一个入口用熟。剩下的状态机会替你看着。