如果你最近在折腾 Codex应该也遇到过这种情况单文件小任务它处理得又快又稳可一旦任务跨三五个文件、涉及既有业务逻辑它就开始“自由发挥”——改错类名、改完不跑测试、问它为什么这么改它还能一本正经给出个错误解释。我一开始以为是模型能力不够试来试去才发现问题多半出在工作流上。后来我把社区里流行的 superpowers 引入 Codex 日常使用算是真正解决了这个问题。别误会这不是什么超级英雄题材的 Mod而是开发者圈子里给 AI 编码代理准备的一套“能力增强方案”。它不换模型、不调 API靠的是流程、提示词和上下文纪律把散漫的编程代理变成“先计划、再执行、勤验证”的靠谱搭档。这篇文章我会把整个使用过程写出来包括安装配置、核心机制拆解、Java 项目实战以及我用了一个多月踩出来的坑。1. 为什么不升级模型我先给 Codex 装了一套 superpowers1.1 裸 Codex 的最大短板不是聪明而是“记性”和“惯性”Codex 本身的水准并不低单看代码生成质量在同类工具里算第一梯队。但实际接到中型项目里它的表现会迅速下滑典型症状有三个。第一个是“只见树木不见森林”。让它改一个模块的接口它会盯着当前文件猛改完全忘了这个接口在别处还有三个调用方。改完之后调用方编译失败它一脸无辜地反问“我只改了接口文件呀别的地方报错不是我造成的吧”第二个是“改完不验证”。它给你输出一段代码你问它跑过测试没有它会说“逻辑上应该没问题”。可在真正的工程里“应该没问题”等于有问题。裸 Codex 默认不主动执行测试也不主动编译这是流程缺失不是能力缺失。第三个是“跨会话失忆”。你上午让它梳理了项目结构下午新开一个对话让它继续改它又从头开始看代码你上午反复叮嘱的“这个模块不要动”它已经完全忘了。这些问题其实都能归到一句话编码代理缺少一套结构化的“操作手册”。它能理解自然语言但它不知道你希望它按什么步骤工作。superpowers 就是为了补上这一层。1.2 superpowers 到底干了一件什么事我理解的 superpowers本质是一层“方法论配置层”。它通过几个机制来约束编码代理的行为项目规则文件比如 AGENTS.md / WORKSPACE.md里面写明项目结构、代码风格、命令规范、禁区事项分阶段工作流把任务拆成“计划阶段”和“执行阶段”避免 AI 跳过确认直接动手落地在磁盘上的持续上下文文件把当前进度、改动记录、下一步计划写下来跨会话也能接上验证闭环每次改动之后强制要求跑编译、跑测试并把结果写回上下文。换句话说它给一个聪明但莽撞的新员工发了一本《团队操作手册》告诉它开工前先读规则改动前列计划改完先跑测试出错先看日志再动手。这听起来像是一堆提示词但实际用起来差别非常大。同样的 Codex 模型加载了 superpowers 之后代码改动路径明显更稳中途返工次数大幅减少。我经常开玩笑说这不是给 Codex 加超能力是给它装了个“项目管理器”。2. superpowers 安装与启用最容易卡住的三个环节2.1 环境准备先说我本机的情况macOSNode.js 18 LTSgit 可用Codex CLI 已经完成登录并且能正常跑通“写一个 hello world”级别的基础任务。安装 superpowers 之前我建议你先确认这几个环境项别装到一半才发现前置条件不满足检查项要求说明git已安装版本 2.x用来拉取项目仓库Node.js18 LTS 或更高superpowers 的安装脚本和本地服务依赖 NodeCodex CLI已登录能正常执行基础问答如果你本机连一次最简单的 Codex 对话都会失败先解决这个再谈 superpowers项目目录有 git 仓库superpowers 的上下文记录会写入项目内文件安装本身不复杂。我用的是从 GitHub 拉取源码到本地、再跑安装脚本的方式过程大致是git clone superpowers 的仓库地址 ~/.superpowers cd ~/.superpowers npm install具体仓库地址我建议你直接去 GitHub 搜索 codex-superpowers 选一个 star 多、更新频率高的版本。这类项目迭代很快不同 fork 之间的差别也不小选的时候重点看两条一是是否支持你正在用的 Codex 版本二是 README 里有没有写明配置文件的结构。我最早选了一个很久没更新的版本装上之后规则文件一直加载不进去换了新的 fork 才正常。2.2 让 Codex 每次会话都自动加载它这一步是最容易出问题的。superpowers 装好了不代表 Codex 会用关键是要让它在你每次启动会话时自动把规则文件读进上下文。我的做法是分三步把 superpowers 里默认的 AGENTS.md 复制到项目根目录按自己的项目情况改一遍在 Codex 的配置里指定项目启动时要读取这个 AGENTS.md 文件或者在项目根目录保留一个稳定的固定路径让 Codex 默认就能发现它如果项目里已经有多个规范文件建议用 imports 的方式把 superpowers 的工作流说明引入而不是把上万字的规则直接堆进 AGENTS.md。我见过不少人在这一步失败原因很简单AGENTS.md 写了一大堆但 Codex 没有在每次会话启动时主动加载它规则根本没进来superpowers 形同虚设。验证方法也很简单新开一个对话直接问 Codex“请告诉我当前项目的 AGENTS.md 里要求的操作流程是什么。”如果能准确复述出“先分析、列计划、确认后再执行”说明加载成功。2.3 离线也能先看说明书别急着“一键全自动”刚开始用的时候我一度想把所有流程都自动化让 Codex 自己读规则、自己定计划、自己执行、自己验证一站式跑完。后来发现这样反而容易失控。更稳妥的用法是先手动跑一轮你自己手动读一遍 AGENTS.md手动触发一次“计划生成”看看输出是否符合预期再让它进入执行阶段。这相当于先走一遍流程确认配置没问题后面再逐步放开自动化。尤其是涉及 Java 项目的 Maven 构建、文件路径调整这种有副作用的操作前期手动确认能减少很多意外。3. 核心机制拆解它到底在后台做了什么3.1 分阶段工作流先计划后执行superpowers 最核心的机制是把一次任务拆成两个阶段。第一个阶段是计划阶段。编码代理只做分析读项目结构、理解需求、列出改动点清单、评估影响范围然后以一份计划的形式输出给用户。这个阶段不写任何实际代码。第二个阶段是执行阶段。用户确认计划之后它才按计划逐项修改并且每一处改动都对应到计划的某一条避免“顺手多改”。我用生活化的方式理解这件事你让一个外卖员去取餐如果没有“先报路线再出发”的机制他可能自己规划了一条绕远路你到家一看饭都凉了。有了计划阶段他先把路线给你看一遍你说“不对走东门更快”他再出发。整个过程可纠正、可干预。实际用下来这个机制最大的好处不是“让 Codex 更听话”而是让作为人类的我能及时发现它的理解偏差。很多时候我不确认计划根本不知道 Codex 把需求理解成了什么样。确认计划这个动作等于加了一道安全闸门。3.2 持续上下文记录把“记忆”写进文件superpowers 另一个让我印象深刻的设计是把状态写进磁盘。它会在项目里维护一份类似 PROGRESS.md 的文件里面记录当前任务是什么已经完成了哪些步骤改动了哪些文件遇到过什么坑下一步计划是什么。这份文件最大的价值体现在跨会话续接。以前我用裸 Codex上午的对话关了下午新开一个会话讲“继续”它基本要从头再来。现在有了 PROGRESS.md新会话一开始先读它几句话就能恢复到上午的状态。我建议你把这份文件纳入 git 管理。好处是每次进度变化都有 commit 记录万一 AI 改乱了可以快速回退到上一个进度点。坏处是 commit 会变多但只要项目是你个人主导这个成本完全可以接受。3.3 验证闭环改完必须证明“能用”superpowers 的流程里执行阶段之后还有一个验证阶段。它要求编码代理运行相关测试或至少让项目编译通过然后把验证结果写回上下文。这一点我特别看重。因为裸 Codex 非常容易陷入“代码生成出来就觉得完工了”的误区它不会主动跑测试也不会主动编译。superpowers 把这个动作固化成流程改完代码之后下一步就是跑测试测试失败就根据日志修修完再跑。这里有一个执行细节验证命令的范围不要一上来就全量跑。后端项目尤其明显一个中型 Spring Boot 项目全量跑测试可能要几分钟如果 AI 每次小改动都全量跑一次效率会低到让人崩溃。正确的做法是在 AGENTS.md 里限定“优先运行与改动模块相关的测试类”只有最后收尾时才做全量构建。4. Java 项目实战让 superpowers 帮我加一个接口4.1 任务背景为了让这套东西不那么抽象我拿一个真实场景演示。项目是一个 Maven 管理的 Spring Boot 服务包名结构大致是com.example.user ├── controller/UserController.java ├── service/UserService.java ├── mapper/UserMapper.java └── entity/User.java需求是新增一个GET /api/users/{id}接口返回用户基本信息并且要求补充单元测试接口风格要跟现有代码保持一致。如果是在裸 Codex 下直接下发这个需求它大概率会直接生成一堆代码然后你可能要花时间检查它有没有用对现有的 DTO、有没有遵循现有的统一返回结构。这次我特意改成 superpowers 流程来做。4.2 我给 Codex 的指令我在 Codex 对话里输入的内容是这样请使用 superpowers 流程处理这个需求新增 GET /api/users/{id} 接口查询用户基本信息。要求先进入计划阶段分析项目结构、现有接口风格、数据库访问方式并输出改动计划。在我确认计划之前不要修改任何代码文件。这句话看起来平平无奇但背后有一个关键点我明确指定了“先进入计划阶段”并且给出了计划阶段需要分析的具体内容。这样 Codex 不会被需求里的技术细节带偏而是先去做信息收集。4.3 完整过程记录第一阶段Codex 输出了如下计划摘要分析 UserController 现有接口的返回值封装确认是否使用统一 Result 结构检查 UserService 是否已有按 id 查询的方法避免重复实现检查 UserMapper 及对应 XML确认 SQL 写法新增 UserController.getUserById 方法新增 UserService 对应方法若已有则复用在 UserMapper 中补充 selectById 方法或确认已有方法可用编写 Controller 层的单元测试mock Service 层。我确认计划后它开始执行。每一步改动我都能从 PROGRESS.md 里看到记录比如“已确认 Result 结构为 ApiResponse 新增 UserController 方法时使用了该返回类型”。这个反馈非常重要说明它读取了现有代码风格而不是自创一套。执行过程中还出现了一个小插曲。Codex 在改 UserMapper 时发现项目里已经存在一个selectByPrimaryKey方法它询问我是否可以直接复用还是新增一个命名更贴切的selectById。这个问题在裸 Codex 场景下它通常不会主动问而是自作主张选了其中一个。现在它能停下来确认是因为 AGENTS.md 里写了“涉及复用与新增之间的选择时先与用户确认”。验证阶段它执行了下面的命令mvn test -DtestUserControllerTest第一次运行测试失败原因是测试代码里 mock 的方法名和实际 Service 方法名不一致。Codex 读取了测试失败日志定位到是方法名不匹配然后修正了测试代码再次运行直到通过。整个任务从下发到全部测试通过大概花了十几分钟。同类需求我用裸 Codex 做过看起来更快因为它直接生成代码但你得额外花时间 review 各种细节。superpowers 模式虽然多了一道“确认计划”的步骤但整体返工次数明显下降拉通算下来反而更省时间。4.4 Java 项目的特别注意事项Java 项目在 superpowers 流程下有几件容易被忽略的事。第一包名与目录结构必须写清楚。Java 的包名和目录路径是强绑定的如果 AGENTS.md 里没有给出完整的包名规则AI 很容易新建文件时把包名写错放在错误目录下。第二DTO 与 Entity 的边界要提前固定。很多 Java 项目里 Controller 层不允许直接返回 Entity要转成 VO/DTO。如果规则文件里不写AI 很可能把 Entity 直接序列化出去后面再来一轮大改。第三Maven 构建日志很长验证环节要引导 AI 只看关键部分。我在 AGENTS.md 里专门加了一条测试失败时先提取日志里的 “Failures” 和 “Errors” 区域不要整段输出日志。这一点既节省了上下文空间也提高了排错效率。5. 实测一个月我踩过的几个坑5.1 上下文文件越攒越大superpowers 会维护 PROGRESS.md 这类持续上下文文件用久了文件会变得很大每次会话都加载它会白白占掉大量上下文空间。我最初没在意在同一个项目里连续跑了三周PROGRESS.md 涨到接近三百行。Codex 的回答开始变“飘”经常忘记最近几步的结论我一度以为是模型出了问题。后来才发现是 PROGRESS.md 太臃肿早期任务的历史信息挤占了宝贵的上下文。解决办法很简单每完成一个大任务就让 Codex 把 PROGRESS.md 里已经完成的内容归档到 docs/history 里当前文件只保留本次任务的信息。这相当于给 AI 定期“清理内存”。5.2 自动执行命令时的权限问题superpowers 的验证闭环意味着它一定会主动执行命令比如mvn test、npm test、git diff。大多数情况下这是好事但你要小心那些有副作用的命令尤其是git push、npm publish、rm -rf这类。我遇到过几次差点出事的情况Codex 在验证完代码后居然尝试执行git push origin main想把改动直接推到远端。幸好我在 AGENTS.md 里提前写了“push 操作必须征得用户同意”它停下来问了我一句我才及时发现。建议你在 AGENTS.md 里明确列出“禁止自动执行”的命令清单并写明原因。这不是对 AI 不信任而是在给它划定安全边界。5.3 不同底层模型的执行质量差异很大superpowers 是一套流程配置它对不同模型的“约束力”不一样。同样是“计划阶段不要改代码”这条规则Codex 自己的模型执行得很好但如果把这一套接到某些小参数模型上模型表面上答应了实际还是会一边“分析”一边偷偷改文件。这不是 superpowers 的问题而是模型的指令遵循能力差异。所以别指望一套配置在所有模型上通吃。如果你在某个模型下发现流程形同虚设先检查是不是模型本身的问题而不是怀疑 superpowers 坏了。5.4 项目结构越乱superpowers 越难发挥作用superpowers 依赖规则文件来约束行为但如果项目本身没有清晰的模块边界、没有测试、依赖关系混乱它能做的其实很有限。它再强也不能把一个完全没有测试的遗留系统变成质量标杆。所以我的建议是引入 superpowers 之前先花点时间把项目的基本结构理清至少做到有明确的模块目录、有少量关键测试。这样 AI 才能在一个相对健康的地基上干活。6. 把 superpowers 用成自己的“能力库”延伸建议6.1 把流程沉淀到团队规范里我现在不光自己用 superpowers还把它的核心流程整理成了团队的编码代理规范。核心就三条动手前先看规则改动前先给计划改完必须给验证结果。这三条不限于 Codex 或 superpowers换成任何编码代理工具都适用。团队使用的收益在于统一的交互方式。以前每个人给 AI 下指令的风格千奇百怪有的人直接丢需求有的人提供大量上下文AI 的表现也因此忽好忽坏。规范统一后至少所有人都会先要求 AI 列出计划再确认执行。6.2 与 CI 流程结合把“验证闭环”做成硬约束superpowers 在本地要求 AI 改完跑测试但这个环节其实是“软约束”AI 有可能跳过。如果你希望强制生效可以在 CI 里加入对应的检查比如 push 前必须通过单元测试和构建。这样即使本地 AI 流程跑偏了CI 也会兜底拦住问题。我目前的实践是本地用 superpowers 管工作流CI 管质量门禁。两者各管一层AI 负责高效产出CI 负责最终把关。6.3 个人项目上的“轻量用法”如果你觉得完整配置太重完全可以只借用 superpowers 的核心理念一个 AGENTS.md 文件 一个“计划确认”习惯。我个人的经验是这一步就能解决八成的问题。不需要把所有技能都堆进规则文件里。AGENTS.md 越精简越好只写那些“不写就会出问题”的事项。比如测试命令、禁止操作、关键目录结构、风格约束。写得太多AI 记不住反而会把重要的部分淹没。我现在维护了好几个项目的 AGENTS.md每个都不超过一百行但每一行都是踩过坑之后沉淀下来的。6.4 把它当成一个持续迭代的规则库最后分享一个我实际的体会superpowers 不是装完就一劳永逸的。它更像一个规则库得跟着项目情况持续迭代。每踩一个新的坑就往 AGENTS.md 里补一条规则每发现某条规则让 AI 变啰嗦了就把它删掉或简化。我大概每两周会回头过一遍 AGENTS.md删掉一些已经不适用或者从未触发过的规则补上最近踩坑记录里的经验。这个过程本身比安装 superpowers 更有价值。因为真正让你获得“超能力”的从来不是某个工具而是你围绕这个工具建立起来的、适合自己的稳定流程。