superpowers 最近在 AI 编程助手圈子里的热度确实高如果你在 Codex CLI、Claude Code 这类终端 agent 上折腾过多半已经看过不少人把它当作必装技能库来推荐。简单说superpowers 不是一堆零散的提示词而是一套能挂到 AI 编程助手上的技能体系把调试、TDD、代码评审、写实施计划这些高频动作从你说一句、AI 自由发挥变成AI 按固定招式和流程出牌。这篇文章我会完整交代我的安装过程、在 Codex 里的配置方式以及在 Java 项目里的真实用法最后把踩过的坑和排查思路一起整理出来。适合正在给 Codex 或类似 agent 增强能力、想让 AI 干活更有章法的开发者参考。1. Superpowers 到底是什么先说清楚它解决什么问题1.1 技能和普通提示词的本质区别很多人的第一反应是我直接在对话里把要求说清楚不就行了吗比如先写测试、再写实现、最后重构这跟装一个技能库有什么差别我一开始也是这么想的直到我对比了几十次执行结果之后才意识到普通提示词的约束力太弱了。普通提示词是一次性的。你在这一轮对话里强调必须 TDDAI 确实会照做但换一个任务、换一个 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 环境终端是 zshCodex 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 -DtestOrderTest失败信息是pay()方法不存在这正是 TDD 技能要求的第一步产出一个有意为之的失败。第二步才是实现public void pay() { if (this.status ! Status.PENDING) { throw new IllegalStateException(只有 PENDING 状态的订单才能支付); } this.status Status.PAID; }再跑一次测试确认通过。第三步重构技能会提示把状态校验提取成私有方法或者加一个可读性更好的枚举映射。整个流程下来代码是最小可用实现测试是真正先行的而不是事后补救。4.3 用系统化调试技能定位一个难缠的 NPENPE 是 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不妨试试这个办法可能也会给你带来类似的收获。