如果你用过 Codex CLI大概率会有这么一种体验它在单次对话里很强能写函数、能改 bug、能解释一段陌生代码但你一旦让它按照团队规范连续产出 20 个文件或者跑完测试再根据报错反推修复它就开始变得飘忽不定。同样是它今天的表现和昨天可能完全是两个样。我一度以为这是模型本身的问题直到我把目光从模型能力转移到工作方式上才意识到问题的核心是Codex 再聪明它也没长手没长脚没有一套稳定的作业程序。而我能找到的、针对这个问题最直接的解法就是 superpowers。superpowers 不是一个替代 Codex 的模型也不是某种魔法 API它是一层薄薄的增强层把系统提示词、技能定义、工具链条和项目上下文整合成一套可持续复用的资产让 Codex 在每次启动时都带着一套标准作业程序去工作。这篇内容不打算复述官方文档我会从实际落地的角度把安装、技能系统、Java 实战、工具联动和踩坑经验全部串起来讲一遍希望对正在折腾 Codex 工作流的你有点帮助。1. superpowers 到底给 Codex 加了什么超能力1.1 默认 Codex 的尴尬处境先聊一个我在团队里经常遇到的场景我们有一套自己的后端编码规范比如异常必须包装成统一响应体、Controller 层不允许写业务逻辑、数据库操作必须走 MyBatis 的 Mapper 接口。这些规范本身不复杂但要让 Codex 每次都遵守难度就大了。默认情况下Codex 是一个会话级失忆者。你今天在提示词里写了所有接口返回 Result 它这一轮老老实实做了明天新开一个会话它忘得一干二净。你可以把规范塞进项目根目录的某个说明文件里然后每次对话都手动拖进去但这套流程既笨重也不稳定。更麻烦的是Codex 对工具调用的理解非常浅。它知道有搜索、有文件读写但你让它一次任务里先扫描整个仓库结构再定位三处公共配置最后统一修改它往往会跳过前两步直接开干结果改出来的代码无法通过编译。1.2 超能力的本质把隐性约定变成显式资产superpowers 解决的就是让 Codex 稳定地按照固定套路干活这件事。它的核心不是给模型充值智商而是把工作流拆成可配置、可复用、可版本管理的资产系统提示词集中管理你的编码规范、命名习惯、项目背景、禁止事项统一放在一份或几份提示词文件里启动时自动注入。想改规范改文件就行不用每次复制粘贴。技能注册表把高频任务代码审查、生成单元测试、重构某个模块固化成技能卡片。技能卡片里有明确的触发词、执行步骤、输出格式Codex 看到对应关键词会主动按卡片里的流程走。工具链条预置把搜索代码、批量替换、跑测试、查编译错误这类操作封装成固定命令避免 Codex 自由发挥时选错工具路径。我第一次体会到这个设计的价值是在一个存量 Java 项目里。那个项目有接近 300 个类靠 Codex 自己在对话里摸索结构基本上就是灾难。把 superpowers 配好之后我只需要在技能卡片里写清楚项目采用 Spring Boot 3.x按 Controller、Service、Repository、Entity 分包Mapper 接口放在 resources/mapper 下Codex 的行为立刻变得规矩了很多生成的代码几乎不用大改。1.3 一个直观的类比你可以把默认的 Codex 想象成一个刚入职、能力很强但不熟悉公司文化的实习生。他能写代码但不知道你们团队的代码风格不知道什么该做什么不该做。你每天临时嘱咐他几句他就按嘱咐干活嘱咐漏了他就自由发挥。superpowers 像是给这个实习生配了一本《团队作业手册》。手册里写清楚了项目结构、编码规范、常见任务的执行步骤、遇到编译错误该怎么处理。他不确定的时候会翻手册而不是瞎猜。手册会跟着项目迭代人换了一批也不影响产出质量。这本作业手册才是 superpowers 能带来最稳定的价值的部分。所以后面我在配置技能的时候一直把可复用、可传递、可版本化当作第一原则。2. 安装与初始化从拉仓库到跑通第一轮对话2.1 环境准备清单在动手装 superpowers 之前先检查一下本机环境。我踩过不少次最后发现是版本不匹配的坑所以这里直接给你一个清单Node.js 18 或更高版本superpowers 的启动脚本和本地服务依赖 Node.js 运行时太老的版本会直接报语法错误。Codex CLI 已登录如果你还没安装过 Codex CLI需要先装好并完成 API Key 或登录配置。用codex --version确认能正常输出版本号。Git虽然也可以直接下载压缩包但后续升级和配置同步最好还是通过 Git 来管理。终端代理或网络通畅安装过程需要拉取一些 npm 依赖和远程资源网络不通会卡住。其中我认为最容易忽略的是 Codex CLI 的版本。旧版 Codex 对系统提示词的处理方式和新版不太一样如果 superpowers 需要注入自定义提示词可能在一个偏老的 Codex 版本上生效得并不彻底。建议把 Codex CLI 升到当前稳定版再跑 superpowers 的安装脚本。2.2 安装步骤安装本身并不复杂核心就三步# 第一步把 superpowers 仓库克隆到本地用户目录 git clone 仓库地址 ~/.superpowers # 第二步进入目录执行安装脚本 cd ~/.superpowers ./install.sh # 第三步检查是否安装成功 superpowers status这里我特别说明一下install.sh到底做了什么不然你会觉得它像个黑盒。它通常做三件事创建一个配置目录比如~/.superpowers/config/用来存放后续生成的配置文件。把启动命令链接到PATH里让你能在任意目录直接执行superpowers。生成一份默认配置文件里面包含模型名称、技能目录路径、提示词注入开关等基础项。如果你不希望脚本自动改动系统环境也可以在install.sh跑完后手动把~/.superpowers/bin加进自己的 shell 配置里效果一样。我个人更倾向于手动加因为这样升级时不容易出边界问题。注意如果你之前已经装过其他 Codex 增强工具需要先确认它们的启动脚本会不会互相覆盖。我在本机上同时装过两个增强工具结果 codex 命令被接二连三地包了一层代理排查了半天才发现是 PATH 顺序冲突。2.3 首次启动验证安装完成后不要急着开始写代码先做一轮简单的验证。执行superpowers status如果配置正确你通常能看到以下信息superpowers 版本号默认模型名称技能目录里已加载的技能数量系统提示词是否处于自动注入状态看到这些信息后建议马上做一个最小验证在任意目录下运行codex或者 superpowers 包装过的启动命令输入一句你好简单自我介绍然后观察模型回复时是否带上了你配置的规范。比如如果你在提示词里写了所有代码注释使用中文那么 Codex 如果回复一段带中文注释的示例代码就说明注入生效了。这一步很多人会跳过但我强烈不建议。因为配置没生效通常不会直接报错而是表现为模型行为没有变化很容易让人误以为是 superpowers 无效实际上是提示词没被加载进去。2.4 初始化阶段常见问题我在群里见过不少新用户安装失败的情况在这里列几个高频问题现象大概率原因处理方式Permission denied安装脚本没有执行权限chmod x install.sh后重试superpowers: command not foundPATH 未生效重新加载~/.bashrc或~/.zshrc或者手动链接到/usr/local/bin本地端口冲突superpowers 默认启动一个本地辅助服务端口被占在 config 文件里换一个端口Codex 登录失效登录态过期导致调用模型 401重新执行codex login这些都不算大问题但第一次装的时候确实容易一头雾水。尤其是端口冲突我没看到报错提示之前还以为是 superpowers 本身就启动不了后来查日志才发现是本地服务被别的进程抢了端口。3. 技能系统让 Codex 学会按卡片办事而不是即兴表演3.1 技能到底是什么如果你第一次接触技能这个说法可能会觉得有点玄。实际上它就是一个有固定格式的文本文件通常用 Markdown 或 JSON 写文件里描述了这样几件事技能的名称和概述让 Codex 知道这个技能干什么。触发条件哪些关键词、哪些语境下应该调用这个技能。比如 review、代码审查、检查代码质量。执行步骤按顺序列出从开始到结束要完成的动作。输出要求最终以什么格式产出比如输出问题清单 修复建议按严重程度排序。技能文件被放进 superpowers 的技能目录后启动时会被加载进 Codex 的上下文里。Codex 在对话里识别到触发条件就会按技能文件里的步骤去执行而不是自己在脑子里临时编排一套流程。3.2 一个 Java 代码审查技能的例子拿我上线的第一个技能举例这个技能管用到今天--- name: java_code_review description: 对 Java 代码执行静态审查重点检查异常处理、资源关闭、并发安全 trigger: 审查 review 代码检查 --- 执行步骤 1. 获取目标文件的完整内容并按类结构拆分出方法清单。 2. 检查异常处理是否存在捕获后直接吞掉异常的代码是否抛出过宽的 Exception。 3. 检查资源关闭InputStream、Connection 是否通过 try-with-resources 自动关闭。 4. 检查并发安全共享变量是否有 volatile 或锁保护线程池是否显式关闭。 5. 输出问题清单格式为文件路径 - 问题级别 - 具体描述 - 修复建议。这个技能文件只有一个用途每次让 Codex 审查代码时它都会严格按这五步走而不是像默认状态下那样下次从第 3 步开始再下次从第 2 步开始。你可能会问为什么不把这些步骤直接写进系统提示词原因在于系统提示词是全局的不论 Codex 干什么任务都会被塞进上下文技能则是按需触发只有遇到审查类需求才会注入。全局提示词写太多会稀释模型的注意力反而让它连简单任务都变得啰嗦。3.3 技能注册与热加载技能文件的加载流程也不复杂大概三步# 第一步创建技能文件 vim ~/.superpowers/skills/java_code_review.md # 第二步重新加载技能 superpowers skills reload # 第三步在 Codex 对话里触发 # 输入审查 src/main/java/App.java执行第三步时Codex 会读取技能卡片按卡片中的步骤进行操作。如果技能没有生效优先检查两处触发词是否覆盖了你的输入。比如你的技能触发词只有 review但你输入的是 检查一下这个文件它可能就不会触发。技能目录路径是否被正确配置。有时候安装脚本生成的默认目录和技能实际存放目录不一致就会发生文件明明存在但不被加载的问题。3.4 技能数量与注意力的权衡技能不是越多越好。我自己实测的感觉是当技能文件数量在 10 个左右时Codex 基本能准确触发到了 30 个以上它就开始频繁误触发比如写普通 CRUD 代码的时候插入代码审查步骤或者把代码审查技能的格式套在生成代码的任务上。这其实不难理解技能文件占用的上下文有限数量太多时每个技能分到的注意力就少了模型对触发条件的判断自然容易混乱。所以我的建议是保留 10 到 15 个高频技能低频场景宁可用临时提示词写。技能描述尽量简洁不要写长篇大论你要相信 Codex 的理解能力它只需要关键信息。定期清理从不触发的技能避免僵尸技能占着上下文本地资源。4. Java 项目里的实战从脚手架搭建到代码重构4.1 为什么 Java 场景特别依赖技能约束说实话用 Codex 写 Python 和用 Codex 写 Java体验差距非常大。Python 项目结构松散Codex 自由发挥的空间大就算生成的代码风格不一致跑起来多数情况下也没事。Java 就不同了强类型 大量样板代码 包结构敏感任何一个类型对不上编译器直接给你一长串错误。所以在 Java 项目里用 superpowers我一般不会让 Codex 一口气生成所有代码而是反过来先让它输出结构规划确认后再逐层填充实现。4.2 实战初始化一个 Spring Boot 项目假设我们要新建一个标准的 Spring Boot 3.x 项目包含实体、Mapper、Service、Controller 四层。通常我这样做第一步在项目目录下创建一个CONTEXT.md文件让 Codex 能读到项目背景# 项目上下文 - 基础框架Spring Boot 3.2 - JDK 版本17 - 数据库MySQL 8 - 包名com.example.demo - 分包规则controller / service / mapper / entity / dto - 接口返回格式统一使用 ResultT - ORMMyBatis-Plus第二步对 Codex 说根据项目上下文里的分包规则生成一个用户模块的 Maven 骨架。这时 superpowers 会先把CONTEXT.md注入对话再让 Codex 生成目录结构和核心依赖。第三步等 Codex 生成了 pom.xml 和目录骨架后不要急着让它写 SQL先让它确认依赖版本是否兼容。这是 Java 项目里最容易被 Codex 忽视的部分它经常生成一个理论上成立、但版本组合跑不起来的 pom.xml。4.3 Java 代码生成的高频翻车点我在这个环节反复踩过几个坑写出来供你参考包名不一致Codex 默认生成的包名经常和实际目录对不上。比如目录是com/example/demo/controller代码里的 package 却是com.example.demo.Controler。这个错误的典型特征是编译时一大片文件全部报错。Lombok 依赖遗漏Codex 很喜欢生成Data、Slf4j这样的注解但 pom.xml 里经常漏掉 Lombok 依赖或者漏掉 annotation processor 配置。结果就是代码看着正常一编译就提示找不到 getter/setter。参数校验缺失写 Controller 时Codex 默认不生成Validated和NotNull这类校验注解。这个不是编译问题但上线后会成为接口的隐患。对应解法也直接在技能或 CONTEXT.md 里明确写清楚包名必须与目录结构保持一致package 第一行必须验证。把 Lombok 依赖写进项目上下文文件不要依赖 Codex 的记忆。在生成接口的提示词里直接要求必须包含参数校验注解。4.4 让 Codex 学会改完就编译验证Java 项目里最痛苦的一件事是 Codex 改完代码后不自己验证。它改完一个文件就停下来把编译环节留给开发者等你发现报错再贴给它它再改循环往复。superpowers 的技能系统可以解决这个问题。我建了一个编译修复循环技能--- name: java_compile_fix description: 编译失败时自动读取错误并修复最多重试 3 轮 trigger: 编译错误 compile failed 构建失败 --- 执行步骤 1. 运行 mvn -q compile 获取编译输出。 2. 解析编译错误按错误文件 - 错误行号 - 错误类型 - 修复建议整理清单。 3. 修复第一个错误暂停等待用户确认。 4. 重复步骤 1-3最多三轮三轮后仍未通过则停止并输出剩余错误。这个技能的作用是给 Codex 装上一个刹车片。它一旦跑编译失败知道自己应该停下来整理错误清单而不是盲目地一口气改完所有文件。这个改动看起来很小但在实际上帮我把 Java 项目里的 Codex 效率提升了不止一倍。4.5 重构场景的降级策略如果你让 Codex 做模块级重构比如把某个 Controller 里的逻辑抽到 Service 层我建议先让它生成一份改动影响清单而不是直接动手改。清单里至少包括涉及哪些文件每个文件要移动哪些方法改完之后的依赖方向是什么在 superpowers 的技能里这对应着一个先规划、后执行的开关。你可以在技能文件里加一句第一步输出改动计划等待用户确认后再继续。虽然这句话很简单但它可以避免 Codex 在你还没看清方案时就先把代码改坏。我在一个老项目里做一次跨模块重构时就靠这个开关保住了一口气Codex 计划把 12 个类的位置全部调整我看完计划发现其中有 3 个类被它错误地挪到了公共模块里。如果不是先看计划等它真改完回滚成本会非常高。5. workbuddy 场景把 superpowers 塞进自动化任务流5.1 workbuddy 扮演什么角色如果你的工作流程里已经使用了 workbuddy 这类任务编排工具那 superpowers 完全可以作为底层执行引擎被接进去。简单来说workbuddy 负责接收意图、调度任务、反馈结果而 superpowers 负责真正驱动 Codex 把活干完。这里的核心思路是不要把 workbuddy 和 Codex 之间的交互做成人在对话里手动转发消息而是把 superpowers 包装成可被命令行调用的脚本接口。这样任何能执行 shell 命令的编排工具都能稳定地驱动它。5.2 一个可复用的接入模型假设现在有一个需求用户通过 workbuddy 面板触发为项目里的 UserController 生成单元测试。整体流程大致这样workbuddy 接收指令解析出目标文件和任务类型。workbuddy 调用一个封装好的脚本接口superpowers run gen_unit_test --target src/main/java/com/example/demo/controller/UserController.javasuperpowers 启动 Codex注入单元测试生成技能让 Codex 了解项目上下文和测试规范。Codex 生成测试代码脚本接口把输出写回指定目录同时返回一个状态码给 workbuddy。workbuddy 读取状态码和日志把结果渲染到前端面板。在这种模式下workbuddy 本身不关心 Codex 怎么思考它只关心命令是否执行成功、产物是否生成。这个抽象层让整个链路变得非常干净。5.3 自动化链路里的安全护栏你可能已经想到了一个问题自动化链路里如果 Codex 放飞自我后果比手动对话更严重。手动对话里你至少能实时中止自动化任务可能等你回家才发现它已经 push 了几十个错误提交。所以在接入 workbuddy 之前我强烈建议做三个配置禁止 Codex 自动执行 Git 写操作。统一走生成 diff - 人工 review - 提交的流程。限制文件写入范围。superpowers 的配置里可以限定 Codex 只允许在指定子目录里创建和修改文件防止它擅自改掉配置文件。设置最大执行轮数。比如在 gen_unit_test 这个命令里写明最多生成 5 个文件超过则停止避免它陷入生成-修改-再生成的死循环。这些护栏不需要很复杂的技术实现在技能文件或脚本接口里多写几步判断就行。但少了它们自动化任务的维护成本会直线上升。5.4 一次小规模联动实测我自己做过一次比较典型的联动通过 workbuddy 定时任务每天早上自动检查某个模块的代码质量生成报告并发送到群里。脚本大致逻辑是superpowers run java_code_review --target ./src/main/java/com/example/demo/service这个命令会加载 java_code_review 技能让 Codex 按卡片里的五步走完一遍然后输出一份 Markdown 报告。workbuddy 拿到报告后调用群机器人的 Webhook 发出去。整个过程不需要人参与Codex 的发挥也被技能卡约束得很稳定。当然第一次跑出来的报告质量并没有想象中那么高它把一些历史遗留问题也当成新问题报了出来。后来我在技能里加了一句只报告本次改动相关的代码问题效果才好很多。这说明技能文件本身就是需要持续维护的不是写一次就完事。6. 踩坑与优化我实际用下来的几个教训6.1 上下文窗口耗尽问题superpowers 最容易被忽视的影响因素是它悄悄增加了每次会话的上下文消耗。技能文件、系统提示词、项目上下文加上对话历史几项叠加很容易逼近模型上下文窗口上限。我遇到过一次非常典型的情况在一个中大型 Java 项目里Codex 突然开始遗忘前面几步的指令明明在第一轮要求它使用 MyBatis第二轮它就开始写 JPA 代码。后来排查发现不是模型变笨了而是上下文被塞满了它只能遗忘早期信息来腾空间。优化手段有几个技能文件精简删掉所有正确的废话描述只留关键参数和执行步骤。不要让 Codex 一次性读整个仓库而是通过 CONTEXT.md 把结构信息喂给它按需读取具体文件内容。长任务拆分成多个短会话每个会话只负责一个阶段阶段之间通过落盘文件传递状态。6.2 多技能互相污染当同时加载多个技能时Codex 可能会把不同技能的执行步骤混在一起。比如代码审查技能和生成单元测试技能同时触发它可能生成一份带着审查意见的测试代码两头不靠。这个问题本质上和上下文注意力有关。技能加载越多模型对触发条件的判断就越模糊。我现在会刻意控制一次对话里可触发的技能数量全局技能保持在 10 个以内其余通过CONTEXT.md里的说明按需临时加载。6.3 工具权限设置不当带来的风险superpowers 如果要发挥超能力通常需要给 Codex 一定程度的文件读写权限、命令执行权限。权限给少了它什么都干不了权限给大了它可能在不该改的地方动了手。我的安全阈值是Codex 可以读全部项目文件可以写 src/ 下的代码可以执行mvn compile、mvn test这类验证命令但禁止修改 pom.xml 的依赖版本、禁止修改 git 配置、禁止 push 到远程。一旦需要这些操作我会手动介入。这在技能文件里就是一句话的事禁止操作 - 禁止修改 pom.xml 中的依赖版本 - 禁止直接 push 到远程仓库 - 禁止修改 .git 目录下的任何文件6.4 配置漂移问题superpowers 升级后有时会重置配置文件或者改变技能文件的加载规则。最直接的表现是今天还好好的技能第二天突然全部失效。应对办法其实很简单把~/.superpowers/下的配置文件和技能目录纳入 Git 管理每次调整提交一次记录。升级前先拉一份干净分支升级后如果出了问题可以快速对比差异。我不夸张地说这个习惯帮我挽救了至少三次配置莫名其妙消失的翻车现场。6.5 不要神化工具要训练工作流最后说一个不算坑但很重要的体会superpowers 不是装完就一劳永逸的。它的价值高度依赖你写的技能卡片和项目上下文文件。如果这些内容写得含糊、过时或者干脆缺失那 superpowers 和裸用 Codex 其实差别不大。我见过不少开发者装完 superpowers 后满怀期待结果用了两三天就卸载了原因是感觉没什么变化。细问才发现他们压根没有往技能目录里放任何自定义技能系统提示词用的也是默认模板。这就相当于买了一整套厨房工具却只用来泡方便面。我的建议是装好 superpowers 之后第一周别急着做复杂任务。先把三个基础技能打磨出来——代码审查、单元测试生成、项目结构解析。这三个技能一旦稳定再往体系里加新的技能、接 workbuddy、做自动化每一步都踩在实地上。跑通第一个技能到上生产这个阶段我大概花了两天时间其中一半时间花在调整技能描述和触发词上。但这一轮投入换来的收益非常值现在无论我一个人写项目还是带上团队一起维护Codex 的输出质量都被牢牢控制在团队可接受的水平线上。这大概就是 superpowers 这个名字真正让人信服的地方——它不给你造一个无所不能的 AI它只是帮你的 AI 变得稳定、可控、好交接。