为什么AI编程需要规格驱动工作流?spec-superflow设计思想完全解读

原创2026-10-24 22:52:412,224 阅读
文章标签:AI 技能AI 插件开发工具工作流自动化

为什么AI编程需要规格驱动工作流?spec-superflow设计思想完全解读

AI 编程最大的坑,往往不是写不出代码,而是"跑偏了还不知道"。今天这篇文章带你完整解读 spec-superflow ——一个源码级融合 OpenSpec 规划引擎与 Superpowers 执行纪律的 AI 编程工作流插件。它以 Spec-first(规格优先) 和契约驱动为核心设计思想,支持 19 个主流 AI 编程平台、内置 9 个 Skill,帮新手和普通用户把"模糊的一句话需求"变成"可核对、可恢复的交付结果"。

一、为什么 AI 编程需要规格驱动?

如果你用过 Claude Code、Cursor 这类 AI 编程工具,大概率遇到过这三类问题:

  1. 范围漂移:让你修一个登录超时,它顺手重构了半条认证链路;
  2. "我已经修好了":AI 声称完成,但你无法验证它到底跑了什么测试、覆盖哪些改动;
  3. 状态丢失:中途断开后,AI 记不清之前批准过什么,只能从头再来。

这些问题的根源是:自然语言需求 → 直接生成代码之间缺少一层"可核对的中间契约"。规格驱动工作流(Spec-Driven Workflow)的思路就是:先写清楚"要做什么、不做什么、怎么算做完",再让 AI 在这份契约的边界内执行。

spec-superflow 正是把这件事做成了开箱即用的插件。

二、双引擎设计:规划引擎 + 执行纪律

spec-superflow 的核心理念可以用一句话概括:用 OpenSpec 的思路管"想清楚",用 Superpowers 的纪律管"做扎实"(运行时并不依赖这两个项目,只做思想借鉴,见 README.md)。

引擎 解决的问题 落地形式
OpenSpec 式规划 需求模糊、范围失控 proposal.md + tasks.md,按需补充 specs/ 与 design.md
Superpowers 式执行 验证走过场、调试打转 最终验证一次、完整 Git range 审查、失败证据不可改写为通过

规划产物有明确分工(详见 docs/artifact-contract.md):

  • proposal.md:为什么改、改什么、明确不改什么、涉及哪些能力;
  • specs/:必须满足的行为与验收条件(delta spec,即"相对当前基线的规格增量");
  • design.md:只在存在真实技术取舍时才写,避免过度设计;
  • tasks.md:有序 checkbox 任务,每项都写明完成条件和检查结果。

想看真实产物长什么样,可以直接读项目内置的两个完整示例:docs/examples/add-dark-mode/proposal.md(新增功能)和 docs/examples/refactor-auth-boundary/(存量代码重构)。

三、v2 的两个执行路径:小改动不再承担大流程

很多工作流框架的通病是"一刀切"——改个文案也要走完整规划流程。spec-superflow v2 的做法是把新任务收敛为两个入口,这是它设计上最值得称道的地方:

3.1 Direct 路径:明确的小改动,直接执行

意图清楚、影响面可判断、验证可复现的改动,一条命令启动,不生成任何规划文档:

ssf workflow start changes/fix-login-timeout \
  --path direct \
  --scope "修复登录超时,不改变认证协议"

只记录用户请求的范围 + 最终验证结果,零固定成本。

3.2 Planned 路径:需要对齐范围的改动,先批准一份短计划

跨模块、动公共接口、改数据语义的改动,先写 proposal.md 和 tasks.md,用户一次批准后进入执行:

ssf workflow start changes/add-session-refresh \
  --path planned \
  --confirm \
  --reason "用户已批准 proposal.md 与 tasks.md"

关键设计:批准只发生一次。v1 时代有五路径问卷、四份规划文档、手写契约、逐阶段确认;v2 全部砍掉,"已批准的执行计划"成为唯一权威依据(对照表见 README.md "为什么是 v2" 一节,完整状态规则见 docs/state-machine.md)。

而且两条路径可以无缝升级:direct 执行中发现范围扩大,补齐两份文档再批准一次即可升级 planned,无需重开状态机。

四、9 个 Skill:按需加载,不是九连关卡

spec-superflow 提供 9 个 Skill(位于 skills/ 目录),但它们不是每次都要走完的九个阶段,而是按需调用的职责模块:

Skill 一句话职责 何时触发
workflow-start 识别新任务/恢复已有任务,选择 direct/planned 显式启用时的唯一入口
need-explorer 澄清范围、非目标、成功标准 需求模糊时
spec-writer 编写 proposal 与 tasks planned 路径
build-executor 按授权范围实现并运行验证 默认执行阶段
bug-investigator 复现问题、追根因,避免试错循环 遇到缺陷/测试失败
code-reviewer 审查完整 Git range 最终审查一次
spec-merger 把 delta spec 原子同步到主规格库 存在 delta spec 时
release-archivist 最终验证、记录结果、处理合并归档 实现完成时
contract-builder 维护旧变更的执行契约 仅兼容 legacy change

典型调用链保持极简:

Direct:  workflow-start → build-executor → release-archivist
Planned: need-explorer? → spec-writer → workflow-start → build-executor
         → code-reviewer → spec-merger? → release-archivist

其中 ? 表示条件满足才调用。默认不创建子代理、不逐任务审查、不自动建 worktree——一切重型能力都显式选择才开启,这是它"低成本优先"哲学的直接体现。

五、最硬核的设计原则:结果必须可核对

读完 docs/decision-points.md 和 docs/state-machine.md 后,你会发现 spec-superflow 最"较真"的部分在于反作弊:

  • "完成"不是 AI 说修好就算:ssf workflow complete 会真正执行一次验证命令并保存退出码;planned 路径还要检查任务完成状态、最终审查结果和 delta spec 同步状态;
  • 空 Git range、截断范围、损坏 hash、过期审查统统不能通过——工具不会用默认值伪造通过;
  • 失败就保留失败:验证失败留在执行阶段修复重试,不会把 failed 改写成 pass;
  • 人类决策可见:用户确实想带已知问题交付时,可以用 --accept-risk 显式记录,状态记为 accepted-risk,理由必须留下,且不会自动合并分支。

这种"授权与证据记录"的思路,本质是把 AI 工作流从"信任黑盒"变成"审计白盒"。

六、平台支持与安装:19 个平台一套设计

spec-superflow 支持 19 个 AI 编程平台(Claude Code、Cursor、Codex、GitHub Copilot、Gemini CLI、Cline、Windsurf、Roo Code、Qoder 等),完整能力差异见 docs/platform-matrix.md。每个平台按三层接入:Skills 部署、phase-guard 规则文件(平台自动加载的守卫机制)、SessionStart 上下文注入钩子。

安装很简单,以 Claude Code 为例:

npm install -g spec-superflow

或者通过插件市场安装(各平台命令见 INSTALL.md):

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

两个值得一提的工程细节:

  • 零运行时依赖:CLI 只使用 Node.js 标准库(要求 Node.js 20+),TypeScript 仅用于构建;
  • 版本自包含:Marketplace 和各平台安装器会把 Skill 与同版本 CLI runtime 一起升级,Skill 只调用安装包内的 runtime,不会误用 PATH 里的旧 ssf。

七、适合谁用?怎么选路径?

你的场景 推荐用法
让 AI 修一个明确的小 Bug direct 路径,一条命令启动
跨模块功能、动公共接口 planned 路径,先批准 proposal + tasks
需求还说不清楚 让 need-explorer 先澄清,再进 planned
中途断线/换会话 ssf resume <dir> + ssf checkpoint list <dir> 恢复上下文

最后给新手一个判断口诀:"改动范围我能一句话说清吗?能,走 direct;不能,走 planned"。如果执行中发现范围悄悄变大,补文档升级 planned 即可,流程不会让你推倒重来。

总结

spec-superflow 的设计思想可以浓缩为四条:

  1. 按需规划——小改动不承担完整 SDD 的固定成本;
  2. 一次批准即可执行——不重复确认,批准记录写入 schema v2 执行计划;
  3. 结果必须可核对——空 range、损坏 hash、过期审查一律挡在门外;
  4. 人类决策可见——风险可以接受,但理由必须留下,且不能伪造验证成功。

对新手而言,它降低了"用 AI 写代码但心里没底"的焦虑;对普通用户而言,它把 19 个平台的 AI 编程体验统一成了一套可恢复、可审计的规格驱动工作流。如果你正在用 AI 编程工具处理真实业务,这套"规格先行 + 契约驱动"的思路值得完整读一遍(版本历史见 CHANGELOG.md)。

登录后查看全文
spec-superflow