手头有好几个项目同时在跑代码量一上来光靠手写业务逻辑就忙不过来了。前段时间把 Codex CLI 纳入了日常开发流一开始挺爽但用久了就发现问题让它改个小函数没问题让它把一个需求从拆解到落地完整干完它经常干到一半就跑偏连自己之前定了什么方案都忘了。后来折腾了一阵子superpowers算是把 AI 编程助手的短板补上了不少。这篇就围绕superpowers是什么、怎么配、怎么用、以及 Java 场景下怎么落地把我踩过的坑和验证过的方法完整写出来给同样在折腾 Codex 的朋友做个参考。1. 先搞清楚 superpowers 到底解决了什么问题1.1 为什么原生 Codex CLI 不够用原生 Codex CLI 的核心能力是你说一句它写一段本质上是一个上下文很短、记忆很浅的对话式编码助手。单文件修改、函数抽取、测试补全这类活它干得确实快但一旦遇到跨文件重构、多步骤实现、或者需要遵循项目既有约定的任务它的问题就暴露得很明显读到哪个文件就把哪段作为重点很容易忽略全局约束进行到第 N 步之后前面定义的技术方案经常被自己推翻甚至出现前后矛盾项目里如果配有 README、开发规范、架构文档它默认不是每次都会主动去读。superpowers这个项目本质上是给 Codex CLI 装配一套结构化的技能体系skills把散落在对话里的临时指令变成存储在项目目录下的可持续复用、可被主动加载的执行规范。它不修改 Codex 本身的推理能力而是通过改变输入端的上下文组织方式让 Codex 在动手之前先看到完整的任务背景和执行步骤。用生活化的类比来说原生 Codex 像一个聪明但没经验的新同事你交代一句它做一步superpowers则是给这位新同事配了一本操作手册、一张任务清单和一个复盘模板让它从随机应变变成按规程办事。1.2 核心设计从提示词升级成技能库superpowers的核心不是某个单一脚本而是一整套约定。它通过AGENTS.mdCodex 能自动读取的项目级指令文件把项目规范注入每次对话的起始上下文同时在.superpowers/目录下组织多个技能定义文件每个技能文件就是一整套面对特定任务时的行为准则和操作步骤。这套设计解决了一个很实际的痛点提示词是不可靠的。你每次在终端里敲一段话AI 不一定能理解你真正想要的质量标准但你把质量标准写成技能文件它每次加载时都能看到同样的完整要求行为和输出就稳定得多。superpowers还引入了 hooks 机制在特定事件任务开始、提交前、测试完成后触发预先定义的动作把 AI 的自觉性变成了条件反射。理解了这层逻辑后面安装和使用的每一步都会变得非常顺理成章。2. 安装与初始化别急着跑先理解配置文件2.1 拉取项目并放到正确位置superpowers的安装方式很直接。先把它克隆到本地然后把核心配置目录链接或复制到 Codex 的项目配置路径下。git clone https://github.com/your-superpowers-repo/superpowers.git cd superpowers # 把 skills 和 AGENTS.md 放进当前项目的 Codex 配置目录 cp -r skills .superpowers/ cp AGENTS.md ./这里有一个关键点AGENTS.md最好放在项目根目录因为 Codex CLI 启动时会自动从当前目录逐级向上查找并加载AGENTS.md把它当作全局背景指令。如果你把它放在子目录里加载时机可能就不对了。提示不同版本的 Codex CLI 对配置文件目录的命名有差异。早期版本读取AGENTS.md新版本可能兼容.agents/或CLAUDE.md等命名。在跑通之前先确认你本地 Codex 的版本和文档别把时间花在无声无息的路径错误上。2.2 AGENTS.md 和 skills 目录的加载机制安装完之后需要理解 Codex 是怎么看见这些配置的。AGENTS.md是在每次会话开始时就进入上下文的相当于开场白里夹带的隐藏说明。skills目录则更灵活——Codex 在思考过程中会扫描项目结构当它发现.superpowers/下面有相关的技能文件时会主动读取对应内容。这就是superpowers比单纯把大段提示词写进AGENTS.md高明的地方。如果所有规范都堆在AGENTS.md里上下文会被撑爆而且很多无关内容会稀释重点。技能库的好处是按需加载碰到写测试需求就读测试技能碰到重构需求就读重构技能互不干扰。2.3 验证安装是否生效安装完成后先别急着展开真实业务跑一个最小验证最稳妥。最简单的验证方式是在项目里新建一个临时文件让 Codex 打开它然后在对话里询问根据项目里的 skill你现在能执行哪些任务如果它能把.superpowers/下的技能文件名列出来说明加载链路是通的。另一个更动手的验证方式挑一个技能文件里描述过的简单任务比如按项目规范生成单元测试直接让 Codex 执行。观察它是否先读取了技能文件再动手而不是直接凭空开写。这个细节能明显看出superpowers生效了没有——生效时Codex 的行为会从联想式发挥变成按文件逐条执行。3. skills 机制拆解让 AI 学会做事流程3.1 一个 skill 文件长什么样superpowers的技能文件本质是带结构化标记的 Markdown 文档。一个典型技能文件大致包含几个区块名称与触发条件说明何时该被加载比如当涉及测试编写时目标定义任务完成后应该达到什么状态执行步骤按顺序拆解的步骤清单每步有明确输入和产出质量约束必须遵守的规则比如禁止模拟测试结果必须实现后运行验证交付物模板最终输出应该包含哪些部分举个例子如果写一个为 Java 方法生成单元测试的技能文件内容会是这样# Skill: Write Java Unit Test ## Trigger 当需要为新写或修改的 Java 方法生成 JUnit 测试时启用。 ## Goal 为指定方法生成可直接编译通过的 JUnit 5 测试覆盖率覆盖主要分支。 ## Steps 1. 先阅读目标方法源码明确参数、返回值和可能抛出的异常。 2. 检查项目测试目录结构确认已有测试类的命名风格。 3. 使用 JUnit 5 Mockito 生成测试代码。 4. 在提交前运行 mvn test确保全部测试通过。 ## Quality Bars - 禁止只写正例测试。 - 禁止使用 Thread.sleep 等待异步结果。 - 测试方法命名必须体现测试场景。这种文件一旦写好Codex 以后每次写测试都会按这套规范执行不再需要你反复在对话里叮嘱。这就是技能库和临时提示词的本质区别——知识被沉淀下来了。3.2 从被动问答到主动执行的转变接触superpowers之前我和 Codex 的协作模式基本是我说一句它答一段我检查完再下一句。引入技能之后Codex 的行为模式发生了明显变化它会先读取相关技能文件和上下文然后自动拆解任务按步骤执行一个完整流程而不是每次等我喂下一句指令。这背后的原理值得展开Codex 的上下文窗口是有限的但思考路径非常依赖上下文质量。没有技能约束时它会把注意力分散到无关文件或过度联想上。技能文件的存在相当于加了一个上下文滤网——它告诉 Codex 哪些信息值得重点读、哪些步骤必须按序走、哪些坑要避开模型就能把有限的推理能力集中到关键环节。对我个人而言这个转变最大的价值是减少了盯盘的时间。以前每等 Codex 写一段都要检查、纠正、重新指导下一次操作现在它自己会跑完一个小闭环我只需要在闭环结束时做检查。3.3 多语言适配针对 Java 项目的实际配置很多人看到superpowers这个项目名会觉得它只适配特定语言或特定场景。实际上它是完全语言无关的只不过需要你针对自己的项目语言做技能定义。这里以 Java 场景为例说说怎么配置最实用。我在 Java 项目里主要配置了四类技能构建与测试循环限定 Maven 或 Gradle 的指令要求提交前必须跑完mvn test异常处理规范要求所有 API 层方法必须捕获并转换异常类型避免堆栈信息直接抛给前端数据库迁移规定新增字段必须先生成 migration 脚本再改实体类日志规范要求日志必须包含操作前后上下文的关键参数方便排障这些技能文件不依赖任何编程语言的魔法只是把团队规范转成了 Codex 能理解的步骤和约束。关键在于Java 项目编译较慢技能里一定要明确何时需要运行完整编译何时可以只做语法级检查否则 Codex 每次小改都跑全量构建效率低得吓人。4. 一个完整的日常工作流实录4.1 任务拆解阶段这里用我实际做过的一个需求来演示整个流程。任务背景是给一个基于 Spring Boot 的内部管理系统加一个批量导入用户的功能涉及 controller、service、mapper 三层还需要校验 Excel 模板格式。按superpowers的方式我没有直接让 Codex 写批量导入功能而是先在项目里建立任务上下文通常我会写一个TASK.md或直接在对话里描述清楚背景、约束和验收标准然后让 Codex 读取技能文件来拆解任务。它会先确认当前代码结构明确要修改的类清单再列出实现步骤。这个阶段的关键是不要着急写代码。拆解阶段多花三五分钟能省下后面一个小时的返工。superpowers提供的技能文件里通常包含任务拆解的规则它会要求自己输出一份方案清单包括涉及文件、技术路线、风险点、验收标准。我只需要确认这份方案符合预期就点头让它进入下一步。4.2 实现与测试循环得到批准的方案后Codex 开始逐步实现。因为技能库里配置了每完成一个模块必须对应一个测试的约束它会先改 mapper 层和 service 层然后立刻生成对应的 JUnit 测试并在本地跑相关测试模块。这里有一个superpowers的设计细节需要专门提一下hooks。它可以配置在检查通过后自动运行测试库之类的钩子比如定义一个 hook 文件内容是提交前必须跑一遍mvn -q test -DskipITs。这个钩子的作用是让 Codex 在修改完后自动执行质量门禁而不是等我把所有代码看完再说跑一下测试。hooks 的配置方式通常是在技能目录下定义事件与命令的映射。Codex 在执行到特定节点时会读取 hook 并执行对应的终端命令。这样一来AI 的工作循环就从写代码 - 等我验收变成了写代码 - 自动验证 - 反馈结果 - 修复问题闭环完整度提高很多。4.3 复盘与技能沉淀任务跑完后我会把过程中踩到的坑和顺利执行的模式整理回技能文件里。比如那次批量导入需求中Excel 解析依赖 POI在大文件场景下频繁触发内存溢出后来在技能文件里加了一条约束POI 解析 Excel 时超过 5000 行的文件必须使用 SAX 模式或 EasyExcel 流式读取。这样下一次碰到类似需求Codex 一开始就会避开这个坑而不是等我把异常日志甩给它再改一轮。superpowers这类工具的真正价值正在于此每一次任务执行都在给未来的自动化积累资产。技能库的沉淀方式没有统一标准。我个人的习惯是每次任务结束问自己两个问题——这次任务中有哪些判断是 AI 一开始就做错的如果重来一次我希望它提前知道什么然后把答案写进对应的技能文件。这种循环只要坚持两三个迭代Codex 在具体项目里的表现就会有肉眼可见的提升。5. 常见问题与排查技巧5.1 技能没生效这是最常遇到的情况。症状是你明明放了技能文件但 Codex 的行为完全没变化还是凭直觉乱写一通。排查思路按顺序来确认AGENTS.md在当前目录或父目录且没有被.gitignore忽略确认 Codex CLI 启动会话的目录和项目根目录一致在对话里显式询问你能读取到 .superpowers 目录下的哪些技能文件看反馈检查技能文件的触发条件是否和你的任务描述匹配——如果触发关键词太窄Codex 可能不会主动加载很多时候问题出在触发条件太窄。比如技能文件里写当用户要求生成 JUnit 测试时启用但你的实际任务描述是帮我补全单元测试用例关键词对不上技能就不加载。解决办法是让触发条件覆盖语义相近的表达方式比如测试单元测试mock 数据覆盖率都列上。5.2 hooks 不执行hooks 不执行通常有几个原因。最常见的是 hook 文件路径配置错误或者文件名不被 Codex 识别。部分新版本 Codex 对 hooks 的配置格式做了调整老配置里的字段名可能失效需要翻一下当前版本的文档确认事件名称和字段定义。另外需要检查终端权限。如果 hook 里配置的命令依赖特定环境变量比如JAVA_HOME而在 Codex 的会话环境里没有加载命令会静默失败。我的经验是hook 里不要依赖交互式终端的环境变量尽量写成绝对路径或者先用source显式加载环境文件。5.3 上下文文件膨胀用superpowers一段时间后技能文件会越攒越多每个文件描述也越来越长。这会导致 Codex 在读取技能时消耗大量 context token反而挤压了处理业务代码的空间。我的处理方案是给技能文件做分层每个技能文件只保留执行步骤和质量约束背景解释和技术原理另外放文档或注释里不进入 Codex 的加载路径。同时定期清理过时条目比如某个技能文件里写着使用 XX 版本的依赖但项目升级后这条已经失效留着只会误导 AI。5.4 跨项目复用问题superpowers的技能文件默认是跟着项目走的但团队协作时每个人机器上的.superpowers目录可能版本不一致导致同样一个项目在不同人手里表现差异巨大。这个问题不复杂但很烦人。我的做法是把技能目录纳入 Git 仓库统一管理在 README 里明确说明使用前先拉取最新技能库。另外把通用的技能日志、异常、测试规范放到上一级目录项目特有的技能留在项目内这样既能统一风格又不互相污染。个人使用体会折腾superpowers这段时间我最大的感受是它不是一个开箱即用、装上就一劳永逸的工具而是一套需要你持续投入维护的工作方法。初次配置和完善技能文件需要花费不少精力但收获是逐步累积的——两个月下来我在常规需求上的编码效率提升非常明显而且 Codex 产出的代码风格越来越贴合项目既有约定review 成本明显下降。最后分享一个小技巧如果你想快速试出superpowers的价值不要一上来就配置十几个技能文件。先挑一个你日常最痛的点比如写单元测试或者提交前检查围绕这一个场景写一个高质量技能文件跑通闭环。等真实感受到流程带来的改变后再逐步扩展其他技能。这样既不会因为初始成本太高而放弃也能最快看到效果。