用过Codex CLI的朋友应该都有同感：这玩意儿确实强，但总有点“偏科”。你让它写点通用代码、做个小工具，它行云流水；可一旦切换到某个具体技术栈，比如Java的Spring Boot项目、或者带复杂构建流程的工程，它就开始泛泛而谈，给出来的方案总是隔着一层。superpowers就是冲着这个痛点来的——它不是替代Codex，而是给Codex装上一套“外挂技能包”，让它能在特定语言、特定框架下真正干出老手级别的活。这篇文章我会从设计思路、安装配置到Java实战逐步拆解，把我在实际项目中把这套工具用起来的完整过程分享出来，适合那些已经在用Codex CLI、或者打算入门的开发者参考。
1. 项目整体设计与思路拆解
1.1 从Codex CLI到superpowers：为什么需要这么一层
先说个场景。你用Codex CLI让它写一个Spring Boot的接口，它大概率会给你生成一个差不多的Controller、Service、Repository，结构没什么毛病，但细节会出问题：包名不对、依赖版本冲突、缺少异常处理、没考虑事务边界。这不是Codex笨，而是它缺少你项目的“语境”。
通用大模型的知识是广而不深的。它知道Java，知道Spring，但它不知道你的项目用了哪个版本的Spring Boot、是否引入了Lombok、有没有统一返回体、异常是怎么处理的。这种“项目级的约定”如果不告诉它，它只能按广义上的最佳实践来写，写出来的东西放进你的工程里，自然会有违和感。
superpowers解决的正是这个问题。它的核心机制是“技能（skills）”：把特定语言、特定框架的最佳实践、项目结构和常见约定打包成结构化的说明文件。当Codex CLI运行时，superpowers会把这些技能注入到对话上下文中，相当于你进场前先塞给了Codex一本《本项目开发手册》。它写出来的代码，从“像是懂Java的人写的”变成“就像是你们团队里那个Java老手写的”。
1.2 核心概念拆解：技能、技能包与配方
刚开始接触superpowers，最容易被它一堆术语绕晕。我拆开来讲，其实就三层东西。
第一层叫“技能（skill）”，这是最小的功能单元。一个技能描述“怎么做一件具体的事”，比如“用Maven管理依赖的正确姿势”“写RESTful API时的命名规范”“处理Java异常的统一策略”。每个技能是一个独立的Markdown文件，里面有背景说明、操作步骤、示例代码和禁忌事项。它的写法很像你在团队Wiki里看到的那种“开发规范”文档，只是结构更严谨、更贴合AI阅读。
第二层叫“技能包（skills pack）”，是技能的集合。比如“Java技能包”会包含Maven构建、Spring Boot开发、JUnit测试、Lombok约定、日志规范等等一组相关技能。“Python技能包”则是另一组。装上技能包，就等于给Codex一次性加载了一整套针对某个技术栈的知识上下文。
第三层叫“配方（recipe）”，是跨技能的工作流。它定义“完成一个目标要依次调用哪些技能”，比如“从零搭建一个Spring Boot项目”这个配方，会先加载“Maven配置”技能，再加载“项目结构”技能，然后是“编写Controller”“编写Service”等等。配方把技能串成了一条流水线。
我举个好懂的例子。技能是《中餐厅后厨手册》里的“切菜标准”“炒菜火候”“摆盘规范”，技能包就是一本完整的《中餐厨师培训教材》，而配方是一份“今晚出一桌宴席”的执行顺序。Codex默认只会炒菜，superpowers给了它整套后厨的规矩，它做出来的菜自然不一样。
1.3 技能加载的底层逻辑：提示词工程与指令合并
superpowers的底层机制并不神秘，原理还是提示词工程，只不过它把提示词工程做得高度工程化了。
在默认情况下，Codex CLI启动一个会话时，读到的上下文只有对话历史和基本的系统提示词。superpowers做的事，是在会话初始化时，根据你当前的项目类型、你指定的目标，动态挑选一批技能文件，把这些文件的内容合并进系统提示词里。你可以把它理解为“动态拼装超级提示词”。
具体来说，它会读取你的项目配置（比如检测到pom.xml、build.gradle就认为这是Java工程），然后从已安装的技能库里匹配对应的技能包。匹配完成后再把技能内容拼接到一份“指令合并文件”中，Codex每次对话都会参考这部分内容。
这个过程有几个关键点决定了效果：
第一，技能文件的格式要规范。不是随便写几句“不要用旧API”就能当技能，而是要有目的、适用场景、操作步骤、代码示例、反面示例这几个结构块。AI读结构化内容远比读散装段落来得稳定。
第二，指令拼接的顺序有讲究。通用技能放前面，具体技能放后面，这样Codex先建立“项目级共识”，再进入“任务级细节”，上下文不会互相打架。
第三，技能的篇幅要克制。一次性塞50个技能文件，Codex会“消化不良”，关键指令被淹没在大段文本里。精挑细选，一次只加载与当前任务相关的10个以内技能，效果才会好。
理解了这层原理，你才能真正用好superpowers——不只是装好了就用，而是会自己调整技能内容，让它越来越贴合你的团队和项目。
2. 环境准备与安装流程实录
2.1 前置环境：Codex CLI、Node.js、Git
提一句，superpowers不是一个独立运行的AI引擎，它是Codex CLI的增强层，所以前提是先有一个能正常工作的Codex CLI环境。
我建议Node.js用18及以上版本，太老的话有些依赖装不上，会平白多出一堆报错。装完Node后，检查一下环境变量有没有配好，终端里执行node -v和npm -v能正常输出版本号就行了。
Codex CLI的安装方式我不过多展开了，简单说就是通过npm全局安装。装完以后先确认它能正常跑起来——随便让它写个“Hello World”程序试试水。这里有个小提醒：如果Codex CLI本身连账号授权、API配置都没搞定，先不要碰superpowers，否则出问题你会分不清是哪一层的故障。先把底层打通，再往上叠工具，排查问题时心里才有谱。
Git也是必需品，两个用途：一是拉取技能包仓库，二是superpowers本身在初始化时可能会用到Git来做版本管理。
2.2 安装superpowers并完成初始化
装superpowers本身并不复杂，跟装其他命令行工具一样，一条npm全局安装命令就搞定。装完以后，执行初始化命令，它会在你的用户目录下建立一个配置文件目录，用来存放技能库、自定义配置和日志。
我第一次安装时踩了一个小坑：装完之后直接执行初始化，提示找不到命令。后来发现是npm的全局bin目录没有加到PATH里。这个在macOS上特别常见，npm全局包的bin目录通常指向/usr/local/bin或者用户目录下的.npm-global/bin，你得确认它在echo $PATH的输出里。没加的话，要么手动加，要么重新设置npm的prefix路径。
初始化完成之后，建议先看一眼生成的配置目录结构。它一般会有一个skills目录（用于存放下载的技能包）、一个config目录（存放配置文件），还有一个cache目录。了解这些目录的位置，后面手动调试技能时会方便很多。
2.3 与Codex CLI整合：AGENTS.md的妙用
superpowers和Codex CLI之间有个关键的“接线”步骤：项目级说明文件。
用过Codex CLI的人应该知道，它支持读取项目根目录下的AGENTS.md文件作为项目的“自我介绍”。superpowers的整合方式就是利用这个机制——在项目初始化时，它会生成或修改一份AGENTS.md，在里面写清楚“这是一个Java项目，请加载Java技能包”“构建工具是Maven，请遵守Maven技能中的规范”之类的指引。
我强烈建议你理解这个文件的作用，因为它其实就是整个系统的“总开关”。如果你发现superpowers明明装好了、技能包也装了，但Codex写出来的代码依然“没内味”，十有八九是这份AGENTS.md没写好，或者Codex CLI没启用读取该文件的配置。
在我实际的工程里，AGENTS.md通常写得非常具体，比如：
# 项目说明 - 技术栈：Java 17、Spring Boot 3.x、MyBatis-Plus - 构建工具：Maven - 代码风格：遵循阿里巴巴Java开发手册 - 异常处理：统一使用BizException，由全局异常处理器捕获 - 数据库：MySQL，主键使用雪花ID - 务必先阅读以下技能：java/spring-boot、java/maven、java/exception-handling这样一来，Codex每次进入项目，第一时间就“读到”了这些约定，后面生成代码时就会主动匹配这套规范。没有这些，superpowers就只是一堆躺在硬盘里的Markdown文件，发挥不了作用。
3. 技能机制深度拆解与自定义
3.1 官方技能包清单与适用场景
superpowers的官方技能库里，我见过并且实际用过的有这么几个方向，先列出来给大家参考：
| 技能包 | 适用场景 | 核心覆盖内容 |
|---|---|---|
| java | Java后端开发 | Maven/Gradle构建、Spring Boot、JUnit、异常处理、日志规范 |
| python | Python项目 | 虚拟环境、类型标注、PEP8、pytest测试、项目结构 |
| typescript | 前端/Node项目 | npm/yarn/pnpm、tsconfig规范、ESLint、React/Vue约定 |
| git | 版本控制辅助 | 提交信息规范、分支管理、冲突处理策略 |
| code-review | 代码审查 | 审查维度、常见缺陷模式、优化建议框架 |
| database | SQL开发 | 建表规范、索引设计、慢查询分析、事务使用规范 |
这里我多说一句：千万别把技能包当成“装了就能学到知识”的东西，它是“装了AI就知道规矩”的东西。比如你装java技能包，并不是让你自己去看里面的Java知识，而是让Codex写代码时有一个“Java老手在旁边监督”。它对你开发水平的提升是间接的——通过更好的AI辅助来体现。
选技能包的原则很简单：按项目技术栈装，别贪多。你一个前端项目装上database技能包，不仅没用，还会因为上下文变长而拖慢响应，甚至干扰Codex对其他指令的执行。
3.2 自定义技能：写给自己的“专属说明书”
如果说安装官方技能包是“用现成的经验”，那自定义技能就是“沉淀自己的经验”。这是superpowers真正值钱的地方。
我举个例子。我们团队的Java项目有一个约定：所有Controller返回统一格式的ResponseResult<T>，结构是{code, message, data}。这个约定在团队Wiki里写得很清楚，但Codex不知道，每次生成的代码都是裸返回，还得人工改。官方Java技能包里也不可能有你们公司的私有约定。
解决方案是写一个自定义技能文件，内容大致这样：
# 统一返回体规范 ## 目的 确保所有Controller层的接口返回统一格式的ResponseResult。 ## 适用场景 所有Spring Boot接口方法。 ## 操作步骤 1. Controller方法的返回值类型必须是ResponseResult<T>。 2. 成功时使用ResponseResult.success(data)。 3. 失败时抛出BizException，由全局异常处理器转换。 ## 代码示例 @GetMapping("/users/{id}") public ResponseResult<UserVO> getUser(@PathVariable Long id) { return ResponseResult.success(userService.getUser(id)); } ## 反面示例 @GetMapping("/users/{id}") public UserVO getUser(@PathVariable Long id) { return userService.getUser(id); }然后把这个文件放到skills/custom/java-team/目录下，再在AGENTS.md里加上一句“同时阅读custom/java-team/response-result技能”。从那以后，Codex生成的接口代码基本不用改返回类型这一层。
这就是自定义技能的价值：AI使用者的核心能力，正在从“会提问”转向“会定义规则”。你定义得越清晰，AI交付得越精准。
3.3 技能生效的调试方法
很多人在使用中会遇到一种尴尬的情况：技能文件写了、也配置了，但Codex的行为没有变化。这时候需要用“调试思维”而不是“抱怨思维”。
我的经验是分三步排查：
第一步，看技能有没有被加载。superpowers有调试模式，开启后会在日志里打印“当前会话加载了哪些技能文件”。这个是最直接的验证方式。如果日志里根本没有你的技能文件路径，那就说明你的配置路径写错了，或者文件名没匹配上。
第二步，看技能内容有没有进入上下文。有些时候技能文件被加载了，但内容被截断或者排到了很靠后的位置，导致Codex“没注意到”。这时候需要精简技能内容，把最关键的指令尽量往前放。一条技能写太长，反而不是好事。
第三步，看Codex的输出有没有“用上”技能。这需要你对比开/关技能两次生成的代码差异。差异越明显，说明技能越有效；几乎没差异，说明技能内容对AI的约束力太弱，需要强化措辞或者补充反面示例。
多说一个合格技能文件的检查习惯：好的技能文件一定有完整的适用场景和反面示例。反面示例尤其重要，大模型从“不要这么做”中学到的，往往比“应该这么做”更多。
4. Java场景实操：Spring Boot项目实战
4.1 安装并加载Java技能包
理论讲再多，不如来一次完整实操。我用最近做的一个内部管理系统为例，展示从安装Java技能包到跑通一个RESTful API的整个过程。
先装Java技能包。superpowers提供了简单的子命令，一条命令搞定。装完以后，先确认技能包文件完整地落盘了，再去项目根目录检查或者生成AGENTS.md，确保里面写明了加载Java技能包。
我习惯在AGENTS.md里写得非常明确：
- 加载java/spring-boot技能 - 加载java/maven技能 - 加载java/exception-handling技能 - 加载custom/java-team/response-result技能 - 加载custom/java-team/mapper规范技能宁可多列两条，也不要用一句“加载所有Java技能”糊弄过去。明确列出技能名，Codex才清楚要“调用哪些知识”，否则它会自行猜测，一猜就容易跑偏。
4.2 实战案例：生成一个基于Spring Boot的RESTful API
这次的需求是给系统加一个“用户积分明细查询”的接口，分页返回，包含积分变动类型、变动值、余额快照和变动时间。按我的经验，这种接口写起来不难，但坑位很多：分页参数怎么定、变动类型用什么枚举、积分余额的精度用什么类型，每个细节都可能被Codex写错。
打开Codex CLI，进入项目目录，启动一个会话。因为AGENTS.md已经写好了，理论上superpowers会自动加载技能。如果用的是支持--load参数的方式，也可以用命令主动指定。
我发出的需求是：
请为会员系统新增一个接口：查询会员积分明细，按时间倒序分页返回。字段包括：积分变动类型、变动积分值、变动后余额、变动时间、订单编号（可为空）。使用标准分页参数page、pageSize，返回统一格式ResponseResult<PageResult<PointDetailVO>>。注意我这段话里包含了几个关键约束：分页参数名、返回格式、字段列表。这些信息如果需求里不给，Codex会自己拍脑袋定，大概率和你团队现有代码对不上。给AI一个“填空式”问题，它就能产出“填空式”的准确答案——问题越具体，答案越可控。
Codex在superpowers加持下完成的东西让我比较满意。它自动识别出项目用的是MyBatis-Plus，生成的Mapper接口带着@Mapper注解，分页用了Page对象，积分变动类型直接用了现有枚举PointChangeType，异常处理统一抛BizException。这些细节，没有加载技能之前它从来没写对过。
4.3 与Codex CLI联动的完整操作链
把整条操作链拉通来看，一次成功的使用流程如下：
- 在项目根目录确认
AGENTS.md存在且技能配置正确。 - 启动Codex CLI，确认加载了superpowers配置。
- 用调试模式跑一次简单需求，确认真实调用了技能包。
- 发出具体需求，尽量包含约束条件。
- 检查生成的代码，重点看是否符合技能中定义的规范。
- 如果需要调整，在对话里补充约束，或者回头改技能文件。
这条链路跑顺之后，效率提升是很明显的。我自己的体感是：以前让Codex写完一个接口，我至少要手改两三处“团队规范级别”的问题；现在基本一次生成就能过code review，偶尔需要微调一下命名或补充注释。
别把superpowers当成“一键生成完美代码”的神器，它的定位是“让你的AI队友更懂你们团队的潜规则”。有了它，Codex从“聪明的新人”变成了“懂规矩的老师傅”，但最终交付质量的把关人，还是你自己。
5. 常见问题与排查技巧实录
5.1 高频问题速查表
用了一段时间，我把经常遇到的问题整理成了一个速查表，分享出来。
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 技能不生效，代码没变化 | AGENTS.md没写清楚或Codex未启用读取 | 检查项目根目录是否有AGENTS.md，确认内容明确列出技能名 |
| 技能包安装后找不到文件 | npm全局bin目录未配置PATH | echo $PATH检查，将npm全局bin目录加入环境变量 |
| Codex响应变慢很多 | 加载了过多无关技能 | 精简技能包，只保留与当前项目技术栈相关的 |
| 技能内容被截断 | 单个技能文件太长 | 拆分为多个聚焦的小技能，每条控制在150行以内 |
| 自定义技能不生效 | 文件路径配置错误 | 开启调试模式，确认日志中技能文件的加载路径 |
| 生成的代码依然不符合团队规范 | 技能中缺少明确的“反面示例” | 补上反面示例，用“禁止”“不要”等强约束词写明禁区 |
| 多个技能内容冲突 | 不同技能对同一场景给出了不一致约定 | 检查技能间的重叠内容，保留一份最权威的，其余删掉或改为引用 |
这个表是我踩过几次坑之后沉淀下来的，每次遇到类似问题，我都是先对着表排查一遍，基本能解决九成的情况。剩下的那一成，要么是新版本工具的兼容问题，要么是自己技能写法本身有逻辑矛盾，需要静下心重新读一遍技能内容。
5.2 我的避坑经验
最后分享几个我实际用下来的心得，算不上系统的方法论，但每条都是从真实项目里磨出来的。
第一，不要一开始就追求“全面覆盖”。我第一次用superpowers的时候，兴致勃勃把Java、Python、数据库、代码审查等四五个技能包全装上了，结果Codex的速度肉眼可见地慢了下来，输出质量也没变好。后来把无关技能全部卸载，只留Java和Git相关的，效果反而立刻提升了。根据任务场景按需加载，才是正确的使用姿势。
第二，技能是“活”的，需要持续迭代。每当你发现Codex在某一类问题上反复出错，想清楚是不是缺了一条对应的技能规则。团队规范变了，同步更新技能文件，这和自己维护技术文档是一样的——过期文档比没有文档更可怕。不妨给技能文件加个“最后更新日期”字段，强迫自己定期review。
第三，自定义技能一定放在独立目录里。我曾经直接修改官方技能包里的文件，下次升级工具，改动全部被覆盖了。正确的做法是建立自己的skills/custom/目录，把团队私有规范放在这里。官方技能负责“通用最佳实践”，自定义技能负责“团队特定约定”，两者不互相污染。
第四，不要只把superpowers当成“给AI看的东西”，它其实也是团队知识库的绝佳载体。我们团队的Java规范原本散落在Wiki、飞书文档和聊天记录里，整理成superpowers技能之后，不仅AI在用，新同学入职时也可以直接打开技能文件学习。一份投入，双重受益。
关于它的新玩法，我最近在琢磨把项目里每次Codex生成效果特别好的代码，提炼成“正面示例”放进技能里。这样做相当于给AI建了一个“优秀作业集”，它后续生成代码会越来越贴手。这个思路能不能跑通还需要更多验证，但方向我觉得是对的——让AI记住你自己的高质量产出，比任何通用模板都更能提升它在你项目里的表现。
