最近工作圈子里聊superpowers的人突然多了起来尤其是配合codex一起用的那批开发者。我最初看到几个 Java 同行在群里发截图说自己的 AI 编码助手“突然开窍了”会先写测试、会自己跑构建、改坏了还会回头修当时第一反应是又出了什么黑魔法。后来耐着性子从安装到跑通一个 Spring Boot 接口完整试了一遍才搞明白它其实是一套配置与技能集方案把 AI 助手默认那种“问一句答一句”的被动工作方式改造成了“接需求、拆任务、写代码、自测、修 bug”的完整工作流。这篇文章不是官方文档的翻译而是我从零开始装、配、用的一份实测记录。重点讲三件事superpowers到底解决了什么问题它安装配置的核心逻辑是什么以及在一个真实的 Java/Maven 项目里怎么把它用起来。不管你用的是原生 codex cli还是基于它的二次封装工具底层思路基本一致看完应该能直接照做。1. 先搞明白 superpowers 到底是什么别急着装很多人一上来就 clone 仓库、跑安装脚本结果装完发现 AI 助手的行为没有任何变化就开始骂“又是割韭菜”。其实问题不出在工具上而是没搞懂它的运行原理。1.1 给 AI 编码助手装“外挂”一个很朴素的需求先还原一下默认状态下 codex cli 的工作方式。你给它一句“帮我写个用户注册接口”它在终端里生成几段代码你复制粘贴然后自己去找 maven 编译错误自己补测试整个流程和搜索引擎差不多。问题在于AI 本身能力是够的但缺少一套约束机制导致它不会主动规划、不会先写测试、也不会在改代码后自己跑验证。superpowers这个项目想解决的就是这件事。它本质上是一组打包好的规则文件和技能skill文件安装之后会挂载到 AI 编码助手的会话进程里。AI 每次收到任务会先读到这些规则知道“哦原来这个项目的老板要求我先拆任务、再写失败测试、然后实现、最后跑通才算完”。所以它带来的不是模型智商提升而是工作习惯的规范化。用一个生活化的类比就是给一个很聪明但没什么章法的实习生发了一本极其详细的《项目操作手册》和一套《工具箱》让他知道什么时候该用什么工具做完一步下一步干什么。这也是为什么很多人在推特上看到演示视频觉得“这 AI 成精了”但自己装完却无感——大概率是没把配置正确挂载到会话里AI 根本没读到那本手册。1.2 为什么叫“超能力”到底增强了哪些能力superpowers里预置的技能通常覆盖几个方面。任务规划能力让 AI 面对复杂需求先拆解再动手而不是直接丢掉上下文就开始写测试驱动开发能力强制它先写失败的单测再写实现代码最后运行测试验证调试巡检能力在测试失败时自动读取错误日志、修改代码、重跑测试直到通过还有代码规范能力让 AI 遵循项目的命名、目录结构、构建工具约定。对 Java 开发者来说这几项能力尤其对胃口。Java 项目普遍依赖 Maven/Gradle 构建有严格的工程结构和单元测试习惯AI 默认模式下经常写出不符合项目规范的代码而有了配置约束之后它会主动调用 Maven 相关技能至少能做到“生成的代码能在当前工程里跑起来”。当然“超能力”这个名字多少有点营销味我更愿意把它理解为一套行为框架。它的价值不是让 AI 变聪明而是让 AI 变得可靠。聪明是模型层面的事可靠则是工程层面的事后者恰恰是日常开发最需要的。2. 安装前先把环境和思路理清楚任何工具装不上或者装了没用八成是前置环境没对齐或者安装方式选错。这节我把前置依赖和两种常见安装方式写清楚。2.1 前置依赖Node、Codex CLI、Git我实测下来superpowers这类技能集工具一般以 Node.js 脚本或 shell 脚本分发所以几样东西是跑不掉的Node.js建议 18 或 20 以上太低版本容易遇到语法不兼容、Gitclone 仓库和版本管理用、codex cli 或者兼容它的 AI 编码助手 CLI。Java 项目本身还需要 JDK 和 Maven/Gradle这个和superpowers没有直接关系但建议把 JDK 17 装好Spring Boot 3.x 项目用得上。验证环境的命令很简单node -v git --version codex --version java -version mvn -v我在配置时发现一个容易忽略的点codex cli 需要先完成认证和登录否则后续安装脚本测试调用时会直接报权限错误。这个认证环节每家 CLI 不一样有的是浏览器 OAuth有的是 API Key按官方文档走一遍即可。另外提醒一句如果你在代理环境下操作注意让终端代理对 GitHub 和 npm 生效不然 clone 和安装依赖容易超时。2.2 安装 superpowers 的两种典型方式以社区最常见的做法为例第一种是全局安装把技能集放到用户目录让所有项目共享。大概流程是git clone 你的仓库地址 ~/.superpowers cd ~/.superpowers ./install.sh安装脚本一般会把技能目录、规则文件链接到 CLI 的配置目录里或者生成一份引用文件。第二种是项目级挂载适合需要定制或者团队统一规范的场景。在项目根目录执行一些初始化命令把技能文件复制进来然后在项目的 AGENTS.md 或等价配置里引入。装完之后别急着用先验证文件是否就位。通常你会看到类似这样的结构~/.superpowers/ ├── SUPER.md ├── AGENTS.md ├── skills/ │ ├── plan.md │ ├── tdd.md │ ├── debug.md │ └── java-build.md └── memory/ └── project-log.md这些文件名在不同发行版里可能有差异但总体的模块划分八九不离十。如果发现目录是空的或者只有 README那说明安装脚本没有真正执行成功。这时候去看安装日志多半是 shell 权限问题或者 Node 版本不对。顺便提一下团队封装工具的情况。有些读者提到团队内部在用基于 codex 的二次封装工具比如有人叫 workbuddy 之类的工作台想知道能不能也用上superpowers。答案是能只要底层还是调用同一套 CLI 协议你只需把技能目录和规则文件挂载到封装工具对应的配置位置原理是一样的。如果封装工具屏蔽了配置接口那就只能等团队更新适配。3. 核心配置拆解技能是怎么被“叫醒”的安装只是把文件放到硬盘上真正决定 AI 行为的是配置文件里的引用关系和技能触发机制。这一节直接拆开看。3.1 配置文件和目录结构谁在指挥 AI以我目前这套配置为例项目根目录下会有一个AGENTS.md这是 AI 编码助手启动时默认读取的规则文件。它相当于项目的“宪法”里面写明了 AI 需要遵守的行为准则。而superpowers的技能文件则放在单独的目录里通过在AGENTS.md中引用让 AI 知道在什么场景下该去读哪个技能文件。关键的引用方式一般是这样的# AGENTS.md ## 规则 - 开始任务前必须先阅读 skills/plan.md 并输出实施计划。 - 涉及代码实现时必须先写失败的单测再写实现。 - 允许运行 mvn test 与 mvn compile 进行验证。 ## 技能 - 当任务包含测试时加载 skills/tdd.md。 - 当构建失败时加载 skills/debug.md。 - 当任务属于 Java 模块时加载 skills/java-build.md。AI 每次会话启动就会读到这份文件所以它的行为不是随机生成的而是被这些规则锚定住了。这一步是整个配置的灵魂很多人安装完没感觉就是因为 AGENTS.md 没有正确配置AI 根本不知道技能文件的存在。3.2 技能触发机制AI 怎么知道自己该用哪个技能文件本身不是被 AI“闭眼读”的而是按需触发。常见的触发方式有几种关键词触发、命令触发、上下文触发。比如当用户的自然语言里包含“测试”“单测”“test”这些词时配置了tdd.md技能的 AI 会去加载它当 AI 发现编译错误时它会主动读取debug.md里的排查流程当检测到当前目录有 pom.xml 时它会调用 Java 构建技能。我打个比方你就明白了。这就像你在 IDE 里装了一堆插件插件不是同时运行而是等你在文件里敲出特定代码时才给出提示。superpowers的技能文件就是给 AI 的“插件”AGENTS.md 里的规则就是插件的激活条件。多个技能之间还可以协作。比如 AI 接到一个“给订单模块加个状态查询接口”的任务流程可能变成先读取 plan.md 拆解任务然后用 tdd.md 的规则先写测试再用 java-build.md 的技能跑 Maven 编译最后用 debug.md 处理测试失败。整个过程像一个流水线而不是一个孤立的单次回答。3.3 给 Java 项目定制一份自己的配置superpowers默认技能里大概率有通用的编程技能但 Java 项目的构建方式和脚本语言完全不同所以定制一份 Java 专属配置是很有必要的。我自己的配置里就额外加了一个java-build.md# skills/java-build.md ## 构建指令 - 当前项目使用 Maven执行命令 mvn compile、mvn test、mvn package。 - 模块路径变化时使用 -pl 参数指定模块。 - 编译失败时先读取错误日志中的 Java 文件路径和行号修复后再编译。 ## 代码风格 - 使用 SLF4J 进行日志输出。 - 错误处理统一返回 ResultT 包装类型。 - 不要在实体类里写业务逻辑。这一步的好处是 AI 在项目里生成代码时会自带“这个项目是 Maven 结构、需要统一返回类型”这类上下文而不是输出一堆风格随缘的代码。我建议每个 Java 团队都维护一份这样的技能文件成本极低收益却很明显。4. 实战用 superpowers 在 Java 项目里跑通一个接口前面讲了一堆原理这节来点真刀真枪的。我以一个 Spring Boot 项目为例目标是在项目里新增一个用户注册接口并带单元测试。整个过程我都让 AI 按照superpowers的规则自主完成我只负责观察和记录。4.1 场景设定与初始状态项目是标准的 Spring Boot 3.x Maven 结构JDK 17已经初始化好了一个空的 Spring Boot 工程。项目根目录下放好了 AGENTS.md 和 skills 目录并且已经验证了superpowers配置能被 codex cli 读取。让我特别提一下初始化这一步。我并没有手动写任何业务代码只是把工程骨架弄好剩下的交互都发生在终端里。这种“人写环境、AI 写代码”的工作方式适合作为团队协作的模板因为环境一致性有保障AI 生成的代码也更容易跑通。然后我给出第一个指令请使用项目里的技能规则为我实现用户注册接口。要求先给出实施计划再写测试最后实现并运行测试验证。注意这里我特意在 prompt 里强调“使用项目里的技能规则”这是为了引导 AI 主动去读 AGENTS.md 和对应技能文件。如果你的配置正确AI 不会立刻开始写代码而是先输出一段计划。4.2 从规划到落地的完整过程AI 的第一轮回答是计划拆解大致内容是新建 UserController、UserService、UserRepository建立数据库表结构这里用 H2 内存库定义用户注册请求体编写失败的单元测试再实现逻辑。这和人类工程师的思路基本一致说明 plan.md 技能确实生效了。接下来的流程让我印象很深。AI 没有直接写实现代码而是先在 test 目录下写了UserControllerTest里面用 MockMvc 请求注册接口断言返回结果。写完测试后它主动执行了mvn test -DtestUserControllerTest结果自然是编译失败因为对应接口还不存在。这时候 AI 进入 debug.md 技能的处理流程读取编译错误信息、定位缺少哪些类、回到 main 目录补实现代码再重新跑测试。这个“失败-修复-重跑”的循环重复了三次第一次是缺少依赖第二次是请求参数校验不符合预期第三次终于全绿。整个过程我没有干预一行代码。如果你以前被 AI 生成的代码坑过应该能理解这种体验的差异——它不再是给你一堆“看起来对但不可能编译通过”的代码块而是会在当前工程里自己构建、自己发现错误、自己修复。4.3 过程中 superpowers 真正起作用的地方用完之后回头看真正起作用的地方有三个。第一个是任务规划AI 没有被大需求吓住而是先把任务拆成模块和步骤整体节奏稳了很多。第二个是测试优先它先写测试再写实现等于给自己设了验收标准后面修改代码时心里有底。第三个是构建验证闭环AI 会主动执行 Maven 命令而不是默认跳过这让最终交付的代码基本都是能跑的状态。当然也不是没有坑。我在第二次测试运行时发现 AI 一直盯着旧的测试结果看没有注意到我改了 application.yml 里的数据源配置。后来我手动加了一条规则每次修改配置类或 yml 文件后必须重启应用上下文重跑测试。加了这条规则之后同类问题再没出现过。这恰好说明了一个要点superpowers不是万能药它是一个可以持续改进的规则框架。你每遇到一个新问题都可以把应对方法写成一条新规则塞进去AI 下次就会自动避开。这套“用规则对抗不确定性”的玩法才是最值钱的部分。5. 常见问题与排查技巧使用过程中我踩了不少坑也帮几个群友排查过问题。这里整理成速查表遇到类似症状可以直接对号入座。5.1 问题速查表症状、原因、处理方式症状大概率原因处理方式安装脚本执行后目录为空脚本没有真正运行完成检查 Node 版本、脚本执行权限查看安装日志AI 回答时无视技能规则AGENTS.md 未被正确创建或引用确认项目根目录存在 AGENTS.md且内容包含技能引用技能虽然加载但被执行AI 没有识别出任务场景关键词在规则中补充更多触发词比如 test、单测、jmeterJava 项目里 AI 乱跑 Gradle 命令没有配置 java-build.md在技能文件中显式指定只使用 mvn 或 gradle测试失败后 AI 反复修改无用文件调试规则里缺少日志分析步骤增加“先读取错误日志行号再定位源码”的规则团队封装工具无法加载技能封装工具屏蔽了底层配置接口等待适配版本或直接在封装工具里补充等效规则排查这类问题有一个通用思路先验证 AI 的会话里到底有没有读入规则。你可以直接在对话里问一句“当前项目下你读了哪些规则文件”如果 AI 答不出 AGENTS.md 里的内容说明挂载有问题如果答出来了但行为不遵守那就是规则本身写得太模糊需要把触发条件和执行步骤描述得更具体。5.2 团队封装工具与自定义场景的处理关于团队封装工具比如之前提到的 workbuddy 一类的工作台我的建议是不要硬怼先看它有没暴露“自定义规则目录”或“额外上下文文件”之类的入口。很多封装工具虽然界面不一样但底层还是会拼接一份系统提示词只要你能把 AGENTS.md 的内容通过它的配置项注入进去技能就能生效。如果封装工具完全不开放配置那就退一步把superpowers里的关键规则手工摘出来作为团队内部文档的一部分由人肉确保 AI 生成代码后按规则审查。这当然没有自动挂载方便但总比 AI 天马行空强。还有一个容易忽略的场景非 Java 项目。superpowers的思想完全不绑定语言Python 项目可以把 java-build.md 换成 pip pytest 的技能Node 项目则换成 npm jest。真正可复用的不是某个文件而是“规则驱动 AI 行为”这套方法论。5.3 几条实操避坑心得最后分享几条从实操里摸出来的经验这些在官方文档里基本看不到。第一规则永远不要写得太抽象。像“注意代码质量”这种规则AI 读了等于没读。要把行为和验收标准写清楚比如“接口必须返回 Result 包装类型”“测试类命名必须以 Test 结尾”AI 才有执行依据。第二不要把技能目录和项目源码混在一起。技能文件是给 AI 读的上下文不是业务代码混在一起容易被误打包部署。我一般把技能配置放在项目根目录下单独的.ai/目录或 docs 目录并通过 AGENTS.md 引用。第三给 AI 设置文件操作边界。superpowers增强了 AI 的工具调用能力这意味着它可能去修改配置文件和无关代码。可以在规则里明确“无提示时不得删除文件”“只允许修改指定模块下的文件”避免 AI 自作主张破坏工程结构。第四定期更新技能集和规则。AI 模型在升级技能文件也需要跟着调。我每两周会刷新一次项目规则把团队近期踩的坑补充进去相当于给 AI 持续做“经验培训”。这套体系跑起来之后我发现团队里新人上手项目的速度都变快了——因为他们面对的 AI 已经学会了团队的所有约定。按照我个人经验superpowers这类工具最大的价值不是立刻提升代码生成速度而是帮你建立了一套可管理的 AI 行为规范。以前 AI 是黑盒用完就忘现在它每次完成任务的路径、用到的技能、遇到的问题都能通过规则文件沉淀下来。这种积累越久AI 在项目里的表现越稳定。如果你正在用 codex cli 或者类似的 AI 编码助手真心建议花半小时装一套试试然后从一个小功能开始调教慢慢你会上瘾的。