从第一次在终端里敲下codex那个命令开始，我就知道这玩意儿不一般。不是说它能写代码就完了，而是它那种“你给它一个任务，它自己拆解、自己跑命令、自己改文件”的自动化程度，确实让人上头。但用了一阵子之后，问题也来了：默认的 Codex CLI 更像一个“聪明的单兵”，你让它做个复杂点的任务，它容易陷进细节里，或者做到一半忘了全局目标。直到我碰上 superpowers，这个局面才彻底改观。

superpowers 不是什么玄学插件，它是一套给 Codex CLI 加 buff 的增强层。你可以把它理解成给 Codex 装了一整套“军规级”的工作流：子代理协作、技能包、状态管理、自动任务分解，全都给你安排上。装上之后，Codex 不再是一个只会“干活”的助手，而是一个能“带领团队干活”的指挥官。这篇文章就围绕 superpowers 的安装、核心机制、实操流程和避坑经验展开，把我实际用过之后觉得最有价值的部分全盘托出。如果你正在用 Codex CLI 做自动化开发，或者刚想入坑 AI 编程助手，这篇应该能帮你少走不少弯路。

1. 内容整体设计与思路拆解

1.1 Codex CLI 的短板在哪里

先捋清楚为什么需要 superpowers。默认的 Codex CLI 最强的地方是“把自然语言变成代码改动”，但它有几个根深蒂固的问题。

第一个问题是“没有长线记忆”。Codex 在每次对话里能记住上下文，但一旦任务跨了多个步骤、多个文件、甚至多次会话，它就会开始“丢三落四”。比如你让它先分析项目结构，再设计一个重构方案，最后分步执行，它经常会在执行阶段忘了之前分析出的约束条件。你不得不反复提醒它“刚才不是说了吗”，非常消耗耐心。

第二个问题是“单线程执行”。Codex 默认是一次性处理一个任务链。它虽然能调用工具，但本质上是在一条路上走到底。遇到需要并行探索多个方案、对比实验结果、或者同时监控多个子任务的时候，它就显得力不从心。比如你要重构一个老系统，既需要梳理业务逻辑，又需要评估数据库变更，还要考虑前端接口兼容，这活儿让单个 Codex 去干，它只能按顺序来，非常慢，而且容易顾此失彼。

第三个问题是“没有可复用的行为模式”。每次你让 Codex 做“给函数加日志”这种重复性工作，它都得重新理解一遍需求。你没法定义一个“技能”，告诉它以后所有类似任务都按这套流程走。结果就是每次都要啰嗦半天，而且不同次对话里的代码风格、处理方式都可能不一致。

这三个短板恰好就是 superpowers 的切入点。它做的事情其实很纯粹：在 Codex 之上加了一层“组织管理层”，让 Codex 具备子代理调度、技能复用、任务状态跟踪的能力。用管理学的类比讲，Codex 是大厂里一个超强的一线工程师，但缺一个项目管理者；superpowers 就是把这个管理者空降下来，还给这个工程师配了一整套公司行政流程。

1.2 superpowers 的核心设计理念：让 AI 自己管理自己

superpowers 的设计思路并不是“重新造一个 Codex”，而是“给 Codex 配上管理框架”。它最核心的概念有三个：子代理（subagents）、技能（skills）、状态管理（state）。

先说子代理。superpowers 允许你创建多个“角色化”的 Codex 实例，每个实例都有自己独立的系统提示词、工具权限和工作目标。你可以创建一个“代码审查员代理”，专门负责检查代码质量；再创建一个“测试代理”，专门负责跑测试和修测试用例。主 Codex（或者说主代理）负责调度这些子代理，像项目经理一样把任务派给不同的人，然后汇总结果。这个机制解决了单线程问题，因为不同子代理可以在逻辑上并行思考和处理不同环节，虽然底层都是同一个模型，但上下文被隔离了，不会互相污染。

再说技能。技能是一段结构化的指令包，包含触发条件、执行步骤、输出格式、注意事项等。你可以把任何一套“最佳实践”固化成技能。举个例子，我给团队定义过一个“Java 接口安全审查”技能：它包含检查认证注解、校验参数、控制返字段、记录审计日志这几个步骤。只要我在任务里提到“走一遍接口安全审查”，Codex 就会自动加载这个技能，严格按照里面的流程执行。这个设计直接把“反复教 AI 怎么做”变成了“一次性定义，永久复用”。

最后是状态管理。superpowers 会维护一个任务状态文件，记录当前任务的进度、已完成事项、待办事项、决策记录、约束条件等。这样即使任务跨了多次会话，Codex 也能通过读取状态文件快速恢复“记忆”，不会出现上下文丢失的问题。这个设计很聪明，它把 AI 的“短期记忆”转成了磁盘上的“长期记忆”，相当于给 AI 装了个外挂硬盘。

1.3 对比原生 Codex：superpowers 到底改进了什么

我用一个表格直接说清楚差异，这样更直观。

看完这个表你就明白，superpowers 不是让 Codex 变得“更聪明”，而是让 Codex 变得“更有组织、更可靠”。它把一个“单兵”变成了“一支有作战体系的部队”。这套思路我认为是当下 AI 编程工具演进的一个正确方向：与其追求更大的模型、更长的上下文，不如先把工程化的工作流做好。

2. 核心细节解析与实操要点

2.1 superpowers 安装前的环境准备

在真正动手安装之前，先把环境理清楚。我实测过的组合是 macOS + Node.js 18+ + Codex CLI 最新版，这套组合最稳。Windows 上跑也没有本质问题，但建议用 WSL2，因为涉及一些 shell 脚本和文件权限操作时，原生 Windows 的命令行环境偶尔会有怪癖。

先确认几个前提：

• 你已经装好了codexCLI，并且能在终端里正常运行。如果还没装，直接去 OpenAI 官方仓库找安装方式就行，这里不展开。
• Node.js 版本别太老。superpowers 有一些依赖需要 Node 18 以上的特性，如果你还在用 16，后面大概率会报错。
• 最好有一个单独的目录来存放 superpowers 的配置和技能文件。我建议是~/.superpowers，这样干净，也方便备份迁移。

安装前我用一个简单的命令列表检查环境：

node -v npm -v codex --version which codex

如果codex命令能正常输出版本号，那就说明你的环境基本没问题。这里要注意一个坑：superpowers 本身不是 npm 包，它是一套需要“注入”到 Codex 配置里的脚本和配置文件。所以安装过程并不是npm install superpowers那种一键搞定，而是需要你把它的文件拉下来，然后改 Codex 的配置文件，让它能加载到 superpowers 的初始化逻辑。

有人说这个过程很繁琐，其实理解了原理就不难。Codex CLI 支持自定义的AGENTS.md文件和一些初始化的提示词配置，superpowers 就是利用了这些扩展点，把自己的“管理层”指令注入进去。所以整个安装的本质，就是“下载文件 + 修改配置 + 验证加载”。

2.2 一步一步安装 superpowers（实操版）

下面给出我实际走通的完整流程，你照着一步步来就行。

第一步，拉取 superpowers 仓库代码。我习惯用浅克隆，只拿最新版：

git clone --depth=1 https://github.com/your-org/superpowers.git ~/.superpowers

注意这里我给的是一个示例地址，实际仓库地址要以你找到的为准。如果你网络环境访问 GitHub 慢，可以考虑通过镜像或者加速方式，但这里不多说，安全合规第一。

第二步，进入目录，运行安装脚本：

cd ~/.superpowers npm install npm run setup

setup脚本会自动探测你的 Codex 配置文件位置，并把 superpowers 的加载入口写入进去。如果你的 Codex 配置文件不在默认位置，脚本会提示你手动指定，不用慌，按提示操作即可。

第三步，验证安装结果。运行：

codex --version codex

进入 Codex 交互界面后，你可以先问它一句“loaded skills?”，如果 superpowers 生效了，它应该会列出已经加载的技能列表或初始化提示词。我第一次测试时就是因为配置文件路径写错，导致 Codex 完全没有加载到 superpowers 的核心提示词，结果问了半天它都一脸懵，后来检查了配置文件才发现问题。所以这一步验证非常关键，不要跳过。

另一个验证方式是直接查看你的 Codex 配置文件，确认里面多了类似superpowers-init这样的条目。如果看到，说明安装脚本已经改好了。

2.3 理解核心配置文件的作用

superpowers 的配置体系其实相当克制，它没有把全世界都塞到 Codex 的提示词里，而是分了三层：

第一层是全局初始化提示词。这层内容会在每次启动 Codex 时被加载，相当于“公司规章制度”，告诉 Codex 整个工作流的基本规则：哪些事情必须先建状态文件，哪些操作需要经过子代理确认，如何拆分任务等。这层提示词写得非常精炼，因为它要占用的上下文窗口，如果太啰嗦，反而会挤占实际任务的思考空间。

第二层是技能定义文件。每个技能都有一个独立目录，里面包含SKILL.md（或者类似命名的文件），用 Markdown 或 YAML 格式描述技能的触发条件、步骤、约束。这些技能文件不是一次性全部加载的，而是按需加载。也就是说，只有当任务里触发了某个技能的关键词，Codex 才会去读取对应的技能文件，这样能极大节省上下文。

第三层是工作区状态文件。暖知识：superpowers 很强调“每个任务都应该有一个状态文件”，这个文件存在于当前项目目录的.superpowers/下，记录了任务的目标、进度、决策、风险。当 Codex 中途被打断，下一次重新运行时，它会被引导去读取这个文件，从而快速恢复“记忆”。我在实际使用中发现，这个机制对复杂任务太重要了，等于给了 AI 一个“项目笔记本”。

理解了这三层结构，你就知道 superpowers 为什么能做到和原生的“死记硬背”不一样：它的记忆是有层级的，全局规则只占很少空间，技能按需加载，状态落盘持久化。这种设计比把所有东西都堆在系统提示词里高明得多。

2.4 技能文件怎么写：一个 Java 项目里的实际案例

我拿自己实际用过的一个技能来举例：给团队定制的“Java 代码提交前检查”技能。技能文件名是pre-commit-java/SKILL.md，内容大致如下：

--- name: pre-commit-java description: Java 代码提交前的自动化检查流程 triggers: - commit - 提交 - pre-commit --- # Java 提交前检查技能 执行以下步骤： 1. 运行 `mvn test`，确保所有单元测试通过。 2. 运行 `mvn compile -Xlint:all`，检查编译警告。 3. 检查 git diff，确认没有遗留的调试输出、TODO 标记、硬编码敏感信息。 4. 验证新增代码符合项目现有的格式化规范（参考 `.editorconfig` 和 `pom.xml` 中的代码风格配置）。 5. 如果以上任何一步失败，输出具体错误信息，并给出修复建议，不要尝试自动修复，先等待主代理确认。 输出格式： - 每步结果用 PASS / FAIL / SKIP 标注。 - 最终给出一个总体结论：可以提交、需要修复后提交、不建议提交。

这段技能文件写得很简洁，但它定义了非常清晰的行为边界。关键是第 5 步的约束：“不要尝试自动修复，先等待主代理确认”。这个约束太重要了，不然 Codex 会在检查到问题后自作主张地改代码，结果改坏了你还不知道。

定义技能文件之后，你只需要在对话里说“对这个改动跑一遍 pre-commit 检查”，superpowers 就会命中触发词，自动加载这个技能，然后严格按流程走。实测下来，执行稳定度远比在对话里临时说一次要高得多，因为技能里的流程是固定的，不会因为模型这次状态不好就漏掉某个步骤。

3. 实操过程与核心环节实现

3.1 实战场景：用 superpowers 重构一个 Java 老项目

理论讲再多，不跑一遍等于零。我当时接手了一个老 Java 项目，遗留问题不少：一个 Service 类写了 3000 多行，各种静态方法满天飞，单元测试覆盖率不到 20%。老板要求把它拆分成几个模块，并且把关键的订单流程补上测试。这个任务如果丢给原生 Codex，我感觉它大概率会在重构到一半时被复杂度的洪流冲晕。所以这次我决定用 superpowers 来跑。

整个作战计划分四个阶段：

1. 先用“架构分析代理”梳理项目现状，输出类职责、依赖关系、疑似坏味道清单。
2. 主代理根据分析结果设计拆分方案，并让“代码评审代理”评审这个方案。
3. 评审通过后，主代理调度“重构执行代理”分批次实施代码变动。
4. 每一批次完成后，自动运行“测试代理”执行测试并反馈结果。

听起来很复杂，但实际操作时，你只需要在主对话里对 Codex 说清楚目标，然后让它“用 superpowers 的模式执行任务”，它就会自动按照上述流程调度。下面我拆解一下每个环节的关键点。

3.2 第一步：让“架构分析代理”跑起来

我在项目的根目录启动了 codex，然后输入了这样一段话：

分析当前项目的模块结构和主要类职责，重点关注 OrderService 类的依赖关系和内部方法调用频率。请使用架构分析代理完成任务，并将结果保存到 .superpowers/analysis.md。

superpowers 会识别“架构分析代理”这个角色，然后加载一个对应的子代理提示词。这个子代理会先去读pom.xml了解依赖，然后用grep和find等命令扫描代码结构，再统计 OrderService 里每个方法的调用次数。它不会贸然去改任何代码，因为子代理的提示词里明确限制了“只分析，不修改”。

几分钟后，我拿到了.superpowers/analysis.md，里面结构化地写了 OrderService 的成员变量、公共方法、依赖的其它类、以及圈复杂度排名最高的几个方法。最让我意外的是，它发现OrderService里居然混着库存抵扣的逻辑，这在业务上本应放在另一个服务里。这个发现成了后面重构的一个重要切入点。

这个阶段我学到一个经验：一定要让子代理把结果写成文件，而不是仅仅在对话里输出。因为文件可以被后续的代理重新读取，形成数据传递；对话输出一滚动就找不到了，而且会占用上下文窗口。

3.3 第二步：方案设计与代码评审的协作

分析结果拿到后，主代理需要基于它设计重构方案。我给它下了一个指令：

基于 analysis.md 的内容，设计 OrderService 的拆分方案。要求： 1. 把库存抵扣逻辑抽离成一个独立的 StockService。 2. 保持现有 API 对外不变。 3. 拆分后为每个新类设计简要的接口定义。 方案完成后，先不要动手改代码，让代码评审代理对方案进行审查。

这里就是 superpowers 比较出彩的地方：主代理会把“设计拆分方案”这个任务先在自己手里做，做完之后，它不会立刻开始改代码，而是调用“代码评审代理”去检查这个方案。评审代理会从一致性、可测试性、迁移风险几个角度提出意见。我记得当时评审意见里有一条是：“建议将订单状态的变更逻辑也封装到 OrderStateMachine 中，否则 OrderService 仍然会承担过多的状态流转职责。”这个意见相当专业，单独让主代理自己思考未必能想到这一层。

经过一轮“设计 -> 评审 -> 修改”的循环后，拆分方案最终定了下来。整个过程我没有写一行代码，只是不断用自然语言推动流程，这种感觉有点像项目管理，而不是手写实现。

3.4 第三步：分批次重构执行

方案定了之后，重头戏来了。我让主代理按以下顺序执行：

按照方案，分四个批次执行重构。第一批：创建 StockService 和 OrderStateMachine 的空接口及实现类；第二批：把库存抵扣逻辑从 OrderService 迁移到 StockService；第三批：把订单状态流转逻辑迁移到 OrderStateMachine；第四批：清理原 OrderService 中废弃的代码和不再需要的引入。每完成一批，都要运行 mvn test 确保不破坏现有功能，然后把状态更新到 .superpowers/progress.md。

superpowers 会把这四个批次看成一个多步骤任务，每一步执行前都会先读取progress.md，确认当前状态，然后只处理该批次的内容，处理完后再更新状态。这个过程里，Codex 真正做到了“知道自己在哪一步，接下来该干嘛”。我记得其中第二批执行完成后，测试挂了，原因是库存抵扣迁移后，某个事务边界发生了变化。这时代码评审代理自动介入，检查了改动，发现是缺少了@Transactional注解。它给出了修复建议，主代理根据建议加了注解，再跑测试，直接通过。

这种“主代理指挥、子代理检查、失败自动修复”的协作模式让整个重构过程保持了较高的稳定性。四个批次全部完成后，OrderService从 3000 行降到了 800 行左右，新模块的代码风格和原有代码保持了统一，所有测试通过。

3.4 第四步：状态管理对断点续跑的价值

重构过程中发生了一次断电事故（我电脑没插电源，跑着跑着自动关机了）。重新开机后，我第一反应是完蛋了，Codex 的上下文肯定没了，得要重新解释一遍任务。但让我惊喜的是，当我再次启动 codex，它提示我可以读取现有的progress.md。我确认之后，它直接说：“检测到上次任务执行到第三批次，当前进度是第三批次的第 2 个文件，是否继续？”我输入继续，它接着之前的进度完成了剩余的代码迁移，完全没有重复劳动。

这个体验让我彻底理解了 superpowers 状态管理的价值。它把一次任务的“记忆”落在了磁盘上，而不是存在易失的对话上下文里。你可以关掉终端、重启电脑、甚至换台机器（只要代码库和状态文件都在），任务都能接续。这对长耗时任务来说是巨大的体验提升。以前用原生 codex，任务超过一小时后，过程中常常因为对话太长导致上下文撑不住，现在有了状态文件，上下文只保存当前关键信息，压力小了很多。

3.5 Java 项目实操中的参数与工具链经验

重构过程中，Codex 频繁使用了mvn命令。默认情况下，Codex 经常直接用mvn test来验证，这在大型项目里很痛苦——一次全量测试可能要好几分钟。我后来定义了项目级技能，让它在执行完单模块改动后，使用mvn -pl <module> -am test只测相关模块，速度提升非常明显。

举个例子，原项目有order-service、inventory-service、api-gateway三个模块。只会涉及到order-service的改动时，命令是：

mvn -pl order-service -am test

这个命令只构建和测试order-service及其依赖的模块，不会去碰其它不相干的模块。我在技能的“测试”步骤里写了这个命令之后，整个重构流程的验证速度从每次四五分钟降到了不到一分钟，效率提升是肉眼可见的。

另一个实用参数是-DskipTests和-Dmaven.test.skip=true的区别。执行编译打包但不想跑测试时，用-DskipTests会编译测试代码但不执行；如果想连测试代码都不编译，就用-Dmaven.test.skip=true。我在让 Codex 做“仅编译检查”时，明确指定了后者，不然它经常会把测试代码也编译一遍，浪费时间还容易报一些无关的错误。

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

4.1 安装后 Codex 不认识 superpowers 命令

这是一个高频问题。表现是：你运行 codex，输入superpowers相关指令，但它回复“我不知道你在说什么”，或者完全忽略你的指令。

我排查过这个问题，大多数时候是配置文件没有生效。你可以先打开 Codex 的配置文件（通常在~/.codex/config.toml或类似位置），确认里面有没有superpowers相关的初始化块。如果没有，说明安装脚本没有改对位置。这时候手动把安装目录里的init.md路径加进去就行。

还有一种可能是版本兼容问题。superpowers 要求 Codex CLI 的版本不能太低，有些旧版本不支持它用的某些特性（比如动态工具注册）。这时候需要升级 Codex CLI，然后再试。我的经验是：遇到莫名其妙的“不识别”，优先升级到最新版，不要在这种问题上花太久排查。

4.2 子代理总是“出工不出力”，输出太笼统

有朋友跟我抱怨，说 superpowers 的子代理虽然被调用了，但输出非常敷衍。比如让它做代码审计，它就只写了“代码整体质量良好，建议优化性能”，完全没细节。

这种情况的根源往往是子代理的提示词定义不够具体。你要在技能或子代理配置里明确“输出必须包含哪些内容”，最好给模板。我在定义“代码审计代理”时，明确要求它按以下格式输出：

• 问题文件路径
• 具体行号
• 问题类型（性能 / 可维护性 / 正确性 / 一致性）
• 建议修改方案
• 优先级（高 / 中 / 低）

有了这个强制模板，子代理的输出自然就详细起来。你可以同理套用到任何需要“深度”的场景。记住，AI 默认会走懒路径，你给它越明确的输出契约，它就越能给出高质量结果。

4.3 技能文件被加载了，但行为没有按步骤执行

这个问题也很有意思。表现为：Codex 明确说“已加载技能”，但执行时却没有按照技能文件里的步骤顺序来，跳步骤或者自作主张。

我分析下来，大多数是因为技能文件里的“步骤描述”写得太模糊。比如“检查代码质量”这种说法，它虽然写了步骤，但每一步没有可验证的“通过标准”，模型就只能自由发挥。

解决办法是给每一步加上明确的“验证命令”和“期望结果”。拿我之前说的 pre-commit 技能举例，第 1 步不能只说“运行测试”，而要写成“运行mvn test，如果构建失败，立刻定位到失败的测试类，输出断言错误信息，然后停止后续步骤”。这样 Codex 就知道“失败了该怎么办”。没有失败路径的步骤描述，本质上是残缺的。我在后续编写所有技能时，都会为每个步骤加上“成功 / 失败后的分支行为”，技能的执行稳定性明显提升了。

4.4 使用过程中的 Token 消耗激增，钱包压力大

superpowers 因为引入了状态读取、子代理调度、技能加载，实际的 Token 消耗确实比直接用原生 Codex 要高一些。我在头几天明显感觉到消耗速度变快了，一度想放弃。

后来我总结了几条省钱经验：

• 尽量让每一个子代理只专注于一个小目标，不要把十个任务塞给一个代理。因为子代理的上下文是独立的，任务越聚焦，Token 浪费越少。
• 不要让主代理把子代理的结果全文转述一遍再输出给你。默认情况下，它经常会把子代理的输出“复述”一遍，这完全是多余开销。在配置里显式规定：“主代理只需要输出子代理结论的摘要，原始结果保存在文件中，不要完整复制到对话里”。
• 状态文件不要每步都重写全部内容，只追加变更部分。可以用 Git 来管理状态文件的版本历史，这样既保留完整信息，又不需要每次都全量写入。

按照这个方法优化之后，我把 Token 消耗控制在了原生版的两倍以内，换来的却是远超两倍的任务完成质量和稳定性，这笔账我认为是划算的。

4.5 常见问题速查表

最后再分享一点我的个人体会

superpowers 这种工具真正给我的冲击，不是某个单一功能的惊艳，而是它让我意识到：AI 编程助力的下一个阶段，可能已经不再是单纯的“对话框里聊需求”，而是变成“给 AI 建立一套可配置、可复用、可审计的工作流”。你像一个团队的 leader 一样，为你的 AI 员工制定制度、划分职责、设定检查点。代码本身仍然是 AI 写的，但整个任务的工程质量、过程透明度、失败恢复能力，完全掌握在你的配置和技能定义里。

我现在的习惯是，每接触一个新类型的工作，都会把工作流沉淀成一个 superpowers 技能。以后再遇到类似任务，直接触发技能，Codex 就会按既定流程执行。这个习惯让我的项目交付质量稳定了很多，也让我从重复性的“保姆式提示词调试”里解放了出来。如果你已经受够了和 AI 对话时反复解释、反复纠错，不妨试试把这个“管理层”装上去。第一次用它接手一个复杂重构的时候，你会重新理解什么叫“让自己的 AI 有超能力”。