superpowers完全指南：从安装到Java实战，让Codex真正听懂你的需求

最近我在给 Codex 调教工作流的时候发现十个人里有八个人都在聊 superpowers。这个词在开发者圈子里已经快变成一个固定搭配了superpowers 使用指南、superpowers 安装、superpowers java、codex superpowers随手一搜全是教程。但我翻了很久大多数文章不是讲得太玄就是把安装过程一笔带过实操的时候该踩的坑一个没少。所以这篇文章我打算彻底讲清楚superpowers 到底是什么、它解决什么问题、怎么安装、怎么在真实的 Java 项目里用起来以及我实际用下来遇到过哪些坑。本文不念说明书只讲经过验证的操作路径适合已经在用 Codex 这类 AI 编程工具、但觉得“AI 能干活但不听话”的开发者。1. 先搞清楚 superpowers 到底是什么1.1 我为什么开始折腾 superpowers我最早遇到的问题是用 Codex 帮我改代码它总是“一步到位”但“一步跑偏”。让它修一个 bug它顺手把整个模块的命名风格改了让它补单元测试它只写了两个 happy path边界条件全没覆盖让它做代码审查它给的建议像是从通用规范里复制粘贴的完全没结合项目上下文。后来我才意识到问题不在 Codex 本身而在“没有给它结构化的做事方法”。大语言模型非常擅长单点生成但不擅长自己组织一套多层次的工作流。如果没有明确步骤和约束它就会用最省 token 的方式完成任务结果就是我们常见的“看起来在干活实际在瞎干”。superpowers 的思路就是给这类 AI 编程代理安装一套“技能包”。它不是一个模型不是花哨的 IDE 插件而是一堆经过整理的 markdown 技能文件每个技能文件都对应一种工作能力。比如规划能力、实现能力、测试能力、代码审查能力。AI 代理加载这些技能之后会按照文件里的步骤来思考和执行而不是自由发挥。1.2 superpowers 与普通 prompt 的核心区别很多新手会把 superpowers 理解成“一堆好用的 prompt”这没错但不完整。普通 prompt 是一次性的你需要每次都重新把要求打一遍superpowers 里的技能文件是持久化的AI 每次工作前都能主动读取对应的技能说明把“操作手册”固定在项目里。它和传统插件还不一样。插件往往需要安装运行时、依赖某个框架而 superpowers 的每个技能本质上就是一个目录里面有SKILL.md作为主说明文件可能还附带一些辅助脚本、模板、示例代码。你甚至不需要联网下载任何二进制只要把目录放到项目里让 AI 能读到就行。这里我做了一个小对比表方便理解形式生命周期作用方式缺点普通 prompt单次会话提示 AI 一次容易遗忘、不一致IDE 插件常驻在编辑器里提供能力依赖特定平台、重superpowers 技能包项目内常驻AI 每次自动读取技能需要主动组织维护它的核心价值是“把工作方法固化下来”。团队里如果每个人都用同一套 superpowersAI 生成的代码风格和操作流程就会高度一致这是在多人协作场景下最有吸引力的点。2. 安装 superpowers 的思路和两种常用方式2.1 装之前先把环境确认好superpowers 本身不是一个大型软件它对环境要求很低。理论上你只要有 Git 和 Node.js 就能跑如果你是在 Java 项目里用它还需要把 Maven 或 Gradle 先装好因为很多技能脚本会直接调用构建工具。我用一句口诀概括安装要点先确认 CLI 能跑再拉仓库然后跑安装脚本最后手动验证技能文件是否被识别。顺序不能乱很多人跳过了最后一步结果 AI 根本没读到技能全白干。我实际测试时的环境操作系统macOSLinux 同理CLICodex 最新版Node.jsv20.11Git2.39Java 项目JDK 17 Maven 3.9如果你在公司电脑上装先确认能不能访问 GitHub以及有没有全局代理配置。这里我不展开但环境不通会导致拉取失败或者安装脚本卡住。2.2 方式一从仓库克隆并跑安装脚本这是官方 README 里最推荐的安装方式也是我觉得最适合新手的路径。打开终端执行git clone https://github.com/obra/superpowers.git cd superpowers ./install.sh脚本会检查你的 CLI 配置目录然后把技能文件复制到全局目录里。装完以后你启动 Codex 或者 Claude Code 时它会在启动阶段扫描这些目录并列出可用的技能。我第一次跑的时候脚本卡了几秒控制台没有任何日志。后来才知道是脚本在等权限确认按了一次回车才继续。所以这里有个经验如果安装脚本看起来“卡住了”先等一下不要立刻 CtrlC。装完之后建议手动验证一下目录结构。通常你会看到类似这样的路径~/.codex/skills/ ├── brainstorm/ │ └── SKILL.md ├── planning/ │ └── SKILL.md ├── implementation/ │ ├── SKILL.md │ └── templates/ └── testing/ ├── SKILL.md └── checklist.md验证方法很简单直接问你的 Codex“你现在有哪些技能”如果它能列出来一堆带说明的技能名字就说明安装成功。2.3 方式二手动配置到项目里有时候你并不想把 superpowers 装到全局而是只想给某个项目使用。比如一个团队统一用一套定制技能就不应该依赖成员个人的全局目录。这种情况下我推荐手动配置到项目里。以 Codex 为例你可以在项目根目录创建一个类似.codex/skills的目录然后把需要的技能文件夹整个复制进去。之后在这个项目目录里启动 Codex它会自动加载项目级技能。对于 Java 项目我通常建议在项目根目录放一个superpowers/文件夹专门存放团队技能和脚本。这样做的好处是技能文件跟随 Git 仓库走新成员 clone 下来就自动拥有同一套能力不需要额外安装。手动配置的步骤如下创建项目技能目录例如.codex/skills。从 superpowers 仓库复制你需要的技能文件夹过去。用桌面端或 CLI 测试 AI 是否能读取到技能。在 README 里记录技能使用方法方便同事上手。这种方式比全局安装更可控也更能体现团队协作价值。2.4 安装前后对比AI 的行为差异安装之前我让 Codex“给一个 Java 类写单元测试”它直接生成了一堆 JUnit 代码然后就不管了。装完 superpowers 之后同样的请求它会先输出测试计划列出覆盖列表询问我是否需要数据夹具最后才生成代码。它甚至会用技能文件里的 checklists 来自查一遍。这种变化不是玄学而是因为它加载了技能文件里对任务的定义和流程约束。我特别建议新手安装完先做这个对比实验否则你很难体会到 superpowers 的价值。3. 在 Java 项目里用 superpowers 跑通一个实战任务3.1 任务背景给一个计算器类补全单元测试我选了一个非常典型的场景一个 Java 项目里有Calculator类包含add、divide、power这几个方法。我想让 Codex 基于 superpowers 的“测试技能”帮我把单元测试补全。这个场景能充分展示 superpowers 的效果因为需求看起来简单但隐藏了不少坑divide方法要考虑除零异常power方法要考虑大数溢出和负数指数这些细节如果没有测试计划AI 很容易漏掉。先看下原有的 Java 类长什么样public class Calculator { public int add(int a, int b) { return a b; } public double divide(int a, int b) { return (double) a / b; } public long power(int base, int exponent) { return (long) Math.pow(base, exponent); } }这个类有个明显的常识性问题divide方法没有处理b 0的情况。这种逻辑缺陷正好是 AI 技能发挥作用的地方因为它会引导 AI 先思考输入边界而不是直接机械翻译代码。3.2 使用技能的第一步先规划再动手在 superpowers 里最核心的一个技能就是“计划先行”。我并没有直接让 Codex 生成测试代码而是先让它使用 planning 技能输出一份计划。具体的做法是在启动 Codex 之后我给它这样的指令请先使用 planning 技能分析这个项目中 Calculator 类需要覆盖的测试场景然后输出一份测试计划。不要直接写代码。然后 Codex 加载了技能文件输出了一份比较完整的计划。计划里包含这些要点正常情况下的加法测试大数相加溢出测试正常除法测试除数为零的异常测试负指数测试幂运算结果溢出测试边界值输入测试这里你能看到superpowers 的价值不是“让 AI 更聪明”而是“让 AI 不偷懒”。它把程序员平时做测试设计时的那套经验模板化了。3.3 让 AI 按计划执行并生成代码计划确认之后我再告诉 Codex计划已经确认请按计划逐条实现测试并用 Maven 运行所有测试最终告诉我哪些用例通过、哪些失败。这次生成的质量明显高很多。它不仅写了Test方法而且还给divide方法预设了ArithmeticException的断言因为在计划阶段就已经识别出了除零问题。Codex 最终生成的测试类大概长这样import org.junit.jupiter.api.Test; import static org.junit.jupiter.api.Assertions.*; class CalculatorTest { private final Calculator calculator new Calculator(); Test void add_shouldReturnSumOfTwoNumbers() { assertEquals(5, calculator.add(2, 3)); } Test void add_shouldHandleOverflow() { assertEquals((long) Integer.MAX_VALUE 1, calculator.add(Integer.MAX_VALUE, 1)); } Test void divide_shouldReturnQuotient() { assertEquals(2.5, calculator.divide(5, 2), 0.0001); } Test void divide_shouldThrowWhenDivisorIsZero() { assertThrows(ArithmeticException.class, () - calculator.divide(1, 0)); } }注意这时候 AI 生成的测试代码里提到了calculator.divide(1, 0)会抛异常但原类里其实没有这个逻辑。这一步是非常重要的检测到了一个 bug。也就是说superpowers 成功地把 AI 从“代码生成器”变成了“工程质量审查员”。3.4 修复代码并回归测试测试跑完之后有红有绿Codex 主动分析了失败原因并建议修改Calculator类中的divide方法。在它的技能文件里有一条规则是“修复代码前必须重新分析原有逻辑”。于是它先给出修复方案再修改代码。最终的divide方法被改成public double divide(int a, int b) { if (b 0) { throw new ArithmeticException(Cannot divide by zero); } return (double) a / b; }修改之后再次运行mvn test所有测试通过。这个流程看起来平淡但实际上已经完成了一个完整的“计划—执行—验证—修复”循环这正是 superpowers 最核心的日常工作模式。如果你只用普通 promptCodex 大概率会直接生成一堆代码然后跑一次测试告诉你通过完全不会主动检查被测类本身的逻辑缺陷。3.5 在 Java 项目里使用 superpowers 的最佳实践我用了大概两周之后总结出几个适合 Java 项目的黄金姿势项目根目录固定一个 skills 目录让团队成员共享同一套技能。把 Maven/Gradle 的 wrapper 纳入版本管理确保 AI 执行的构建命令在任何机器上结果一致。让 AI 每次动手前先写计划并保存在一个plans/目录里方便追溯。技能文件里的模板不要盲改先确认改动不会影响其他技能的执行流程。这些做法不复杂但对稳定性提升非常大。尤其是 Maven wrapper 这一点我在 CI 环境里遇到过太多次“本机能跑、CI 上跑不了”的问题都是因为大家用的 Maven 版本不一致。4. 常见问题与排查技巧实录4.1 装了技能但 AI 完全没反应这是最常见的问题很多人安装 superpowers 后发现 AI 的行为跟以前一模一样感觉白装了。我遇到这种问题会按顺序排查检查技能目录是否在 CLI 扫描范围内。不同的 CLI 可能只扫描特定路径比如.codex/skills还是~/.codex/skills。询问 AI 当前可用技能。直接问“你现在有哪些技能”如果它列不出来说明技能没有加载。确认 SKILL.md 的格式。有些技能文件用了 YAML front matter 来声明名称和描述如果格式错了CLI 会跳过。还有一种情况是你在一个子目录里启动 CLI而技能目录在项目外层扫描不到。解决办法是始终从项目根目录启动或者用 CLI 提供的配置指定路径。4.2 Java 项目里的编码问题superpowers 的技能脚本里经常会有“读取文件内容”、“生成代码文件”这一类操作。如果项目里有中文注释或者中文资源文件终端默认编码不是 UTF-8 时AI 读取的内容会乱码它生成的代码也可能因为编码问题编译失败。我的解决方法是在技能执行前先设置 JVM 文件编码直接在 Maven 的pom.xml里加上properties project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties或者在终端里临时设置export JAVA_TOOL_OPTIONS-Dfile.encodingUTF-8这个小动作能避免很多从编码引发的问题。不要小看这个我至少看过三个人因为乱码问题放弃了 superpowers。4.3 技能文件太多导致上下文爆炸我用 superpowers 的初期把所有技能都复制进项目里结果发现 AI 每轮对话都会读取一大堆技能说明上下文很快就满了。而且推理速度明显变慢甚至会出现前后记忆混乱的情况。后来我改成按需加载项目里只放当前阶段需要的技能。比如我刚接到一个重构任务就只放 planning、implementation、testing 三类。等重构完成再把 documentation 技能放进去。如果你是全局安装也可以通过配置禁用不必要的技能。不要贪多技能多不等于效果好结构化的工作流才是核心。4.4 技能修改失效或冲突团队协作时很可能会有人偷偷改了技能文件结果其他人拉代码之后发现 AI 行为变了。这时候最好的排查办法是查看技能文件的 Git 提交历史。因为 superpowers 本身就是普通文件完全可以纳入版本控制。如果出现技能冲突比如两个技能都定义了“测试规范”AI 可能会不知道用哪个。我建议在文件名上做统一前缀比如java-testing、web-testing避免内部描述重叠。5. 我的一些心得和避坑建议5.1 不要把 superpowers 当成黑盒很多人的第一个反应是“我装一个 superpowers 就完事了”但这是错误用法。它最有价值的地方在于技能文件完全开放你能看到 AI 每一条行为规范是从哪里来的。一旦觉得 AI 做得不好你应该去改技能文件而不是去改 prompt。我现在的做法是每遇到一次 AI 执行质量不佳的情况都会沉淀一条新的规则到技能文件里。比如有次它生成的代码没有遵循团队的日志规范我就把日志格式的要求写进了implementation/SKILL.md。慢慢地superpowers 越来越像一个团队的“数字化操作手册”。5.2 对 Java 生态要有一点额外耐心superpowers 最初并不是为 Java 设计的很多技能模板里的示例脚本都偏向 JavaScript 或 Python。你用 Java 项目跑的时候技能文件里的命令可能需要手动调整。比如构建命令从npm test改成mvn test依赖安装从npm install改成mvn dependency:resolve。第一次对接时你可能觉得麻烦但这其实是好事。它逼着你把项目里“人做的操作”全部显性化。当你把 Java 项目的构建、测试、打包流程都写清楚之后AI 在项目里的可用性会上升一个档次。5.3 从“装技能”到“造技能”最后我想说superpowers 的真正价值不是“开箱即用”的那几十个技能而是它提供了一套组织 AI 能力的框架。你完全可以在项目里创建自定义技能把团队特有的规范、流程、checklist 都写成技能文件。我亲自做过一个最折腾的例子给一个老旧的 Spring Boot 项目创建“增量重构技能”。这个技能会指导 AI 每次只重构一个模块、每次改动不超过 200 行、每次重构后必须跑全量测试。因为有了这个技能那段时间我的重构频率反而变快了风险却降低了不少。这个东西后续的扩展空间真的很大。你可以把它当成团队知识库的“可执行版本”让 AI 不只是一个生成代码的工具而是真正融入团队工作流的成员。如果你也想让 Codex 从“会写代码”变成“会做人”我强烈建议你亲自把 superpowers 装一遍跑一个真实任务体验一下区别。