superpowers插件实测：让Codex CLI从回答机器变为结对工程师

最近一直在折腾 Codex CLI，确实好用，但用久了就发现一个问题——它更像一个“回答机器”，而不是“结对工程师”。你问一句它答一句，复杂任务经常做着做着就跑偏，改起代码来也没什么章法。后来我在 GitHub 上翻到superpowers这个插件项目，装上之后整个体验完全不一样了。

简单说，superpowers是一套给 Codex CLI 开挂的技能增强插件。它不是帮你写某一段代码，而是给 Codex 装上了一整套“工作方法论”：接到任务先规划、动手前先思考、出错时系统化排查、重构前先铺测试。装上它之后，Codex 从一个“你推一步它走一步”的工具，变成了一个会拆任务、会列计划、会自我检查的结对工程师。

这篇东西就把我这几周的实操经验完整写出来：它到底是什么、怎么装、核心技能怎么用、真实项目里怎么落地，以及我踩过的那些坑。适合所有在用 Codex CLI 但觉得它“不够聪明”的人，也适合刚听说这个插件、想试试但不知道怎么下手的同学。

1. superpowers 是什么：Codex CLI 的“外挂”到底加了什么

1.1 先搞懂 Codex CLI 缺什么

Codex CLI 本身是个很爽的终端 AI 编程工具。你给它一个任务，它能读仓库、改文件、跑命令，GitHub 上热度也很高。但真要拿它做正经项目，痛点非常明显：

• 任务一复杂就失控。你说“帮我优化一下订单模块”，它可能直接上手改逻辑，改到一半你发现方向不对，前面全白干。
• 没有规划意识。它倾向于立刻给答案，而不是先想清楚步骤。哪怕任务需要改 10 个文件，它也会闷头开始，改完一个再想下一个，经常前后矛盾。
• 调试靠瞎试。测试挂了，它就开始猜，改一行跑一次，跑了再猜，效率极低。
• 没有“安全网”概念。重构代码前不会先看看有没有测试兜底，经常把能跑的代码改成不能跑的。

这些问题的根源不是模型能力不够，而是缺少一套“工作流程”。Claude Code 之所以让很多人觉得好用，就是因为有 Skills 机制，能让模型按预设流程思考。superpowers就是把这个思路搬到了 Codex CLI 上。

1.2 superpowers 补上了什么

superpowers项目来自 GitHub 上的开源仓库，作者是一线开发者，设计思路非常朴素：维护一批 Markdown 格式的“技能文件”，每个技能定义一种工作流，然后用 Codex CLI 的插件机制在合适的时机把这些技能注入到模型的上下文里。

装上之后，Codex 会获得一组新能力，我用下来最核心的是这几个：

它还有个很实用的设计：支持自定义技能。你不满意它自带的工作流，或者有自己团队的规范，可以直接写一个 SKILL.md 放进技能目录，Codex 就能学会你们团队的做事方式。

1.3 适用人群和场景

说实话，不是所有人都需要superpowers。如果你只是拿 Codex 写点脚本、问几个 API 用法，装上它反而会觉得“怎么这么多废话”。但如果你是这几类人，强烈建议试一下：

• 独立开发者，一个人维护一个完整项目，需要 AI 按工程化方式干活。
• 团队里的技术负责人，想让 AI 生成的东西有章法可循，而不是每次都碰运气。
• 在 Java、Go、Python 这类工程化项目里搬砖的。superpowers跟语言无关，Java 项目里照样能用，后面我会拿 Java 场景专门讲一下。
• 所有觉得“AI 写代码像新手水平”的人。问题往往不是模型不会写，而是它没有一套资深工程师的做事流程，superpowers补的正是这个。

2. 安装与初始化：从零到能用的完整配置

2.1 安装前置条件

先把前提条件说清楚，避免你装到一半卡住：

• 你的 Codex CLI 版本不能太旧，建议 0.4x 以上。旧版本对插件的支持不完整，我一开始在 0.3x 版本上装，怎么配都不生效。
• 需要能正常访问 GitHub 并拉取仓库。
• 电脑上要有git，这个一般都有。
• Codex CLI 本身要已经配置好 API Key 并能正常对话，这是地基，地基没打好先别折腾插件。

2.2 三步完成安装

第一步，克隆仓库到 Codex 的插件目录：

git clone https://github.com/obra/superpowers.git ~/.codex/plugins/superpowers

这里要提醒一下：不同版本、不同安装方式下，Codex 的配置目录可能不一样。有的是~/.codex，有的在~/.config/codex。不确定的话，先跑一次codex命令，看它启动日志里打出的配置路径，或者直接查看~/.codex和~/.config/codex哪个存在。

第二步，编辑 Codex 配置文件，声明启用这个插件。用你顺手的方式打开配置：

code ~/.codex/config.toml

在配置里加上：

[plugins] "superpowers" = { path = "plugins/superpowers" }

这一步的作用是告诉 Codex CLI：启动的时候去plugins/superpowers目录下加载插件。注意路径是相对路径，基于你的 Codex 配置目录。这个格式我确定是能用的，但不同 Codex 版本对插件字段的写法确实有差异，最稳妥的办法是直接看superpowers仓库 README 里的最新示例。

第三步，重启 Codex CLI。不是退出当前会话那么简单，我建议把终端进程也关掉重新开，确保配置被重新加载。

2.3 验证安装是否生效

装没装上，最怕的就是“感觉好像行了，但不确定”。我一般用两个方法验证：

方法一，进交互模式，直接问一句“你现在有哪些技能可以调用”。模块正常加载的话，它会列出 plan、think、debug 这些技能。如果答非所问或者说不知道，那就是没加载成功。

方法二，看它的启动日志。Codex CLI 启动时会打印插件加载信息。如果看到类似Loaded plugin: superpowers的记录，就是装好了；如果搜不到任何插件相关日志，基本可以断定配置没被读到。

2.4 配置细节与避坑

在配置这块我踩过几个很典型的坑，写出来给你排雷：

第一个坑是目录名不对。我的插件目录一开始叫superpowers-main，因为直接从 GitHub 下载 ZIP 解压后目录名带了-main。Codex 加载插件是按配置里的路径找目录的，目录名不对或者配置里写的路径和实际目录对不上，它就会静默跳过，不报错也不提示。

第二个坑是配置文件格式。TOML 配置对缩进和写法有要求，[plugins]这个表头下面写"superpowers" = { path = "plugins/superpowers" }这种内联表，别拆行写。我见过有人写成：

[plugins.superpowers] path = "plugins/superpowers"

在某些版本里也能行，但不如内联表稳定。建议直接照仓库 README 的写法来。

第三个坑是 hook 时机。superpowers的功能除了注入技能，还有一些依赖“用户发送消息前”这个钩子。如果你是在codex -c这种一次性命令模式下用的，很多钩子是触发不了的。我第一次测试就是在一次性命令模式下试的，结果毫无效果，还以为是没装好，其实这种模式本来就不支持完整功能。

3. 核心技能拆解：plan、think、debug、tdd 到底怎么干活

3.1 plan：先写 PLAN.md 再做事的威力

plan 是我用得最多的技能，也是superpowers最核心的加分项。以前给 Codex 派一个“给订单模块加缓存”的任务，它很可能一头扎进代码里，先改 service 层，再改 dao 层，中途发现方案不对又推翻重来。

用了 plan 之后，它会先问清楚需求，然后在项目里生成一份PLAN.md，把任务拆成具体步骤，每一步做什么、涉及哪些文件、有没有风险都列出来，还会先征得你同意再动手。

我在实际项目里让 Codex 用 plan 处理过一个需求：把登录接口从同步逻辑改成异步登录。它生成的 PLAN.md 大概是这样的结构：

1. 梳理当前登录接口的调用链和依赖
2. 设计异步处理方案，明确消息队列选型和数据格式
3. 拆分核心代码改动点（Controller、Service、消息消费者）
4. 列出需要同步修改的配置和测试用例
5. 按依赖顺序分阶段实施，每阶段结束后跑测试验证

关键作用是：任务还没开始写代码，方向就已经定了。我作为开发者只需要在计划阶段纠偏，后面执行阶段基本不用一直盯着。这个习惯如果养成，AI 产出质量的提升会非常明显。

3.2 think：什么时候该让它停下来想

think 这个技能一开始我嫌它多余。模型思考不是自动的吗？为什么还需要一个技能来触发？

用多了才发现，Codex CLI 在“加速执行”模式下追求一个 token 利用率，很多推理过程被压缩了，遇到需要权衡的方案，它会直接选一个自以为最优的，不做解释。think 的技能文件会把“先思考再输出”这个流程重新注入上下文，让模型显式地列出：

• 已知的信息和不确定的信息
• 可选方案各自的代价
• 推荐哪一种，依据是什么

我举个例子。有次我让它帮忙选一个 Java 项目的本地缓存方案，不触发 think 的时候，它直接说“用 Caffeine 吧”，然后就开始写配置。触发 think 之后，它先分析了 Guava Cache、Caffeine、ConcurrentHashMap 手动管理三种方案，对比了命中率、淘汰策略、内存控制、与 Spring Cache 的集成难度，最后才给了结论。思路完整得多。

那个什么场景该用 think？我觉得是：任务涉及方案选型、改动范围模糊、影响面不确定的时候。它本质上是在逼 AI 先把问题想清楚，而不是当个“答嘴快的工具人”。

3.3 debug：从“乱试”变成“排查”

以前用 Codex 调试代码，最让我头疼的就是它太爱猜了。测试报个错，它能连着瞎改好几次，每次改完看上去有道理，跑起来还是错。

superpowers 的 debug 技能会把它引导成一个标准排查流程：

1. 先要求复现问题，收集完整的报错信息
2. 再阅读相关代码，梳理出可能的失败路径
3. 逐一定位根因，而不是只修表面现象
4. 修复后跑完整测试，确认没有引入新问题

这个流程看起来简单，但被写成技能文件之后，模型执行起来的稳定性完全不同。有一次线上反馈某个 Java 接口偶发超时，以前我可能得自己盯半天，后来直接委托给 Codex 用 debug 流程排查。它先复现了高并发场景下的线程阻塞，再顺着日志定位到连接池配置参数的问题，最终给出修改建议。全程有理有据，而不是东一榔头西一棒子。

3.4 refactor 与 tdd：改代码前的安全网

refactor 和 tdd 这两个技能我放在一起说，因为它们是配套的。重构最怕什么？怕改出隐性 bug，表面测试全绿，线上炸了。superpowers的 refactor 技能会先强调“重构前必须要有测试保护”，如果发现项目里相关模块没有测试，它会先建议补上，或者明确提示风险。

tdd 技能解决的是“AI 写代码不写测试”的老毛病。技能文件里有一套清晰的循环：先写一个会失败的测试，再写最小实现让测试通过，接着在绿灯状态下安全地改进代码。这个过程叫红绿循环。Java 项目里用这个流程特别舒服，配合 JUnit 和 Maven，Codex 能自己跑mvn test验证，全程不用我切窗口。

我自己在 Java 项目里的经验是：只要用了 tdd 流程，AI 写的代码明显更小、更聚焦。因为它必须保证每个步骤都有测试兜底，没有机会去写一堆用不上的“防御性代码”。

4. 实操：用 superpowers 跑通一个 Java 项目的完整过程

4.1 一次真实的 Java 任务：给订单模块加缓存

前面讲了不少理论，拿一个实际任务串一遍最有说服力。我前两周在一个 Spring Boot 项目里加订单列表缓存，就用 superpowers 全程主导，过程记录在下面。

任务背景：订单列表接口查库比较重，每天被调用几十万次，响应时间不稳定，需要引入本地缓存。这个任务涉及 controller、service、配置类、pom 依赖、测试代码多个文件，还需要考虑缓存的过期策略和并发穿透问题。完全适合用 plan 技能先规划。

我直接给 Codex 下了指令：“用 plan 技能处理这个任务：订单列表接口引入本地缓存”。它在交互模式里自动匹配了 plan 技能，先跟我确认了需求，然后生成 PLAN.md，列出的关键步骤包括：

1. 确认订单查询接口的数据特性和调用链路
2. 评估本地缓存与 Redis 缓存的取舍，给出结论
3. 确定缓存 key 设计和过期时间策略
4. 改动依赖、配置、Service 层代码
5. 编写缓存行为测试，验证缓存命中与失效逻辑
6. 压测对比优化前后响应时间

这个计划比我自己平时列的清单还细。我基本没改，直接就让它开工了。

4.2 先写测试再写实现：TDD 流程自然落位

开始动手之后，它没有直接去写缓存实现，而是按 tdd 的思路，先写了几个测试用例：

• 第一次查数据应该从数据库加载并写入缓存
• 同一条件短时间内重复查询，第二次应该直接命中缓存
• 缓存过期后应该自动回源数据库
• 并发场景下缓存未命中时，不能出现重复查库的穿透问题

正是这几个测试用例，把这次任务的质量拉高了一个档次。它写测试的过程中其实也在逼自己确认行为细节，比如缓存 key 到底包含哪些查询参数、过期时间到底设多少，这些如果直接写实现，很可能被我忽略。

写完失败测试，它才开始写具体实现。选型上和我预期一致，选了 Caffeine，理由也很充分：单机本地缓存、需要过期淘汰策略、不想引入额外的外部依赖。实现过程中它反复跑mvn test，每跑一次确认一次进度，我在旁边看着，整个过程非常踏实。

4.3 中途杀出个并发问题：debug 技能的实战价值

本来以为顺风顺水，结果测试跑到并发穿透用例的时候挂了。挂了其实是好事，说明测试真的在起作用。Codex 自动进入了 debug 流程，先把报错信息完整贴出来，然后开始定位：

它先查了 Caffeine 在默认配置下对并发加载的处理机制，发现如果加载逻辑里用了get(key, Function)，Caffeine 自身有原子加载能力，按理说不会穿透。但项目里我之前对缓存做了多层封装，外层有一道“查询结果为空就不写缓存”的判断，这个判断在并发场景下会拆散 Caffeine 的原子操作，导致多个线程同时回源。

定位到根因之后，它给出的修复方案是：调整缓存封装结构，让 Caffeine 的原子加载逻辑直接管理回源动作，空结果用特殊标记缓存，避免外层判断打散原子性。改完再跑测试，全绿。整个排查过程有逻辑链条，有根因结论，不是瞎试，这正是 debug 技能的价值所在。

4.4 Java 场景下的使用体验总结

这个任务跑完，我的感受非常直接：以前让 AI 独立完成一个 Java 功能改造，基本不敢放手，现在敢了，因为它会先规划、先写测试、出问题会系统排查。

Java 项目给 AI 带来的额外挑战是“结构复杂、依赖多、编译慢”，而 superpowers 的工作流恰好逼着它每一步都做验证，反而弥补了 Java 项目不适合盲目试错的特性。

还有个细节值得提：Java 项目编译一次要几秒到几十秒，Codex 每改一点就主动跑测试，如果流程不顺，这个成本其实很高。但因为有 plan 把关方向、tdd 保持改动最小化，实际上反而减少了无效编译次数。

5. 常见问题与排查技巧实录

5.1 技能完全不生效，Codex 像没装插件一样

这是最多人遇到的问题。排查方向按顺序来：

• 先确认插件目录位置对不对。我前面说过，ZIP 解压的目录名经常是superpowers-main，跟配置里的路径不一致。
• 再确认 config.toml 是否真的被 Codex 读取。可以在配置里故意写一个错误参数，如果启动时没有报错，说明这个配置文件根本不是它在读的那份。
• 接着确认是否在交互模式下测试。一次性命令模式下技能和钩子大概率不触发。
• 最后检查 Codex 版本。版本太老的话，对插件的解析逻辑不完整。

把这四步走完，90% 的问题能定位到，剩下 10% 基本是配置格式差异，直接去仓库看最新的 README 对照一遍。

5.2 技能触发了，但执行到一半偏离流程

有时候你会看到它“意识到”自己在用某个技能，但执行着执行着又退化成自由发挥模式。我遇到好几次，比如它在 debug 的中途突然跳过了回归测试，直接跟我说“修复完成”。

这个问题多半出在上下文长度和模型能力上。如果上下文太长，早期注入的技能指令会被挤到注意力窗口边缘，模型逐渐“忘记”自己应该按什么流程走。解决办法有几个：

• 把任务拆小，不要在一个会话里同时让它做多件事
• 发现偏离就立刻打断，提醒它“按照你正在使用的 xx 技能流程继续”
• 如果你是本地部署或者可切换模型，换一个推理能力更强的模型，执行技能文件的稳定度会明显提升

5.3 改动文件前的前置确认防护

AI 改文件有时候是真果断，不打招呼就把你代码改了。superpowers 的 plan 技能会先写计划再动手，但它也只能约束自己的流程，管不住你误操作。

我的习惯是，重要项目先确认 Git 状态是干净的，任何大改动之前先让 Codex 明确列出要改动的文件清单，我确认一遍再让它继续。如果项目没有纳入 Git 版本管理，强烈不建议让 AI 直接操作。这不是 superpowers 的问题，而是所有 AI 编程工具都适用的一条红线：没有版本控制兜底，不要放权给 AI。

5.4 关于“worbuddy 怎么用 superpowers”这类问题

最近经常看到类似“某某工具怎么用 superpowers”的问题，特别是那个看起来很像是拼写错误的词。统一说下我的理解：凡是能调用 Codex CLI 的封装工具、脚本、自动化流程，只要最终是通过 Codex CLI 本身的插件机制来加载技能的，理论上都能吃到 superpowers 的增强。但如果那个工具是自己重新实现了一遍提示词拼接，不走 Codex 的插件钩子，那 superpowers 就管不到它。

判断方法很简单：看那个工具加载的是 Codex 的config.toml和插件目录，还是它自己的一套东西。走前者就兼容，走后者就是两回事。

5.5 其他小坑经验

最后整理几个容易被人忽略的细节：

第一，升级 superpowers 的方式就是去插件目录下拉最新代码，git pull就行。但升级后旧会话里的技能定义可能不会刷新，建议重启 Codex。

第二，自定义技能别乱放目录。它扫描的是固定的技能目录，不是整个仓库随便塞个 SKILL.md 就能认。具体路径看 README，放错了既不报错也不加载，特别容易让人困惑。

第三，如果你用国内网络访问 GitHub 慢，先把代理环境配好再拉仓库。这个不用多解释，懂的自然懂，但确实会影响安装体验。

6. 一些真实的使用体会收尾

用superpowers这几周，最大的感受不是“它能写更多代码”，而是“它让我敢把更大的任务交给它了”。以前让 Codex 独立改一个跨多个文件的功能，我心里没底，总想盯着每一步；现在它先出计划、再写测试、出问题按流程排查，我只需要在关键节点确认方向，这种体验上的提升是质变的。

我最推荐的方式是别一次性把所有技能都用上。刚上手的时候，先用 plan 就够了，等熟悉了它的执行节奏，再慢慢把 tdd、debug、refactor 引入日常流程。技能文件本身是死的，核心是它帮你建立起来的工作习惯，这个习惯一旦形成，你换任何 AI 工具都会觉得受用。

如果你已经在用 Codex CLI 写正经项目，装一个试试不会吃亏；如果你还在犹豫用不用 Codex，那建议先从 Codex 本身开始，等体会到了“回答机器”和“结对工程师”的差距，再来装这个插件，收获感会更强。