Superpowers 完全上手指南：给 Codex CLI 注入工程实战能力
如果你最近关注 AI 编程工具，应该会注意到 Codex CLI 这类终端 AI 助手正火。但很多人用着用着就发现一个问题：它能聊天、能改代码、能解释概念，可真让它干活的时候，总差那么一口气——不会自动跑测试、不敢改多个文件、更不会在改完之后帮你复盘。我折腾 superpowers 这个工具集半个多月，可以负责任地说，它解决的正是这个“最后一公里”的问题。
superpowers 不是某个具体软件，而是一组专门给 Codex CLI 这类 AI 编码助手用的“技能包”和配置集合，装好之后，你的 AI 不再只会坐在那儿跟你聊天，而是像一个真正坐在工位旁的结对工程师：会自己开终端跑测试、会派子代理去并行处理独立任务、会先把代码走读一遍再动手改。这篇内容就是我的完整实测记录，包括安装、核心技能拆解、Java 场景落地，以及我在真实项目里踩过的各种坑。如果你也想让 Codex CLI 真正“能干活”，这篇文章就是为你准备的。
1. 先把 superpowers 到底是个什么东西说清楚
1.1 从 Codex CLI 的局限说起
先说一个核心判断：Codex CLI 本身的能力底子很好，但它默认状态下更像一个“编码陪聊”，而不是“编码工人”。它可以定位模糊类、写函数、做代码评审，可做完这些它不会自己 compile，不会自己跑测试，更不会在改完某个模块后到另一个模块里检查有没有破坏别的东西。打个比方，它像一个理论知识很扎实的实习生，你让它写一段代码，它写得出来，但你让它起身去倒杯水、把房间打扫一遍，它就懵了——因为它没有“工具”去执行这些动作。
superpowers 做的，就是把这一层补上。它会往 Codex CLI 里注册一系列自定义命令和工具，主要通过 MCP（Model Context Protocol，模型上下文协议）来实现。MCP 可以理解成一个给 AI 模型“外挂工具箱”的标准接口：模型本身会“说话”，但通过 MCP 它可以调用外部工具去“动手”——跑命令、读文件、写文件、查 git 状态，全都在终端里完成，不需要你来回复制粘贴。
1.2 它的核心构成：技能包、子代理指令和配置文件
我拆解过 superpowers 的结构，它其实包含三部分：第一部分是技能包（skills），每个技能包对应一个具体的工程能力，比如 run-tests、create-tests、review-changes；第二部分是子代理指令（subagent prompts），用来让 Codex 派发“分身体”去处理独立任务；第三部分是CLI 集成配置，也就是告诉 Codex CLI 怎么找到并启动这些工具。
这三者配合起来的效果，你可以想象成：原来你只有一个大脑（Codex CLI），现在给它配了一双手（跑命令）、一双眼睛（读文件、查状态）、以及一群可以临时借调的外包（子代理）。这就是 superpowers 名字的由来——不是玄学，就是字面意思上的“给 AI 加超能力”。
1.3 适合谁用，解决什么问题
我在几个不同身份的朋友身上验证过这套东西的适用范围：
- 独立开发者或技术负责人：需要让 AI 自动改代码并确保测试全绿，减少手动返工。
- 用 Codex CLI 做日常编码的工程师：不想每次都写一大堆“帮我看看哪里错了”的提示词，希望说一句“跑一下测试”AI 就去执行。
- 团队里负责研发流程建设的人：想把 AI 编码流程标准化，让新成员也能用同一套命令和流程干活。
不夸张地说，只要你的日常工作是“在终端里写代码 + 跑测试 + 改 bug”，superpowers 就值得装。但如果你只是偶尔用 Codex 问一问代码怎么写，那这玩意儿对你来说可能有点杀鸡用牛刀。
2. 安装部署：从零到能跑的全流程
2.1 装之前确认这几件事
在动手之前，先确认你的环境满足这些前提（我是基于 macOS 的 zsh 环境实测的，Linux 和 Windows 的 WSL 也适用）：
- 已安装 Node.js（版本建议 18 以上，我有一次在 16 上跑直接报语法错误）
- 已经装好 Codex CLI 并且能用 OpenAI 账号登录，能正常对话
- 网络环境能访问 npm registry（如果公司内网有代理，先配好 npm 代理）
- 终端用的是 bash/zsh，别用 cmd
这些条件缺一不可，尤其是 Node.js 版本。我一开始在旧版本上装，node 模块加载直接失败，报的是ERR_REQUIRE_ESM，后来升到 18 才消停。
2.2 完整安装步骤
superpowers 的安装方式，官方和社区有大体一致的流程，我这边的完整命令如下：
# 1. 全局安装 superpowers 包 npm install -g @superpowers/core # 2. 初始化配置，这一步会生成 .superpowers 目录及相关配置 npx superpowers init # 3. 将工具注册到 Codex CLI（这一步会读取并修改 Codex 的配置文件） npx superpowers install # 4. 验证是否安装成功 superpowers --version如果你遇到command not found: superpowers，多半是 npm 全局 bin 目录没加到 PATH，macOS 上通常是~/.npm-global/bin或/opt/homebrew/bin，自己加到.zshrc里就可以了。
接着验证 Codex CLI 是否已经能识别这些工具，你可以直接进入 Codex 交互模式问一句：
你有哪些可用工具？请列出来。如果 Codex 开始列出 run-tests、subagent 之类的工具，说明注册成功。如果它回答“我没有这类工具”，那就回头检查npx superpowers install是否真的执行成功，以及 Codex 的配置路径是否正确。
2.3 安装时容易踩的坑
有几点我必须专门提醒：
- 不要同时装多个插件。我在安装 superpowers 之前，机器上还有另一个 Codex 插件，结果两边在 MCP server 端口上冲突，Codex 直接起不来。如果你的环境里已经挂了别的 MCP 工具，先停用或卸载，再装 superpowers。
- 配置文件会被修改。
npx superpowers install会往 Codex 的配置文件里追加内容，如果你对这个文件有自定义设置，建议先备份一份。我是用cp备份了原始的配置文件，后来回滚时才没有手忙脚乱。 - 版本更新很快。这项目迭代非常勤，两天不更新可能就有新技能包。我习惯每周跑一次
npm update -g @superpowers/core，不然某个技能包可能因为版本差异而无法触发。
安装完成只是一个开始。接下来真正重要的，是理解并利用好它的技能包组合，这才是 superpowers 的精华所在。
3. 核心技能包解析：每个“超能力”到底怎么用
3.1 技能包全景表
superpowers 在初始化之后，会自带一批常用的技能包。我把至今为止实测过的核心技能包整理成一个表格，方便你对照着理解：
| 技能包名称 | 核心动作 | 使用场景 | 触发方式 |
|---|---|---|---|
| run-tests | 自动识别项目测试框架并执行测试 | 改完代码后验证是否破坏已有功能 | 在对话中直接说“运行测试” |
| create-tests | 为指定函数或模块生成测试用例 | 新写了一个函数，懒得手动补测试 | 说“给 xxx 写测试” |
| subagent | 生成并派发子代理处理独立任务 | 同时改多个模块、并行做代码审查 | 说“派一个子代理处理 xxx” |
| review-changes | 对当前 git diff 做走读审查 | 提交前自查、发现潜在问题 | 说“审查我当前的改动” |
| file-commands | 批量执行文件级读写、搜索、替换 | 跨文件重构、批量修改配置 | 正常情况下直接交给模型调度 |
| memory | 记录和读取跨会话的项目知识 | 记住项目的技术栈、编码约定 | 说“记住这个项目的约定” |
这几个技能包是内置的，装完就有。但我后来也学会了加自定义技能包，这在后面第 4 章会展开讲。
3.2 run-tests：从“报告结果”到“主动执行”的跨越
在我眼里，run-tests是 superpowers 最实用的一个技能。没有它之前，Codex 改成一段代码后，只会告诉你“应该没问题”，然后就没了。有了它之后，Codex 会自己在项目目录里找到测试运行器，把测试跑起来，再把 stdout、stderr 读回来，根据输出决定下一步是修代码还是继续。
实测中我发现，它对主流框架的识别相当准确：JavaScript/TypeScript 项目会自动用npm test或yarn test，Python 项目会自动用pytest，Java 项目会自动识别mvn test或gradle test。不过有一点要提醒：如果你的项目根目录有多个测试框架并存，它可能会选错。比如一个前端项目同时有 Jest 和 Vitest 的配置，它默认可能跑的是 Jest。解决办法是，在项目级的配置文件里显式指定测试命令。
做法很简单，在项目根目录的.superpowers/config.json里写明：
{ "testCommand": "npx vitest run" }这样一来，后面的所有run-tests调用都会用这个命令，不会再出现“跑错框架”的尴尬。
3.3 subagent：把大任务切成并行的小任务
subagent是我个人最喜欢的技能，它解决的是 AI 编码的“单线程”问题。
默认情况下，Codex CLI 是线性工作的，改一个文件就改一个文件，不会并行。但实际项目里，你经常需要同时改好几个独立的点——比如重构 A 模块的同时，另一个完全不相关的 B 模块也要换函数名。用 subagent，你可以让 Codex 派一个“分身”去改 B 模块，主线程继续处理 A 模块。
具体用法是直接说“派一个子代理去处理 xxx”，Codex 会弹出一个子任务面板，然后自己分配范围、执行、汇报结果，效率提升非常明显。我在一个 5 万行左右的中型项目上实测过，两个互相不依赖的功能修改并行执行，整体耗时只有串行时的 60% 左右。不过要注意，子代理之间不能共享内存上下文，所以你分派任务时必须把“该做什么、边界在哪里、交付到哪个路径”说清楚，不然子代理会在一些细节上自嗨，产出的代码风格和你主线不一致。
3.4 review-changes：提交之前的“AI 走读”
review-changes相当于给代码合并之前加了一道自动把关。以前我提交代码前，总要自己重新看一遍 diff，或者让同事花时间 review。现在我习惯让 superpowers 先做一轮走读。
它做的事情包括：读取当前分支的 git diff、检查每个改动点是否有明显问题（比如空指针风险、资源未释放、SQL 注入风险）、看看测试是否覆盖到改动、最后输出一份 walkthrough。这套流程之后，我把交给真实同事 review 的代码质量提高了一个档次，很多低级问题在 AI 走读阶段就被拦下来了。
但我也要泼一盆冷水：review-changes不代表真实评审，它没有领域知识，更像是一道语法级、模式级的检查。有些业务逻辑层面的问题，它根本发现不了。所以它的定位应该是“提交前最后一道自动化防线”，而不是替代人。
3.5 memory：让 AI 记住项目的“上下文”
还有一个容易被忽视的技能是memory。它的作用是跨会话保存项目级知识。比如你在项目里约定“所有 API 返回格式统一为{ code, data, msg }”，或者“后端不能用 Lombok”，这些约定如果每次都写进提示词里，既啰嗦又容易漏。有了 memory 技能，你只需要说“记住这个项目的 API 返回约定”，它就会写入.superpowers/memory.md，以后每个新会话它都会自动读一遍。
这个技能我目前天天用。说实话，我觉得它比我见过的大部分 AI 编程辅助记忆功能做得好，因为它是项目级的，而不是全局级的——不会把一个电商项目的约定带到另一个工具项目里去。
4. 实操过程：在一个真实项目里用 superpowers 干活
4.1 我选的实验项目
为了验证表单收集齐全的应用场景，我专门挑了一个 Java 支付模块的示例项目来做测试。这个模块是朋友公司里的一个结算服务，代码量不算大，但涉及面很广：数据库事务、对外 API、异步任务、参数校验，前后端分离，用 Maven 构建，测试框架是 JUnit 5 + Mockito。
在这个项目上，我的目标是完成一个需求：把原有的支付回调接口从“同步处理”改成“先落库再异步处理”，同时保证所有原有测试通过。放在以前，这种改动我自己写也要大半天，而且还要提心吊胆地怕改坏回调逻辑。
4.2 用 superpowers 跑起来的完整工作流
先是在项目目录里启动 Codex CLI，并加载 superpowers 配置。我第一句话是：
用 superpowers 先跑一遍现有的测试，看看基线是否通过。Codex 先是识别出了 Maven 项目，然后自己执行了mvn test。跑完的结果是 47 个测试通过、2 个失败。这个基线很重要，因为后面任何改动都得保证不能把 47 个绿的全弄红了。
基线确认后，我要求它分析回调接口的现有实现并给出改造方案，并明确要求“先把方案列出来，不要马上改代码”。Codex 通过file-commands技能读取了控制层、服务层和数据层的文件，整理出了改造步骤。这一步的意义在于：如果直接让 AI 动手改，它经常会改一步看一步，最后改出一个自己都说不清的大杂烩。先有方案再动手，可控性高很多。
确认方案后，我让 Codex 开始改造，并加上一句“改完立刻跑测试，确认 47 个原有测试通过”。
实际的执行过程是：它先改了 3 个类，引入了一个@Async注解和消息队列，然后自动触发mvn test，第一次跑挂了 5 个测试。它自己回读日志后发现，问题出在测试环境里没有初始化 MQ 连接，然后它去改了测试配置，加了 Mock 对象，第二次跑全绿。整个过程没有我介入一行代码。
4.3 让子代理并行处理“独立小任务”
在这个项目里，我还用subagent处理了一个独立任务：把项目中所有硬编码的微信支付证书路径改成配置项读取。这个改动与其他回调逻辑完全无关，非常适合扔给子代理去做。
我直接说“派一个子代理去把所有硬编码的证书路径改成从 application.yml 读取”，它生成子任务后，自己列了一个需要改动的文件清单，逐文件修改，并在最后汇报：“改了 6 个文件，其中 2 个文件涉及常量引用，我一并替换了”。
之后我检查了它的产出，代码风格基本和主线程一致，只是因为项目里没有对应的测试，它只做了静态检查，没有跑真实验证。这也是 subagent 的局限——它不会主动去补测试。如果你需要子代理改完后补测，必须明确要求。
4.4 本地调试时的一些实际细节
在这个实操过程中，有几个细节值得你留意：
- Codex 执行
mvn test时会阻塞交互。如果你不想盯着终端，可以加一个超时限制，或者在提示词里要求它“测试结果直接总结，不需要输出全部日志”。不然满屏 JUnit 输出会冲掉上下文窗口。 - 测试失败时的日志是它的主要判断依据。我发现很多时候 Codex 修复 bug 不是靠“看懂代码”，而是靠读懂测试日志里的堆栈。所以在提示词里要求“跑完测试后，先分析失败原因再改代码”，比让它直接盲改有效得多。
- 改完以后记得让它跑一遍
review-changes。实际用下来，这一步能抓出不少问题。比如那次改造里，我就是靠 review-changes 发现了异常处理里漏掉了一个对事务回滚的判断。
整个需求从开始到全绿，总共花了一个半小时，其中很大时间是我在“看它干活”而不是“替它干活”。如果我把提示词写得更好一点，时间可以压缩到 40 分钟以内。
5. Java 场景落地：把 superpowers 用在 Java 项目上的特殊配置
5.1 Java 项目为什么需要额外照顾
在搜索热词里能看到“superpowers java”，说明不少人关心 Java 场景。我必须说，Java 项目和其他动态类型语言项目不太一样，它对构建工具和测试框架的依赖很重，而且编译慢、测试慢，一个不合适的配置就可能导致 AI 反复瞎试。
我在 Java 项目上使用 superpowers 的结论是：必须先解决两件事——测试命令的稳定性和构建缓存。否则 Codex 每次跑测试都会从头编译，既慢又容易因为消息太长超出上下文窗口。
5.2 Maven 项目的推荐配置
如果你用的是 Maven，我建议在项目根目录建.superpowers/config.json，内容如下：
{ "testCommand": "mvn test -q -DskipTests=false", "buildCommand": "mvn compile -q", "repoType": "java-maven", "testTimeoutSeconds": 600 }解释一下这几个配置参数的意义：
-q参数让 Maven 只输出错误和关键信息，减少日志淹没 AI 上下文的概率。testTimeoutSeconds设置测试超时时间，因为 Java 编译本来就慢，默认值如果是 60 秒，大型项目很容易误触发超时。
我用这套配置实测下来，跑一个 200 多测试类的项目，总耗时要 3 分钟左右，但至少不会再因为日志太长导致 Codex 半路断片。
5.3 JUnit 5 和 Spring Boot 测试的适配技巧
如果你是 Spring Boot 项目，还有一个隐性问题：测试启动非常慢，而且会因为上下文加载失败而出现假失败。superpowers 内置的 run-tests 技能不一定会自动识别这种场景，它可能跑出一个失败测试，然后按常规修复逻辑去改源码，结果越改越乱。
我的处理方式是在提示词层面做约束。实际使用中我固定用这样一段“开场白”：
这个项目是 Spring Boot + JUnit 5 项目。测试如果出现启动失败，先查测试配置和 @SpringBootTest 注解，不要直接改业务代码。这句话非常管用。它把 AI 的修复方向限定在测试上下文层，避免它去动核心业务代码。我在实际项目里观察到的现象是，有一次测试报错是因为某个测试类没有加@ActiveProfiles("test")，如果不对 AI 加约束，它很有可能会去改 Service 层的逻辑来“适配”测试。
另外，对于使用 Testcontainers 的项目，需要注意一点：superpowers 的 run-tests 会直接调用 Maven，而 Testcontainers 需要 Docker 环境。如果 Docker 没启动，测试就会全部失败。这种情况下，我在配置里干脆指定只跑非容器测试类，或要求 AI 先检查 Docker 是否可用，避免白跑一轮。
5.4 Java 项目的代码风格约束
Java 项目普遍有编码规范，比如 Google Java Style、内部规范等。superpowers 的 memory 技能在这里能发挥很大作用。我可以直接把项目的编码规范写进.superpowers/memory.md，比如：
- 项目统一使用 Lombok，禁止手写 getter/setter - 事务注解必须写在实现类上，不能写在接口上 - 所有对外接口返回值使用统一 Result 包装类之后 Codex 每次在这个目录里启动，都会自动读这个记忆文件，行为会非常“懂规矩”。我在多个项目里验证过，加了规范约束后，AI 生成的代码风格明显更贴合项目，不太会出现“一看就是 AI 写的”那种四不像代码。
5.5 给 Gradle 用户的一个提醒
如果你是 Gradle 项目，配置大致相同，把命令换成：
{ "testCommand": "gradle test --console=plain -q" }但 Gradle 默认的守护进程有时会导致 AI 跑测试时日志不同步，我建议加上--no-daemon参数，或者设置环境变量GRADLE_OPTS让日志实时输出。这个坑我踩过一次，AI 对着空日志愣了半天，最后我手动跑了一遍才发现测试结果早出来了，只是守护进程没有及时刷新。
6. 常见问题与排查技巧实录
6.1 我实测遇到的典型报错与解法
这几周使用下来，我把我自己遇到过的、以及社区里高频出现的问题整理成了一张速查表：
| 问题现象 | 可能原因 | 解决办法 |
|---|---|---|
superpowers: command not found | npm 全局目录不在 PATH 中 | 把 npm 全局 bin 目录加入.zshrc，重开终端 |
| Codex 说没有可用工具 | superpowers 未成功安装到 Codex 配置 | 重新执行npx superpowers install，或手动检查 Codex 配置文件 |
跑测试时报ERR_REQUIRE_ESM | Node.js 版本过旧 | 升级 Node.js 到 18+，我实测 20 最稳 |
| 子代理不执行任务，只返回“已了解” | 子代理上下文被清空或边界描述不清 | 重写子任务指令，明确输入路径、输出路径、交付物 |
| Maven 测试一直失败但本地手动跑通过 | 测试环境差异（如 Docker 未启动） | 检查 Docker、检查 profile 配置，必要时在 config 里跳过容器测试 |
| 测试日志过长冲掉上下文窗口 | Maven 输出太多 | 加-q参数，或限制testTimeoutSeconds |
| superpowers 版本更新后技能包丢失 | 更新没有同步重新安装到 Codex | 重新执行npx superpowers install |
每一行我都实际碰到过，不是网上抄来的。特别是“子代理不执行任务”这个问题，在初期几乎每次都会出现。你需要把子代理当成一个刚入职的实习生来交代任务，边界越清楚，它干得越利索。
6.2 一个必然要处理的坑：测试永远在“最后一步”失败
还有一个非常典型的场景：Codex 改完代码，跑测试，前面几十个测试都过了，最后一个失败，它修一下，结果前面又有一个失败，就像打地鼠。整个过程极其耗时，而且会消耗大量上下文窗口，最终 AI 越来越“笨”。
我的解决办法是，在提示词里明确要求它“先跑一次完整测试拿到所有失败列表，再分类处理，不要逐个修复”。这个提示词效果立竿见影。因为 Codex 默认倾向于“失败一个修一个”，这种模式在多个测试文件同时失败时会迅速失控。一次性拿到失败列表，它自己就能判断哪些失败是同一根因，处理起来效率高很多。
6.3 关于 worbuddy 的疑问
热搜里还有“worbuddy 怎么用 superpowers”，我猜你可能是看到某个开发者分享了 worbuddy 与 superpowers 搭配的用法。从我目前了解到的信息看，worbuddy 是另一个社区里讨论度逐渐上升的 AI 编程工具或插件，它和 superpowers 的配合方式，本质上和其他 AI 编程工具配合 superpowers 一样：把 superpowers 作为一组外部技能，让主 AI 调用。不过这个项目目前改版和变动非常快，我建议你直接看官方仓库的 README，那里有最新的集成命令和方法。
千万别去信那种“下载一个整合包一键搞定”的教程，工具类项目更新太快，一周前的整合包很可能已经失效。我自己吃过亏，下载过一个宣称“全家桶”的包，结果里面预置了几个明显过时的技能配置，跑起来反而出问题。老老实实用官方命令安装，是最稳的。
6.4 几个我认为非常重要的“独家”心得
在使用 superpowers 一段时间之后，有一些体会是文档里不太会写的，我在这分享几个：
- 提示词里直接点名“用 superpowers”有效吗？有效，但看情况。如果你只是说“跑一下测试”，Codex 可能会自己用终端命令解决，不一定会调用 superpowers 的 run-tests。但如果你说“用 superpowers 的 run-tests 跑测试”，它会强制走技能包，行为更可预测。在需要它自动连环操作（跑测试→改代码→再跑测试）的复杂场景下，明确指定技能包能减少很多不确定性。
- 配置文件的优先级是项目级 > 用户级 > 全局。我之前在全局层配了一个 testCommand，后来某项目需要不同命令，发现项目级配置总是覆盖全局，这个设计很合理。
- 不要一次塞太多任务给一个会话。superpowers 确实是给 Codex 加了不少能力，但上下文的窗口始终有限。一次会话聚焦一个目标，做完就开新会话，配合 memory 技能保留关键信息，体验会好很多。强行让它在一个会话里做三四个大任务，到后面的质量断崖式下跌。
- 要学会看日志，而不是只会等结果。用 superpowers 干活时，AI 执行工具的过程日志都留在终端里。我以前习惯只等最终结果，后来发现很多时候问题根因就在中间日志里。养成扫日志的习惯，排查和介入的速度会快很多。
我个人现在的工作方式，已经离不开这套工具了。不是因为它神秘，而是因为它把一个“只会聊天的 AI”变成了一个“真的在干活的 AI”。用过超级英雄的比喻容易被当成中二病，但在这个场景下，我觉得这个命名确实贴切——它就是给 AI 装上了原本缺失的那几块能力拼图。如果你也在用 Codex CLI，并且对目前的“应用深度”不满意，我建议你花一个下午时间把这套东西装好、跑通，然后在你的真实项目里试一次。等它第一次自动跑完全部测试并给你一个全绿的汇报时，你会回来感谢自己的。
