最近我一直在折腾Codex CLI原本以为装好之后就能让AI老老实实写代码结果发现默认状态下的Codex顶多算个“会用搜索引擎的实习生”——你说一步它动一步说的不细它写跑偏更别提什么代码风格统一、依赖版本检查、异常处理规范。真正让它从“能用”变成“好用”的是一套叫superpowers的技能包。这名字听着中二实际却很贴切它把提示词工程、代码库索引规则和复杂任务拆解策略打成一个开箱即用的配置框架让AI在动手写代码之前先想清楚“你是什么项目、有什么约束、该按什么顺序干活”。这篇文章主要聊两件事一是superpowers的安装和使用指南二是怎么在Java项目里把它的能力真正发挥出来。不管你是刚开始接触AI编程助手还是已经在团队里推Codex这篇文章都值得花十分钟看完。1. Superpowers到底是什么一个给AI编程助手叠Buff的配置框架1.1 Codex与Superpowers的关系Codex本身是一个对话式编码助手它能理解自然语言、写代码、跑命令但它的默认行为是“你问什么它答什么”缺少主动搜集上下文的能力。这在实际项目里很致命你让AI“写一个用户注册接口”它大概率直接给你甩一个Controller出来既不看你项目里的Service层叫什么也不管你用的Spring Boot是哪个版本甚至可能生成一个Java 8写的类让你在Java 17的项目里直接编译不过。superpowers的核心是一个“技能包”机制。每个技能包由一组Markdown文件组成里面定义了任务步骤、代码规范、上下文获取命令和输出格式。当Codex加载superpowers之后它就不再是一个单次对话的问答工具而是一个会按照技能包里的策略先扫描项目结构、读取pom.xml或build.gradle、分析包名规则然后再给出方案的“结构化编码助手”。我打个比方默认Codex像一个刚进公司的新人聪明但不懂规矩superpowers就是一份新员工手册告诉它“去哪个目录拿需求文档、代码要遵守什么规范、完成工作的标准是什么”。没有手册它纯靠临场发挥有了手册它才真正开始干活。1.2 为什么不用直接改系统提示词很多人第一反应是既然superpowers本质是提示词那我直接在Codex的系统提示词里写清楚不就行了我一开始也这么想但实测下来有三个绕不开的问题。第一提示词过长会被截断。Codex的上下文窗口是有限的你把“所有项目规范、所有技术栈说明、所有编码风格要求”一股脑塞进去还没开始写代码上下文就快满了。superpowers采用按需加载的方式只有对话中出现特定触发词时对应的技能包才注入上下文利用率高很多。第二全局系统提示词无法适配项目差异。一个人可能同时维护Spring Boot老项目和Quarkus新项目两套规范完全不一样。你把规则写死在全局配置里AI切换项目时就会犯糊涂。superpowers允许每个项目有自己的.superpowers/目录项目A和项目B互不干扰。第三默认对话没有任务拆分和验证步骤。直接让Codex“写一个用户注册接口”它往往会一口气把所有代码吐出来中间不做任何确认也不自查。而superpowers可以定义“先分析实体、再定DTO、再写Service、最后Controller每步完成之后停下让我确认”的任务流让AI从“莽夫”变成“稳一点的老哥”。1.3 它解决的核心痛点总结一下superpowers主要解决了这四个真实痛点上下文缺失AI不知道项目的依赖版本、包名前缀、代码分层方式生成的代码经常不兼容现有工程。superpowers提供了项目上下文采集技能让AI在动笔前先“读”项目。任务颗粒度太粗“写一个用户注册接口”这句话颗粒度太大。superpowers可以把任务拆成多个可验证的小步骤每步输出都经过确认避免一步错步步错。规范不一致团队编码规范往往只写在文档里AI根本看不到。superpowers把规范做成技能包AI触发相关关键词时自动加载生成风格能跟团队现有代码对齐。不可回溯直接在提示词里改规矩改了之后说不清哪次改了。superpowers的技能包是文件可以进Git仓库review、回溯、对比全都能做。2. 安装与初始配置从零到能跑通一个演示任务2.1 环境准备与前置依赖我的实测环境是macOS Node.js 20 LTS GitLinux和Windows的操作基本一致。开始之前请先在终端确认下面这些命令能正常工作node -v npm -v git --version codex --version如果你的codex命令还不存在先装好Codex CLI并完成登录确保它能正常发起对话。我见过不少朋友跳过这一步直接装superpowers最后发现Codex根本没接上白白折腾半天。另外提醒一句superpowers本身不是模型它不会替你做AI推理。它需要的是一个能执行外部工具、读取本地文件的编码助手底座。目前我用下来Codex CLI是最顺手的宿主环境理论上其他支持技能注入的编码助手也可以但本文的例子都基于Codex。注意安装之前建议先跑一遍codex随便问个问题比如“用Java写一个Hello World”确认能正常回答。如果这一步都卡住先解决Codex的登录和网络问题再看下面的内容。2.2 安装Superpowers的三种典型方式方式一全局安装CLI适合日常频繁使用的场景。npm install -g superpowers/cli安装完成后用superpowers --version确认版本信息。我这边装到的是1.4.x版本命令结构和配置项在不同小版本之间偶尔有微调遇到参数对不上就以你本地的--help输出为准。方式二通过npx临时拉起适合只想在某个项目里试一下的人。npx superpowers initnpx会自动下载并执行最新版不需要全局污染Node环境。缺点是每次执行都可能重新拉包多多少少会慢一点。我一般建议重度用户用全局安装尝鲜用户用npx。方式三从源码安装适合想改源码或者研究内部实现的人。从官方仓库克隆下来之后依次执行npm install npm run build npm link这种方式能让你随时切分支测试新功能但对大多数人没必要。我更推荐直接用npm包。2.3 在项目里初始化技能包安装好了之后进入你的Java项目目录执行cd your-java-project superpowers init --language java这个命令会做三件事创建.superpowers/目录在目录下生成skills/、rules/、context/三个子目录根据--language java参数生成一套Java项目通用的基础技能模板。初始化之后记得把技能包挂载到Codex配置里。这一步特别容易漏。你需要编辑~/.codex/config.toml加入类似这样的配置[experimental] skill_dirs [/绝对路径/your-java-project/.superpowers/skills, /绝对路径/your-java-project/.superpowers/rules]注意我这里建议写绝对路径。之前我用相对路径踩过坑因为Codex解析相对路径时是相对于它自己的工作目录而不是项目目录。切换项目之后经常加载不到技能包改成绝对路径就再也没出过问题。配置保存之后重启Codex CLI接着在对话里问列出你已经加载的所有技能。如果能看到java-style、project-context之类的技能名说明superpowers已经生效了。2.4 验证安装是否成功最后再跑一遍superpowers doctor它会检查配置文件和技能目录的有效性输出每个技能文件是否有格式错误以及Codex配置文件里挂载的路径是否真实存在。我每次改完规则之后都会跑一次算是省心小帮手。如果一切正常你会看到类似下图的输出状态提示技能已加载数量、规则文件数量、配置路径是否正确。这里我不贴终端截图了反正核心就是看最后一行是不是all checks passed。3. 实战过程用Superpowers驱动Codex改造一个Java项目3.1 先让AI“读”项目再让它“写”代码默认情况下Codex不会主动去翻你项目里的几十个文件。它更像一个“即问即答”的助手问题范围只限于你提供的上下文。superpowers里的project-context技能就是为了解决这个问题。在对话中触发这个技能的方式是发送指令关键词比如了解项目。或者直接说加载项目上下文重点关注Spring Boot版本、Java版本、包名前缀和已有Controller的命名习惯。技能被触发后Codex会执行一组工具命令读取根目录的README.md、解析pom.xml、扫描src/main/java下的包结构、识别启动类位置。执行完这些之后它会返回一份压缩的项目摘要。实际工作中我会在开始一个任务前先花30秒让AI加载上下文确认它知道项目里用的是Spring Boot 3.2.5、Java 17、包名是com.example.platform而且已有的Controller都以/v1/xxx作为前缀。这样一来AI后续生成的代码基本不会出现“把Java 8语法塞进Java 17项目”这种低级错误。3.2 把团队编码规范注入技能包团队里最怕的是什么是每个程序员写出来的风格都不一样。更怕的是AI写出来的风格跟团队里谁也不一样。superpowers允许我在.superpowers/rules/java-style.md里定义强规则AI只要触发关键词就会自动遵守。举个例子我服务过的一个团队有很明确的规范Controller只做参数绑定和调度不允许写业务逻辑Service接口和实现必须分离所有请求DTO必须用jakarta.validation注解禁止System.out.println异常统一交给GlobalExceptionHandler。我把这些写成一个规则文件--- name: java-style triggers: [java, spring, controller, service, dto, mapper] --- ## 强制规则 - Controller只做参数绑定和调用Service不允许写业务逻辑。 - Service接口必须与Impl分离接口命名用XxxService实现类命名用XxxServiceImpl。 - 请求DTO使用jakarta.validation注解校验失败统一抛BizException。 - 禁止使用System.out.println一律使用SLF4J。 - 异常处理走GlobalExceptionHandler不能在各层自行catch后吞掉。保存之后在.superpowers目录下执行superpowers reload让配置重新加载。然后再开一个新对话向Codex提一个包含“Spring”或“Controller”关键词的需求比如“写一个分页查询用户的Controller”它就会自动把上面这些规则纳入生成代码的约束。实测下来这套配置的效果非常明显。AI生成的代码直接符合团队规范review的时候少了很多“这里为什么要这样写”的争论。我说个真实感受以前用Codexcode review基本是在审查AI接入superpowers之后code review变成了对照规则逐项打勾省心太多。3.3 复杂任务拆解以写一个用户注册接口为例面对“写一个用户注册接口”这种任务我强烈建议用superpowers的任务拆分功能。命令是这样的superpowers task add 实现用户注册接口 --steps 1.分析现有User实体和数据库表;2.定义RegisterRequest DTO并加校验注解;3.实现UserService与UserServiceImpl;4.实现UserController;5.在GlobalExceptionHandler中补参数字校验异常映射任务添加成功后Codex会看到这个任务及对应步骤。它不会一次性把所有代码吐给你而是从第一步开始完成之后问你“这是第一步的结果是否继续下一步”。我通常会在第三步之后先停下来检查代码确认Service层接口命名和依赖注入方式符合现有工程再让它继续。这里贴一个简化版的生成效果注意它已经遵循了规则文件里“接口与实现分离”的要求// UserService.java public interface UserService { User register(RegisterRequest request); }// UserServiceImpl.java Service RequiredArgsConstructor Slf4j public class UserServiceImpl implements UserService { private final UserRepository userRepository; private final PasswordEncoder passwordEncoder; Override public User register(RegisterRequest request) { if (userRepository.existsByEmail(request.getEmail())) { throw new BizException(邮箱已被注册); } User user new User(); user.setEmail(request.getEmail()); user.setPassword(passwordEncoder.encode(request.getPassword())); return userRepository.save(user); } }Controller和DTO的生成我就不贴了重点在于整个流程不是“一口气生成完”而是每完成一步都跟你对齐一次。这个“对齐”的过程比生成的代码本身更有价值。3.4 让AI自动跑测试并自查superpowers还可以定义“完成前自查”技能。我给自己的项目配置了一个pre-submit-check技能要求AI在写完代码后主动执行Maven的单测命令并根据测试结果决定是返工还是交付。触发方式是在任务结束时加一句完成后运行 mvn test保证核心逻辑测试通过。实测中AI在跑测试遇到编译错误时会回退到上一步重新修改而不是直接忽略。这一点对项目质量非常重要因为AI写代码最容易栽的地方就是“看起来对一编译就死”。4. 使用指南精讲核心命令、配置项与自定义扩展4.1 常用命令速查用了一段时间之后我把自己最高频的命令整理成了一张表方便你们直接抄走命令作用示例superpowers list列出当前项目已加载的所有技能superpowers listsuperpowers enable skill启用指定技能superpowers enable project-contextsuperpowers disable skill停用指定技能superpowers disable old-rulesuperpowers add-rule file添加一条规则文件superpowers add-rule rules/exception-handling.mdsuperpowers reload重新加载项目技能目录superpowers reloadsuperpowers doctor检查配置、路径和技能文件格式superpowers doctorsuperpowers task add desc --steps ...创建拆分任务superpowers task add 写登录接口 --steps 1. 写DTO; 2. 写Service这些命令我基本每天都会用尤其是reload和doctor一个用于改完配置后快速生效一个用于排查为什么技能没加载。4.2 配置项详解在.superpowers/config.yaml或初始化生成的配置文件中有一些核心配置项值得单独说明。auto_load_context控制是每次对话都自动加载项目上下文还是需要手动触发。我建议保持默认的false因为自动加载会消耗大量上下文窗口导致后面生成代码时可用token变少。手动触发更有控制感。context_max_bytes用于限制项目上下文文件的大小上限。Java项目动辄几百个文件如果无限制扫描AI会把一堆无关文件塞进上下文。我一般设置为 200KB只保留pom.xml、核心配置类和关键目录结构。default_language设定默认技能语言Java项目填java即可。如果项目里还有少量Kotlin代码也可以配置additional_languages。不过我用下来还是建议一个项目一个语言为主混写项目对AI的规则加载负担比较大。下面是一个参考配置auto_load_context: false context_max_bytes: 204800 default_language: java skills_dir: .superpowers/skills rules_dir: .superpowers/rules4.3 自定义技能模板的编写思路除了使用现成的技能包superpowers最大的价值在于你可以自己写技能模板。我不依赖官方模板而是根据团队实际需要编写自己的技能。技能文件的基本结构是Markdown头部加YAML frontmatter。下面这个例子是我写的一个“排查测试失败”技能模板--- name: debug-failed-test description: 当项目测试用例失败时按步骤定位问题。 triggers: [测试失败, 单元测试挂了, mvn test失败] context: - 项目构建工具为Maven - 测试框架为JUnit 5 --- ## 步骤 1. 先执行 mvn test -Dtest指定测试类复现失败。 2. 查看失败堆栈第一行判断是断言失败还是异常抛错。 3. 如果是断言失败找到对应的业务逻辑代码重点比对预期值与实际值。 4. 如果是异常抛错检查是否缺少依赖、空指针、或者数据库连接问题。 5. 修复后再次运行测试确认通过。写完之后放在.superpowers/skills/debug-failed-test.md执行superpowers reload。当你在对话里提到“测试失败”Codex就会自动加载这个技能按照步骤帮你排查。为什么我推荐自己写技能因为每个项目的痛点不一样。官方提供的技能包是通用做法但你团队里的“启动类找不到”“Redis序列化报错”“Maven私服依赖拉不下来”这些具体问题只有你把自己的排查经验写成技能AI才能真正帮上忙。4.4 如何把团队规范做成版本化资产我个人的做法是把.superpowers/目录纳入Git仓库让所有成员共用同一套技能包。每次调整规则都通过merge request流程合入主干。这样团队里的AI行为是统一的不会出现“你的AI不懂异常处理规范我的AI懂”这种混乱。有人可能担心技能文件里包含过多内部敏感信息。这个确实要注意尤其是context/目录下如果抓取了内部服务地址或密钥一定不要提交到公开仓库。可以在.gitignore里排除包含密钥的上下文文件技能规则和任务流程尽量跟代码工程绑定。5. 常见问题与排查技巧实录5.1 安装后 command not found这是最常遇到的安装问题。明明npm安装成功了执行superpowers却报找不到命令。原因几乎都是npm全局bin目录不在PATH里。首先执行npm prefix -g这个命令会输出npm全局安装路径。然后把输出的路径底下的bin目录加到PATH。macOS和Linux通常在~/.zshrc或~/.bashrc里加一行export PATH/path/to/npm/prefix/bin:$PATHWindows用户则需要在系统环境变量里手动加Path。加完之后重新打开终端再执行superpowers --version就能通过了。提示如果全局安装命令权限报错可以检查npm是否用了损坏的全局目录。我自己在macOS上遇到过/usr/local/lib/node_modules权限问题解决办法是把npm全局前缀调整到用户目录下而不是强改系统目录权限。5.2 技能不生效的排查方法技能不生效第一步先看配置路径。在~/.codex/config.toml里配置的skill_dirs路径必须是真实存在的绝对路径。很多人改了配置之后忘了重启Codex或者路径里指到了上一级目录技能自然加载不出来。第二步用superpowers list查看技能状态。如果出现在列表里但对话里不生效八成是触发词没对上。技能文件的triggers列表比较严格比如我写了一个triggers: [spring]的技能如果我在对话里用“Spring”开头但大小写不匹配有些版本可能不触发。建议多写几个变体比如“Spring Boot”“springboot”“写个接口”增加触发命中率。第三步检查技能文件格式。YAML frontmatter写错一个缩进整个文件就会被跳过。用superpowers doctor通常能直接指出哪个文件有问题。5.3 Java项目里AI乱改依赖版本怎么办这是我在Java项目里踩过最深的坑。AI在加载上下文不完整的情况下偶尔会“自作主张”把Spring Boot版本从3.2.5改成3.1.0理由是“修正已知漏洞”。但实际上项目里有一套私有依赖体系随便降级会导致一堆兼容性问题。解决办法是在规则文件里加一条明确约束--- name: dependencies-lock triggers: [版本, dependency, pom.xml, 依赖] --- ## 依赖锁定规则 - 修改pom.xml中任何依赖版本之前必须先向用户确认。 - 未获确认前不得改动parent标签中的版本号。 - 如果需要升级依赖列出当前版本、目标版本、升级原因等待用户批准。加了这条规则之后AI再也不敢乱动版本号了。它会在动手前先问“我准备把xxx从1.0.0升到1.1.0是否可以”。这种“先确认再干活”的交互方式比生成完再去review要节省大量时间。5.4 输出过长被截断怎么办上下文窗口有限让AI一次生成五个Java文件几乎必然出现后半段代码被截断的问题。superpowers的解决思路是“拆小任务”。我习惯把生成目标拆成多个对话或任务步骤一次只让AI生成一个类。比如“现在写UserService接口不要写实现”“现在写UserServiceImpl只写核心逻辑不要写import”。这么做一方面避免截断另一方面也让每次输出更容易检查。如果已经遇到截断最简单的办法是让AI把缺失的部分重新生成一次它会基于之前的对话上下文补充输出。但我不建议依赖这个最好还是设计好任务颗粒度。5.5 技能规则互相冲突怎么处理多个技能文件可能包含冲突规则比如一个文件说“Controller必须返回统一Result对象”另一个文件说“Controller可以直接返回实体类”。superpowers的处理方式是按技能文件名的字母顺序加载后面的会覆盖前面。我建议在规则命名时加一个前缀来控制优先级。比如00-common-rules.md定义最基础的通用规则10-java-style.md定义Java项目特有风格90-project-specific.md定义某个子模块的特殊规则。数字越大优先级越高这样冲突的时候行为是可预期的。结尾一点个人体会现在我基本已经离不开superpowers这套工作流了。说实话它并没有给Codex增加什么智力它做的最重要的事情是让AI在正确的时机看到正确的上下文并且严格按照我认可的顺序去执行任务。就像给一个聪明但没经验的新人配了一套完整的操作SOP和团队制度剩下的发挥就看它自己了。最后再分享一个小技巧我除了把编码规范写进技能包还会把每次解决典型Bug的排查思路也沉淀成技能文件。时间长了项目里的.superpowers/skills/就像一本不断更新的团队知识库。AI不再是“你的人肉搜索”而是一个能读懂团队经验老手的编码协作者。这个方向我觉得还有很多可以玩的空间比如把历史故障案例、性能优化检查项、甚至发布回滚流程都加进去。反正技能包就是纯文本文件改起来不心疼大家可以放心大胆去试。
最近我一直在折腾Codex CLI原本以为装好之后就能让AI老老实实写代码结果发现默认状态下的Codex顶多算个“会用搜索引擎的实习生”——你说一步它动一步说的不细它写跑偏更别提什么代码风格统一、依赖版本检查、异常处理规范。真正让它从“能用”变成“好用”的是一套叫superpowers的技能包。这名字听着中二实际却很贴切它把提示词工程、代码库索引规则和复杂任务拆解策略打成一个开箱即用的配置框架让AI在动手写代码之前先想清楚“你是什么项目、有什么约束、该按什么顺序干活”。这篇文章主要聊两件事一是superpowers的安装和使用指南二是怎么在Java项目里把它的能力真正发挥出来。不管你是刚开始接触AI编程助手还是已经在团队里推Codex这篇文章都值得花十分钟看完。1. Superpowers到底是什么一个给AI编程助手叠Buff的配置框架1.1 Codex与Superpowers的关系Codex本身是一个对话式编码助手它能理解自然语言、写代码、跑命令但它的默认行为是“你问什么它答什么”缺少主动搜集上下文的能力。这在实际项目里很致命你让AI“写一个用户注册接口”它大概率直接给你甩一个Controller出来既不看你项目里的Service层叫什么也不管你用的Spring Boot是哪个版本甚至可能生成一个Java 8写的类让你在Java 17的项目里直接编译不过。superpowers的核心是一个“技能包”机制。每个技能包由一组Markdown文件组成里面定义了任务步骤、代码规范、上下文获取命令和输出格式。当Codex加载superpowers之后它就不再是一个单次对话的问答工具而是一个会按照技能包里的策略先扫描项目结构、读取pom.xml或build.gradle、分析包名规则然后再给出方案的“结构化编码助手”。我打个比方默认Codex像一个刚进公司的新人聪明但不懂规矩superpowers就是一份新员工手册告诉它“去哪个目录拿需求文档、代码要遵守什么规范、完成工作的标准是什么”。没有手册它纯靠临场发挥有了手册它才真正开始干活。1.2 为什么不用直接改系统提示词很多人第一反应是既然superpowers本质是提示词那我直接在Codex的系统提示词里写清楚不就行了我一开始也这么想但实测下来有三个绕不开的问题。第一提示词过长会被截断。Codex的上下文窗口是有限的你把“所有项目规范、所有技术栈说明、所有编码风格要求”一股脑塞进去还没开始写代码上下文就快满了。superpowers采用按需加载的方式只有对话中出现特定触发词时对应的技能包才注入上下文利用率高很多。第二全局系统提示词无法适配项目差异。一个人可能同时维护Spring Boot老项目和Quarkus新项目两套规范完全不一样。你把规则写死在全局配置里AI切换项目时就会犯糊涂。superpowers允许每个项目有自己的.superpowers/目录项目A和项目B互不干扰。第三默认对话没有任务拆分和验证步骤。直接让Codex“写一个用户注册接口”它往往会一口气把所有代码吐出来中间不做任何确认也不自查。而superpowers可以定义“先分析实体、再定DTO、再写Service、最后Controller每步完成之后停下让我确认”的任务流让AI从“莽夫”变成“稳一点的老哥”。1.3 它解决的核心痛点总结一下superpowers主要解决了这四个真实痛点上下文缺失AI不知道项目的依赖版本、包名前缀、代码分层方式生成的代码经常不兼容现有工程。superpowers提供了项目上下文采集技能让AI在动笔前先“读”项目。任务颗粒度太粗“写一个用户注册接口”这句话颗粒度太大。superpowers可以把任务拆成多个可验证的小步骤每步输出都经过确认避免一步错步步错。规范不一致团队编码规范往往只写在文档里AI根本看不到。superpowers把规范做成技能包AI触发相关关键词时自动加载生成风格能跟团队现有代码对齐。不可回溯直接在提示词里改规矩改了之后说不清哪次改了。superpowers的技能包是文件可以进Git仓库review、回溯、对比全都能做。2. 安装与初始配置从零到能跑通一个演示任务2.1 环境准备与前置依赖我的实测环境是macOS Node.js 20 LTS GitLinux和Windows的操作基本一致。开始之前请先在终端确认下面这些命令能正常工作node -v npm -v git --version codex --version如果你的codex命令还不存在先装好Codex CLI并完成登录确保它能正常发起对话。我见过不少朋友跳过这一步直接装superpowers最后发现Codex根本没接上白白折腾半天。另外提醒一句superpowers本身不是模型它不会替你做AI推理。它需要的是一个能执行外部工具、读取本地文件的编码助手底座。目前我用下来Codex CLI是最顺手的宿主环境理论上其他支持技能注入的编码助手也可以但本文的例子都基于Codex。注意安装之前建议先跑一遍codex随便问个问题比如“用Java写一个Hello World”确认能正常回答。如果这一步都卡住先解决Codex的登录和网络问题再看下面的内容。2.2 安装Superpowers的三种典型方式方式一全局安装CLI适合日常频繁使用的场景。npm install -g superpowers/cli安装完成后用superpowers --version确认版本信息。我这边装到的是1.4.x版本命令结构和配置项在不同小版本之间偶尔有微调遇到参数对不上就以你本地的--help输出为准。方式二通过npx临时拉起适合只想在某个项目里试一下的人。npx superpowers initnpx会自动下载并执行最新版不需要全局污染Node环境。缺点是每次执行都可能重新拉包多多少少会慢一点。我一般建议重度用户用全局安装尝鲜用户用npx。方式三从源码安装适合想改源码或者研究内部实现的人。从官方仓库克隆下来之后依次执行npm install npm run build npm link这种方式能让你随时切分支测试新功能但对大多数人没必要。我更推荐直接用npm包。2.3 在项目里初始化技能包安装好了之后进入你的Java项目目录执行cd your-java-project superpowers init --language java这个命令会做三件事创建.superpowers/目录在目录下生成skills/、rules/、context/三个子目录根据--language java参数生成一套Java项目通用的基础技能模板。初始化之后记得把技能包挂载到Codex配置里。这一步特别容易漏。你需要编辑~/.codex/config.toml加入类似这样的配置[experimental] skill_dirs [/绝对路径/your-java-project/.superpowers/skills, /绝对路径/your-java-project/.superpowers/rules]注意我这里建议写绝对路径。之前我用相对路径踩过坑因为Codex解析相对路径时是相对于它自己的工作目录而不是项目目录。切换项目之后经常加载不到技能包改成绝对路径就再也没出过问题。配置保存之后重启Codex CLI接着在对话里问列出你已经加载的所有技能。如果能看到java-style、project-context之类的技能名说明superpowers已经生效了。2.4 验证安装是否成功最后再跑一遍superpowers doctor它会检查配置文件和技能目录的有效性输出每个技能文件是否有格式错误以及Codex配置文件里挂载的路径是否真实存在。我每次改完规则之后都会跑一次算是省心小帮手。如果一切正常你会看到类似下图的输出状态提示技能已加载数量、规则文件数量、配置路径是否正确。这里我不贴终端截图了反正核心就是看最后一行是不是all checks passed。3. 实战过程用Superpowers驱动Codex改造一个Java项目3.1 先让AI“读”项目再让它“写”代码默认情况下Codex不会主动去翻你项目里的几十个文件。它更像一个“即问即答”的助手问题范围只限于你提供的上下文。superpowers里的project-context技能就是为了解决这个问题。在对话中触发这个技能的方式是发送指令关键词比如了解项目。或者直接说加载项目上下文重点关注Spring Boot版本、Java版本、包名前缀和已有Controller的命名习惯。技能被触发后Codex会执行一组工具命令读取根目录的README.md、解析pom.xml、扫描src/main/java下的包结构、识别启动类位置。执行完这些之后它会返回一份压缩的项目摘要。实际工作中我会在开始一个任务前先花30秒让AI加载上下文确认它知道项目里用的是Spring Boot 3.2.5、Java 17、包名是com.example.platform而且已有的Controller都以/v1/xxx作为前缀。这样一来AI后续生成的代码基本不会出现“把Java 8语法塞进Java 17项目”这种低级错误。3.2 把团队编码规范注入技能包团队里最怕的是什么是每个程序员写出来的风格都不一样。更怕的是AI写出来的风格跟团队里谁也不一样。superpowers允许我在.superpowers/rules/java-style.md里定义强规则AI只要触发关键词就会自动遵守。举个例子我服务过的一个团队有很明确的规范Controller只做参数绑定和调度不允许写业务逻辑Service接口和实现必须分离所有请求DTO必须用jakarta.validation注解禁止System.out.println异常统一交给GlobalExceptionHandler。我把这些写成一个规则文件--- name: java-style triggers: [java, spring, controller, service, dto, mapper] --- ## 强制规则 - Controller只做参数绑定和调用Service不允许写业务逻辑。 - Service接口必须与Impl分离接口命名用XxxService实现类命名用XxxServiceImpl。 - 请求DTO使用jakarta.validation注解校验失败统一抛BizException。 - 禁止使用System.out.println一律使用SLF4J。 - 异常处理走GlobalExceptionHandler不能在各层自行catch后吞掉。保存之后在.superpowers目录下执行superpowers reload让配置重新加载。然后再开一个新对话向Codex提一个包含“Spring”或“Controller”关键词的需求比如“写一个分页查询用户的Controller”它就会自动把上面这些规则纳入生成代码的约束。实测下来这套配置的效果非常明显。AI生成的代码直接符合团队规范review的时候少了很多“这里为什么要这样写”的争论。我说个真实感受以前用Codexcode review基本是在审查AI接入superpowers之后code review变成了对照规则逐项打勾省心太多。3.3 复杂任务拆解以写一个用户注册接口为例面对“写一个用户注册接口”这种任务我强烈建议用superpowers的任务拆分功能。命令是这样的superpowers task add 实现用户注册接口 --steps 1.分析现有User实体和数据库表;2.定义RegisterRequest DTO并加校验注解;3.实现UserService与UserServiceImpl;4.实现UserController;5.在GlobalExceptionHandler中补参数字校验异常映射任务添加成功后Codex会看到这个任务及对应步骤。它不会一次性把所有代码吐给你而是从第一步开始完成之后问你“这是第一步的结果是否继续下一步”。我通常会在第三步之后先停下来检查代码确认Service层接口命名和依赖注入方式符合现有工程再让它继续。这里贴一个简化版的生成效果注意它已经遵循了规则文件里“接口与实现分离”的要求// UserService.java public interface UserService { User register(RegisterRequest request); }// UserServiceImpl.java Service RequiredArgsConstructor Slf4j public class UserServiceImpl implements UserService { private final UserRepository userRepository; private final PasswordEncoder passwordEncoder; Override public User register(RegisterRequest request) { if (userRepository.existsByEmail(request.getEmail())) { throw new BizException(邮箱已被注册); } User user new User(); user.setEmail(request.getEmail()); user.setPassword(passwordEncoder.encode(request.getPassword())); return userRepository.save(user); } }Controller和DTO的生成我就不贴了重点在于整个流程不是“一口气生成完”而是每完成一步都跟你对齐一次。这个“对齐”的过程比生成的代码本身更有价值。3.4 让AI自动跑测试并自查superpowers还可以定义“完成前自查”技能。我给自己的项目配置了一个pre-submit-check技能要求AI在写完代码后主动执行Maven的单测命令并根据测试结果决定是返工还是交付。触发方式是在任务结束时加一句完成后运行 mvn test保证核心逻辑测试通过。实测中AI在跑测试遇到编译错误时会回退到上一步重新修改而不是直接忽略。这一点对项目质量非常重要因为AI写代码最容易栽的地方就是“看起来对一编译就死”。4. 使用指南精讲核心命令、配置项与自定义扩展4.1 常用命令速查用了一段时间之后我把自己最高频的命令整理成了一张表方便你们直接抄走命令作用示例superpowers list列出当前项目已加载的所有技能superpowers listsuperpowers enable skill启用指定技能superpowers enable project-contextsuperpowers disable skill停用指定技能superpowers disable old-rulesuperpowers add-rule file添加一条规则文件superpowers add-rule rules/exception-handling.mdsuperpowers reload重新加载项目技能目录superpowers reloadsuperpowers doctor检查配置、路径和技能文件格式superpowers doctorsuperpowers task add desc --steps ...创建拆分任务superpowers task add 写登录接口 --steps 1. 写DTO; 2. 写Service这些命令我基本每天都会用尤其是reload和doctor一个用于改完配置后快速生效一个用于排查为什么技能没加载。4.2 配置项详解在.superpowers/config.yaml或初始化生成的配置文件中有一些核心配置项值得单独说明。auto_load_context控制是每次对话都自动加载项目上下文还是需要手动触发。我建议保持默认的false因为自动加载会消耗大量上下文窗口导致后面生成代码时可用token变少。手动触发更有控制感。context_max_bytes用于限制项目上下文文件的大小上限。Java项目动辄几百个文件如果无限制扫描AI会把一堆无关文件塞进上下文。我一般设置为 200KB只保留pom.xml、核心配置类和关键目录结构。default_language设定默认技能语言Java项目填java即可。如果项目里还有少量Kotlin代码也可以配置additional_languages。不过我用下来还是建议一个项目一个语言为主混写项目对AI的规则加载负担比较大。下面是一个参考配置auto_load_context: false context_max_bytes: 204800 default_language: java skills_dir: .superpowers/skills rules_dir: .superpowers/rules4.3 自定义技能模板的编写思路除了使用现成的技能包superpowers最大的价值在于你可以自己写技能模板。我不依赖官方模板而是根据团队实际需要编写自己的技能。技能文件的基本结构是Markdown头部加YAML frontmatter。下面这个例子是我写的一个“排查测试失败”技能模板--- name: debug-failed-test description: 当项目测试用例失败时按步骤定位问题。 triggers: [测试失败, 单元测试挂了, mvn test失败] context: - 项目构建工具为Maven - 测试框架为JUnit 5 --- ## 步骤 1. 先执行 mvn test -Dtest指定测试类复现失败。 2. 查看失败堆栈第一行判断是断言失败还是异常抛错。 3. 如果是断言失败找到对应的业务逻辑代码重点比对预期值与实际值。 4. 如果是异常抛错检查是否缺少依赖、空指针、或者数据库连接问题。 5. 修复后再次运行测试确认通过。写完之后放在.superpowers/skills/debug-failed-test.md执行superpowers reload。当你在对话里提到“测试失败”Codex就会自动加载这个技能按照步骤帮你排查。为什么我推荐自己写技能因为每个项目的痛点不一样。官方提供的技能包是通用做法但你团队里的“启动类找不到”“Redis序列化报错”“Maven私服依赖拉不下来”这些具体问题只有你把自己的排查经验写成技能AI才能真正帮上忙。4.4 如何把团队规范做成版本化资产我个人的做法是把.superpowers/目录纳入Git仓库让所有成员共用同一套技能包。每次调整规则都通过merge request流程合入主干。这样团队里的AI行为是统一的不会出现“你的AI不懂异常处理规范我的AI懂”这种混乱。有人可能担心技能文件里包含过多内部敏感信息。这个确实要注意尤其是context/目录下如果抓取了内部服务地址或密钥一定不要提交到公开仓库。可以在.gitignore里排除包含密钥的上下文文件技能规则和任务流程尽量跟代码工程绑定。5. 常见问题与排查技巧实录5.1 安装后 command not found这是最常遇到的安装问题。明明npm安装成功了执行superpowers却报找不到命令。原因几乎都是npm全局bin目录不在PATH里。首先执行npm prefix -g这个命令会输出npm全局安装路径。然后把输出的路径底下的bin目录加到PATH。macOS和Linux通常在~/.zshrc或~/.bashrc里加一行export PATH/path/to/npm/prefix/bin:$PATHWindows用户则需要在系统环境变量里手动加Path。加完之后重新打开终端再执行superpowers --version就能通过了。提示如果全局安装命令权限报错可以检查npm是否用了损坏的全局目录。我自己在macOS上遇到过/usr/local/lib/node_modules权限问题解决办法是把npm全局前缀调整到用户目录下而不是强改系统目录权限。5.2 技能不生效的排查方法技能不生效第一步先看配置路径。在~/.codex/config.toml里配置的skill_dirs路径必须是真实存在的绝对路径。很多人改了配置之后忘了重启Codex或者路径里指到了上一级目录技能自然加载不出来。第二步用superpowers list查看技能状态。如果出现在列表里但对话里不生效八成是触发词没对上。技能文件的triggers列表比较严格比如我写了一个triggers: [spring]的技能如果我在对话里用“Spring”开头但大小写不匹配有些版本可能不触发。建议多写几个变体比如“Spring Boot”“springboot”“写个接口”增加触发命中率。第三步检查技能文件格式。YAML frontmatter写错一个缩进整个文件就会被跳过。用superpowers doctor通常能直接指出哪个文件有问题。5.3 Java项目里AI乱改依赖版本怎么办这是我在Java项目里踩过最深的坑。AI在加载上下文不完整的情况下偶尔会“自作主张”把Spring Boot版本从3.2.5改成3.1.0理由是“修正已知漏洞”。但实际上项目里有一套私有依赖体系随便降级会导致一堆兼容性问题。解决办法是在规则文件里加一条明确约束--- name: dependencies-lock triggers: [版本, dependency, pom.xml, 依赖] --- ## 依赖锁定规则 - 修改pom.xml中任何依赖版本之前必须先向用户确认。 - 未获确认前不得改动parent标签中的版本号。 - 如果需要升级依赖列出当前版本、目标版本、升级原因等待用户批准。加了这条规则之后AI再也不敢乱动版本号了。它会在动手前先问“我准备把xxx从1.0.0升到1.1.0是否可以”。这种“先确认再干活”的交互方式比生成完再去review要节省大量时间。5.4 输出过长被截断怎么办上下文窗口有限让AI一次生成五个Java文件几乎必然出现后半段代码被截断的问题。superpowers的解决思路是“拆小任务”。我习惯把生成目标拆成多个对话或任务步骤一次只让AI生成一个类。比如“现在写UserService接口不要写实现”“现在写UserServiceImpl只写核心逻辑不要写import”。这么做一方面避免截断另一方面也让每次输出更容易检查。如果已经遇到截断最简单的办法是让AI把缺失的部分重新生成一次它会基于之前的对话上下文补充输出。但我不建议依赖这个最好还是设计好任务颗粒度。5.5 技能规则互相冲突怎么处理多个技能文件可能包含冲突规则比如一个文件说“Controller必须返回统一Result对象”另一个文件说“Controller可以直接返回实体类”。superpowers的处理方式是按技能文件名的字母顺序加载后面的会覆盖前面。我建议在规则命名时加一个前缀来控制优先级。比如00-common-rules.md定义最基础的通用规则10-java-style.md定义Java项目特有风格90-project-specific.md定义某个子模块的特殊规则。数字越大优先级越高这样冲突的时候行为是可预期的。结尾一点个人体会现在我基本已经离不开superpowers这套工作流了。说实话它并没有给Codex增加什么智力它做的最重要的事情是让AI在正确的时机看到正确的上下文并且严格按照我认可的顺序去执行任务。就像给一个聪明但没经验的新人配了一套完整的操作SOP和团队制度剩下的发挥就看它自己了。最后再分享一个小技巧我除了把编码规范写进技能包还会把每次解决典型Bug的排查思路也沉淀成技能文件。时间长了项目里的.superpowers/skills/就像一本不断更新的团队知识库。AI不再是“你的人肉搜索”而是一个能读懂团队经验老手的编码协作者。这个方向我觉得还有很多可以玩的空间比如把历史故障案例、性能优化检查项、甚至发布回滚流程都加进去。反正技能包就是纯文本文件改起来不心疼大家可以放心大胆去试。
