Superpowers 的暗面：当流程本身成为返工的源头

> 问题不在 Skill 本身，而在 Skill 之间的衔接处。

Superpowers 可能是 2026 年最火的 AI 编程框架。GitHub 89K+ stars，Claude Code 官方插件市场上架，核心理念就一句话：Process over Prompt（流程大于提示词）。

它的标准工作流看起来完美：

brainstorming → worktrees → writing-plans → subagent/executing-plans
→ TDD → code-review → finishing-branch

每个 Skill 内部都有铁律保护——TDD 强制先写测试、brainstorming 苏格拉底式提问、code-review 双阶段审查。但越来越多用户发现：跑完一整套流程，返工率依然高得离谱。

问题出在哪？

在 Skill 与 Skill 之间的缝隙里。

---

一、三个致命衔接处

衔接处 1：brainstorming → writing-plans（设计文档漏掉了安全细节）

brainstorming 的产出是一份 spec 文档，writing-plans 假设这份 spec 已经足够完整。但 spec 里的信息在传递过程中会发生系统性衰减。

典型场景：

• brainstorming 阶段讨论了"用户登录功能"，确认了 OAuth 2.0 + JWT 方案
• 但安全细节（token 过期策略、刷新机制、CSRF 防护）只是随口一提，没有写入 spec
• writing-plans 读取 spec 时，只能基于已写入的内容拆解任务
• 结果：plan 里完全没有安全相关的任务，代码写完后发现 auth 漏洞

为什么 Skill 内部不会出错？ brainstorming 的铁律要求"逐层澄清需求"，但它只澄清了写入文档的部分。没有被写入文档的隐含假设，skill 没有机制去捕获。

自检方案（5分钟）： 1. 读完 spec 后，问自己：这份设计如果给一个新来的实习生，他会漏掉什么？ 2. 强制检查清单：安全边界、异常处理、数据持久化、第三方依赖、性能瓶颈 3. 如果 spec 中某部分只有结论没有推导过程，回退到 brainstorming 补充

---

衔接处 2：writing-plans → subagent-driven（计划中的模糊词让代理"猜着做"）

writing-plans 的假设是："执行者是一个热情的初级工程师，品味堪忧，没有判断力，不喜欢写测试。" 所以计划写得极度详细——每个任务精确到文件路径、完整代码、验证步骤。

但极度详细 ≠ 没有歧义。

典型陷阱：

• "添加适当的错误处理" → subagent 猜：用 try-catch 还是返回错误码？
• "优化查询性能" → subagent 猜：加索引还是改写 SQL？
• "保持与现有代码风格一致" → subagent 猜：现有代码风格是什么？
• "必要时重构" → subagent 猜：什么时候是"必要"？

这些模糊词（appropriate、optimize、consistent、when necessary）是人类工程师之间的润滑剂——我们可以凭上下文推断。但 subagent 没有上下文，只能猜。猜错的代价是：代码写完后，reviewer 发现完全不符合预期，整段重写。

为什么 Skill 内部不会出错？ writing-plans 的铁律要求"每个步骤2-5分钟"，但它没有检查"描述是否可被无歧义执行"。subagent-driven 的铁律要求"双阶段审查"，但审查只能发现"做错了"，不能发现"理解错了"。

自检方案（5分钟）： 1. 在 plan 中搜索以下模糊词：appropriate、suitable、reasonable、optimize、refactor、when necessary、if needed、consistent with、best practice 2. 每个模糊词替换为可验证的具体描述：

• ❌ "添加适当的错误处理" → ✅ "所有 API 调用必须包 try-catch，返回 {error: string} 格式，HTTP 状态码 500"
• ❌ "优化查询性能" → ✅ "将 N+1 查询改为 JOIN，确保单个请求 < 100ms"

3. 用"假设执行者完全不懂业务"的视角通读 plan，任何需要"推断"的地方都重写

---

衔接处 3：code-review → verification（审查问题未修复就直接验证）

Superpowers 的 code-review 流程很严格：每个任务完成后，先 Spec Review（是否符合 plan），再 Code Quality Review（代码质量）。问题按严重性分级：Critical / Important / Suggestion。

但code-review 的产出是一份问题列表，verification 的输入是"代码是否通过测试"。两者之间没有强制衔接。

典型失败路径： 1. subagent 完成任务，代码通过测试 2. code-review 发现 3 个 Important 问题（内存泄漏、异常处理缺失、边界条件未覆盖） 3. 主 Agent 把问题列表加入 TODO，但没有阻止进入 verification 阶段 4. verification 只检查"测试是否通过"——测试当然通过了，因为问题在测试覆盖不到的地方 5. Agent 宣布"任务完成"，进入下一个任务 6. 一周后生产环境崩溃，回查发现是 code-review 阶段就指出的问题

为什么 Skill 内部不会出错？ code-review 的铁律会标记问题严重性，但它没有规定"Important 以上必须修复才能进入 verification"。verification 的铁律要求"跑测试"，但测试覆盖不到 review 发现的所有问题。

自检方案（5分钟）： 1. 在 code-review 后，强制检查清单：

• Critical 问题：数量是否为 0？
• Important 问题：每个都有修复方案吗？
• 所有 Important 问题的修复都已验证了吗？

2. 如果还有未修复的 Important 问题，阻塞 verification，不允许进入下一个任务 3. 修复完成后，必须重新跑 review，确认问题确实解决（而不是"打算解决"）

---

二、5个零散的坑

坑 1：worktree 依赖安装（using-git-worktrees 的隐藏成本）

using-git-worktrees 创建隔离工作区，但新 worktree 不会自动安装依赖。subagent 进入 worktree 后，直接运行测试，结果报错：module not found。

subagent 花了 10 分钟排查，最后发现只是忘了 npm install。这 10 分钟本可以避免——如果 worktree 创建阶段就包含了"安装依赖"的强制步骤。

修复：在 using-git-worktrees 的产出检查清单中，加入："运行 npm install / pip install / bundle install，确认测试基线通过"。

---

坑 2：DONE_WITH_CONCERNS 的处理

subagent 返回状态有三种：DONE / NEEDS_CONTEXT / BLOCKED。但实践中还有第四种灰色状态：DONE_WITH_CONCERNS——任务"完成"了，但执行者有一些顾虑或警告。

例如："测试通过了，但我用了临时方案，建议后续优化"。主 Agent 收到 DONE 状态，直接标记完成，concerns 被忽略。一个月后这个临时方案成为技术债务的源头。

修复：subagent 返回状态必须包含一个 concerns 字段。如果非空，主 Agent 不能自动标记完成，必须人工确认或把 concerns 转化为新的任务项。

---

坑 3：验证证据的时效性

verification-before-completion 要求"证据优先"——声称完成前必须跑验证。但验证证据的有效期很短。

典型场景： 1. 任务 A 完成后通过验证，测试全绿 2. 任务 B 修改了共享模块，但只跑了任务 B 的测试 3. 任务 A 的测试其实已经被任务 B 破坏，只是没人重跑 4. 最终合并时，任务 A 的测试红了

修复：verification 必须包含"回归测试"步骤——每个新任务完成后，重跑所有已完成的任务的测试。或者，使用影响分析工具，只重跑可能被影响的测试。

---

坑 4：上下文漂移的隐性版本

Superpowers 的文档警告过"上下文漂移"——聊久了 Claude 忘了自己有 skill，开始按默认模式跳步骤。解法是用 /using-superpowers 重置。

但更隐蔽的是跨 Skill 的上下文漂移。例如：

• brainstorming 阶段讨论了 A 方案
• 中途切换到 writing-plans 时，Agent 默认选择了 B 方案（因为 B 方案在训练数据中出现更频繁）
• 用户没有注意到这个切换，直到执行阶段发现不对劲

修复：在每个 Skill 切换点，强制要求 Agent 总结"上一个 Skill 的关键决策"，并在下一个 Skill 中显式确认"这些决策被继承"。

---

坑 5：plan 的粒度悖论

writing-plans 要求每个任务 2-5 分钟。但如果任务太细，计划文档会膨胀到几百个步骤，维护成本超过收益。如果任务太粗，又失去了"精确可执行"的意义。

更深层的问题：2-5 分钟是对人类工程师的估计，但对 subagent 来说，同样的任务可能需要 10-15 分钟（因为 subagent 需要读取代码、理解上下文、搜索相关文件）。plan 的粒度基于错误的时间假设，导致进度失控。

修复：plan 的粒度应该基于"步骤复杂度"而非"时间估计"。例如："每个步骤只修改一个文件"或"每个步骤只引入一个概念"。

---

三、根本问题：流程不是银弹，执行者才是瓶颈

Superpowers 的设计哲学是"用流程约束替代人的判断力"。这个假设在单个 Skill 内成立，因为 Skill 内部有明确的铁律和 checklists。但在 Skill 之间的过渡地带，判断力仍然不可或缺——而 Superpowers 没有为这些地方提供足够的约束。

这揭示了一个更广泛的真理：

> AI 编程工具最大的问题不是智力，是纪律。但纪律只能解决已知的问题，不能解决未知的问题。

Skill 之间的衔接处，本质上是一个"未知问题"的生成器——每个项目、每个团队、每个需求都有不同的隐含假设和边界条件。这些无法被预先编码到流程中，只能依赖执行者的判断。

---

四、实用建议：如何让 Superpowers 真正减少返工

1. 在每个衔接处加入"桥接检查清单"

衔接处	桥接检查项
brainstorming → writing-plans	安全边界、异常处理、数据持久化、第三方依赖、性能瓶颈
writing-plans → subagent	搜索模糊词并替换为可验证描述、假设执行者零上下文
code-review → verification	Critical 必须为0、Important 必须有修复方案、修复后重跑 review

2. 把"自检"变成流程的一部分，不是可选步骤

当前 Superpowers 的自检是"建议性的"（你可以花5分钟检查，也可以跳过）。应该把它变成强制性的：在 Skill 切换时，Agent 必须输出桥接检查清单，并确认所有项通过后才能继续。

3. 引入"验收测试"作为跨 Skill 的契约

brainstorming 的产出应该包含一组验收测试用例（Acceptance Tests），这些测试用例在 writing-plans 阶段被拆解为单元测试，在 verification 阶段被整体验证。这样，每个 Skill 的产出都有明确的、可验证的契约。

4. 记录并复盘返工原因

每次返工后，强制记录：

• 返工发生在哪个衔接处？
• 如果做了桥接检查，能避免吗？
• 如果是 Skill 内部的缺陷，反馈到 Superpowers 社区

这些记录会积累成团队自己的"返工预防知识库"，比任何通用的 Skill 都更有针对性。

---

结语：流程是骨架，判断力是肌肉

Superpowers 是一个极好的框架——它把软件工程的最佳实践编码为可复用的流程，显著提升了 AI 编程的基线质量。但流程只能保证下限，不能替代上限。Skill 之间的衔接处，正是上限与下限之间的灰色地带。

约15分钟的自检（三个衔接处各5分钟），可以避免数小时的返工。这个投入产出比，值得每个使用 Superpowers 的团队认真对待。

但更重要的是认识到：流程是骨架，判断力是肌肉。骨架决定了你能不能站起来，肌肉决定了你能跑多快。 Superpowers 给了你骨架，但肌肉还得自己练。

---

参考

• Superpowers GitHub: https://github.com/obra/superpowers
• Superpowers 中文增强版: https://github.com/jnMetaCode/superpowers-zh
• 核心概念：Process over Prompt、Skill 系统、TDD、Subagent 驱动开发
• 相关工具：Claude Code、Codex、Cursor、OpenCode

#AI编程 #Superpowers #流程优化 #返工预防 #ClaudeCode #AI开发 #工程实践 #工作流 #代码审查 #TDD