Superpowers 阅读分析与使用笔记

这篇文章解决什么问题

superpowers 是 Jesse Vincent / obra 维护的一个 agentic skills 框架，仓库地址：

• obra/superpowers

它不是一个传统 SDK，也不是一组“让 AI 更聪明”的 prompt。它更像一套给 coding agent 用的工程纪律：

• 先澄清需求
• 再写设计
• 再拆计划
• 再用 TDD 实现
• 再做 code review
• 再验证完成
• 最后处理分支、PR、合并或丢弃

一句话：

superpowers 不是给 agent 加能力，而是给 agent 加流程、边界和刹车。

先说结论

• superpowers 的核心价值不是 skill 文件多，而是它把 AI 编程从“聊天式执行”改成“流程式交付”。
• 它强调 brainstorming、worktree、writing-plans、subagent-driven-development、TDD、code review、verification-before-completion。
• 它适合复杂编码任务，不适合每个小改动都完整照搬。
• 它最强的地方是防止 agent 自作主张、跳过测试、改太多、声称完成但没验证。
• 它最重的地方也是流程：如果任务很小，完整使用会显得慢。

我的判断：

superpowers 更像“AI 工程经理 + 测试负责人 + code reviewer”的流程包，而不是“提示词优化包”。

它从什么问题出发

AI coding agent 最常见的问题不是完全不会写代码。

真正麻烦的是：

• 需求没问清就开写
• 写完才补测试
• 做了用户没要的功能
• 顺手重构无关代码
• 修 bug 时猜原因
• 看到测试绿就说完成，但没验证真实目标
• 上下文太长后，自己忘记前面约束
• 多任务混在一个会话里，越做越乱

这些问题在人类工程里也有，但 agent 更容易放大。

因为 agent 写代码成本很低，它会很快生成大量东西。方向错时，错得也很完整。

superpowers 的思路是：不要只靠“请你谨慎一点”这种软约束，而是把谨慎拆成一组强制流程。

它和普通 AGENTS.md 有什么区别

普通 AGENTS.md 或 CLAUDE.md 通常写项目规则：

• 用什么语言
• 不要新增依赖
• 不要跑格式化
• 目录怎么放
• 回复用什么语言
• 完成后说明改了什么

这些规则很重要，但它们通常偏静态。

superpowers 的重点是动态流程：

类型	解决的问题
AGENTS.md / CLAUDE.md	这个项目有哪些规则
prompt 模板	这次任务怎么问
memory	过去踩过什么坑
skills	遇到某类任务时，必须按什么流程做
superpowers	把一组 skills 串成完整交付方法论

所以它不是替代项目规则，而是补齐“如何执行任务”的部分。

核心工作流

README 里给出的基本流程很清楚：

1. brainstorming
2. using-git-worktrees
3. writing-plans
4. subagent-driven-development 或 executing-plans
5. test-driven-development
6. requesting-code-review
7. finishing-a-development-branch

这条链路像一个严格版软件交付流水线。

1. brainstorming：先问清楚再写

brainstorming 的目标是把“模糊想法”变成“可实现设计”。

它会要求 agent：

• 先探索项目上下文
• 再问澄清问题
• 再给 2-3 个方案
• 再说明优缺点和推荐方案
• 再写设计文档
• 再让用户确认

它最反 AI 直觉的一点是：

不允许直接进入实现。

这对很多人来说会觉得慢。但它解决的是最贵的问题：方向错。

比如你说：

帮我加一个导出功能。

普通 agent 可能直接写 CSV 导出。

但 brainstorming 会逼它问：

• 导出什么数据
• 当前筛选条件还是全部数据
• 权限怎么控制
• 文件格式是什么
• 同步下载还是异步任务
• 大数据量怎么办
• 敏感字段是否过滤

这些问题不问清，后面写得越快，返工越多。

2. using-git-worktrees：隔离工作区

using-git-worktrees 用来给任务创建独立 worktree。

它解决两个问题：

• 多个任务并行时，不互相污染
• agent 改坏后，更容易丢弃或回滚

它还会要求：

• 找 .worktrees 或 worktrees 目录
• 确认目录被 git ignore
• 创建新分支
• 安装依赖
• 跑 baseline test
• 确认起点干净

这很工程化。

很多 agent 失败不是因为不会写代码，而是因为在一个脏工作区里继续叠改，最后不知道哪些问题是它造成的，哪些问题是本来就有的。

worktree 把这个边界切干净。

3. writing-plans：把任务拆到可执行

writing-plans 要求写一份非常具体的执行计划。

不是这种：

1. 添加接口
2. 修改前端
3. 增加测试

而是要写到：

• 精确文件路径
• 每一步做什么
• 测试代码怎么写
• 运行什么命令
• 预期失败是什么
• 预期通过是什么
• 每个任务 2-5 分钟粒度

它甚至要求计划里不能出现：

• TBD
• TODO
• implement later
• add appropriate error handling
• write tests for above

这点很值得借鉴。

很多 AI 计划看起来像计划，实际是愿望清单。writing-plans 逼计划变成“低上下文执行说明”。

它的目标是：即使执行者是一个不了解项目、判断力一般、讨厌测试的人，也能照着做出可验收结果。

这句话虽然刻薄，但很实用。因为 coding agent 很多时候就像这样。

4. subagent-driven-development：任务交给干净上下文

subagent-driven-development 是 superpowers 很核心的部分。

它强调：

• 每个任务派一个 fresh subagent
• subagent 不继承主会话历史
• 主会话给它精确上下文
• 实现后做两阶段 review
• 先看 spec compliance
• 再看 code quality
• 有问题就返工，不进入下一步

这解决了上下文污染问题。

长会话里的 agent 会带着很多历史噪音：

• 已废弃的方案
• 用户中途否掉的方向
• 旧错误假设
• 无关文件内容
• 前面失败尝试的残影

fresh subagent 的价值是“只拿当前任务需要的上下文”。

这和人类团队分工类似：不要把所有会议纪要都塞给每个工程师，只给他清晰任务、必要背景、验收标准。

5. test-driven-development：先红再绿

superpowers 的 TDD skill 很硬。

它不是“建议写测试”，而是要求：

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

流程是：

1. 写一个失败测试
2. 看它因为预期原因失败
3. 写最少代码让它通过
4. 跑测试确认通过
5. 再重构

它还特别反对“测试后补”。

原因很简单：

• 代码写完后再补测试，测试容易迎合实现
• 测试一开始就通过，无法证明它能抓住问题
• 没看过红灯，就不知道绿灯有没有意义

这条对 agent 尤其重要。

因为 agent 很擅长写“看起来有测试”的代码，但那些测试可能只是在验证 mock、验证实现细节，或者根本没有覆盖真实行为。

6. systematic-debugging：先找根因再修

systematic-debugging 是另一条重流程 skill。

它的核心是：

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

它把 debug 拆成四阶段：

阶段	做什么
Root Cause Investigation	读错误、复现、查最近改动、收集证据
Pattern Analysis	找工作示例、对比差异、理解依赖
Hypothesis and Testing	提出单一假设，做最小验证
Implementation	写失败测试，修根因，验证

这解决 agent 最常见的坏习惯：猜。

比如测试失败了，agent 很容易：

• 改 mock
• 改 timeout
• 改断言
• 加 try/catch
• 换 API
• 顺手改好几处

如果没找到根因，这些都是随机修补。

systematic-debugging 逼 agent 先证明问题在哪里，再动代码。

7. requesting-code-review：早审查，别等最后

requesting-code-review 要求在任务完成后派 reviewer agent。

重点是：

• reviewer 拿精确上下文
• 不继承主会话历史
• Critical 立即修
• Important 继续前必须修
• reviewer 错了可以反驳，但要有技术理由

这和 subagent-driven-development 配套。

一个实现 agent 容易对自己的代码产生路径依赖。reviewer agent 的价值是换一个上下文，从要求和 diff 看问题。

8. verification-before-completion：没有证据别说完成

这个 skill 的态度很硬：

没有新鲜验证证据，就不能声称完成。

它要求先回答：

• 什么命令能证明完成
• 是否刚运行过
• 输出是什么
• 退出码是什么
• 是否真的覆盖目标

这条很实用。

AI agent 特别容易说：

• 应该好了
• 看起来没问题
• 已完成
• 测试应该会过

但这些不是证据。

真正能交付的说法应该是：

已运行 `pnpm build`，exit 0。
未运行浏览器验证，因为当前任务没有启动 dev server。

或者：

未运行构建。只能确认文件改动和链接文本已接入，页面实际可访问需要你本地启动验证。

这比“完成了”更诚实。

仓库结构怎么理解

从仓库目录看，superpowers 不是只给 Claude Code 用。

它同时面向多个 coding agent / CLI：

目录或文件	作用
.claude-plugin	Claude Code 插件
.codex-plugin	Codex 插件
.cursor-plugin	Cursor 插件
.opencode	OpenCode 集成
GEMINI.md	Gemini CLI 指令
AGENTS.md	agent 通用入口
skills/	核心 skills
commands/	命令入口
hooks/	生命周期或自动触发相关能力
tests/	测试
docs/	文档

这说明它的目标不是“某一个工具的提示词库”，而是跨 agent 的工作流层。

它把同一套方法论包装给：

• Claude Code
• OpenAI Codex CLI / App
• Cursor
• OpenCode
• GitHub Copilot CLI
• Gemini CLI

这点很重要。未来 agent 工具会变，流程纪律应该尽量能迁移。

它的核心思想

README 里列了四个 philosophy：

• Test-Driven Development
• Systematic over ad-hoc
• Complexity reduction
• Evidence over claims

这四条可以翻译成工程语言：

原则	反对什么
TDD	写完再补测试
Systematic over ad-hoc	猜、试、乱改
Complexity reduction	过度设计、一次做太多
Evidence over claims	没验证就说完成

它最关心的不是“模型能力最大化”，而是“模型行为可控”。

这点和很多 AI 工具宣传不一样。

很多工具在说：

• 更快生成代码
• 更强模型
• 更大上下文
• 更自动化

superpowers 反而在强调：

• 慢一点问清楚
• 小任务执行
• 强制测试
• 强制 review
• 强制验证
• 有证据再说完成

这更接近真实工程。

和 andrej-karpathy-skills 的关系

本站前面有一篇：

• andrej-karpathy-skills：把 AI 编程的坏习惯写成约束

它和 superpowers 方向相近，但层级不同。

项目	重点
andrej-karpathy-skills	把 AI coding 坏习惯写成通用行为约束
superpowers	把多个工程流程写成可触发、可执行的 skills 系统

可以这样理解：

• andrej-karpathy-skills 更像“工作纪律”
• superpowers 更像“完整交付流程”

前者提醒 agent 不要乱做，后者直接规定 agent 每一步怎么做。

和 prompt-optimizer 的关系

prompt-optimizer 解决的是提示词本身怎么优化：

• prompt 怎么结构化
• 怎么测试原始 prompt 和优化 prompt
• 怎么迭代
• 怎么做模板

superpowers 解决的是 agent 工作流怎么约束：

• 什么时候要问
• 什么时候要写计划
• 什么时候要开 worktree
• 什么时候要 TDD
• 什么时候要 review
• 什么时候才能说完成

所以两者关系是：

项目	更像什么
prompt-optimizer	prompt 工作台
superpowers	agent 工程方法论

如果你是写提示词，先看 prompt-optimizer。

如果你是让 AI 改代码，superpowers 更有参考价值。

一个实际例子：做一个登录 bug 修复

假设用户说：

登录偶尔失败，帮我修一下。

普通 agent 可能会：

1. 搜登录代码
2. 猜 token 过期
3. 改刷新逻辑
4. 跑一下测试
5. 说修好了

superpowers 的路线会更长：

1. systematic-debugging：先问失败现象、错误日志、复现条件
2. 读错误和最近改动
3. 找登录成功路径和失败路径
4. 提出单一假设
5. 写复现测试
6. 看测试失败
7. 做最小修复
8. 看测试通过
9. code review
10. completion verification

这看起来慢，但对“偶尔失败”这种问题更安全。

因为偶发 bug 最怕猜。猜中一次不代表根因对，下一次还会出现。

一个实际例子：加一个新功能

用户说：

帮我做一个报表导出。

superpowers 会把它当成设计任务：

brainstorming 阶段

先确认：

• 报表类型
• 数据范围
• 权限
• 格式
• 大小限制
• 是否异步
• 是否需要历史记录
• 是否需要审计

writing-plans 阶段

再拆成任务：

• 后端导出服务
• 权限校验
• 文件生成
• 前端按钮
• 下载状态
• 错误提示
• 测试

TDD 阶段

每个任务先测试：

• 无权限不能导出
• 空数据导出空文件
• 大数据走异步
• 文件名符合规则
• 前端失败提示正确

review 阶段

再检查：

• 是否按 spec 做
• 是否多做了没要求的东西
• 是否缺边界测试
• 是否引入不必要依赖

这比“直接写功能”更稳。

它适合什么任务

适合

• 多文件功能开发
• 不确定需求
• 需要测试保证的业务逻辑
• 复杂 bug
• 长时间 agent 自主执行
• 多任务并行
• PR 质量要求高的开源项目
• 需要严格 review 的团队项目

不太适合

• 改一个 typo
• 加一条文档链接
• 很小的样式微调
• 临时探索型 demo
• 用户明确说不要流程、直接小改

不过，即使小任务不完整跑流程，也可以借用里面几条原则：

• 改前读上下文
• 明确完成标准
• 只改目标文件
• 不乱扩范围
• 不验证就不声称验证过

它最值得借鉴的设计

1. Skills 是可执行流程，不是建议

很多规则写着“应该”“建议”，agent 很容易忽略。

superpowers 的 skills 写法更强：

• MUST
• NEVER
• Red Flags
• Checklist
• Iron Law
• When to Use
• Integration

这种语气不是为了凶，而是为了对抗模型的“合理化”。

Agent 很会给自己找理由：

• 这次很简单
• 不用测试
• 我已经知道原因
• 先修再说
• 用户应该想要这个

所以 skill 里大量写“这些想法就是红旗”，是在提前堵住 agent 自我说服。

2. 把反模式写进规则

superpowers 的很多 skill 都有反模式或 rationalization 表。

比如 TDD 里会直接说：

• “测试后补”不等于 TDD
• “太简单不用测试”是借口
• “我手动测过”不是证据
• “保留已有代码当参考”会污染测试先行

这很重要。

因为 agent 不是不知道正确流程，而是会在压力下跳过流程。

反模式列表等于把常见逃跑路线提前封死。

3. 用 subagent 降低上下文污染

很多人用 subagent 只是为了并行。

superpowers 更强调 fresh context。

它的关键点不是“更多 agent 更快”，而是：

每个 agent 只知道它该知道的东西。

这能减少：

• 被旧方案影响
• 被无关上下文干扰
• 把主会话猜测当事实
• 在复杂任务中越走越偏

4. Review 分成 spec 和 quality

它的 review 不是泛泛“看看有没有问题”。

先看 spec compliance：

• 是否做了要求
• 是否漏了要求
• 是否多做了要求外的东西

再看 code quality：

• 实现是否清晰
• 测试是否真实
• 是否过度设计
• 是否有维护风险

这个顺序对。

如果需求都没做对，代码再漂亮也没意义。

5. Verification 单独成 skill

把“完成前验证”单独拆出来，是很好的设计。

因为 agent 最容易在最后松懈：

• 写完了
• diff 看着对
• 自己觉得完成
• 直接总结

独立 verification skill 能强制最后一道门：

你说完成之前，证据在哪里？

这比“记得跑测试”强很多。

它可能带来的成本

superpowers 不是没有代价。

成本一：流程重

完整流程会消耗时间和 token。

对小任务来说，brainstorming、spec、plan、worktree、TDD、review 全上，可能过重。

所以需要判断任务大小。

成本二：需要用户配合

它会问问题，会等用户确认设计，会让用户选择执行方式。

如果用户只是想快速改一个文案，这会打断节奏。

成本三：TDD 在旧项目里可能难落地

很多老项目测试基础差。

严格 TDD 可能遇到：

• 没测试框架
• 测试环境慢
• mock 很重
• 现有代码耦合
• UI 改动难写单测

这时不能机械套用，但可以保留“先定义可验证标准”的精神。

成本四：subagent 需要平台支持

不是所有工具都有好用的 subagent。

即使有，也要处理：

• 上下文传递
• 文件冲突
• review 合并
• 成本控制
• 失败重试

所以 superpowers 在 Claude Code 这类环境里体验更完整，在其他环境里可能要折中。

给个人使用者的建议

如果你想借鉴它，不一定要完整安装。

可以先抄三条：

1. 任何编码任务先写完成标准

例如：

完成标准：
1. 新增文档放到 src/notes/ai
2. index.md 有入口
3. sidebar 有入口
4. 不跑项目命令
5. 最后说明未验证运行

这能立刻减少“做到哪算完”的问题。

2. 修 bug 前先写根因假设

例如：

假设：登录失败不是 token 过期，而是 refresh 请求并发导致旧 token 覆盖新 token。
验证：添加日志或测试，证明并发时 token 写入顺序错误。

不要一上来改代码。

3. 完成前必须说清验证证据

例如：

已运行：pnpm build，exit 0。
未运行：浏览器手动验证。
原因：没有启动 dev server。

这比“已完成”有用。

给团队使用者的建议

团队如果要用 superpowers，不要一上来全量照搬。

推荐分三步。

第一步：先统一交付口径

要求 agent 每次交付必须说明：

• 改了哪些文件
• 为什么这么改
• 运行了什么验证
• 没验证什么
• 有什么风险

第二步：给复杂任务加计划门槛

只有复杂任务需要：

• brainstorming
• design doc
• writing plan
• 用户确认

小任务直接执行，但仍要保留边界和验证。

第三步：引入 subagent review

先从 review 开始，不急着让 subagent 写代码。

因为 review 的收益高、风险低：

• 主 agent 做实现
• reviewer agent 看 diff 和要求
• 发现漏项、过度实现、测试缺失

等流程稳定后，再把实现也拆给 subagent。

我对这个项目的评价

superpowers 最有价值的地方，不是它给了很多具体技能，而是它抓住了 agent 编程的本质问题：

AI agent 需要的不是更多自由，而是更好的约束。

过去我们常用 prompt 约束 agent：

请你谨慎一点，不要乱改。

这太弱。

superpowers 的做法是：

遇到需求，先 brainstorming。
遇到计划，先 writing-plans。
遇到实现，先 TDD。
遇到 bug，先 systematic-debugging。
遇到完成，先 verification-before-completion。

它把“谨慎”变成流程，把“专业”变成 checklist，把“不要乱来”变成可触发 skill。

这比单次 prompt 更可靠。

最小实践清单

如果不安装，只借鉴思想，我建议先用这份清单：

1. 任务开始前：写完成标准。
2. 改代码前：读相关模块。
3. 需求有歧义：先列选项和推荐方案。
4. 新功能：先写可验证行为。
5. 修 bug：先找根因，不猜。
6. 大任务：先拆小任务，每步有文件和验证。
7. 长任务：用新上下文做子任务或 review。
8. 完成前：跑能证明结果的检查。
9. 不能跑检查：明确说没验证和原因。
10. 交付时：只总结事实，不夸大状态。

什么时候不该套完整流程

这些情况不用完整 superpowers 流程：

• 改错别字
• 新增一条导航
• 调整一行配置
• 用户明确要求快速改
• 没有代码行为变化

但仍然要保留两个底线：

• 不要碰无关文件
• 不要把没验证说成已验证

最后总结

superpowers 是一套面向 coding agent 的软件工程方法论。

它的关键词不是“自动写代码”，而是：

• 需求澄清
• 工作区隔离
• 计划拆解
• TDD
• 系统化调试
• 子代理执行
• 两阶段 review
• 完成前验证

它最适合复杂编码任务，尤其是那种 agent 容易越界、猜测、跳过测试、乱改一片的任务。

对个人来说，它是高质量 AI 编程习惯样本。

对团队来说，它是把 agent 纳入工程流程的参考模板。

但要记住：

流程不是目的，可靠交付才是目的。

小任务保留轻流程，大任务用强流程。这样最值。