1. 给Codex CLI装上superpowers之前我受够了“聪明但没规矩”的AI助手1.1 一次让我抓狂的单元测试补写大概几个月前我用Codex CLI跑一个Spring Boot项目任务很单纯把登录模块的单元测试补齐。我把项目结构、Maven配置、核心业务代码都喂给它自认为上下文已经很完整。结果它一口气生了十几个测试类顺手干了三件让我血压飙升的事先把三个已有的测试类改了断言逻辑说“这样更符合Mockito惯用法”然后自作主张把pom.xml里的Spring Boot版本从2.7升到3.2理由是“新写法能少写两个注解”最后测试数据里直接出现了生产环境的用户名密码。那个下午我花了一个多小时清理它的“好心”。问题根源不是模型能力不行而是Codex CLI默认状态下不具备“职业素养”这个概念。它不知道哪些文件不许动、哪些测试必须是回归基线、哪些依赖版本是业务方钦定的。你每次都要在prompt里重复一遍“你是资深Java工程师第一条规则是……”写烦了我就开始找能让规则固化的方案。superpowers就是在这个背景下出现在我视野里的。它是一个开源项目专门为Codex CLI扩充“技能系统”把那些你希望AI每次都能遵守的规矩、标准流程、领域知识做成可复用的Skill文件。装完之后Codex在开工前会像翻工具箱一样读取当前任务相关的技能照着你的剧本干活而不是凭自己的“自由意志”即兴发挥。1.2 原生Codex CLI的三个结构性短板在我实测超过两个星期之后把原生Codex CLI的不足归结为三点这也是superpowers主要针对的场景。第一规则不持久。你在对话里交代的规范只对当前会话有效新开一个终端就归零。项目里但凡有《编码规范.md》Codex也不会主动去读除非你明确“请先看docs目录”而且还要祈祷它别漏掉。第二流程不固定。让AI完成“改代码→跑测试→修失败→再跑→提交”这种闭环它经常跳步。比如跑一次测试全绿就宣布完成根本没执行最后一遍回归或者改到一半突然切换思路去重构另一个类。第三工具使用全凭想象。Codex默认有Shell权限但什么时候用grep、什么时候读文件、什么时候执行测试它没有一个稳定的决策模型。在我的记忆里它不止一次为了确认一行代码把整个项目树打印出来Token消耗蹭蹭往上涨。superpowers把这三件事分别解决掉规则变成Skill文件、流程变成Command脚本、工具使用变成Subagent委派。后面我会挨个拆开讲。2. superpowers的Skills、Commands和Subagents它到底革了什么命2.1 Skills用Markdown把你的“项目规矩”固化下来superpowers里最核心的概念是Skill。一个Skill就是一个带有frontmatter元信息的Markdown文件典型结构大致是这样--- name: java-maven-safe-build description: 在Java Maven项目里执行构建检查修复失败并遵守不随意升级依赖版本的规则 allowed-tools: [shell, read, edit] --- 工作流程 1. 先运行 mvn test 建立基线 2. 如果测试失败逐个读取失败日志修复代码而不是修改测试断言 3. 不要升级或移除pom.xml里的依赖版本除非issue中明确要求 4. 修复完成后重新执行 mvn test直到全绿仔细看这个文件它做的事情就是把自己变成Codex的“岗位说明书”。模型读到frontmatter知道这个Skill叫什么、解决什么问题、允许用哪些工具读到正文就知道具体的操作顺序和禁忌。我特别喜欢“允许用哪些工具”这个设计。原生Codex默认所有工具都可能被调用遇到复杂任务它会东摸一下西摸一下。有了allowed-tools约束比如只允许读文件和编辑文件、不允许执行shellCodex完成任务的方式会收敛很多误操作的概率也直线下降。2.2 Commands把多步操作打包成“一句话指令”Commands是superpowers里的第二层封装。如果说Skill是“怎样做一件事”的规范Command就是“帮我触发这件事”的快捷入口。装好之后你可以直接对Codex说“/troubleshoot”或者“/fix-maven-build”它会自动加载对应的技能、子代理甚至预置的提示词然后按步骤执行。我自己最常用的场景是调试。以前遇到单元测试失败我要在prompt里写“先跑mvn test然后看surefire报告再分析失败原因”。现在一句“/troubleshoot”就能把整个排查链路触发起来而且每一步的“下一步动作”是配置文件里写好的不是模型临场发挥的。Commands的价值在于一致性。同样一个问题让不同的人去用Codex可能给出完全不同的prompt结果也不同但用同一个Command结果会稳定非常多。这对团队协作特别有意义等于把个人经验沉淀成团队资产。2.3 Subagents它真的会“喊人帮忙”第三个让我惊喜的机制是Subagent。superpowers允许你定义各种“虚拟专家”每个Subagent有独立的身份、上下文窗口和擅长领域。比如我可以定义一个“Maven专家”它的任务描述是“只负责解析Maven依赖树和分析构建错误”再定义一个“测试专家”专门负责围绕JUnit断言和Mockito打补丁。调用方式很直白在主对话里委派任务就行大致是这样请委派给 Maven专家分析当前pom.xml中所有冲突依赖并给出最小化修复方案被委派的Subagent会带着独立的上下文去工作就像你在团队里找了一个同事私下讨论技术问题而不是让所有人挤在一个会议室里。优势很明显主对话的上下文不会被中间产物顶掉Token利用率更高而且每个Subagent只关心自己领域内的事行为稳定得多。3. 从克隆仓库到/skills列表非空superpowers安装配置实录3.1 前置条件Node.js版本和Codex CLI版本对不上就白搭我这边的环境是macOS zshNode.js是20.xCodex CLI通过npm全局安装。如果你是用其他操作系统流程一样只有路径写法会略有差异。先确认Node.js版本node -v我建议Node.js至少18以上最好20。版本太老的话克隆superpowers仓库后跑npm install容易遇到ESM语法报错因为仓库里的脚本普遍用了较新的JavaScript特性。然后安装Codex CLInpm install -g openai/codex安装完先跑一下codex --version确认基础命令可用。第一次运行Codex CLI会要求登录OpenAI账号这个按提示操作就行。需要特别注意登录和鉴权是在Codex层面完成的superpowers本身不处理任何密钥它只是往Codex里塞技能和命令。3.2 克隆superpowers仓库到本地安装superpowers没有独立的包管理器常规做法是直接把仓库克隆下来然后在配置文件里指过去。我用的目录是~/dev/superpowerscd ~/dev git clone https://github.com/workbench/superpowers.git cd superpowers npm install这里有两个容易踩的坑。第一个是网络问题如果你在公司内网或者代理环境下git clone和npm install都可能超时建议提前把镜像和代理配置好。第二个是仓库更新频率高隔一两个星期就可能会有新版所以最好养成定期git pull的习惯。跑完npm install后仓库里会多出node_modules目录。这个目录不用管它给仓库自身的生成和管理脚本用。真正被Codex加载的是config文件里指向的路径以及skills、commands这些子目录所以千万别手抖把这些目录删了。3.3 修改Codex配置让CLI找到superpowers技能库Codex CLI本身很迷你它连“技能”这个概念都没有superpowers入口是通过Codex的配置文件注册的。不同版本配置文件路径略有差异最常见的是~/.codex/config.toml[project] cwd /Users/你的用户名/dev [superpowers] enabled true skills_path /Users/你的用户名/dev/superpowers/skills commands_path /Users/你的用户名/dev/superpowers/commands不同版本的实际字段名可能不同有些版本直接在配置里加一行引用就行。我遇到过把skills_path写成复数skill_path导致加载失败的情况这类细节建议你以当前版本文档为准。修改完配置后重新打开Codex CLI让它重新加载配置。3.4 验证安装跑一个内置的/skills诊断命令把配置改完启动Codex CLI在会话里输入/skills如果安装成功它会列出当前可用的所有技能和命令。我第一次看到那个列表时还挺震撼的里面有troubleshoot、code-review、test-driven-development等一堆现成技能等于开箱就带了一套最佳实践。如果列表为空或者提示权限不足先检查配置文件路径有没有写错再确认仓库目录是否存在。还有一个常见原因是Codex CLI版本太老某些配置字段不识别直接升级到最新版就好。4. 实战写一个专门管Java Maven构建的Skill4.1 为什么要用Java项目当例子“superpowers java”在搜索里热度不低因为Java项目的构建链路本来就复杂Maven和Gradle两套体系并存依赖冲突、测试基线、多模块构建都是AI容易“自由发挥”的重灾区。我自己日常主力语言又是Java所以这个例子最有说服力。假设你手里有一个多模块Maven工程模块A是核心业务模块B是Web入口模块C是集成测试。以前让Codex改任何一处的代码它都可能在module B的pom里乱加依赖结果模块C编译失败。Superpowers解决这个问题的思路是写一个Java多模块墙规Skill告诉Codex项目的边界、依赖原则和操作顺序。4.2 Skill文件的结构和元信息应该怎么写我创建一个名为java-multi-module-guard的Skill文件放在superpowers/skills/java-multi-module-guard/SKILL.md--- name: java-multi-module-guard description: 用于Java多模块Maven项目的通用约束任何改动前必须先明确所属模块 allowed-tools: [shell, read, edit] --- # 模块边界 - 每个模块的pom.xml必须单独管理禁止跨模块直接修改依赖 - 增加依赖时必须在对应模块的pom.xml中操作并在commit message中注明原因 # 构建顺序 1. 修改代码前先执行 mvn -pl 目标模块 -am test 确认基线 2. 修改完成后执行全量 mvn test 3. 如果全量构建失败先定位失败模块再回到对应模块修复 # 红线 - 禁止升级Spring Boot、Flink等核心框架版本除非任务描述里明确要求 - 禁止为了修复测试而修改已有断言的语义这个职业技能几乎是“人肉规则”的搬运。Codex读到description后会在任务开始时自动判断是否与之相关。一旦识别到这是Java多模块项目它就把这些规则装进自己的行为约束里。文件名不叫README而叫SKILL.md这是约定写错就识别不了。4.3 让Maven专家作为子代理加入工作流光是规则还不够真正的效率提升来自和Subagent的联动。我在superpowers/subagents目录里加了一个maven-agent--- name: maven-agent description: Maven依赖和构建诊断专家只负责读取pom和管理构建不负责业务代码改动 --- 你只做三件事 1. 读取pom.xml分析模块依赖树 2. 执行mvn命令定位构建失败 3. 输出最小化修复建议然后在Skill正文里明确要求遇到构建类问题必须先委派给maven-agent。这样Codex不会在改业务代码的时候顺便去动依赖Maven问题就由专门的子代理来处理。上下文各管各的主对话里不会堆满构建日志。4.4 Skill之间的互相引用和参数传递建了第一个Skill后你会发现真正好用的技能是可以组合的。上面那个java-multi-module-guard我在description里写了“任何改动前必须先明确所属模块”而在另一个troubleshoot的Command里又让它遇到Maven构建失败时自动加载maven-agent和java-multi-module-guard两个技能。技能之间的互相引用在superpowers里通过frontmatter的depends-on字段实现--- name: troubleshoot-maven description: 排查Maven构建失败并修复同时遵守多模块项目规范 depends-on: [java-multi-module-guard, maven-agent] ---这样一条命令下去Codex会依次加载依赖技能先了解项目红线再让Maven专家上场。观察一下实际效果它不会再把“修复单元测试”和“升级依赖版本”混在一起了定位问题的路径稳定清晰评审代码时也少了很多不必要的争论。5. 真实项目里跑了一百多次之后我总结的避坑经验5.1 上下文窗口是有限的Skill从设计上就要克制我刚开始写Skill的时候恨不得把项目文档全部塞进去结果发现一个问题Skill内容一多Codex每次读取它都要占用大量Token反而把真正要处理的业务代码上下文给挤掉了。后来我定了一个原则Skill只写“当前场景下模型必须知道但容易忽略的约束”不写通用Java知识那部分模型本来就会。上下文规划的思路是“让Codex把有限的窗口留给业务代码而不是浪费在通用常识上”。如果某条规则对当前任务无用就不该出现在Skill里。5.2 权限和危险操作没有万能药只有护栏superpowers可以让Codex更听指挥但不能让它“不会出错”。我实测下来最有用的护栏是allowed-tools。比如涉及生产数据修复的任务我写一个Skill只允许[read, edit]禁止shell然后让用户手动执行命令。--- name: prod-data-audit description: 分析生产数据问题并生成修复SQL不自动执行 allowed-tools: [read] ---把危险操作拆成“生成建议”和“手动执行”两个阶段比让AI一把梭安全得多。哪怕你的Codex有Shell权限也可以通过Skill设计把这些权限按场景收窄。这个方案我强烈建议任何接了生产环境的团队试一下。5.3 版本升级带来的兼容性坑技能会“静默失效”superpowers和Codex CLI都在快速迭代我踩过最疼的坑是某次我把Codex CLI从某个版本升级后原来的skill路径配置在config里失效了。起因是那次升级改了配置文件加载逻辑日志里没有任何提示Codex只是安静地回到了原生模式。现在我的处理办法很简单升级前先git commit当前superpowers仓库的版本把Codex CLI版本号记到commit message里升级后用/skills命令验证一次。基本杜绝了“默默降级”的情况。5.4 并行Subagent会互相打架写操作必须串行Subagent虽然好用但并行跑多个子代理会踩到资源冲突。我试过让三个子代理分别改三个模块的代码结果它们同时操作同一个根pom.xml直接在git里制造了一场冲突。教训是对于写操作绝对不要并行委派给多个Subagent读操作可以随便并行。如果确实需要并行最好让子系统分别工作在不同的git分支或工作树里。这个教训让我把“禁止并行写同一文件”写进了团队内部的Skill规范。典型问题根因我的对策Codex升级后技能全部消失配置加载逻辑变更旧字段被静默忽略升级前记录版本号升级后跑/skills验证Skill太长导致主对话截断技能文件与业务上下文争抢Token只写约束和流程通用知识留给模型两个Subagent同时写pom.xml并行写操作缺少文件级互斥写操作串行读操作并行必要时拆分支6. 从用别人的技能到沉淀自己的把superpowers变成真正的“超能力”6.1 高频场景清单这些地方投入产出比最高我用了这么长时间归纳出几个性价比极高的应用场景新手可以照这个清单去补你自己的技能库代码审查写一个code-review Skill约定审查顺序、红线规则、输出格式问题列表修改建议风险等级让AI的评审结果稳定、可读。测试驱动开发先写测试再写实现再回归。把这条链路做成Command避免AI“忘了先看测试”。构建修复参考前面maven-agent的做法把构建日志分析与修改操作分开降低夹带私货的概率。技术债笔记让AI在每次会议或阅读代码后按照固定模板输出Note沉淀到仓库的docs目录形成团队知识库。6.2 一个我一直在用的“慢思考”参数组合除了superpowers本身Codex CLI还提供了对推理过程的控制。我可以透露一个我常用的组合把reasoning effort调到“max”再加上superpowers的troubleshoot Command很适合处理那种“看起来很简单但一直复现”的疑难问题。副作用是Token消耗明显增加所以我在日常简单任务里还是会调回默认值只在棘手的Bug排查时拉满。6.3 给新手的最后几点提醒第一不要一上来就追求技能数量。先用好内置的skills跑通一两个自己的场景再逐渐加东西。技能库膨胀之后Codex光判断“当前该用什么技能”都会增加额外开销。第二Skill文件属于代码资产要纳入版本管理。我见过有人把整个superpowers仓库塞进.gitignore结果团队里其他人clone下来之后都没有技能排查半天才发现。这里我强烈建议团队成员共用一套技能库改动走PR评审技能质量会随项目演进而提升。第三保持怀疑。superpowers再稳也只是一种自动化编排它改变的是AI编码的“流程纪律”不是模型能力本身。遇到复杂业务判断该人工兜底还是要人工兜底。把superpowers定位成“让AI稳定发挥的工具”而不是“让AI替你做决定的工具”心态就对了。最后再分享一个小技巧我本地建了一个自定义的kitchen-sink Skill把写日报、生成commit message、整理Changelog这类琐碎操作全做成命令。每次要花两分钟的机械劳动现在一句话就搞定实测下来省下来的时间远比当初配置Skill花的时间多。只要你的工作流里存在“每次都要重复交代背景”的场景就值得把superpowers用起来。这些不起眼的自动化沉淀得越多你自己的“超能力”边界就越宽。