如果你最近在用 Codex CLI 辅助写代码大概率已经体验过那种“聊得挺好干起活来又差半口气”的感觉它能理解需求但面对一个多文件改造时经常要来回追问好几轮改着改着还会偏离方向。“superpowers”这个项目我第一次看到的时候就觉得名字起得特别准——它给 Codex 装上了一组可复用的“超能力”斜杠命令把 AI 从“随叫随到的问答助手”变成“会规划、能执行、懂自查的结对同事”。这篇文章是我从零部署、再到真实 Java 服务改造项目里跑完整流程的记录适合正在用、或者正准备用 Codex CLI 做日常开发的工程师参考。1. 为什么需要 superpowersCodex 原生能力的最后一公里1.1 从“能聊天”到“能干活”的差距Codex CLI 本身已经具备很强的代码理解和生成能力但原生的交互方式更偏“对话驱动”。你每次开一个新会话都要重新交代一遍项目背景、代码规范、测试要求甚至要反复强调“别动不相关的文件”。这种重复劳动在单文件小任务上还能忍一旦碰上一个跨模块的改动会话上下文会迅速膨胀AI 的注意力反而被稀释。我做第一个真实项目时就吃过这方面的亏让 Codex 给一个 Spring Boot 服务加新接口它连续改了三个 Controller 文件还把两个不该动的 Mapper 给“顺手优化”了。问题不在模型能力而在于没有一个稳定的作业框架去约束它。superpowers 做的就是这件事它把一套经过验证的作业流程固化成命令让 Codex 每次开工前先想清楚“我要改什么、影响到谁、怎么验证”。1.2 核心定位把“约束”变成“资产”superpowers 的设计思路本质上是把“提示词工程”升级成“命令文件工程”。它利用 Codex CLI 的自定义斜杠命令机制在~/.codex/commands/下挂载了一大批 Markdown 命令定义。每个命令文件都包含一段精心设计的指令模板有的还会调用本地辅助脚本来做代码库扫描、生成结构化上下文。用个生活类比Codex 原生状态像一个聪明但没受过训练的新员工你问一句他答一句做事毫无章法superpowers 就像给这个新员工发了一套标准作业指导书。它不是换一个人而是让同一个人按照成熟的工作流去干活。每次调用/plan、/implement时Codex 都会先读取对应的命令模板按模板里的步骤执行而不是凭直觉乱来。1.3 命令是怎么被加载和执行的这套机制的关键在于 Codex CLI 本身已经支持用户自定义 slash commands。你可以在~/.codex/commands/下放一个 Markdown 文件文件名就是命令名文件内容就是命令触发时注入给模型的提示词。superpowers 只不过把这套机制玩到了极致它不是一两个命令而是一整组互相配合的命令还带共享脚本和配置。安装之后你进入 Codex 交互界面输入/help会看到比原生多出一大串命令。这些命令有的负责“看”代码扫描、影响分析有的负责“想”拆解任务、制定计划有的负责“做”改代码、跑测试有的负责“查”审查 diff、复盘问题。命令与命令之间还有明确的输入输出关系比如/analyze的产物可以直接喂给/plan让整个会话像流水线一样推进。这也是为什么它叫 superpowers——单看每个命令可能不起眼组合起来就是一套完整的工作流。2. 安装与环境准备从零跑通2.1 前置条件检查动手安装之前先确认三样东西Codex CLI 本体、Node.js 运行时、以及 Git。superpowers 本身不修改 Codex 的二进制只依赖它的自定义命令机制所以 Codex CLI 版本不能太老建议至少是 0.3x 之后的版本越新越好因为自定义命令的解析能力一直在迭代。Node.js 是用来跑辅助脚本的建议 18 以上20 更稳。Git 主要用于代码仓库操作某些命令比如生成 diff 报告、回滚改动会依赖它。检查方式很简单codex --version node --version git --version如果版本正常就可以继续。这里有个小提醒如果你之前给 Codex 配置过别的自定义命令先备份一下~/.codex/commands/目录避免安装过程覆盖掉你已有的东西。别问我怎么知道的——我第一台测试机上就有过一个自己写的daily命令安装 superpowers 时没备份直接被顶掉了。2.2 安装步骤与方式选择superpowers 的安装方式主要有两种我推荐先用 npm 全局安装省事升级方便。npm install -g codex-superpowers安装完成后执行初始化命令superpowers setup它会自动检测 Codex CLI 的配置目录把命令文件写入~/.codex/commands/同时备份原有的配置文件。整个过程中你只需要确认几个 yes/no 的问题基本无脑。不想用 npm 的话也可以从 GitHub 仓库直接拉源码搜索codex-superpowersclone 到本地后运行仓库里的install.sh有的版本是make install。源码安装的好处是你会得到一个完整的项目目录方便自己改命令模板。缺点是升级时得手动拉代码再跑一次安装不如 npm 干净。以下是我实际测试后的选型参考安装方式适合场景维护成本备注npm 全局安装大多数个人开发者低一行命令升级推荐首发源码 clone 安装想深度定制命令模板、团队二次开发中需手动跟进上游适合动手能力强的人团队共享配置多人协作统一命令版本低放仓库里同步需要配合 Git 管理2.3 验证安装与目录结构安装结束后我建议先跑一次验证别直接上生产项目。进入一个空目录启动 Codexcodex在交互界面输入/help如果看到类似/analyze、/plan、/implement、/test、/review这些命令说明安装成功。再去看一眼目录结构~/.codex/commands/ ├── analyze.md ├── plan.md ├── implement.md ├── test.md ├── review.md ├── refactor.md ├── fix.md └── shared/ ├── scan.js └── context.jsshared/目录里的脚本是命令的“幕后工具”负责扫描代码结构、提取上下文。重点在于这些 Markdown 文件都是纯文本你随时可以打开看甚至直接改。也就是说superpowers 的每个“超能力”你都能拆开研究而不是黑盒。这一点对我后来做团队定制特别重要。3. 核心命令拆解把 Codex 变成真正的队友3.1 命令的分层设计逻辑我第一次看命令清单时有点懵命令太多了。跑了几轮项目之后才摸清楚它们的组织逻辑是“分析—规划—执行—检查—复盘”五个阶段。每个阶段的命令只负责一件事且尽量不越界。这样设计的好处是你可以只用一个阶段的命令也可以全流程串起来用。以/analyze为例它只做代码理解和问题发现不写任何代码/plan只在拿到分析结果后做任务拆解/implement才真正动手改代码。层级清晰职责单一。真出了问题你能快速定位是“分析错了”还是“执行错了”不用去猜是整个流程哪里崩的。3.2 分析类命令先搞清楚现状再动手/analyze是整套工作流的入口命令。它会扫描当前代码库识别项目类型、依赖关系、模块边界以及调用链上的关键文件。在 Java 项目里它能识别出 Maven 或 Gradle 的结构甚至能大致圈出 Spring Bean 的依赖方向然后生成一份结构化摘要告诉 Codex 代码库里有什么、哪些地方“碰了会出事”。还有一个我常用的(/scan)变体针对单个模块做快速体检不会扫全库适合改动范围明确的小任务。它的输出会收敛到“当前改动涉及的文件清单”和“潜在风险点”两项。这个命令是我每天用得最多的因为它快而且能让 Codex 在动手前先“对齐地图”避免跑到无关目录里去。3.3 规划与执行类命令把任务拆到可落地的颗粒度/plan是我认为整个工具链里最有价值的一个。它会把一个模糊需求比如“给订单模块加一个导出功能”拆解成具体的执行步骤每一条都包含改哪个文件、为什么要改、影响哪些调用的边界。拆完后它会请你确认这等于在动手前先做了一次设计评审。确认计划之后就可以用/implement按计划执行。执行过程中如果遇到计划里没覆盖到的模糊点它不会闷头瞎猜而是回到/plan层补充计划再继续。这个“先补充计划再动手”的行为是模板里写死的也是它比原生 Codex 靠谱的核心原因。我实测有一个执行策略参数值得注意叫--strategy或者你版本里的--approach默认是balanced稳妥优先切到aggressive会更快推进但偶尔会改出多余代码conservative则每一步都要你确认适合动核心模块。个人建议核心代码选conservative边缘模块用balanced永远别在跑批量重构时选aggressive除非你愿意事后逐行 review。3.4 质量保障类命令让 AI 自己给自己找毛病/test命令会分析当前改动涉及的范围自动定位相关单测执行并汇总失败用例。它比你自己手敲mvn test然后翻日志要智能的地方在于它会分析“为什么这个用例会挂”把失败原因归纳成几条而不是甩给你一坨堆栈。/review命令专门用来检查尚未提交的改动。它会从“安全性、可读性、性能、边界条件”几个维度给 diff 打分并逐文件给出改进建议。它不会替你改只会提问题相当于让 Codex 扮演一个“带枪的 code reviewer”。刚开始我用的时候觉得有些建议很“学究”但时间久了发现它能抓住不少真实问题比如某个接口没做空指针防护、某条 SQL 没用参数绑定。再往下还有/refactor这个命令跟/implement最大的区别在于目标是“不改变外部行为、只改善内部结构”。它做完之后会自动要求/test验证防止重构引入回归。我一般只在有测试覆盖的代码上用它没有测试的老代码块会先补测试再重构。3.5 Java 场景实战superpowers 怎么融入日常开发说回 Java 开发。我之前拿一个真实的 Spring Boot 服务做实验任务是“给用户模块增加一个批量查询接口”。完整流程是这样的第一轮我用/analyze扫描整个服务它识别出 Controller、Service、Mapper 三层结构并且指出“批量查询如果直接拼 SQL 会有拼 SQL 风险建议走 MyBatis 的foreach标签”。这个结论其实已经超过我原本的要求但确实对。第二轮/plan把任务拆成了四步新增 DTO 和 VO、改 Mapper 接口和 XML、改 Service 层、加 Controller 层入口。每一步都标注了影响面包括需要改哪些测试数据。第三轮/implement按计划改完代码然后调用/test跑了一遍相关模块的单测第一次跑挂了两个用例——不是因为新代码逻辑错而是它改动了一个MapperScan的包路径影响了旧测试的 bean 注入。这个过程让我很满意没有命令约束的原生 Codex 不会主动发现这种连锁影响而 superpowers 的流程会强迫它“做完后自查”把风险暴露在测试阶段而不是上线后。如果你用的不是 Spring 而是普通 Java 项目或者你在写 Android 代码命令模板本身没有任何 Java 框架预设你只需要在AGENTS.md里写好“这是什么类型项目、测试用什么框架”superpowers 的流程依然适用。这点后面单独说。4. 实际项目中的工作流编排4.1 一个典型任务从分析到交付的全流程前面讲的是单命令的能力真正磨合还在组合使用。我现在处理一个中大型任务的标准流程是这样的阶段命令输入产出耗时参考现状摸底/analyze项目根目录结构摘要、风险清单1-2 分钟任务拆解/plan分析结果 需求分步执行计划2-3 分钟分步执行/implement确认后的计划代码改动视任务规模而定自动验证/test改动范围测试报告取决于测试速度代码审查/review未提交 diff审查意见1-2 分钟以我最近一个“给定时任务模块增加失败重试机制”的真实任务为例。/analyze跑完先把五个相关类列出来了还标出其中两个类的构造器有循环依赖这直接影响了“重试逻辑应该放在哪一层”的决策。/plan基于这个分析给出了“先抽一个重试策略接口再按类型替换旧实现最后改动注册中心调用”的路径并且建议先写测试再重构——这个建议当时看有点保守事后发现非常正确。整个流程里我几乎没有手动改代码只做了三件事确认计划、看git diff、批准最终改动。一台 AI 编程工具能不能用在生产项目里就看它能不能把主动权交回给你。4.2 错误修正与回滚别让 Codex 把问题越改越大AI 写代码不是每次都能一步到位。我遇到最多的情况是/implement改完代码/test挂了然后它尝试修复修着修着波及范围越来越大。superpowers 里的/fix命令就是为了处理这种情况设计的。/fix会把“当前失败信息 相关代码 已有改动”作为上下文重新分析但它会先判断失败根因再动手而不是像原生 Codex 那样“看到报错就改报错那一行”。这个差别很关键。之前我遇到一个空指针异常原生 Codex 在第一处调用点加了个判空结果第二个调用点又报错循环补丁打了好几轮。用/fix之后它先审视了整个对象创建链路发现根因是某个 DTO 的属性没有在工厂方法里赋值一处修改就解决了。不过也得说实话/fix不是万能药当它连续两轮没找到根因时我的习惯是手动回滚到上一个稳定点重启一次分析。回滚操作我强烈建议由人来做别让 AI 自己git checkout否则容易出现不可控的连环操作。我的做法是每次用 superpowers 做完一个阶段先在本地提交一次标注wip-superpowers前缀。这样出问题一键回滚且不丢失阶段进度。4.3 让 superpowers 适应你的团队习惯superpowers 的命令模板看起来像是“别人的工作流”但它最大的优点恰恰是可以改。每个.md文件都是纯文本你对团队工作流有特殊要求直接改模板就行。举个例子我们团队要求所有新增接口必须带 OpenAPI 注解、所有公共方法的注释必须包含示例而且 Controller 层不允许写业务逻辑。这些要求早期全靠 code review 的时候人工提醒。后来我直接把/implement模板里的“完成标准”段落改成“新增或修改的 Controller 方法必须包含 Operation 注解Service 层必须处理参数校验Controller 方法只允许调用一个 Service 方法。”从那之后Codex 交回来的代码基本没有违反过这些约定。另外一个重要的团队配置是AGENTS.md文件。这是 Codex 生态通用的项目级说明文件放在仓库根目录Codex 启动时会自动读取。superpowers 命令模板会参考这个文件里的信息来做决策所以你可以在里面写清楚“这个模块属于 XX 业务线”“测试跑命令是mvn test -Dtestxxx”“禁止使用System.out.println输出日志”等约束。我把这文件称为“团队的面试题库”因为它才是让 AI 真正融入团队协作的关键superpowers 是一个严格的面试官而AGENTS.md是你们团队给出的标准答案。5. 常见问题与排查技巧实录5.1 命令不生效或找不到命令这是我被问得最多的问题自己也踩过。先说排查顺序先检查~/.codex/commands/下文件是否真的存在再检查 Codex CLI 的版本最后检查是不是同时装了新旧两套配置导致解析冲突。有一个特别容易忽略的坑不同版本的 Codex CLI 对自定义命令文件的 front-matter 解析要求不同。early 版本只认标题和正文新版本支持 model、temperature、permission-mode 等元信息。如果你从旧版本升级后命令突然失效八成是 front-matter 格式不兼容。解决办法是删掉~/.codex/commands/里的旧文件重新跑一遍superpowers setup让初始化脚本写入新格式。5.2 权限与执行报错superpowers 的辅助脚本有时会执行文件系统操作比如扫描目录、读取配置如果你的 Codex CLI 开了沙箱模式脚本可能因为没有文件权限而跑不起来。报错通常会是一串 Node.js 的EACCES或EPERM。解决方案有两个一是在命令文件 front-matter 里给该命令指定permission-mode: bypassPermissions只建议测试环境使用二是给沙箱配置加白名单允许它读取项目目录和临时目录。我更推荐后者因为本身跑代码生成就不应该放开所有文件权限否则 AI 改到你系统配置文件你都不知道。5.3 上下文超限与输出截断长流程容易出现问题分析结果太大塞不进模型上下文窗口导致/plan生成的计划质量暴跌甚至直接截断。我自己遇到过/analyze扫描一个大型微服务仓库时输出上下文超出窗口后面的/plan只能看到一半的分析结果计划做得一塌糊涂。解决思路是“缩小边界”。/analyze命令通常支持指定目录范围比如/analyze ./order-module只分析订单模块。还可以在配置里关掉不必要的扫描深度比如不分析测试目录、不读取构建日志。这本质上是控制信息量让模型在有限的上下文里聚焦最重要的问题。5.4 常见问题速查表现象可能原因处理方式/help里看不到命令命令文件缺失或路径错误重新执行superpowers setup命令执行报EACCES沙箱权限不足调整沙箱白名单或权限模式/plan质量变差上下文超限分析结果被截断缩小扫描范围减少上下文命令模板修改后不生效Codex 缓存了旧文件重启 Codex 会话必要时重启终端多文件改动出现越界修改缺少AGENTS.md约束在仓库根目录补充明确的项目规范安装后原自定义命令被顶掉安装脚本覆盖了旧配置安装前备份~/.codex/commands//implement反复改同一处模板中的“完成标准”不明确在模板中增加具体验收条件辅助脚本运行慢扫描范围过大调整命令参数限定扫描目录5.5 安全与 AGENTS.md 配置最后必须聊安全。AI 编码工具权限越大越要注意别让它越权。我见过有人为了让 Codex 干活顺畅直接给它bypassPermissions结果它顺手改了全局 npm 配置。这种事一旦发生排查成本极高。我的安全底线是代码改动只允许发生在项目仓库内读取操作可以放宽到项目依赖目录写操作严格限制在工作区凡是涉及密钥、配置中心、生产环境的路径一律在AGENTS.md里明确禁止读取和修改。另外建议开启 Codex 的审计日志每次 AI 执行过的命令都有记录出问题能从日志里还原全过程。这不算麻烦是责任问题。还有一个容易被忽视的点superpowers 的命令模板是用 Markdown 写的但 Markdown 本身能嵌入命令。安装第三方命令文件之前先打开看看里面有没有exec这种执行标记确认没有恶意行为再投入使用。这个道理跟检查开源代码一样环境安全永远大于效率。我从这个项目里最大的收获不是“能用 AI 写更多代码”而是“AI 开始按流程做事了”。它不再是那个给一句话就冲出去乱撞的毛头小子而是会先问清楚边界、列好计划、做完自查的同事。如果你手里也有一堆 Codex 用得不得劲的项目我建议先花一下午把 superpowers 装上拿一个小任务完整跑一遍流程。等你看完/plan生成的步骤清单大概率会和我一样把原生对话式写代码的方式彻底丢进回收站。