superpowers实战：为Codex和Java项目打造AI编码技能包

最近一段时间，我一直在折腾一个叫superpowers的开发辅助工具。说实话，第一次听到这个名字，我的第一反应是“名字起得这么中二，到底能干嘛”。但真正用起来之后，我发现自己有点“真香”了。尤其是当我把superpowers接到日常的 Java 项目里，配合手里已有的 Codex 类编码辅助能力一起用，整个开发节奏明显不一样了——不是说代码不用写了，而是很多琐碎的、重复的、要反复查文档的活，确实被压缩了一大截。

这篇文章不打算写成那种官方文档式的介绍，那样太无聊了。我想以一个实际折腾过的开发者视角，把superpowers是什么、怎么装、怎么配、怎么用、会遇到哪些坑，一次性讲清楚。如果你正在用或者准备用 Codex 系列工具，又觉得默认能力不够“聪明”或者不够贴合自己的项目，这篇文章应该能帮你省下不少试错时间。

1. 先搞清楚 superpowers 到底是什么

1.1 一个给 AI 编码代理装“外挂”的框架

先别急着敲命令，停下来想清楚一件事：superpowers本质上是什么？

我自己更愿意把它理解成一个“技能包框架”。它本身不是一个独立的 IDE，也不是一个非要替换掉现有工作流的重型平台。它像是一个中间层，把你现有的 Coding Agent（比如 Codex、终端里的 AI 编程助手）和一大堆预设的、可复用的“技能”连接起来。这些技能不是简单的提示词模板，而是一套结构化的指令集合——它们规定了 AI 在接到任务时，应该按什么步骤思考、调用什么工具、输出什么格式的成果。

拿生活里的例子类比：你雇了一个很能干的实习生，他聪明、执行力强，但他不知道你们公司的项目规范是什么、代码放在哪、测试怎么跑。superpowers相当于给这个实习生发了一本“岗位操作手册”——每项任务对应一套标准动作，从理解需求到产出代码再到跑测试，都有明确的路径。这样一来，AI 的下限被抬高了一大截，至少不会出现“答非所问”或者“给一堆看着像代码实际跑不起来的伪代码”这种尴尬情况。

1.2 它和 Codex、Java、那些工具链到底是什么关系

搜索热词里出现了codex superpowers、superpowers java、worbuddy 怎么用 superpowers，这其实点出了它的几个典型使用场景。

先说codex superpowers。Codex 是 OpenAI 出的编码代理，能直接在终端里干活，读仓库、改代码、跑命令，确实很强。但它的默认行为更多是“回答问题”和“完成任务”，而不是“按照团队既定标准去完成一套规范化流程”。superpowers恰恰补上了这一块——它给 Codex 挂上一整套技能框架，让 AI 在动代码之前先做分析、写计划、拆任务，干完之后还能自我检查。用了一段时间后我的感受是：代码质量确实更稳定了，跑偏的概率明显降低。

再说superpowers java。很多工具对 Java 的支持往往停留在“会写 Java 代码”层面，但对 Maven 多模块工程、Lombok 注解、Spring Bean 的生命周期、单元测试的规范写法，就有点力不从心。superpowers的技能包允许针对性地补充这类领域知识，让 AI 在写 Java 代码时，不只是生成语法正确的代码，而是生成符合当前项目工程习惯的代码。这一点的价值在大型老项目里尤其能体现——老项目里那些约定俗成的命名方式、分层方式，直接交给默认 AI 经常会被忽略，挂上定制技能包之后情况会好很多。

至于worbuddy（或者拼成 work buddy，一个偏向团队协作场景的工具），它和superpowers的关系更像是“上下游配合”。superpowers负责把 AI 的产出质量拉高、流程理顺，worbuddy这类工具负责把成果同步给团队、发起评审、追踪任务状态。对我这种平时既要在本地写代码、又要和远程同事对接的人来说，两者配合确实省了不少沟通成本。

2. 环境准备与安装：5 分钟跑起来

2.1 依赖检查与版本选择

先说结论：superpowers对不同系统的兼容性做得不错，macOS 和 Linux 下体验比较顺畅，Windows 用户需要稍微注意一下 shell 环境。

在安装之前，先确认几样东西：

• 一个能正常工作的终端环境（macOS 上我用的是 iTerm2 + zsh，Linux 上实测 bash 也没问题）。
• 本机已装好 Node.js，建议版本 18 以上。这是因为superpowers的技能运行时依赖 Node 生态，版本太低可能导致部分脚本无法加载。
• 如果是配合 Codex 使用，请先确保 Codex CLI 已经能跑起来，并且在当前目录下能正确识别你的项目。
• 如果要在 Java 项目里用，本地得有 JDK 和 Maven/Gradle，这个不用多说。

我建议先把现有环境升级到较新版本再装superpowers，否则遇到奇怪报错时，你压根分不清是工具的问题还是环境的问题。

2.2 安装步骤与初始化配置

安装过程本身不复杂。以 npm 方式安装的话，一条命令就能搞定：

npm install -g superpowers

装完之后先别急着用，先跑一下初始化：

superpowers init

这个命令会在你的用户目录下生成一个配置文件夹，里面存放技能包的索引、全局配置、日志文件等。init 过程中它会问你要不要启用“严格模式”，我第一次选的是“是”，后来发现有些任务确实会变得啰嗦，AI 会在动手前输出一大堆分析。建议普通项目先关掉严格模式，等团队已经形成一套固定流程后再开。

初始化之后，需要把superpowers接入到你的编码代理上。以 Codex 为例，在 Codex 的配置文件里，加上：

{ "tools": { "superpowers": { "enabled": true, "autoLoadSkills": true } } }

这里autoLoadSkills设为true，表示启动 Codex 时自动加载superpowers的技能列表。设成false的话，就需要在会话里手动通过/load-skill之类的命令加载，适合那些不想让技能影响所有会话的谨慎派。

2.3 验证安装是否成功

装完最怕什么？最怕不确定它到底有没有生效。我自己的验证方法是三步走：

superpowers --version superpowers skill list

第一条确认工具本体正常，第二条查看当前可用技能包列表。如果列表里能看到一堆技能条目，说明安装和索引都正常。接着打开一个项目目录，启动 Codex，随便输一句“解释一下当前项目的模块结构”，观察它的回复。如果回复前出现了“正在加载 superpowers 技能”之类的日志，或者 AI 的思考过程明显变长、输出内容更结构化，那基本可以确定挂载成功。

注意：如果superpowers skill list输出为空，多半是技能包数据没拉全。可以执行superpowers update手动更新索引。这个问题我第一次装的时候遇到过，一度以为是安装失败了，后来发现只是索引没刷出来。

3. 核心设计逻辑：技能是怎么“跑”起来的

3.1 技能包（Skill）的组成结构

superpowers里最核心的概念就是“技能”（Skill）。一个技能不是一个简单的“提示词字符串”，而是一个包含多文件的结构化目录。

一个典型的技能包长这样：

skils/ ├── plan-code-change/ │ ├── SKILL.md │ ├── rules.md │ └── templates/ │ └── implementation-plan.md

SKILL.md是这个技能的入口文件，里面写清楚这个技能的用途、使用场景、触发条件，以及完整的执行流程。rules.md存放的是这个技能必须遵守的硬性规则，比如“不得在未运行测试前修改核心逻辑”，或者“修改必须附带对应的单元测试”。templates/下面放的是产出物模板，例如项目改造计划、代码评审清单。

当 AI 决定使用某个技能时，它会读取这些文件，把里面的指导原则和约束加载到当前会话中。这就是为什么superpowers的效果比“单纯写一段提示词”要稳定得多——因为它把约束写进了 AI 的执行上下文，而不是靠用户每次手动叮嘱。

3.2 核心技能拆解：从任务拆解到代码评审

我在日常工作中用得最多的几个技能，大致可以分成四类，放在一起对比会更直观：

任务拆解型技能，我建议新手优先掌握。因为在没有拆解技能的情况下，AI 收到“帮我实现用户登录功能”这种需求，很容易上来直接甩一大段代码。代码看起来很完整，但放到项目里往往水土不服：目录结构不匹配、命名风格不一致、异常处理缺失。而挂上拆解技能后，AI 会先输出一份包含现状分析、改动点、涉及文件、实施顺序的方案，然后逐步执行。这个“先计划再动手”的转变，对产出质量的提升特别明显。

3.3 与我之前用过的裸 Codex 的对比

我用没有挂superpowers的裸 Codex 开发过一阵子，最深的感受是“上限很高、下限也很低”。它在处理一些定义得很清楚的小任务时表现得挺聪明，比如“把这段 Python 翻译成 Java”，基本手到擒来。但一旦任务稍微复杂一点，需要多文件联动、理解业务背景、遵循项目现有规范时，裸 Codex 的回复就开始“飘”了——设计的方案看起来很流畅，实际整合进项目时就会出现各种概念偏差。

挂上superpowers之后，第一个明显差异是“行为模式”变了。AI 不再急于给结论，而是先进行一轮上下文分析，再给出多条候选路径并标注推荐项，最后才动手改代码。过程确实会变长，但结果更稳。

第二个差异是“风格跟随”能力。superpowers的技能包可以读取项目里的现有代码风格，在生成新代码时尽量保持一致。这一点对长期维护的项目来说太重要了——最烦的就是 AI 生成一段“看起来对、实际风格跟全项目都不一样”的代码。

4. 实操演示：给 Java 项目定制一套开发流程

4.1 创建一个自定义技能包

光用别人现成的技能包还不够，更高级的玩法是给团队定制专属技能包。我拿 Java 项目举个例子。

先创建技能目录：

mkdir -p ~/.superpowers/skills/java-service-dev cd ~/.superpowers/skills/java-service-dev

写一个SKILL.md，定义技能元信息：

--- name: java-service-dev description: 用于 Java Service 层代码的编写与重构，遵循项目既有分层规范 version: 1.0.0 triggers: - "编写 Service 层" - "重构 Service 代码" --- # Java Service 开发流程 当需要编写或修改 Service 层代码时，严格按以下步骤执行： 1. 分析 Controller 层传入的参数，明确入参类型与边界情况。 2. 检查既有 Service 接口定义，确保实现类遵循接口签名。 3. 业务逻辑如需事务控制，在方法上标注 `@Transactional`，并说明传播行为。 4. 涉及数据库操作时，确认是否走既有 Mapper，不得新建重复查询逻辑。 5. 代码完成后，给新增方法编写对应的单元测试，覆盖正常路径与异常分支。

再写一个rules.md，把“不可违背的规则”单独拎出来：

# 硬性规则 - 不得在 Controller 里编写业务代码，业务逻辑必须下沉到 Service。 - 修改现有方法时，必须保持原方法的返回值语义，不得静默改变调用方行为。 - 所有异常必须有明确的日志记录，禁止 catch 后直接吞掉。 - 新增依赖前，先检查项目里是否已有同等功能的类。

配置好之后，运行superpowers skill reload，新技能就会进入索引。之后启动 Codex，当任务描述匹配到java-service-dev触发词时，AI 就会自动按你规定的流程走一遍。

4.2 settings.json 与项目级配置

这里有一个很多新手容易忽略的点：superpowers虽然安装在用户全局目录，但它的配置是可以按项目细分的。

我通常会在每个 Java 项目的根目录下放一个.superpowers/settings.json，内容大致长这样：

{ "skills": { "include": ["java-service-dev", "unit-test-writer"], "exclude": ["frontend-styler"] }, "behavior": { "runTestsBeforeDone": true, "requirePlanForLargeTasks": true }, "context": { "maxInputTokens": 120000, "autoScanReadme": true } }

include和exclude控制这个项目里哪些技能允许被 AI 加载。比如前端相关的技能，在一个纯后端 Java 项目里就该被排除，免得 AI 在错误的时机给出不必要的建议。

runTestsBeforeDone很有用，它强制 AI 在完成代码后执行一次测试命令，并把测试结果写到回复里。如果 AI 改了 Java 代码却没有跑测试，这面“照妖镜”就会亮红灯。

maxInputTokens是上下文窗口的硬上限。设得太大，AI 容易丢失早期信息；设得太小，它对项目结构的把握又会不足。我目前对中型 Java 项目设置的是 120k 左右，实测效果尚可。

4.3 一个完整任务示例：实现订单状态流转功能

纸上谈兵没意思，我用一个实际任务串一遍完整流程。

假设项目里有一个需求：“当订单支付成功后，把订单状态从待支付改为已支付，并写入支付流水。”我直接在 Codex 会话里输入：

使用 java-service-dev 技能，实现订单支付成功的状态流转功能。

挂载了superpowers的 Codex 第一轮回复不是代码，而是一个简短的分析：

• 定位到OrderServiceImpl和OrderStatusEnum两个关键文件。
• 提出实现方案：新增markPaid方法，在 service 层完成状态校验与更新。
• 指出涉及事务问题：支付回调场景下，状态更新必须与支付流水写入处于同一事务。
• 列出会影响的测试类。

看到这个结构化的方案后，我确认“按此方案执行”。随后 AI 才开始生成代码。整个过程里最让我满意的是，它没有自作主张把状态更新逻辑直接写进 Controller，也没有跳过事务注解——这正是我在技能包里设定的“硬性规则”在起作用。

代码生成完成后，因为runTestsBeforeDone被打开了，AI 自动执行了相关的单测，并在回复里附上测试结果。如果测试失败，它会继续修复、重跑，直到通过或明确报告无法解决。

我录了一段这个过程的日志，截图发到团队群里，一个平时对 AI 编码工具比较保守的老同事看了之后说：“如果每次都能按这个流程走，那倒是可以考虑试着让 AI 写点边角料。”

5. 全局技能库与上下文优化

5.1 全局技能库的使用逻辑

除了项目级的settings.json，superpowers也有全局技能库的概念。可以把那些跨项目通用的技能放到全局里，比如“写 Git 提交信息”或者“解释复杂代码逻辑”，这样不管你在哪个目录下启动编码代理，这些能力都在。

全局技能库的位置一般在用户目录的~/.superpowers/skills下。项目级技能则放在项目里的.superpowers/skills。两边的优先级不同：项目级技能优先于全局技能。也就是说，如果同一个技能在两边都存在，AI 会使用项目里的版本。

这个设计我觉得挺合理。全局放通用能力，项目放专属规范，既照顾效率又不失灵活性。实际工作中，我一般把“规范类”技能下沉到项目里，“通用类”技能保持在全局，尽量少在两边放重复的东西，不然索引一多，AI 反而可能挑错技能。

5.2 上下文窗口优化技巧

用superpowers时，一个最容易踩的坑是“上下文过载”。AI 的上下文窗口是有限的，技能加载得越多，能容纳的项目代码就越少。很多人贪多求全，巴不得把所有技能一次性全挂上，结果 AI 反而变“笨”了。

我现在的做法是：

• 一个项目最多同时include4-6 个技能。
• 核心技能拆解和测试生成类常驻。
• 评审类按需手动触发，不给它长期开着，免得有效上下文被频繁占用。
• 明确技能触发条件，非相关任务不要强行关联技能。

另外，autoScanReadme这个选项我建议打开。它会让 AI 自动读取项目的 README 来补充背景知识，比让 AI 全盘扫描源码目录要省很多 token，效果也不错。

6. 常见问题与排查记录

6.1 安装后 command not found

有段时间我换了台新电脑，装完superpowers后发现终端提示找不到命令。排查后发现是 Node 的全局 bin 目录没加到 PATH 里。

解决办法：

export PATH="$(npm prefix -g)/bin:$PATH"

写入~/.zshrc或~/.bashrc后重新加载即可。这个问题在 macOS 上比较常见，Linux 下一般自动配好了。

6.2 技能加载了但没生效

有时候superpowers skill list能看到技能，但 AI 的回复风格没有任何变化，看起来就像技能没被加载一样。排查下来，最常见的原因是技能包的SKILL.md里写错了触发条件。

比如我在一个技能里写的 triggers 是“编写 Service”，但实际任务描述用的是“创建服务层代码”，关键词不匹配，AI 就不会自动触发。后来我加宽了触发条件，或者把技能设为alwaysLoad: true（仅适用于那些确实需要全程生效的技能），问题就解决了。

6.3 生成的 Java 代码风格和项目不一致

这是一个很现实的问题。superpowers的技能规则是“动态约束”，不是“静态模板”。如果项目里已经存在大量的既有代码，AI 仍然可能生成风格不一致的新代码。

我建议在项目的根目录下放一个CODING_STANDARDS.md，把项目约定写清楚，比如“DTO 必须继承 BaseDTO”“所有 Manager 层方法必须有幂等校验”“禁止使用*导入”等。然后在superpowers的配置里，把这个文件声明为“必读参考文件”：

{ "context": { "referenceFiles": ["CODING_STANDARDS.md"] } }

这样 AI 每次启动都会先将规范文件纳入上下文。在团队里推行一个月后，AI 生成代码的风格一致性明显上了一个台阶。

6.4 错误日志与服务状态排查

如果遇到诡异行为，第一件事是看日志。

superpowers logs --tail 50

日志文件存放在用户目录下的.superpowers/logs中，记录的粒度挺细，包括技能加载时间、AI 调用了哪些技能、执行耗时、报错上下文等。排查时，我会先找找有没有 “skill load failed” 或 “timeout” 相关字样。

有一次某技能导致 AI 响应特别慢，打开日志才发现是模板渲染阶段无限循环了。问题不在 AI 本身，而是我写的技能模板里引用了一个并不存在的变量。修正模板后，问题迎刃而解。

常见问题速查表：

7. 踩坑心得与个人体会

7.1 小步拆分比憋大招更稳

用superpowers的过程，我的体会是“小步走”会比“一口气输出”更稳。以前用 AI 编码工具，总期待它一步到位生成整个模块。后来发现，让 AI 按照技能包拆解出的子任务逐个执行，每完成一步就校验一步，到最后整体质量高得多。

有个中间件项目，我尝试让 AI 一次性生成消息处理器的整个骨架，结果差强人意。后来改成先让我画整体设计，再让 AI 按服务层、存储层、接入层分别开发，中间每层都跑了测试，最终效果就符合预期了。核心原因在于：拆小之后，每一步的上下文更干净，AI 对当前任务的把握也更准。

7.2 别让“工具安全感”麻痹你

我必须提醒一句：工具再好用，也不能代替人来审查。superpowers可以降低 AI 犯低级错误的概率，但它并不理解你的业务，也无法替你做架构决策。

我在团队里定的规矩是：AI 生成的代码，必须有真人 Review；涉及资金、权限、数据一致性的逻辑，AI 只允许做方案辅助，不允许直接改线上代码。这套规矩执行下来，大家在享受工具带来的效率提升的同时，也依然保持着对代码的掌控力。

7.3 从“会用”到“用得顺手”的进阶路径

如果这篇文章你只记住一个建议，那就是：先拿现成的技能包跑通一两个项目，用顺手之后，再为你所在的团队沉淀一套专属技能包。真正让superpowers发挥价值的时刻，不是安装成功的那一刻，而是你和团队梳理出“我们平时到底该怎么写代码、怎么评审、怎么保证质量”并把它固化到技能包里的那一刻。

按我个人的经验，第一次搭建自定义技能包可能需要两三个小时，但之后每次开发、每次评审都在复用这套标准。这个回报率，怎么算都划算。

下一篇我打算专门讲一讲如何在遗留系统里引入这套技能框架，以及怎么把“技能包”这种思维复制到团队内部，让整个研发流程都跟着受益。希望这篇文章能让你少走一些弯路，少踩几个我已经替你踩过的坑。