最近被一个叫 Superpowers 的热词刷屏了。别误会，这里说的不是美剧里那些变种人的特殊能力，而是开发者社区正在讨论的一套 AI 开发工作流工具。它跟 Codex 这类代码生成模型配合使用，尤其适合 Java 技术栈的日常开发。你可能会问，又是一个命令行工具？它到底能做什么？简单说，它把“让 AI 帮你写代码”这件事从碰运气变成了一套可复用的流程：你给它一个任务描述，它按照你预先定义的规范去生成代码、补测试、跑构建，最后把结果交给你 review。这篇文章我不打算讲概念，直接从安装、配置、实战到排坑，把一份能落地的 Superpowers 使用指南完整过一遍。
1. Superpowers 到底是什么，为什么值得装
1.1 它不是魔法，而是给 AI 编码加了一层“流程规范”
现在很多程序员手里都有一个 AI 编码助手，输入一句话就能生成一段代码。但问题也很明显：同一个问题，不同人问出来的代码风格天差地别；同一个模型，生成十个版本可能有十个包名、十种异常处理方式。Superpowers 做的事情，就是在这中间插入一层“流程控制”。
它本质上是一套命令行工具：当你输入superpowers run "生成用户管理模块"时，它并不是直接把这句话丢给 Codex 模型完事，而是先根据当前项目的语言类型、构建工具、目录结构和团队技能模板，把任务拆解成若干个子步骤。比如先读取你项目的pom.xml，确认 Java 版本和依赖，再检查src/main/java下的包结构，然后才调用模型生成代码，最后自动执行编译和测试命令。
我用一个生活化的类比来理解：Codex 像一个能力很强但没有完整认知的实习生，你让他“写个用户接口”，他可能会给你写得漂漂亮亮，但包路径是错的、日志格式是乱的、返回值也不符合团队统一风格。Superpowers 就是给他发的一本员工手册，告诉他“在我们这个项目里，接口应该放在哪个包、统一返回什么结构、必须用什么注解”。模型还是那个模型，但因为有了流程规范，输出质量会明显稳定。
所以不要把 Superpowers 当成“自动编码机”，它更像是一个“流程增压器”。它不能替你思考业务，但能保证生成过程符合工程化要求。这一点在 Java 项目里尤其重要，因为 Java 生态里约定大于配置，规范和结构比“能跑的代码”更关键。
1.2 Java 开发者的基础设施焦虑，它刚好戳中
做过 Java 项目的人都有一种刻板印象：写业务逻辑本身并不难，难的是写代码之前那一大堆基础设施。新项目要从零搭 Spring Boot，要拉依赖、配日志、配 MyBatis 或 JPA、写统一异常处理、封装返回结果、加 Swagger 注解，然后还要保证 Controller、Service、Mapper 的分层结构不乱。这些工作重复性极高，但每次都要人肉去写，稍不注意就出细节偏差。
Superpowers 被很多 Java 团队关注，主要是因为它可以把这些重复劳动“技能化”。比如你在团队里定义一个spring-rest技能模板，里面写清楚“所有 Controller 必须放在controller包下、统一返回ApiResponse<T>、接口必须以/api/v1开头、要带 Swagger 注解”。之后无论谁执行superpowers run “新增一个商品查询接口”，生成的代码都会自动符合这套约定。
它解决的第二个痛点是单测覆盖率。Java 项目的单元测试往往是最容易被砍掉的部分，因为写测试比写业务代码还费劲。Superpowers 可以在生成业务代码之后顺手补一份 JUnit 5 + Mockito 的测试，它会先分析目标类的依赖关系，自动 mock 掉外部调用，再生成正常路径和异常路径的用例。当然，AI 生成测试不可能做到 100% 符合你的业务语义，但至少能帮你把框架搭出来，把覆盖率基线拉起来。
第三个痛点是代码审查。传统 code review 依赖人的经验和耐心，而 Superpowers 可以把你的 checkstyle 规则、SonarQube 规则、甚至团队自己的 Java 编码规范注入给 Codex，让它先做一轮“机器 review”。它发现的问题不一定全对，但能过滤掉大量低级错误，让人的注意力集中在真正的业务逻辑上。
2. 安装与初始化：用一个真实 Java 工程跑通
2.1 环境准备：Node.js、JDK、Codex CLI，一个都不能少
在开始的开始，我先明确一下前提：Superpowers 本身依赖 Node.js 运行时，所以你的机器上需要装有 Node.js 18 或更高版本。Java 工程那一侧，JDK 11 以上是基本要求，如果你用的框架是 Spring Boot 3.x，那建议直接上 JDK 17。构建工具我用的是 Maven，Gradle 项目也同样支持，只是配置文件里的buildTool字段要换一下。
然后是 Codex CLI 的安装。我用的是官方提供的命令行工具，安装命令很简单：
npm install -g @openai/codex装完之后先跑一下codex --version，能输出版本号就说明基础环境没问题。这里要特别提醒：Codex CLI 首次运行时需要配置 API Key，你可以通过环境变量OPENAI_API_KEY注入，也可以在运行codex的时候按照交互提示输入。这个 Key 一定要保管好，别写进 Git 仓库里，不然被同事或机器人扫到就麻烦了。
接下来安装 Superpowers 本体。不同发行版的包名可能会有差异，以官方 README 为准，我这里用当前社区里最常见的命令：
npm install -g superpowers-cli安装完成后，执行：
superpowers --version如果提示command not found，别急着怀疑人生，这大概率是 npm 全局安装目录不在 PATH 里。我在后面第 5 章会专门讲这个问题，这里先跳过。
2.2 初始化项目配置：让 Superpowers 认识你的 Java 工程
环境准备好之后，进到任何一个 Java 项目根目录，执行：
superpowers init这个命令会在当前目录下生成一个配置文件和一些默认目录。我实际用下来的生成结果大概是这样：
project: demo-user-service language: java buildTool: maven sourceDir: src/main/java testDir: src/test/java codex: model: gpt-4o maxTurns: 8 skills: - team-java每个字段的作用我稍微解释一下。
project是项目名，Superpowers 会用它来命名生成的模块或者作为上下文的一部分。buildTool决定了后续它用 Maven 还是 Gradle 命令来编译、测试。sourceDir和testDir是项目的源码目录和测试目录，如果你们公司的目录结构不是 Maven 标准布局，就必须改这里，否则后续生成的文件会放错位置。codex.model是调用模型时的默认模型名，maxTurns表示一次任务最多允许模型跟脚本交互几轮，限制轮数能防止它在一棵树上吊死。skills是当前项目启用的技能模板列表，这个是 Superpowers 最核心的配置，第 4 章我会展开说。
配置文件生成后，运行一次自检：
superpowers doctor它会检查 Node.js 版本、Codex CLI 是否可用、当前目录是不是 Java 工程、pom.xml能否被正确解析。如果输出里出现绿色勾，说明基础链路已经通了。我第一次跑的时候，doctor提示找不到pom.xml，原因是我在项目子目录里执行的init，而父工程的 Maven 配置在上一层。把命令移到根目录重新初始化就好了。
2.3 第一条命令：先让 AI 分析项目结构
配置完成之后，不要急着生成代码。我先跑一条最简单的命令验证整套链路：
superpowers run "分析当前项目的模块结构，列出核心依赖和每个模块的职责"这条命令不会生成任何文件，它只是把项目上下文打包后交给 Codex，让模型输出一份结构说明。如果你能看到一份还算准确的描述，比如“这是一个 Maven 多模块项目，包含 common、domain、api 三个模块，其中 api 模块依赖了 Spring Web”，那就说明配置文件解析正确，AI 的调用链路也是通的。这一步相当于新员工入职第一天先看公司架构图，后面再干活才不会乱。
3. 三个核心场景，把 Superpowers 用起来
3.1 场景一：从需求描述到 Spring Boot 模块骨架
第一个实战场景，是用一条命令生成一个完整的业务模块。假设现在要做一个用户管理模块，包含用户实体、Repository、Service 和 Controller。传统做法是先在 IDE 里手动建包、建类、写注解，再补依赖。用 Superpowers 的话，我只需要输入：
superpowers run "生成用户管理模块，包含实体 User、Repository、Service、Controller，使用 Spring Boot 3 风格，包路径保持当前项目结构"它内部执行的动作大概分这几步：
- 读取当前 Maven 工程的
pom.xml，判断 Spring Boot 版本、Java 版本、是否已有 Web 依赖。 - 扫描
src/main/java下面的基础包路径，决定生成的包名。 - 读取启用的技能模板，把团队规范注入到模型上下文。
- 调用 Codex 依次生成实体类、Repository 接口、Service 实现和 Controller。
- 执行 Maven 编译，如果编译失败，它会把错误信息回传给模型，尝试自动修复。
- 输出摘要，告诉你生成了哪些文件、哪几个文件还需要人工确认。
我自己跑的时候，生成的代码确实能通过编译，但有个小问题：Controller 里的返回类型没有用团队的ApiResponse<T>，而是直接返回了业务对象。原因是我当时没有在技能模板里写明统一返回结构。后来我在模板里加了一条规则，再次生成就正常了。这个教训很重要：Superpowers 的效果上限，取决于你的技能模板写得有多细。
3.2 场景二：为现有 Service 层补单元测试
第二个高频场景是补测试。Java 项目里 Service 层往往依赖 Repository、外部接口、消息队列，写单测需要大量 mock，非常枯燥。用 Superpowers 的典型命令是：
superpowers run "为 UserService 生成 JUnit 5 单元测试，使用 Mockito，覆盖正常创建用户、用户名重复、用户不存在三种场景"它会先分析UserService的方法签名、参数类型和依赖注入情况，然后自动生成一个UserServiceTest文件。这里的关键是，技能模板里可以规定测试风格的细节：类名必须以Test结尾、测试方法名使用should_条件_预期结果格式、断言统一使用 AssertJ、mock 对象用@Mock注解而不是手动 new。这些约定写清楚之后，AI 生成的测试读起来才像团队自己写的。
测试生成之后，Superpowers 还会顺手执行 Maven 的test命令。假如测试失败，它会读取失败日志，自动判断是代码问题还是测试问题，然后尝试修改测试代码或业务代码。我实际遇到底情况是，AI 生成的测试里 mock 了一个当前类不依赖的接口，导致测试启动报错。它会在下一轮交互中修正掉。当然，AI 自动修复不是万能的，如果业务逻辑太复杂，它反复修三四次还是跑不过，我就手动介入了。所以我的原则是：AI 补测试可以，但没人确认过的测试用例不能上 CI。
3.3 场景三：Codex 驱动的代码审查与自动修复
第三个我觉得特别实用的场景，是本地代码审查。平时我们用 IDE 的静态检查只能查语雀级别的错误，但很多风格问题和潜在 Bug 要人肉一眼一眼看。Superpowers 提供了一个 review 命令：
superpowers review --diff--diff表示只看当前分支未提交的改动。它会收集改动的文件内容、项目的编码规范、以及常见的 Java 陷阱清单，然后交给 Codex 输出一份 review 意见。意见会标出问题所在文件、行号和修改建议。如果只是想自动修复格式问题，可以用：
superpowers fix --checkstyle这个命令会把 Checkstyle 报告里的错误项交给 Codex，让它挨个修复。这里额外提一句，我使用的时候比较谨慎，不会让 AI 直接修改所有问题，因为它可能在修复一个问题时引入另一个风格问题。我会把fix的修改结果用git diff再检查一遍，确认改动符合预期才提交。
4. 把 Superpowers 变成团队规范的一部分
4.1 技能模板才是 Superpowers 的灵魂
很多人一开始用 Superpowers，只是把它当成一个“AI 命令行助手”，随便跑几个命令，感觉很新鲜，但用几天就发现生成的东西没那么靠谱。这里我特别想强调一个观点：Superpowers 不是靠模型取胜，而是靠技能模板取胜。
所谓技能模板，就是你在项目目录下维护的一份说明文档，里面用自然语言写清楚“在这个项目里，AI 应该如何生成代码”。它的目录结构一般长这样：
.superpowers/ skills/ team-java/ SKILL.md examples/ user-controller.java api-response.javaSKILL.md是核心文件，用 Markdown 写成。它不需要复杂的语法，就用大白话把规则一条条列出来。我自己的SKILL.md大概是这样的：
# team-java 技能 本技能适用于所有 Java 代码生成任务。 ## 代码风格 - 使用 Spring Boot 3 的注解风格。 - Controller 统一返回 ApiResponse<T>，禁止直接返回实体。 - 实体类使用 Lombok @Data，不手写 getter/setter。 - 日期类型统一使用 LocalDateTime，禁止使用 java.util.Date。 ## 分层规范 - Controller 只做参数接收和结果封装，不写业务逻辑。 - Service 接口定义在 service 包，实现在 service/impl 包。 - Repository 继承 MyBatis-Plus 的 BaseMapper。 ## 测试规范 - 测试类位于 src/test/java 对应包路径下。 - 使用 JUnit 5 + Mockito。 - 测试方法命名格式：should_条件_预期结果。写完之后，在项目配置文件里启用它：
skills: - team-java之后每次执行superpowers run时，它都会把这个 Markdown 文件的内容作为上下文的一部分发给 Codex。这样 AI 生成出来的代码，从一开始就是按团队风格来的，不需要你在命令里反复提醒“要用 Lombok”“要用 LocalDateTime”。
4.2 一个真实案例：从“AI 乱写”到“AI 懂规矩”
我最早在团队里推广 Superpowers 的时候，遇到的最大反弹是同事说“AI 生成的代码和我写的风格完全不一样，还不如自己写”。后来我把团队现有的 Controller 抽了一个样例，放进examples/user-controller.java，然后在SKILL.md里加了一句话：“生成 Controller 时，优先参考 examples 目录下的 user-controller.java 的写法。”
这个操作立竿见影。因为 Codex 是强上下文依赖的模型，给它一个具体样例，比给它一百句抽象描述都要管用。从那之后，生成代码的接受度明显提升。所以如果你也想在团队落地，我建议一定不要只写规则，要配上真实代码样例。规则用来兜底，样例用来对齐。这套方法不仅适用于 Java，任何语言都一样。
5. 常见问题与排查技巧实录
5.1 安装之后superpowers命令不生效
这个问题出现频率最高，而且新手最容易懵。npm install -g superpowers-cli执行成功了，但一敲superpowers就提示 command not found。原因基本是 npm 全局 bin 目录不在系统的 PATH 环境变量里。你先执行下面这条命令查看全局目录：
npm config get prefix如果输出的是/usr/local，那 bin 目录就是/usr/local/bin，一般已经在 PATH 里。如果输出的是一个带node或nvm的路径，比如/Users/你的用户/node_modules/.bin或者~/node_modules/.bin，那就需要手动把对应的bin目录加进 PATH。Windows 用户更简单，用管理员权限打开 PowerShell，执行npm install -g superpowers-cli命令一般会自动处理好。还有一个小概率的情况是 Node.js 版本太旧，Superpowers 某些版本要求 Node 18+，升级到 LTS 版本基本能解决。
5.2 Java 多模块工程识别错乱
如果你在一个 Maven 多模块项目里运行superpowers run，会发现它有时候只识别到了模块的一部分，甚至把模块目录搞混。原因通常是sourceDir配置成了固定的src/main/java，但在多模块结构里，每个子模块都有自己的源码目录。
解决办法有两个。第一，在配置文件里把模块列出来：
modules: - api - service - dal这样 Superpowers 会依次进入每个模块生成或分析代码。第二，用自动扫描命令：
superpowers scan它会遍历当前工程下的所有pom.xml，根据 Maven 模块关系生成一个模块认知清单。我建议在初始化项目之后马上扫描一次，再跑生成任务，能省掉很多定位问题的时间。
5.3 生成的代码总是偏离团队风格
如果你发现 AI 生成的代码怎么都不对味，先别怪模型，大概率是技能模板没生效。排查顺序是：确认superpowers.config.yml里skills字段是否挂上了正确的技能名；确认SKILL.md文件路径和文件名是否正确；确认技能内容里是否有足够具体的规则和样例。我曾经遇到一个情况：配置里写的是team-java，文件夹却叫team_java，下划线和中划线不匹配，导致技能没有加载。这个问题superpowers doctor不会报错，因为它只管环境配置，不管技能映射。所以检查的时候一定要靠肉眼。
还有一个技巧：在run命令后面加上--trace参数，它会把发送给模型的内容打印出来。你可以直接看到SKILL.md的内容到底有没有被拼进提示词里。如果没进去，就从配置映射找原因。
5.4 Codex 超时、限流与上下文过长
用 Superpowers 做大型任务时，最常翻车的是 Codex 返回超时，或者提示上下文过长。上下文这个问题尤其容易发生在大型 Java 项目里：如果项目扫描的文件太多，把一堆源码全部塞给模型，那很容易超过模型窗口限制。我的处理方法是尽量缩小任务范围。比如不要一次生成整个模块，而是拆成“先生成 User 实体，再生成 Repository，再生成 Service”。或者用--scope指定只处理当前目录：
superpowers run "给 UserService 加一个分页查询方法" --scope src/main/java/com/example/service如果只是 API 限流，可以在配置里降低请求频率，或者把maxTurns调小一点，不要给 AI 无限重试的机会。它连续修三次还修不好的问题，你再给它五次机会大概率也是浪费时间。
5.5 我踩过的几个坑总结
最后分享几条个人体会。
第一，不要把 AI 生成的代码直接提交到主干。哪怕它已经编译通过，也要至少过一遍 review，因为编译通过只能证明语法对，不能证明业务对。第二，技能模板需要持续迭代。我第一次写的模板只有五条规则，用了两周之后逐步补到了二十条，越用越顺手，团队的代码风格也确实逐渐统一了。第三，Superpowers 的价值不在“生成代码”那一瞬间，而在“沉淀规范”的整个过程。很多团队规范平时散落在人心里，新人来了全靠带，老人离职就断层。把规范写进SKILL.md，它就变成了一种可执行的项目资产。
如果你现在正纠结要不要在 Java 项目里引入 AI 辅助开发，我建议从一个小模块开始试：先写一份三到五条的团队规范技能，然后跑一条生成 Controller 的命令，看看产物和预期差多少。你会发现第一次用可能只打了个及格分，但只要你把差异补进模板，后面的每一次生成都会更接近你想要的结果。这个工具不难，真正的门槛其实是“你愿不愿意把自己的要求讲清楚”。
