从第一次在终端里敲下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 对比原生 Codexsuperpowers 到底改进了什么我用一个表格直接说清楚差异这样更直观。能力维度原生 Codex CLI加上 superpowers 之后任务记忆依赖单次对话上下文长任务容易忘通过状态文件持久化跨会话可恢复子任务处理单线程顺序执行支持子代理并行调度结果互相隔离流程复用每次重新描述需求技能包一键加载流程标准化复杂度上限适合 30 分钟以内的子任务可以撑起数小时甚至跨天的复杂重构失败恢复出错了从头再来有状态记录可以从断点继续自我检查有时候干了错事还觉得自己很对通过子代理“审查员”互相监督降低幻觉影响看完这个表你就明白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 --depth1 https://github.com/your-org/superpowers.git ~/.superpowers注意这里我给的是一个示例地址实际仓库地址要以你找到的为准。如果你网络环境访问 GitHub 慢可以考虑通过镜像或者加速方式但这里不多说安全合规第一。第二步进入目录运行安装脚本cd ~/.superpowers npm install npm run setupsetup脚本会自动探测你的 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 来跑。整个作战计划分四个阶段先用“架构分析代理”梳理项目现状输出类职责、依赖关系、疑似坏味道清单。主代理根据分析结果设计拆分方案并让“代码评审代理”评审这个方案。评审通过后主代理调度“重构执行代理”分批次实施代码变动。每一批次完成后自动运行“测试代理”执行测试并反馈结果。听起来很复杂但实际操作时你只需要在主对话里对 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.skiptrue的区别。执行编译打包但不想跑测试时用-DskipTests会编译测试代码但不执行如果想连测试代码都不编译就用-Dmaven.test.skiptrue。我在让 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 常见问题速查表问题现象可能原因快速解法安装后没有效果配置文件未生效 / Codex 版本太低手动检查配置升级 Codex CLI子代理输出空泛提示词中没有输出模板定义强制输出格式技能执行跳步步骤缺少失败分支为每一步补充成功/失败处理逻辑Token 消耗过高主代理复述子代理结论 / 状态文件全量重写配置摘要输出状态文件增量更新跨会话恢复丢失工作目录不对或状态文件被删确认任务在项目根目录启动.superpowers 目录保留命令被系统拒绝子代理执行了超出权限的命令在配置里限制工具白名单最后再分享一点我的个人体会superpowers 这种工具真正给我的冲击不是某个单一功能的惊艳而是它让我意识到AI 编程助力的下一个阶段可能已经不再是单纯的“对话框里聊需求”而是变成“给 AI 建立一套可配置、可复用、可审计的工作流”。你像一个团队的 leader 一样为你的 AI 员工制定制度、划分职责、设定检查点。代码本身仍然是 AI 写的但整个任务的工程质量、过程透明度、失败恢复能力完全掌握在你的配置和技能定义里。我现在的习惯是每接触一个新类型的工作都会把工作流沉淀成一个 superpowers 技能。以后再遇到类似任务直接触发技能Codex 就会按既定流程执行。这个习惯让我的项目交付质量稳定了很多也让我从重复性的“保姆式提示词调试”里解放了出来。如果你已经受够了和 AI 对话时反复解释、反复纠错不妨试试把这个“管理层”装上去。第一次用它接手一个复杂重构的时候你会重新理解什么叫“让自己的 AI 有超能力”。