1. 先说清楚：superpowers 到底是哪门子的超能力
1.1 AI 编程助手为什么“总是差一步”
最近如果你也在用 Codex CLI，大概率已经碰到过这种感觉：让它写一个函数，写得很利索；让它从头到尾实现一个完整功能，就开始“指一步走一步”。你让它加个折扣计算，它直接打开 OrderService 改起来，改完之后你发现没测试，跑起来还报错，你问它为什么没有测试，它道个歉，又改了一版，还是不测试。
这不是模型不够聪明，而是它默认的工作模式就是“根据你这句话猜下一段代码”。它不会像资深工程师一样，在动手之前自动过一遍：需求是否清楚、测试用例有哪些、先做什么后做什么、怎么验证自己有没有做对。它更像一个打字很快但不太会自己安排活儿的实习生，你给一句，它干一句。
superpowers 这个项目，就是专门来治这个病的。它不是给你个人用的“效率神器”，而是给 Codex 这类 AI 编程助手装的一套技能包，让它们在你下达任务之后，先按照一套标准流程走：先列计划、先写测试、确认失败、再实现、再重构。看起来只是换了个方式说话，实际用下来差别非常大。
这类工具为什么这几个月忽然火起来，还有一个现实背景：Codex、Claude Code 这些编码代理已经能读文件、跑命令、看测试结果，能力上“手”是齐了，但缺一套工作方法。superpowers 补的正是这一块——不是给 AI 加功能，而是给 AI 加流程。
1.2 “技能包”到底是个什么东西
要理解 superpowers，得先说清楚这里面的“技能”是什么。
一个技能，本质上就是一个目录，目录里放一个用 Markdown 写成的SKILL.md文件。这个文件里面写着某个能力的完整操作步骤、注意事项、检查清单。比如 TDD 技能，文件里可能会写：
当接到一个“实现新功能”的任务时，必须按以下步骤执行：
- 列出需求中的边界条件，写出至少 3 个测试用例；
- 只写第一个测试，运行测试，确认它是失败的；
- 用最少的代码让这个测试通过；
- 运行全部测试，确认没有回归；
- 重构并保持测试全绿。
当对话中触发了对应技能，AI 会读取文件，然后照着这个流程干活。和普通 prompt 的区别在于，普通 prompt 是你在对话里临时说一句“你要先写测试啊”，AI 可能这一轮记住了，几轮之后就被上下文冲掉了。技能文件是稳定存在的，每次都能读到，而且可以被版本管理、可以团队共享。
我用一个不太精准但比较好懂的类比：普通 prompt 是你在工位上喊一句“新来的，干活记得先测一下”；技能包则是你递过去一本操作手册，里面不光写了“要测”，还写了“怎么测、测挂了怎么办、什么时候可以提交”。AI 的效果自然会不一样。
1.3 为什么大家都在搜“codex superpowers”和“superpowers java”
从最近的热搜词来看，最集中的两类需求就是：怎么在 Codex 里装上 superpowers，以及在 Java 项目里怎么用。
前者好理解，很多人已经把 Codex CLI 作为日常工具了，装技能包是自然下一步。后者也合理——Java 项目通常有 Maven/Gradle 这种成熟的构建体系，有 JUnit 这种强测试惯例，代码改动往往牵一发动全身。AI 如果不管三七二十一直接改代码，很容易出现“编译过了但业务逻辑错了”的情况。而 superpowers 里的 TDD、系统调试这类流程，恰好是 Java 工程化开发里最缺、也最需要的那部分。
所以下面我会以 Codex 环境为主线，讲清楚安装、配置、实战和踩坑。Claude Code 的安装思路完全一样，只是目录和配置字段略有差异，你可以对照着来。
2. 安装：把 superpowers 接到 Codex 上
2.1 先确认基础环境
在动手之前，先确认你已经在用 Codex CLI，并且能正常登录使用。这一步跳过的话，后面全部白搭。
打开终端跑一下：
codex --version如果你的版本比较老，先升级到当前稳定版。原因很简单：太老的版本可能还没有开放技能目录读取的机制，装了半天读不到，白折腾。
此外需要一个能用的 git 环境，因为技能包本身是一个 git 仓库，后面升级、回滚都要靠它。Node.js 版本建议 18 及以上，这也是 Codex 官方常见的要求，我的话只是帮你确认一下，具体以官方 README 为准。
2.2 把技能包仓库克隆到本地
定位到用户目录，把 superpowers 仓库克隆到 Codex 的技能目录下。我目前环境里是这样做的：
git clone https://github.com/obra/superpowers ~/.codex/skills/superpowers如果你只希望当前项目生效，也可以放在项目目录下的.codex/skills/文件夹里。区别在于：用户级目录对所有项目生效，适合个人长期使用；项目级目录方便团队一起维护，可以跟着仓库走。新手我建议先用用户级，等确定这个流程对你有用，再迁到项目级。
需要强调一点：这种技能类项目迭代很快，仓库地址和目录结构也许会变。安装前花三十秒看一下官方 README，比我写什么你都信要靠谱。我这里写的是在我自己环境里验证过的通用路径。
2.3 让 Codex 知道去哪读技能
克隆只是把文件放到本地，Codex 还要知道去这个目录加载。目前不同版本给出的配置方式不一样，常见的有两种：
第一种，启动时用命令行参数，类似：
codex --skill-dir ~/.codex/skills第二种，在 Codex 的配置文件里写死目录。路径一般是~/.codex/config.toml，打开之后加一段：
[skills] dirs = [ "~/.codex/skills", ]配置完记得退出当前 Codex 会话再重开。技能文件一般在会话启动时读取，你开着一个老会话去改配置、改文件，它是感知不到的。这个问题我后来踩过好几次，每次都要提醒自己。
如果你发现自己的 Codex 版本里既没有--skill-dir也没有[skills]这个配置项，不要硬猜，直接codex --help看它认哪些参数，或者去官方文档查插件和技能相关的说明。不同版本的字段名会有差异，这不是你在网上看到的教程错了，而是工具本身还没统一。
2.4 验证安装到底成没成
装完之后别急着开始干活，先验证一下。新开一个 Codex 会话，输入：
请列出你当前加载了哪些技能。
如果配置没问题，输出里应该能看到 test-driven-development、systematic-debugging 之类的名字。看到名字，说明技能入口已经通了。
如果没看到名字，按顺序排查三件事：
- 路径对不对：
ls ~/.codex/skills/superpowers/skills，看看里面是不是真的有SKILL.md。 - 会话有没有重启：技能快照是会话级别的，老会话不会自动发现新文件。
- 目录层级对不对：有些版本要求目录名和技能名一致，层级不能多套一层。
这三条占了安装失败原因的九成，剩下那一成是版本兼容问题，先升级再试。
3. 核心技能包拆解：AI 到底多了哪些真本事
3.1 看一下技能包目录结构
superpowers 装好之后，里面并不是一个大文件，而是按技能分好的一组目录。大致长这样：
superpowers/ ├── README.md ├── skills/ │ ├── test-driven-development/ │ │ ├── SKILL.md │ │ └── examples/ │ ├── systematic-debugging/ │ │ └── SKILL.md │ ├── careful-coding/ │ │ └── SKILL.md │ └── ... └── tools/skills目录是核心，每一个子目录代表一个技能。examples里面是一些示例对话或示例代码，AI 可以通过这些例子理解“这种场景下我该怎么表现”。tools目录通常放一些辅助脚本。
我说实话，第一次看到这种结构时有点意外——这么火的项目，核心竟然只是 Markdown 文件。但用了一周之后我理解了：对模型来说，结构清晰的文本指令就是最高效的引导方式。你不需要写复杂的插件逻辑，你只需要把流程说清楚，模型就能照着走。这也是为什么技能包可以快速流行，任何一个懂行的人都能直接打开SKILL.md修改。
3.2 TDD 技能：让 AI 先把测试写给你看
在 superpowers 里，最值得先试的就是 test-driven-development 技能，也就是 TDD。
为什么对 AI 特别有效？因为模型天生有“抄近路”的倾向。你让它实现一个功能，它大概率会顺手把测试也一起写出来，而且这测试多半能通过——因为实现和测试是同一个模型在同一个回合里生成出来的，等于自己出题自己答，看起来“全绿”，实际没有验证价值。
TDD 技能干的是一件事：强制把“先写测试”和“再写实现”拆成两个独立步骤，并且中间必须运行一次测试，看到失败。你可以在会话里这样要求：
在这个项目里使用 test-driven-development 技能开发一个功能：计算订单折扣。先写测试，运行 mvn test 确认失败，再实现，最后再跑测试。
这时候 AI 的行为会和平时明显不一样。它会先列出测试用例，让你看边界条件够不够全；然后写出第一个测试并执行，把失败信息摆在你面前；确认“红了”之后，才开始动手写实现。整个过程有极强的节奏感。
有一点要提醒：很多人用了这个技能但感觉没效果，问题出在“运行测试”这一步。如果你的 Codex 没有执行mvn test的权限，或者项目根目录不对，AI 会默认跳过运行，直接自己脑补“测试应该能过”。没看到真实的红色，就等于没做 TDD。后面我会专门讲权限怎么配。
3.3 系统调试技能：让 AI 停止“瞎改-道歉”循环
另一个我经常用的技能是 systematic-debugging，属于调试方法论。
AI 调试代码的日常大家都不陌生：你给它一段报错日志，它看到最后一行，开始猜原因，改一个地方，不行，再改一个，还不行，然后开始道歉。这个循环特别让人高血压，因为它根本没有在“调试”，它只是在“试探”。
systematic-debugging 技能会强制 AI 换一套打法：
- 先复现问题，确认不是偶发的；
- 收集完整的错误信息，而不是只看最后一行；
- 列出几种可能的根因，并给出每一项的判断依据；
- 用最小的实验去验证假设，确认之后再做改动；
- 改动之后重新运行，确认问题消失并且没有引入回归。
拿 Java 项目举例，以前 AI 看到一个 NullPointerException 的堆栈，经常直接改调用处加个判空。用了调试技能之后，它会先看整个堆栈，找到真正传入 null 的源头，再问“这个值是从哪里来的？为什么这里会是 null？”，最后根据根因来修。这两种做法，结果可能都是加了一个判空，但前者可能掩盖了上游的数据问题，后者才可能真正把 bug 解决。
3.4 别的技能怎么选
superpowers 里还包含一些与规划、代码打磨相关的技能。比如动手编码之前先输出一份计划，或者完成后做一轮自查，看看有没有遗漏边界、有没有删除无用代码。
我的建议是，刚开始不要一口气全开。先激活 TDD 一个技能，用上一周，等你在 Codex 的对话里已经习惯了它“先测试后实现”的节奏，再加调试技能。技能包这东西和人的习惯一样，堆太多反而让 AI 在每一步都要判断“该用哪个”，容易混乱。少而精，效果反而更好。
4. 实战：在 Java 项目里用 superpowers 走完一个完整功能
4.1 准备一个最小的 Maven 项目
前面说了这么多，还是得来一个真实的 Java 场景。我挑了一个非常常见的需求：OrderService增加一个满减折扣功能，规则是满 300 减 50，金额不能小于 0。
项目结构我直接手写，不用 IDE 生成，方便你复现：
order-service/ ├── pom.xml └── src/ ├── main/java/com/example/OrderService.java └── test/java/com/example/OrderServiceTest.javapom.xml里面最关键的依赖是 JUnit 5：
<dependencies> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter</artifactId> <version>5.10.0</version> <scope>test</scope> </dependency> </dependencies>OrderService.java一开始可以只是一个空壳：
package com.example; public class OrderService { public double calculateDiscount(double amount) { return amount; } }这么做是为了让后续的“红-绿-重构”过程更完整。如果一开始就写了一大坨实现，技能包的流程感就被冲淡了。
4.2 在 Codex 会话里让 AI 走一遍 TDD
接下来打开 Codex，输入这样一段：
请使用 test-driven-development 技能为 OrderService 增加满减功能：满 300 减 50，金额不能小于 0。项目根目录是 /path/to/order-service，用 Maven 跑测试。
加了技能包之后，AI 的回复会明显多一个步骤：先给测试用例清单。我当时看到它列的是：
- 金额 300，期望结果 250；
- 金额 299，期望结果 299；
- 金额 0，期望结果 0；
- 金额为负数，应该抛出异常。
然后它会在OrderServiceTest.java里先写这几个测试，再执行mvn -q test。这一步会报失败，因为calculateDiscount目前就是原样返回。AI 会把失败信息贴出来，告诉你“测试如预期失败”。
这时候才轮到实现。它会在OrderService.java里加上折扣逻辑和参数校验，再跑一次测试。如果全绿，它还会主动问你要不要做一次小重构，把魔法数字 300 和 50 提成常量。
整个过程下来，你能明显感觉到它不是在“一口气交作业”，而是在按流程走每一步。这种体验和没有 superpowers 时的区别，用过一次就知道了。
4.3 这段过程里我踩过的几个坑
你以为装上技能包就万事大吉？不是。我在 Java 项目里第一次用就遇到了至少三个问题。
第一个是目录问题。Codex 有时候会在它自己认为的项目根目录执行mvn test，但那里根本没有pom.xml，结果报错它还一脸无辜。解决办法是在 prompt 里把绝对路径写清楚，比如“项目根目录是 /Users/me/work/order-service”，不要指望它每次都判断对。
第二个是Maven 首次运行卡顿。新项目第一次跑mvn test要下载一堆依赖，可能卡几十秒，AI 有时候会以为命令无响应，甚至自己取消掉。我的办法是先手动跑一遍mvn -q test把依赖库预热好，再让 AI 去跑测试。
第三个是断言风格。AI 默认生成的 JUnit 断言五花八门，有assertEquals的，有assertThat的，如果你们团队统一用 AssertJ，建议直接在技能文件里补一句“本团队测试断言统一使用 AssertJ”。不要指望它自己从项目里推断出来，你写了这句话，它就老实了。
4.4 把团队规范写进技能包
这也是 superpowers 这类项目最被低估的价值：技能文件是可以改的。
你可以打开~/.codex/skills/superpowers/skills/test-driven-development/SKILL.md，在注意事项部分加上你们团队的约定，比如“新功能必须覆盖边界条件”“测试命名统一用 should_xxx 格式”“不允许使用 System.out 调试”。保存之后重启 Codex 会话，这些要求就会变成 AI 的默认行为。
我自己团队做法是复制了一份技能包到公司内部 git 仓库，和项目代码一起版本管理。这样新同事 clone 下来项目，技能规范也一并到位，AI 的行为在团队内部是统一的。这种“把人的工程规范翻译给 AI”的做法，我猜是接下来一两年里很值得投入的方向。
5. 常见问题与踩坑记录（速查表）
5.1 技能装好了，但 AI 完全不按技能走
这是我被问得最多的一个问题。技能能看到，但让它做 TDD，它还是上来就写实现。
原因通常不是没加载，而是技能触发不够显式。你可以在 prompt 里直接点技能名，比如“使用 test-driven-development 技能”，这时候它没法假装没看见。还有一种更稳的做法，把技能要求写进项目根目录的AGENTS.md文件里，比如：
开始任何新功能开发时，先应用 TDD 技能，遵守“红-绿-重构”流程。
AGENTS.md是很多编码代理会自动读取的项目级说明文件，等于常驻的指令，比你每次在对话里重复要稳定得多。
5.2 AI 说“已加载技能”，但行为没有变化
这种情况一般有两个原因。
一个原因是技能文件里的流程写得太过笼统，模型读了但没有落到行动上。你可以打开SKILL.md检查一下，看它里面有没有明确的“必须运行测试命令并展示失败输出”这类硬性要求。没有的话，补上。
另一个原因是上下文太长，技能指令被淹没了。解决方法是把最关键的步骤写进AGENTS.md，或者你在任务 prompt 里直接把技能包中最重要的一句话说出来，比如“请先写完第一个测试并运行它，确认失败后告诉我”。技能是辅助，prompt 是主导，两头都要有。
5.3 Codex 执行mvn test被拦住了
Codex 默认对命令执行有确认机制，尤其是不在白名单里的命令，它会弹确认，或者直接拒绝。这种情况下 AI 不会真的去跑测试，它可能就嘴上说“测试应该能过”，然后继续推进——这就是 TDD 流程失效的根源。
解决办法是在 Codex 配置里把mvn加入允许执行的命令，或者把项目相关的测试命令放白名单。如果你用的是交互式会话，第一次弹确认时选“总是允许”。这里我不展开具体配置字段，因为版本差异挺大，最简单的方法是测试一下codex --help里看有没有命令白名单相关参数。
但安全问题必须强调：不要为了省事直接全部允许。技能包本质上是一个对你“注入指令”的来源，不可信的技能可能会让 AI 执行危险命令。你自己也要守住底线，rm -rf这种命令永远不要让 AI 自动执行。
5.4 升级技能包之后，AI 行为突然变了
技能包是个 git 仓库，版本一变，行为就可能变。你可能周日升了个级，周一让 AI 干活，发现它处理流程和你上个月习惯的不一样了。
想稳定就锁定版本。在技能目录里跑：
git log --oneline -5 git checkout <commit>固定到某个 commit，再也不用担心上游变化。需要升级时，先看 changelog，再在测试项目里试一下，没问题再切换。
5.5 安全提醒：第三方技能包别乱装
这一点单独拎出来说，因为真的太容易忽略。
技能包的本质是 Markdown 指令，但它会引导 AI 去执行命令、读写文件。如果你从一个不信任的来源安装技能包，就等于让别人替你给 AI 下达了一批指令。这些指令可能是良性的，也可能夹带私货。
我自己的标准是：装之前把SKILL.md从头读一遍，不理解的地方就问为什么；tools目录里的脚本一定要打开看，看懂之后再决定要不要安装。配置命令白名单时，只放必要的构建和测试命令。安全这事儿，靠别人不如靠自己。
最后再说几句实在的
superpowers 用下来，给我最大冲击的不是某一单次输出质量高了，而是 AI 终于开始“有节奏”了。以前它像那种手速飞快但想到哪写到哪的开发者，现在它更像一个按着 check-list 推进的工程师，先列测试用例、红了、绿了、再重构。你看得到它在做什么，也知道下一步是什么，心里踏实很多。
如果你刚开始接触这套东西，我建议不要一把梭把全部技能都开了。就先一个 TDD，在一个简单的 Java 项目里跑通“红-绿-重构”的流程，感受一下它带来的变化，再慢慢加上系统调试、代码审查这些技能。技能不在多，用得顺手才是关键。
最后再分享一个小技巧：技能文件其实是文本，你可以把它当成一份给 AI 的“团队新人手册”来维护。凡是 AI 没做好的地方，都可以在SKILL.md里补一句硬性要求，改完立刻重启会话试一次。这个过程本身，就是把自己的工程经验沉淀成可复用资产的过程。
