superpowers 最近在 AI 编程助手圈子里的热度确实高，如果你在 Codex CLI、Claude Code 这类终端 agent 上折腾过，多半已经看过不少人把它当作"必装技能库"来推荐。简单说，superpowers 不是一堆零散的提示词，而是一套能挂到 AI 编程助手上的技能体系，把调试、TDD、代码评审、写实施计划这些高频动作，从"你说一句、AI 自由发挥"变成"AI 按固定招式和流程出牌"。这篇文章我会完整交代我的安装过程、在 Codex 里的配置方式，以及在 Java 项目里的真实用法，最后把踩过的坑和排查思路一起整理出来。适合正在给 Codex 或类似 agent 增强能力、想让 AI 干活更有章法的开发者参考。
1. Superpowers 到底是什么：先说清楚它解决什么问题
1.1 技能和普通提示词的本质区别
很多人的第一反应是：我直接在对话里把要求说清楚不就行了吗？比如"先写测试、再写实现、最后重构"，这跟装一个技能库有什么差别？我一开始也是这么想的，直到我对比了几十次执行结果之后才意识到，普通提示词的约束力太弱了。
普通提示词是"一次性"的。你在这一轮对话里强调"必须 TDD"，AI 确实会照做，但换一个任务、换一个 session，它又回到自己习惯的套路。而且提示词是静态文本，AI 可能只是"读过"并没有真正按流程执行，尤其是任务稍微复杂一点的时候，它经常自作主张跳步。
superpowers 的做法完全不同。它把每个高频动作封装成一个带名称、触发条件、操作步骤、决策规则的"技能"文件，agent 在接到任务时会先判断这个任务匹配哪个技能，然后按技能正文里的步骤走，而且每一步都有明确的产出要求。换句话说，它把"执行规范"从对话上下文里抽出来，变成了 agent 自身的"肌肉记忆"。
1.2 一套技能目录里面到底有什么
以我从 GitHub 拉下来的仓库为例，安装完成后会看到类似这样的结构：
skills/ ├── brainstorming/ │ └── SKILL.md ├── systematic-debugging/ │ ├── SKILL.md │ └── scripts/ │ └── repro_runner.sh ├── tdd/ │ └── SKILL.md ├── code-review/ │ └── SKILL.md ├── writing-plans/ │ └── SKILL.md └── post-test-editing/ └── SKILL.md每个技能的核心是SKILL.md，头部是 YAML 格式的元信息，正文就是操作手册。拿 debugging 技能举个例子，它的 frontmatter 大概长这样：
--- name: systematic-debugging description: 当测试失败、出现异常堆栈、或者程序行为不符合预期时，使用系统化调试流程定位并修复问题。 ---这个 description 是 agent 决定"要不要调用这个技能"的依据，所以写得越具体、触发词越多，命中率越高。正文部分通常包含：复现步骤怎么写、如何缩小问题范围、每一步完成后要记录下来、什么情况下回退到上一阶段。一些复杂技能还会在scripts/目录里放辅助脚本，供 agent 直接调用。
1.3 适合谁、不适合谁
我的判断是，superpowers 最适合已经在用 AI 编程助手做日常开发的人，尤其是项目构建链路复杂、有大量既有测试、又希望 AI 输出风格统一的团队。比如 Java 项目里 Maven 多模块、JUnit 版本混用、静态检查一堆规则，这种环境里 agent 自由发挥很容易翻车，技能能强制它按项目约定执行。
反过来，如果你只是偶尔让 AI 写个小脚本、问个语法问题，那确实没必要装。技能是有维护成本的，装多了反而让 agent 在手感轻快的场景里也变得拖沓。先看清楚自己的需求，再决定要不要上这套体系。
2. 从安装到初始化：照着做就能跑起来
2.1 环境准备与前置条件
安装本身不复杂，但有几个前置条件值得先确认。第一是 Git，因为整个技能库是从 GitHub 仓库克隆下来的，这个不用多说。第二是看你打算让哪些技能跑起来，有些技能正文里带脚本调用，比如执行测试、统计覆盖率，这些脚本可能依赖 Node.js 或者 Python，建议本地先装好，免得用到的时候卡住。
我实际安装时用的是 macOS 环境，终端是 zsh，Codex CLI 版本是当时的最新版。如果 Windows 用户，建议在 Git Bash 或 WSL 里操作，后面我会专门讲 Windows 下的坑。
2.2 克隆仓库并复制技能文件
先拉代码：
git clone https://github.com/obra/superpowers.git cd superpowers仓库根目录下就是skills/文件夹。接下来有两种挂载思路：全局挂载和项目级挂载。我个人的建议是先用全局挂载，让所有项目都能用，验证没问题之后，再按项目需求把特定技能复制到项目里。
全局挂载到 Codex 的目录：
mkdir -p ~/.codex/skills cp -r skills/* ~/.codex/skills/如果你同时在用 Claude Code，也可以挂一份到~/.claude/skills，两个路径互不冲突。复制完之后看一眼目录结构是否完整，别只复制了SKILL.md丢了scripts/子目录：
ls ~/.codex/skills find ~/.codex/skills -name "SKILL.md" | wc -l正常情况下列出的技能数量应该和仓库里一致。
2.3 项目级挂载与 AGENTS.md 声明
全局挂载的问题是：所有项目都会加载全部技能，实际用不上的技能也会占掉一部分上下文窗口。所以我在做正经项目时更倾向于项目级挂载。
操作也很直白，在项目根目录下建.codex/skills，然后把需要的技能子目录复制进去：
mkdir -p .codex/skills cp -r skills/tdd skills/systematic-debugging skills/code-review .codex/skills/复制完以后，还要在项目的AGENTS.md里声明这些技能的存在。为什么一定要声明？因为 Codex 的 agent 对技能的索引主要是靠描述匹配，但这个匹配不是无限全局搜索，项目级技能如果没有在 AGENTS.md 里"报备"，agent 可能压根不知道自己有这些工具可用。我在AGENTS.md里一般会加这么一段：
## Skills - tdd: 位于 .codex/skills/tdd/SKILL.md，开发新功能时必须按 TDD 流程执行，先写失败测试再实现。 - systematic-debugging: 位于 .codex/skills/systematic-debugging/SKILL.md，所有 bug 修复必须走系统化调试流程。这样 agent 在规划执行路径时，能明确看到本项目有哪些技能可用，以及它们对应的文件位置。
2.4 验证技能是否真的生效
装完别急着开干，先做一次体检。最简单的办法是启动 Codex，问一句：
> 你现在有哪些可用技能？分别适合什么场景？如果它能列出 tdd、systematic-debugging 等技能，并且能说清每个技能的触发条件，说明挂载成功。如果它只说得出 AGENTS.md 里的规则、说不出技能文件内容，大概率是路径或者声明有问题，回到上一节检查。
另外补充一个细节：技能文件只在会话启动时加载，你中途往技能目录里新增了文件，旧会话里是看不到的。凡是改过技能，老老实实重启一个会话再测。
3. 让 Codex 用上 Superpowers 的两种接入方式
3.1 全局技能目录的加载逻辑
Codex CLI 本身有一套技能加载机制。放在~/.codex/skills下的技能属于全局技能，理论上每个会话都能看到。实测下来，Codex 对全局技能的处理比较"隐式"——它会根据任务内容自己判断要不要用，但判断的准确率取决于技能描述写得好不好。
这里有一个很关键的点：技能的 description 不要写得太像"功能说明书"，而要写成像"触发条件清单"。我看到不少人在这一步吃亏，比如把调试技能的描述写成"用于调试代码"，这句话太泛，agent 遇到任何代码问题都可能牵扯进来，结果该走调试流程的反而不走。更好的写法是把触发信号列清楚："当测试失败、出现异常堆栈、程序输出与预期不符时，必须调用本技能"。触发条件越明确，匹配越准。
3.2 通过 AGENTS.md 做显式引用
全局技能适合尝鲜，真正要让项目稳定跑出固定流程，靠的还是 AGENTS.md 显式引用，我在 2.3 已经给过示例。这里再多说一句为什么这条路更可靠：AGENTS.md 是 agent 每次会话都会先读的"项目说明书"，里面对技能的描述会直接影响 agent 的任务规划。你等于是告诉它"这个项目里修 bug 不是自由发挥，是按某个流程走"，这种约束力远比隐式的全局匹配强。
我目前的习惯是：全局技能保留一套通用的作为兜底，项目里只放三到四个高频技能，然后在 AGENTS.md 里给每个技能配一句强制性的使用场景。比如 Java 项目里我强制要求"新增业务逻辑必须先用 tdd 技能"，这样 agent 在写代码之前会把测试先行这个动作当成默认前提。
3.3 实测：让 Codex 跑一个带技能的任务
空谈加载机制没意思，我给你还原一次实际的会话记录。我建了一个空的 Maven 项目，故意在OrderService里留了一个 bug，然后启动 Codex：
> 运行 mvn test，修复所有失败用例，不要改已有的测试。agent 先扫描项目结构，然后它识别出这属于"测试失败"，自动调用了 systematic-debugging 技能。接下来它的行为就明显不一样了：先自己跑了mvn -q test拿到完整失败输出，再逐行读堆栈，定位到OrderService.calculateTotal()里对items的空判断写反了，接着写了一个最小修复，再跑测试确认全绿，最后输出了一段 root cause 说明。
整个过程里它的每一步动作都和技能正文里的步骤对得上，而不是像以前那样直接猜着改。这个对比非常直观：有技能的时候，agent 像一个按规程操作的人；没技能的时候，它更像一个凭直觉答题的实习生。
4. Java 项目里的实战：TDD 和调试技能最值得先上
4.1 为什么 Java 场景尤其吃技能
Java 项目有几个特点，决定了它是技能体系的高收益场景。第一，构建链路长，Maven 或 Gradle 编译、测试、打包一圈下来动辄几十秒，agent 如果盲目试错，成本极高；技能里明确规定"每次改完必须跑最小范围的测试"，能省下大量无效构建。第二，Java 的类型系统和异常处理严格，编译错误、NPE、受检异常这些问题，需要的是系统化定位而不是随机试答案。第三，团队项目里代码风格和分层约定多，agent 自由发挥很容易写出"能跑但不符合项目规范"的代码，技能正好能把规范固化下来。
我自己的 Java 项目里，tmd 和 systematic-debugging 两个技能的调用频率最高，下面分别演示它们的实际效果。
4.2 用 TDD 技能驱动一个订单状态机
假设要给Order加一个支付能力，状态从PENDING变到PAID。没有技能时，agent 大概率直接写实现类，顺便把测试也写了，但测试往往是事后补的，覆盖边界全靠心情。有 tdd 技能时，它会严格按"先写失败测试、再写最小实现、最后重构"的顺序来。
第一步，先写一个肯定会失败的测试：
// src/test/java/com/example/OrderTest.java import org.junit.jupiter.api.Test; import static org.junit.jupiter.api.Assertions.*; class OrderTest { @Test void shouldTransitionFromPendingToPaidAfterPayment() { Order order = new Order(); order.pay(); assertEquals(Order.Status.PAID, order.status()); } }然后跑测试确认失败：
mvn -q test -Dtest=OrderTest失败信息是pay()方法不存在，这正是 TDD 技能要求的第一步产出：一个有意为之的失败。第二步才是实现：
public void pay() { if (this.status != Status.PENDING) { throw new IllegalStateException("只有 PENDING 状态的订单才能支付"); } this.status = Status.PAID; }再跑一次测试，确认通过。第三步重构，技能会提示把状态校验提取成私有方法，或者加一个可读性更好的枚举映射。整个流程下来，代码是最小可用实现，测试是真正先行的，而不是事后补救。
4.3 用系统化调试技能定位一个难缠的 NPE
NPE 是 Java 里的常客，但有些 NPE 特别隐蔽。我碰过这么一个问题：接口偶尔返回 500，日志里只有一行堆栈：
java.lang.NullPointerException: Cannot invoke "com.example.Order.items()" because the return value of "com.example.OrderRepository.findById()" is null如果让 agent 直接修，它可能随手在调用处加一个 null 判断，问题看似没了，但根因完全没解决。systematic-debugging 技能要求的流程是：先复现，再隔离，再定位根因，最后补回归测试。
复现阶段，agent 会写一个最小测试，模拟findById返回空值的情况；隔离阶段，它会沿着调用链发现，问题不在调用方，而在于findById在订单不存在时返回 null，而上层业务又没有空值处理策略；根因定位后，它选择了"订单不存在就抛明确异常"的修复方案：
public Order findById(Long id) { return orders.stream() .filter(o -> o.id().equals(id)) .findFirst() .orElseThrow(() -> new OrderNotFoundException(id)); }调用方改成了捕获异常并转成 404 响应。最后补一条回归测试，再跑全量测试。这个过程中最值钱的不是修复本身，而是"先复现、再定位、后修复"这个顺序被技能强制执行了，agent 没有再出现那种看一眼堆栈就动手改代码的毛病。
5. 常见问题排查实录（附速查表）
5.1 技能列表里看不到任何技能
最常见的问题是挂载路径不对。Codex 对技能目录的识别是区分大小写的，~/Codex/skills、~/.codex/Skills都可能导致加载失败，老老实实用小写路径。另外，如果你用的是旧版 Codex CLI，它可能根本不支持项目级技能目录，这时候优先检查 CLI 版本，或者改用 AGENTS.md 引用方案。
5.2 调用了技能但行为完全不对
技能被调用了，说明描述匹配成功，但执行结果跑偏，八成是技能正文和项目实际环境对不上。比如技能正文里写的命令是npm test，你的 Java 项目根本不吃这一套。解决办法是自己改技能正文，把命令、目录约定、测试命令全替换成项目里的真实命令。技能不是神圣不可改的，它本来就是给你定制的。
5.3 Windows 环境下脚本执行失败
Windows 上有两个坑。第一，直接从仓库复制带 shell 脚本的技能，切换作用域或执行脚本时可能因为换行符和权限问题失败，建议用cp -r而不是符号链接，符号链接在部分 Windows 环境下权限很麻烦，大概率失效。第二，项目路径带空格或中文时，脚本里引用的相对路径会解析出错，尽量把项目放在纯英文无空格路径下，省心。
5.4 和现有 AGENTS.md 规则冲突
项目里通常已经有一份 AGENTS.md，如果里面写了"修改代码先跑测试再提交"这类规则，而技能里又是另一套说法，agent 会陷入两难，执行时可能一会儿听这个、一会儿听那个。我的做法是在 AGENTS.md 里明确写一句"技能文件中的操作流程优先级高于本文件中的通用开发规则"，把冲突裁判权交给技能，避免来回摇摆。
5.5 问题速查表
| 现象 | 常见原因 | 处理方式 |
|---|---|---|
| agent 完全不知道有技能 | 目录名大小写错误或 CLI 版本过旧 | 改用小写路径，升级 Codex，或用 AGENTS.md 显式声明 |
| 技能被错误触发 | description 写得太泛 | 重写 description，加入具体触发信号 |
| 技能调用了但步骤不对 | 正文命令与项目环境不匹配 | 定制技能正文，改成项目真实命令 |
| 脚本执行失败 | 换行符/权限/路径问题 | 项目挪到纯英文路径，用 cp -r 复制 |
| 新旧技能行为不一致 | 改了文件但没重启会话 | 所有技能改动后重启会话再验证 |
| 与其他规则冲突 | AGENTS.md 规则打架 | 显式声明技能优先级 |
6. 用了一段时间后的几点实在建议
最后说几个我自己用下来的体会，这些不是文档里会写的东西，但对长期使用很有帮助。
第一个建议是别贪多。我刚装的时候一股脑把所有技能全部复制进项目，结果 agent 每遇到一个小任务都在不同技能之间跳来跳去，上下文窗口被技能描述占掉一大截，做事反而变慢。后来我只保留 tdd、systematic-debugging、code-review 三个高频技能，手感立刻清爽很多。技能是为你用的，不是用来凑数量的。
第二个建议是定期从上游仓库拉更新。技能这类东西更新频率不低，作者会修 bug、调整步骤、适配新版本 CLI，你装在本地之后就成了一个快照，一直用旧版本会错过很多优化。我一般一个月拉一次，拉完对比变更，只把有意义的更新合并进项目目录。
第三个建议是把技能纳入版本库。项目里的.codex/skills和 AGENTS.md 里的技能声明，应该和代码一起提交到 Git，这样新同事克隆项目之后直接就有整套规则，不用每个人手动配一遍。这也意味着，技能里不要写个人化的绝对路径，一律用相对于项目根目录的路径，才能保证别人拉下来也能用。
我这个月开始试着让 agent 每次调完成调试技能后，额外输出一段不超过五行的大白话原因说明，效果意外地好。因为它被要求"解释给一个不懂代码的业务同事听"，所以不能只说"我修了一个 NPE"，必须讲清楚"为什么订单会查不到，以及后面怎么避免"。这个习惯逼着 agent 把修复过程再消化一遍，我回看提交记录、写变更说明的时候都省事不少。如果你也在用 superpowers，不妨试试这个办法，可能也会给你带来类似的收获。
