最近这段时间一直在折腾 Codex CLI 的增强玩法。朋友推荐我关注一下 superpowers说这东西能让 Codex 的自动化能力上一个台阶。我最初没当回事毕竟 GitHub 上打着“超能力”旗号的 prompt 仓库太多了。直到我在一个 Java 老项目里连续改了三版代码都被 review 打回、抱着试试看的心态把 superpowers 的技能机制用上之后我才意识到问题的关键不是模型不够聪明而是缺了一层“干活的方法论”。这篇不聊玄的就讲我实际安装、配置、使用 superpowers 的过程踩过的坑以及在 Java 场景里和 WorkBuddy 配合做任务编排的实战记录。如果你也在用 Codex 这类编码代理工具觉得它能跑通但用不深这篇应该能帮你把“能用”变成“好用”。1. 先搞清楚 superpowers 到底是什么不是魔法是给 Codex 装上“职业素养”很多第一次见到这个项目名的人都会理解成“是不是装了个插件之后AI 就能自动搞定一切”。我一开始也是这么以为的结果发现方向完全错了。superpowers 不提供任何模型能力它做的是另一件事把使用编码代理时容易遗漏的思考过程、检查节点和回退策略固化成一套可加载的“技能文件”让 Codex 在动手之前先学会一套职业习惯。1.1 我最初对它的误解我最早是在 GitHub 上搜“codex superpowers”时看到这个项目的。README 里的描述很简短为 Codex CLI 提供可组合的技能定义与工作流配置。当时我脑袋里的画面是——装完就拥有“超级能力”模型自动升级。于是我很兴奋地装好打开一个 Python 项目让 Codex 写一个带缓存的爬虫。结果发现它跑得和之前一模一样该问的问题还是问该写的代码还是写没什么区别。后来我才明白superpowers 默认不注入任何“魔法提示词”它只提供一套机制让用户显式声明“什么时候该做什么检查”。如果不主动配置技能它就是个空壳。这个设计其实非常克制也符合编码代理工具的发展逻辑——与其让模型自由发挥不如给模型一套清晰的 SOP。1.2 核心构成拆解技能、工作流与上下文注入按我的理解superpowers 由三部分组成技能定义Skills一组 markdown 或 yaml 文件描述某个具体能力的触发条件、执行步骤、输入输出要求。比如java-refactor、test-generation、security-review每个技能都像一份岗位说明书。工作流Workflows把多个技能编排成一条流水线。一个重构任务可能包含“调用链分析 → 变更方案 → 分步执行 → 测试验证”四段每一段对应一个技能前一个技能的输出作为后一个技能的输入。上下文钩子Context Hooks在特定时机向对话中注入项目信息。比如任务开始前自动加载AGENTS.md、编译错误日志、最近改动文件列表模型不需要反复问就知道当前状态。这三部分合在一起本质上是一套“任务执行框架”。框架本身不回答“代码怎么写”的问题但能保证模型在写代码前先想清楚改什么、影响什么、怎么验证。这也是我后来觉得它比单纯的调 prompt 有用的根本原因——它不依赖运气而是把每一步都结构化。1.3 为什么默认的 Codex 用起来“有力气没技巧”裸奔的 Codex 其实很强单轮问答、写个函数、改个 bug它都能干。但一旦进入多文件、多步骤、需要反复验证的任务它就暴露出几个问题容易直接动手缺少全局信息收集。问它“重构这个类”它可能打开文件就开始改而不是先看一眼调用关系。验证环节薄弱。改完代码它不会主动思考“这个改动会不会破坏其他模块的测试”。上下文管理混乱。对话一长早期结论被遗忘前后行为不一致。superpowers 解决的就是这三件事用技能定义强制它先分析再动手用工作流把验证纳入必选步骤用上下文钩子让关键信息始终可见。所以准确地说superpowers 不是给模型“加能力”而是给模型“加流程”。2. 安装 superpowers 的两条路线与我的选择官方文档里提供了两种安装方式一种走包管理器一种直接拉仓库。两条路我都试过各有各的适用场景这里把我自己的取舍逻辑说清楚。2.1 路线一通过包管理器安装如果你用的是 Codex CLI 的较新版本可以直接用内置扩展机制安装codex install superpowers这条命令会自动拉取技能仓库并在~/.codex/superpowers/下建立目录结构。装完之后运行codex doctor会看到多出一项superpowers: OK说明核心机制已经被识别。包管理器路线的好处是干净依赖关系由工具自己处理升级也方便。但问题在于默认安装的技能库可能只包含核心技能如果你想在 Java 项目里用一些深度扫描类的功能还得自己往里补技能文件。而补技能文件这件事在包管理器模式下要处理权限和覆盖策略比较绕。2.2 路线二手动 git clone 到我更推荐的做法我自己最终选择的是手动拉取仓库git clone https://github.com/你的源/superpowers.git ~/.codex/superpowers然后手动编辑~/.codex/config.json加入{ superpowers: { enabled: true, skillsPath: ~/.codex/superpowers/skills } }选择手动 clone 的理由有两个。第一技能文件本质上是 markdown我想直接改里面的步骤、加自己的检查点手动 clone 让我可以像改自己的代码库一样改技能。第二我在内网环境有离线需求clone 一次之后可以完全脱离网络运行。2.3 验证安装是否生效的步骤安装完别急着开干先做一个最小验证。我常用的是这个三步流程在任意项目目录运行codex --list-skills看看能不能列出技能清单。运行codex --skill-path ~/.codex/superpowers/skills describe java-refactor查看某个技能是否被正确解析。在一个空的临时目录里让 Codex 执行“用 test-generation 技能为下面这个函数生成测试”观察它是否先输出分析步骤再写代码。如果第三步里能看到模型先输出“分析函数输入输出 → 列出边界情况 → 编写用例”这样的流程说明技能加载成功。要是它直接噼里啪啦写测试代码那就是技能没有被调用问题多半出在配置文件路径或版本匹配上。2.4 安装时最容易踩的版本坑我第一次安装时codex CLI 的版本比较旧跑codex install superpowers直接报unknown command。查了半天才发现扩展机制是从某个版本之后才引入的。当时我花了五分钟升级了 CLI 就解决了。所以如果你装的时候遇到类似报错先别怀疑项目有问题先看一眼版本codex --version另外技能文件的格式如果包含新版才支持的字段老版本解析器可能直接跳过整个技能文件导致明明有配置却“无技能可用”。这个坑会伪装成“路径没配对”排查思路我放到后面的踩坑章节里专门说。3. 让“超能力”真正生效的关键配置从空壳到满配安装只是把文件放到磁盘上真正的功夫在配置。这一章我会把技能加载机制和我实际用的核心配置全部摊开包括一个完整的代码审查技能定义示例。3.1 两级配置模型全局配置与项目配置superpowers 的设计里有一个很好的点配置分全局和项目两个层级。全局配置在~/.codex/config.json定义通用偏好和默认加载的技能集。项目配置放在项目根目录下的.superpowers/config.json会覆盖全局同名项适合团队统一规范。比如团队要求所有改动必须附带影响面分析就可以把这条写进项目配置谁跑 Codex 都得遵循。我的项目配置长这样{ extends: ~/.codex/superpowers/base.json, skills: { load: [core/*.md, java/*.md, workbuddy/*.md] }, hooks: { beforeTask: [ load:git-status, load:todo ], afterTask: [ run:tests ] } }注意skills.load支持通配符这让我可以按目录加载一批技能而不是逐个点名。hooks则定义了任务前加载 git 状态和待办事项任务后自动跑测试。这两个钩子是提高项目自动化程度的关键也是“超能力”真正发挥威力的地方。3.2 技能文件的三种来源与加载优先级技能文件并不是只能放在一个地方实际运行时会从三个位置读取来源路径优先级内置技能库~/.codex/superpowers/skills低项目技能目录project/.superpowers/skills中用户临时技能~/.codex/skills高同名技能冲突时优先级高的覆盖优先级低的。这个设计很实用项目里可以放团队定制的专属技能不会和官方更新冲突。我通常会把通用改造原则放在项目技能目录里因为不同团队对“重构完成”的定义不一样有的要求测试覆盖率 90%有的要求通过 code review 后才算完。3.3 一个完整的代码审查技能定义示例技能文件格式我用的是 yaml因为它比 JSON 更适合人读也更容易写注释。下面这是我目前最常用的core/code-review.md--- name: code-review version: 1.2.0 description: 对本次变更进行系统性的代码审查 trigger: - 审查本次改动 - review my changes - 检查一下这段代码 steps: - section: 变更梳理 action: 读取 git diff --stat 和 git diff列出所有变更文件 output: 文件清单 变更类型新增/修改/删除 - section: 逻辑审查 action: 逐个检查变更文件的核心逻辑关注错误处理、边界条件、状态一致性 output: 每个文件的风险等级 具体风险点 - section: 影响面分析 action: 搜索变更函数的所有调用方检查是否涉及其他模块 output: 受影响的调用方列表 潜在风险说明 - section: 测试建议 action: 基于影响面给出需要新增或修改的测试用例 output: 测试清单含用例名称和预期结果 verification: - 变更文件数量与描述一致 - 每个风险点都标注了文件名和行号 - 测试建议可执行不写空话 ---这段定义的核心在于每个 section 都明确告诉模型“读什么、输出什么”最后还有 verification 阶段强制模型自查。我实际用下来加入这份技能后Codex 的代码审查结果从“泛泛而谈几个问题”变成了“直接指出某个配置文件里异常没有被 catch”。差距非常明显。3.4 如何确认技能真的被调用配置写完了怎么确定模型真的在按技能跑我的土办法是看它的思考过程。如果模型在回答开头出现了类似“按照 code-review 技能我先梳理变更文件”这样的表述大概率是命中了。另外我还会刻意在技能文件里加一个“启动提示词”字段规定模型开始阶段必须输出一段固定格式的话比如[sKILLcustom-java-build] 开始执行 Java 构建检查这样在对话记录里搜索sKILL一眼就能分辨技能是否被触发。这个方法适用于任何技能框架虽然没有官方指标那么优雅但胜在直观。4. 在 Java 项目里的实战从“改得动”到“改得对”前面讲了安装和配置这一章进入真正的应用场景。我手里有一个接手很久的 Spring Boot 服务代码结构乱、测试覆盖低每次改动都像拆盲盒。用 superpowers 之前Codex 在这个项目里基本只敢让它写写单元测试或改改配置。配置完 Java 相关技能之后我开始让它承担更复杂的重构任务效果确实不一样了。4.1 场景背景一个典型的老 Java 项目困境这个项目的特征是Service 层很厚一个类动不动上千行一个方法里同时做参数校验、权限检查、业务处理、日志记录依赖注入靠字段注入到处都是Autowired。理论上应该用 Spring 的构造器注入但历史遗留太多根本不敢大动。这种环境下Codex 直接改代码的风险很高——它可能把一个只被 A 调用的方法误以为也被 B 调用然后串改逻辑。以前我的应对方式是把上下文尽量缩小明确告诉 Codex“只改这个文件其他不要动”。效果一般因为它对调用链的理解始终是盲人摸象。使用 superpowers 之后我在项目技能目录下放了一个java-refactor.md规定重构前必须先读调用链。4.2 配置 Java 专项技能的核心思路Java 项目和 Python、JS 项目最大的不同在于类型信息丰富、编译链路长而且工程结构往往是 Maven/Gradle 多模块。技能定义需要包含这些信息才能跑得动。我的 Java 重构技能开头的配置是这样的--- name: java-refactor version: 1.3.0 description: Java 项目安全重构流程 trigger: - 重构这个类 - 重构方法 - 拆分类 - refactor java context_required: - pom.xml 或 build.gradle 中模块划分 - 目标类所在模块及其依赖模块 - 当前分支的改动范围 steps: - section: 调用链分析 action: 使用 grep 和 IDE 索引文件搜索目标方法的所有引用整理调用方列表 output: 调用方类名 调用方式 是否跨模块 - section: 变更边界确定 action: 基于调用链列表圈定可影响范围标记不可变接口 output: 变更边界说明列出不允许改签名的方法 - section: 分步重构 action: 每完成一个小步骤先编译一次mvn compile 通过后再继续 output: 每一步的变更摘要 编译结果 verification: - 所有调用方引用未被破坏 - mvn -q compile 通过 - 相关模块测试通过 ---这里特别强调mvn compile作为验证门禁是因为 Java 的编译器本身就是最好的“静态检查器”。很多时候模型改完代码你肉眼看着没问题一编译就暴露类型不匹配。把这个步骤写进技能等于让 Codex 在提交结论前先过一遍编译效果比任何 prompt 魔法都牢靠。4.3 我用一段实际操作复盘真实效果我挑了一个 800 行的OrderService做拆分实验。这个类里既有订单创建的流程又有价格计算和库存扣减的逻辑是典型的“多职责混合”。我直接说“使用 java-refactor 技能把价格计算逻辑拆到独立的 PriceCalculator 类。”Codex 的输出流程明显和以前不一样。它先跑了调用链分析列出了一长串引用calculatePrice方法的类名和测试类名。然后它没有直接创建新类而是先输出变更边界保留OrderService中所有公开方法的签名不变只挪内部实现。这一步以前从来没见过——以前它会直接把整个方法搬走导致调用方全部要改。拆分过程中它分了三步先建PriceCalculator类并迁入纯计算逻辑再改OrderService内部调用最后跑mvn test。中途第一次编译报错原因是原来在OrderService里用了一个私有静态常量迁移时没有一起带过去。Codex 看了编译日志之后自动修正第二次编译通过相关测试全绿。整个过程我几乎没有插手只做 review。这种体验确实是“改得动”也“改得对”。4.4 这个方案的边界与注意事项Java 重构技能不是万能的在两类场景下效果明显打折? 大量使用反射、动态代理的项目。反射调用在静态分析阶段根本搜不到调用链分析会漏技能定义里必须补一条“搜索 xml 配置和注解驱动里的 bean 名称引用”。多模块之间有循环依赖的项目。这种结构下编译本身就有顺序问题模型容易在分析依赖关系时绕晕。遇到上述情况我会手动干预一下把关键信息补充到对话里或者在技能文件的context_required里多写一项“运行时组件扫描配置”。如果你们项目也有类似的硬骨头建议先从没有反射、没有循环依赖的模块开始试点成功率会高很多。5. 搭配 WorkBuddy 做多任务编排一个完整的任务流示例superpowers 本身解决的是“单技能执行”的问题但实际开发中更多是“多任务流水线”先分析、再重构、再测试、再写文档。这种场景我选择配合 WorkBuddy 来用。我注意到有人把它写成 worbuddy其实指的是同一个工具。WorkBuddy 相当于总调度负责拆解任务、分配技能、检查中间输出superpowers 则提供每个节点的具体技能。两者结合之后整个流程的自动化程度会显著提升。5.1 WorkBuddy 在整条链路中的角色如果把一次开发任务比作一个项目WorkBuddy 就是项目经理它负责识别当前项目类型、读取待办列表、规划任务依赖关系、调用适合的技能节点、在失败时安排重试。而 superpowers 里的技能文件就像是项目经理手下的不同工种有专门写测试的、有专门做安全审查的、有专门做重构的。它们之间的通信基于配置协议。WorkBuddy 会读取 superpowers 的技能清单把它当作可调度的“能力池”。用户只需要给 WorkBuddy 一个目标比如“在重构同时补齐测试”它就会规划出一个包含java-refactor和test-generation两个技能的执行序列。5.2 集成方式与配置示例我用的集成方式是在项目.superpowers/config.json中注册 WorkBuddy 为默认编排器{ orchestrator: workbuddy, skills: { load: [core/*.md, java/*.md, test/*.md] }, workbuddy: { maxIterations: 5, checkpointInterval: each-step, errorPolicy: rollback-and-report } }checkpointInterval设成each-step的好处是每完成一个技能节点WorkBuddy 会要求 Codex 输出一份简短的状态报告写清楚“做了什么、还剩什么”。项目复杂时这个机制能有效防止模型跑偏。5.3 一个从任务描述到落地执行的完整案例我举一个实际执行过的任务“将订单模块的折扣逻辑调整为一等会员 8 折二等会员 9 折并确保相关测试更新。”我只要把这句话丢给 Codex配合 WorkBuddy 后实际执行过程是这样的WorkBuddy 先读取项目里的AGENTS.md识别出订单模块位于module-order核心折扣类在DiscountService。它调度java-refactor技能先完成调用链分析找出DiscountService的所有入口确认改动影响面。进入code-edit技能修改折扣规则同时保留原有扩展点。调度test-generation技能为新的折扣逻辑生成测试用例覆盖一等、二等、非会员三类情况。执行mvn test如果失败WorkBuddy 会捕获失败信息并重新调度修复技能。全部通过后输出变更摘要列出修改的文件和测试结果。整个流程里我和模型的交互就只有最初那一句话。中间的所有步骤都是靠技能和工作流在推动。这个用法遇到的最大好处是Codex 不会再像以前那样一次性把代码全改完然后丢给你一堆编译错误而是每步都验证、每步都汇报。5.4 编排失败时的应急处理方法WorkBuddy 也不是永远顺利。我遇到过一次因为测试环境缺少某个配置导致mvn test一直失败而 WorkBuddy 执着地反复重试同一套测试浪费了很多时间。后来我在配置里增加了errorPolicy: rollback-and-report意思是遇到失败先回退到上一个检查点然后输出失败原因而不是原地硬试。这个改动大大减少了无效的循环。如果你也遇到编排器反复重试的问题建议直接设置maxIterations上限比如最多 5 轮。在这个范围内如果还没跑通就让模型停下来输出总结报告由你来判断是环境问题还是逻辑问题。把“无脑重试”换成“有边界地重试”是执行复杂任务链时的关键调优手段。6. 踩坑记录四类最常见的问题与完整排查链路这一章专门写我过去这两个月里被绊倒过的问题。每个问题我都会给出现象、排查思路和修复方案。比起直接给你“正确答案”我觉得把判断过程记录下来更有价值。因为工具的版本不断变化下次你遇到问题时的表象大概率和我不同但排查链路是相通的。6.1 技能文件存在却没有被加载现象codex --list-skills输出正常技能文件在磁盘上但模型的实际行为完全没有技能痕迹。排查链路先检查技能文件的头部 frontmatter 是否完整。name和steps是必填项我有一份技能的description写太长导致解析失败整个文件被静默跳过。确认技能文件名后缀。我当时的文件是.md.txt系统直接不认。检查配置里skills.load的通配符是否覆盖到该文件所在目录。比如技能放在custom/下但配置写的是core/*.md那自然加载不到。用codex --debug --list-skills查看解析日志。这个方法最有效可以直接看到哪些文件被读取、哪些被跳过、跳过原因是什么。6.2 对话太长导致上下文溢出技能后半段被忽略现象任务开始阶段还能看到模型按技能走到后半段它突然开始“自由发挥”忘记验证步骤。原因Codex 的上下文窗口有限当对话内容膨胀到一定规模较早期的技能指令会被清理掉。这个非常隐蔽因为表面上看技能配置没变模型也在工作。我的解决方案把技能文件里最重要的约束尽量放在开头比如verification步骤必须前置。减少任务颗粒度每次对话只执行一个技能节点。如果任务是重构加测试就分开两次执行不要挤在一次对话里。如果确实需要长对话我会在配置里开启“上下文压缩”选项让系统定期摘要早期内容。6.3 Java 项目里调用链分析漏掉注解式注册的 Bean现象模型搜不到某些调用方导致重构时漏改代码编译通过但运行期报错。原因项目用了 Spring 的Service、Repository这类注解调用方不是通过传统方法引用而是通过 IoC 容器注入。静态搜索只能搜到类型引用搜不到容器装配关系。排查链路打开技能文件在context_required中加上“扫描 Autowired 字段和构造器参数”。在调用链分析步骤中增加指令搜索Autowired字段的类型声明以及applicationContext.getBean(xxx)的模式。如果项目使用了 MyBatis-Plus 或 JPA 的 Repository 代理还要告诉模型“接口的实现类不在源码中显式存在需搜索调用该接口的地方”。经过这三个调整漏调用方的问题基本解决了。说到底还是技能定义要跟项目的实际构造方式匹配。6.4 与 Codex CLI 版本不兼容造成的异常现象安装 superpowers 后运行任何命令都提示superpowers config parse error但配置文件本身是有效的 JSON。排查链路我先用json.tool验证配置没问题。然后把配置简化到只剩{enabled: true}依然报错。最后检查 Codex CLI 版本发现版本太旧缺少对 skill 目录数组格式的支持。升级到较新版本后问题消失。从那以后我养成了一个习惯每次升级 Codex CLI 之后先跑一遍codex doctor看 superpowers 是否仍显示OK。版本兼容是这类工具最常踩的暗坑也是最容易被忽略的。7. 自己动手扩展一个私有技能把团队规范固化下来工具用得再熟如果只是调用现成技能你的水平就停留在“会用”层面。真正让 superpowers 发挥价值的是把自己团队特有的流程固化成技能文件。这一章分享一个我扩展技能的完整过程包括结构、样例和心得。7.1 设计技能文件的基本结构一个技能文件本质上就是“触发条件 执行步骤 验证条件”三个部分。我通常按这个模板来组织--- name: 技能名称 version: 版本号 description: 一句话说清楚这个技能干什么 trigger: - 触发词1 - 触发词2 steps: - section: 阶段名 action: 具体要做的事 output: 期望输出物 verification: - 验证项 ---这个结构的核心价值在于“输出物”的明确性。很多技能定义失败的原因是只写“分析一下”这种含糊指令模型做完分析后没人知道分析结果长什么样。我在实践中学到每个步骤都要写明输出物比如“输出调用方列表”“输出测试建议清单”模型才知道怎么交付。7.2 我写的一个团队私有技能数据库迁移脚本检查我们团队经常遇到数据库迁移脚本写错导致上线失败。我写了一个db-migration-review技能内置了团队约定--- name: db-migration-review version: 1.0.0 description: 审查 Flyway 迁移脚本的安全性与正确性 trigger: - 检查迁移脚本 - review migration steps: - section: 变更定位 action: 读取迁移目录下的新 SQL 文件按版本号排序 output: 新脚本文件名 数据库类型 - section: 结构审查 action: 检查 SQL 是否包含 DROP TABLE 或 TRUNCATE如有则标记高风险 output: 风险类型表 - section: 可回滚性 action: 检查每个 DDL 是否有对应回滚脚本 output: 缺失回滚项清单 verification: - 所有 DDL 都有回滚脚本 - 高风险的破坏性 SQL 必须输出警告 ---这个技能上线之后团队里跑 Codex 生成的迁移脚本质量提升非常明显。不是我写的 prompt 文案多精妙而是技能定义把团队的失败经验变成了执行约束——先查危险操作再查回滚最后才给出结论。7.3 扩展技能的两个有效期建议第一技能文件不是写了就完了要跟着项目演进定期更新。我们在容器化改造后新增了“检查镜像依赖”的步骤因为有一次模型生成的脚本漏掉了基础镜像版本变更。这种来自事故的补充是技能库最有价值的部分。第二技能要尽量“小而专”。不要试图写一个包含所有场景的巨型技能那会让模型在判断用哪个技能时犯迷糊。我目前的经验是单个技能文件控制在 20 行左右的 yaml 结构覆盖一种任务类型触发词控制在 5 个以内效果最好。说完这些内容回到实践上。我现在的习惯是任何需要 Codex 参与的任务先问自己一句“这属于哪个技能场景”如果有现成的就用现成的没有就先写一个草稿技能再动手。这个习惯养成后不只是 Codex 的输出质量变高了连我自己对项目的理解也更清晰了。工具给人带来的“超能力”本质上还是人把思考结构化的能力superpowers 只是把那套结构搬到了模型面前。
