我是在一个很偶然的场景下接触到 superpowers 的。当时我正在用 Codex CLI 处理一个接手很久的 Java 老项目写 prompt 写到怀疑人生每次新会话都要把项目结构、依赖版本、编码规范重新交代一遍稍微复杂一点的任务跑到一半AI 就开始自说自话生成的东西根本不敢往主分支上合。后来一个同事丢给我一句“去搜搜 superpowers”我才发现原来给 AI 编码代理加“超能力”早就不是一句玄学口号而是一整套可落地的工作流增强方案。最近这一两周我把 superpowers 完整跑通并把它接到 Codex 的日常链路里效果比我预想中稳太多。这篇就当作一份使用指南加踩坑实录把安装、配置、Java 场景实战和团队协作的做法一并交代清楚。1. 先搞明白superpowers 解决的到底是哪个痛点1.1 直接用 Codex 不够爽的问题出在哪先说结论superpowers 不是一个新的模型也不是要替代 Codex它是叠在 Codex 这类编码代理之上的一层“技能编排层”。为什么需要这层东西因为我实测下来裸用 Codex 处理真实工程任务有三个绕不开的坎。第一个坎是上下文失忆。Codex 的单次对话能力再强它的工作上下文也是有限的。当一个任务跨了十几个文件、涉及多次编译运行、还要根据报错信息做策略调整时聊着聊着它就忘了最初的设计目标开始顺着最近的错误信息一路狂奔最后给你改出一个能通过编译但完全不符合业务语义的“缝合怪”。第二个坎是项目背景不能沉淀。团队里真正值钱的工程约定比如目录规范、异常处理风格、禁止使用的 API、测试覆盖率要求散落在各种文档里。每次开新会话如果我忘了贴背景材料代码质量立刻回到“能用但很脏”的原始状态。靠 AGENTS.md 做静态约定能解决一部分问题但没法解决“针对当前任务动态加载对应知识”的需求。第三个坎是任务太宽泛时AI 没有“战役规划”能力。直接丢一个“帮我把登录模块的单元测试补全”这种任务它通常会一条路走到黑先给你生成 20 个测试文件然后跑一遍 mvn test红了就盲目修修完再跑。中间没有任何人帮它拆解“先摸清模块结构、再分析依赖、再设计用例、最后分批次执行”的步骤。结果就是看着好像很忙实际上产出一坨难以 review 的代码。superpowers 这套方案的切入点恰好就是这三个坎把解决某类问题的完整打法固化成“技能包”把项目背景做成可动态加载的上下文模块把长任务强制拆成分阶段验证的里程碑。1.2 它的核心设计思路其实很朴素说得更直白一点superpowers 做的事就是三句话把高手处理任务的方法论写进文件里让 AI 在执行时按方法论走而不是信马由缰。我用一个生活化的类比来解释普通人学做饭是看菜谱炒一个菜看一个菜谱高手学做饭是掌握“火候-调味-食材处理”的通用框架换任何食材都能套用。superpowers 的“技能包”就是 AI 编码领域的通用框架。一个写好的 java-test-gen 技能包里面包含了对 Java 项目结构进行预扫描的步骤、生成测试用例的规则、如何识别不可测试的老代码、以及修改后如何用 Maven 进行增量验证。下次再遇到类似任务直接把技能包丢给它它就有了方法论不再是瞎试。理解了这层思路再看它的功能模块就比较顺了技能包Skill Pack以目录为单位管理每个技能包有明确的职责边界比如代码审查、单元测试生成、依赖升级、性能巡检。上下文注入启动任务时工具会把项目结构、配置约定、相关文档片段按需注入到 AI 的上下文中等于每场对话前自动“补课”。任务编排把一个大任务拆成多个阶段每个阶段都有独立的验证标准只有通过验证才会推进到下一阶段。1.3 谁最适合现在就用上这套东西说实话superpowers 不适合所有人。如果你只是偶尔用 AI 生成一两段工具函数那没必要折腾直接开 Codex 网页版闲聊就行。但如果你是下面三类人我会强烈建议你尽快试一遍频繁用 Codex CLI 处理真实业务代码的开发者尤其是那些要在多个项目之间切换每次都要重新解释项目背景的人。需要让 AI 在 Java、Python、前后端混合仓库里干活的人因为跨语言场景下通用对话的失误率会指数级上升而技能包可以按语言分别定制。带小团队想统一 AI 使用规范的技术负责人与其天天口头叮嘱“AI 生成的代码要 review”不如直接把 review 规则写进技能包让每个人每次执行都走同一套流程。2. 安装与初始化把“超能力”装进本地环境2.1 动手前的准备清单不同版本的 superpowers 在安装方式上会有一些差异我下面以我自己在用的 0.8.x 版本为例这个版本对 Codex CLI 的适配比较成熟而且技能包格式已经稳定。安装前请先确认三样东西Node.js 18superpowers 的命令行本身是用 Node 写的依赖新版运行时的一些 API。Codex CLI 已完成登录这一步经常被忽略。你得先保证裸 Codex 能跑通再谈增强否则后面会出现各种鉴权报错排查起来非常痛苦。Git 可用安装过程中的技能包仓库拉取、团队共享技能包的更新全都依赖 Git。检查完这三样建议顺手确认一下 Codex 能跟官方 API 正常通信。我自己第一次装的时候就是 Codex 一直报网络错误浪费了半天时间排查后来才发现是本地代理配置把请求劫持了。2.2 从 0 到 1 的完整安装过程安装本身不复杂核心就是把 superpowers 的命令行工具装到一个全局目录然后让它“接管” Codex 的部分配置。步骤如下# 安装命令行工具 npm install -g superpowers/cli # 初始化本地工作区这一步会创建 ~/.superpowers 目录 superpowers init # 拉取官方技能包仓库里面包含 java、python、frontend 等常用技能包 superpowers skills install java superpowers skills install code-review安装完成后它会自动修改 Codex 的配置文件在原有配置基础上追加 superpowers 的上下文注入钩子。如果你第一次跑codex发现启动参数变了这是正常的不是配置被搞坏了。我强烈建议你在全局配置之外单独为项目建一个局部配置。全局配置放通用设定比如数字、日期格式、语气倾向局部配置放项目特有的东西比如这个项目的 Maven 仓库地址、测试命令、禁止修改的文件列表。superpowers 在读取配置时局部配置会覆盖全局配置这样你在不同项目之间切换时不需要频繁改动全局设置。2.3 装完怎么确认它真的生效了安装不是终点确认生效才是。我第一次装完就以为自己大功告成了结果跑起来发现 AI 根本没用上技能包气得不行。后来才意识到要验证直接运行superpowers doctor命令它会检查三件事命令行版本、Codex 集成状态、技能包加载状态。superpowers doctor正常的输出应该包含这样几行确认信息CLI 版本号、Codex 配置路径已更新、至少一个技能包已加载。如果看到 “skill pack not found” 或者 “codex hook not active” 之类的内容不要慌张多半是路径问题。我踩过的坑是当时用 npm 装了新版本但终端 PATH 还指向旧版本目录导致命令执行时一直找不到技能包目录。提示安装完成后我建议先在一个临时项目里跑一次最简任务比如让它生成一个 README确保整条链路通了再上真实项目。不要一上来就拿核心业务代码试水万一链路有问题改坏代码都不知道是 superpowers 的问题还是你的 prompt 的问题。3. 核心实操用技能包给 Java 老项目“做体检”3.1 技能包到底是什么形态Java 是我主力语言所以我把 superpowers 用在 Java 项目上的经验拿出来单独讲。先说技能包的形态它本质就是一个带规则文件的目录里面最核心的是 SKILL.md 这个文件。名字叫 md但它的作用不是给你看的是给 AI 看的“操作手册”。我拆开过一个 java-review 技能包里面就三种内容职责声明、执行流程、红线规则。职责声明用一句话告诉 AI 这个技能包是干什么的避免同一会话里多个技能包相互干扰。执行流程是一串有序步骤比如先读取项目根 pom.xml再定位业务模块再检查类设计最后生成审查报告。红线规则是不可协商的内容比如“不得修改自动生成的代码”“局部变量命名必须使用驼峰”“检测到 ThreadLocal 滥用时一定要标记”。你可以把 SKILL.md 理解成给 AI 的“带约束的菜谱”它既是方法论又是流程检查清单。3.2 让技能包自动生成单元测试我拿一个真实场景来说接手一个用了 Spring Boot 2.7 的老项目里面的订单模块有几个核心 Service 类测试覆盖率几乎为零而且有几个方法内部还直接 new 了依赖对象没有走依赖注入。如果让普通 Codex 直接生成测试它大概率会生成一个 Mockito 测试然后试图 mock 那些 new 出来的对象结果是 Mockito 根本 mock 不掉编译直接失败。我当时的做法是先把 superpowers 的 java-test-gen 技能包加载进来然后用一段非常精简的指令开始任务superpowers run java-test-gen \ --target ./src/main/java/com/company/order/service/OrderService.java \ --framework junit5 \ --verify mvn -pl order-module test -DtestOrderServiceTest执行之后superpowers 的动作明显跟裸 Codex 不一样它先扫描了 OrderService 及其关联类的结构然后在上下文里梳理出当前类的依赖链再开始设计测试用例。最关键的是它没有一头扎进 mock 的坑里而是识别出那几个 new 对象的代码是测试阻碍点并在生成测试的同时先输出了一份“需要重构”的提示清单问我是否允许在测试生成前先做最小化改造。这个“先评估再动手”的过程恰恰是技能包的价值所在它把老 Java 项目里最常见的问题——过度耦合、静态方法依赖、私有方法难测试——都明确写进了流程AI 不再需要从零摸索。跑完生成流程后它还会自动执行我传进去的 Maven 验证命令。我发现第一次运行下来生成的 12 个测试里有 7 个通过另外 5 个失败失败原因大多是测试数据构造问题。接下来它基于失败信息做第二轮修复每修一次跑一次单测直到全部通过。整个过程完全自动化我只需要在最后做一次代码 review。3.3 依赖升级也能交给它闭环处理Java 项目永远绕不开的一个话题就是依赖版本升级。Spring Boot 从 2.7 升到 3.x 这种大版本迁移手动改 pom 能改到崩溃。我试过直接用 Codex 让它升级结果它把 version 字段替换得倒是很勤快但完全没处理 javax 到 jakarta 的包名迁移编译一跑直接红了一片。而用 superpowers 的 java-migration 技能包跑同一件事效果完全不同。这个技能包内置了完整迁移流程先对比分析当前 pom 中的依赖树确定所有受影响模块然后逐模块扫描 import 语句找出 javax 开头的旧包引用接着按官方迁移手册生成替换表分批替换最后执行编译和关键模块的测试。superpowers run java-migration \ --from spring-boot-2.7 --to spring-boot-3.2 \ --scan-imports javax \ --verify mvn -DskipTests compile中途发生过一次很有意思的情况迁移到>skills-repo/ ├── java/ │ ├── java-test-gen/ │ ├── java-migration/ │ └── java-code-review/ ├── common/ │ ├── security-scan/ │ └── performance-tips/ └── SKILLS.md # 索引文件新成员按这个文档了解每个技能包的用途每次技能包更新后由一个人负责 review 合并其他人执行superpowers skills update拉取最新版。这样既保证了统一又不需要每个人自己维护一堆散落的规则文件。实践中我还会把团队近半年踩过的高频 bug 场景逐步沉淀成新的技能包这个过程本身就是团队工程能力的持续积累。另外说一个细节共享技能包里尽量不要写死个人偏好比如某个人喜欢方法名用缩写或者某个人习惯不用 Lombok。这些偏好一旦进了共享规则其他人执行时会觉得很别扭。共享技能包只放“团队共同认可的、可强制执行的标准”。5. 踩坑实录与排查速查表5.1 五个我真实踩过的坑再顺的工具用起来也总有翻车的时候。这五条坑是我这几周反复撞出来的每一条都付出过实际的调试时间。第一个坑技能包里的命令没有加--yes参数任务卡在人工确认步骤。superpowers 在部分操作比如修改 pom.xml默认会弹人工确认在 CI 环境下直接挂住。我的解决办法很简单运行命令时统一传--yes但在本地开发时绝对不开这个参数本地还是希望人肉把关的。第二个坑上下文超限时完全没有预警。老项目文件多有次跑全模块审查AI 直接上下文爆炸然后开始在无关文件里瞎逛。后来我养成了习惯任务范围能卡单个模块就卡单个模块不要动不动就扫描整个仓库。大任务一定要拆批处理比如按 controller、service、repository 分批执行。第三个坑Java 项目的编码不规范导致技能包流程错乱。有次跑测试生成AI 明明已经完成了代码生成却在验证阶段反复报编译错误。排查半天才发现项目里有几个文件保存成了 GBK 编码而 superpowers 默认以 UTF-8 读取文件内容根源上读出来就是乱码编译当然过不了。这个问题的解决方案是在项目局部配置里显式声明文件编码然后统一把核心源码转成 UTF-8。第四个坑技能包仓库更新后本地配置被覆盖。有一次我改了本地 skill 的自定义参数自己没记到 Git 里然后执行了 skill update结果自定义参数全没了。现在我的习惯是所有对技能的个性化修改一律走自己的覆盖层目录不动公共仓库的文件这样即使更新也不会丢。第五个坑分支污染。最惨的一次教训是 AI 在一个临时分支上做实验它自己 commit 了一条记录然后我切换分支时把未提交的改动一起带到了主分支上。虽然最终没有造成事故但吓得我出了一身冷汗。现在我的铁律是所有 superpowers 执行任务前先确认当前 Git 分支是干净且正确的任务的中间产物一律输出到target/ai-gen/这种忽略目录绝不直接提交。5.2 排查思路速查表现象可能原因推荐处理方式superpowers doctor找不到 Codex hookPATH 指向旧版本或全局配置未更新重装 CLI检查 npm 全局目录与终端 PATH技能包执行时总跳过某些步骤SKILL.md 中的前置条件未满足打开技能包文件阅读前置要求按步骤手动补全AI 生成的代码跟项目风格严重不符局部配置里的风格规则没有生效检查配置覆盖机制确认局部配置路径是否正确验证命令一直失败但看不出原因项目编码或原生代码本身存在语法问题先手动跑一次验证命令排除环境因素再让 AI 继续任务进行到一半被强行中断上下文超限或单步超时缩小任务范围拆成更小的子任务分批执行这张表是我自己贴在终端旁边的速查小抄遇到问题先对号入座比盲目重启有效得多。5.3 几点毒舌心得最后说几句可能不太中听、但很实在的话。第一superpowers 不会让一个不懂工程的人变成高手。它的技能包本质上封装的是“高手做事的流程”但如果使用者连“什么样的改动是危险的”“什么样的测试是有意义的”都判断不了那就算流程再完善你也只是在盲人摸象。第二不要迷信终极 prompt。我刚开始也试图找一个万能 prompt一劳永逸地解决所有问题。实测下来没有这种万能灵药。superpowers 能帮你把流程标准化但任务描述的质量比如你给的目标是否清晰、验证条件是否明确、边界范围是否划定仍然直接决定产出质量。第三再好的工具也要配合 Human Review。任何一份让 AI 自动生成的代码都有概率在你知道或还不知道的地方埋雷。我的做法是让 AI 承担代码生成和自检的脏活累活但涉及核心业务逻辑的变更我一定会自己通读一遍 diff重点看异常分支和不变量是否被破坏。我个人在大量实操中最深的体会是superpowers 真正值钱的不是那几条命令而是它逼着你把项目里那些“只可意会不可言传”的工程经验显式地写成了 AI 能理解的流程。我自己的方法是每次从一次失败任务里复盘时都会把这次的教训追加到对应技能包的注意事项里。这样过了一个月技能包越来越厚AI 跑得也越来越稳那感觉就像真的给自己的编码代理装了天线让它越来越懂你的项目、你的团队、你的代码洁癖。如果你正准备开跑我最后再分享一个很实用的小动作拿到任何新技能包先花十分钟打开 SKILL.md 通读一遍再决定要不要用它。不要等任务跑到一半才发现技能包里的约束跟你的项目冲突。这十分钟的投入能帮你省下后面一整个下午的排错时间。