我不止一次被问到："你天天让 Codex 帮你写代码，它到底和直接用 ChatGPT 网页版有什么不一样？" 以前我会回答"它能动文件、能跑命令"，但用久了之后我渐渐意识到，真正的分水岭不在"能不能干活"，而在"干活的习惯靠不靠谱"。
最近我把大量时间花在一个叫 superpowers 的技能包上，它算是把 Codex CLI 的潜力真正打开的那类工具。这篇文章不聊虚的，就从"它是什么、怎么装、怎么用、Java 场景怎么落地、在 WorBuddy 这类图形客户端里怎么生效"一条线讲清楚，顺便把我踩过的坑全部交代出来。如果你是第一次听说 superpowers，或者装了半天发现技能根本没加载成功，这篇文章应该能帮你省下不少时间。
1. 先搞清楚 Superpowers 是什么
1.1 它是给 Codex CLI 用的"技能包"，不是新模型
很多人第一次看到 superpowers 这个名字会以为它是个独立 AI 工具，甚至以为是某种模型增强插件。其实它没那么玄乎，它是一个跑在 Codex CLI 之上的技能集合，本质是一批精心编写的 Markdown 文件。
Codex CLI 是 OpenAI 推出的开源命令行编程代理，它能读你的代码仓库、直接修改文件、执行终端命令，能力确实强。但用过一段时间你就会发现一个很明显的短板：每次会话它都像失忆一样，你不在提示词里反复交代流程，它就不会主动按照工程规范干活。你要求它"先写测试再实现"，它可能这次照做，下次又直接甩实现代码了。
superpowers 解决的就是这个问题。它把这些理想的"开发习惯"固化成结构化的技能文件，每个文件里写清楚：这个技能在什么场景下触发、执行时按什么步骤走、每一步需要遵守什么规则。Codex 在会话加载阶段读取这些技能后，就会严格按照里面的流程行动。它不是让模型变得更聪明，而是让模型的行为习惯变得更规范，这是两个完全不同的维度。
1.2 为什么需要这样一套技能
我自己的体会是，人和 AI 协作最大的成本其实是"每次重新教一遍"。
举个例子，你的团队已经约定好：任何改动之前先跑一遍现有测试、任何新增功能必须带测试、大改动要先出任务拆分。这些规则如果用自然语言提示，你每次新开会话都要重复一遍，而且模型每次理解的程度还不一样。技能文件存在的意义就是把"这些规则"变成一个固定资产，一次配置、处处生效，团队的规范从"靠嘴说"变成"靠文件约束"。
还有一个很现实的问题：Codex 这类工具的能力上限很高，但很多开发者并不知道怎么把它的上限逼出来。大家默认它只是一个"代码生成器"：你说需求，它给代码。而 superpowers 这类技能包真正改变的是工作流形态——比如它可以让 Codex 先输出一份带验收标准的任务清单，再进入编码阶段；可以让它先写失败测试，再写实现。这些"隐性工程经验"是最难用普通提示词稳定触发的，技能文档恰好能稳定约束。
1.3 这套东西适合谁读
我不是说所有人都需要它。如果你只是偶尔让 Codex 帮你写个脚本、改个正则，那直接用默认能力就行，技能包反而多余。但如果你是下面这几类人，我建议你认真看完这篇文章：
- 已经在用 Codex CLI，但觉得它的产出质量不稳定，尤其是"想让它按流程干活很难"
- 做技术负责人或团队 AI 编程的推进者，想把团队的工作流标准化
- 在 WorBuddy 这类图形化客户端里用 Codex，但不知道怎么把技能包接入进去
- 听说过 superpowers 但安装后技能不生效、不知道从哪里排查的开发者
2. 安装与配置：把 Superpowers 挂到你的 Codex 上
2.1 准备环境：先确认你的 Codex 是新的
开始之前，先把基础环境准备好。superpowers 依赖 Codex CLI 来加载技能，所以你的机器上必须装好 Codex。
安装命令很简单，我一般用 npm 装：
npm install -g @openai/codex装完以后验证一下版本：
codex --version如果你以前装过，建议顺手升个级。技能加载这块功能一直在迭代，旧版很可能不支持新的 skill 引用语法。Codex 的配置目录默认在~/.codex，一般情况下你直接查看这个目录就能看到全局配置文件，后面安装技能时会用到。
提示：有些开发者的环境里同时装了多个 Codex 客户端（比如命令行和 IDE 插件各自带一个），升级时要注意你实际调用的那个 codex 命令到底指向哪个路径。
which codex这个命令能帮你看清楚。
2.2 把 superpowers 下载到技能目录
技能文件到底放哪，其实取决于 Codex 约定的 skill 目录。以最常见的配置为例，Codex 会扫描~/.codex/skills/这个全局目录，所以最直接的安装方式就是把仓库 clone 进去：
mkdir -p ~/.codex/skills git clone https://github.com/你的目标仓库/superpowers.git ~/.codex/skills/superpowers仓库地址我在博文里就不写死具体某个 fork 了，因为 superpowers 在 GitHub 上已经有不少衍生版本。核心是：你 clone 下来的目录里，应该有若干.md技能文件，并且目录名最好就是superpowers。这个目录结构决定了后面注册时的引用路径。
除了全局安装，还有一种项目级安装方式。如果你只想在某个具体项目里启用部分技能，可以把技能文件复制到该项目根目录下的.codex/skills/或者.agents/skills/目录中，具体看客户端约定。项目级安装的好处是：同一个团队可以锁定同一个技能版本，避免不同成员机器上的技能文件不一致导致行为差异。
2.3 注册技能：告诉 Codex 你有哪些超能力
下载完文件不算安装完成，很多人在这一步栽了跟头：文件都放好了，但 Codex 完全感知不到技能的存在。
要让 Codex 加载技能，需要在指令文件里做引用注册。项目级的指令文件叫AGENTS.md，放在项目根目录；全局的指令文件放在~/.codex/AGENTS.md。两种方式都支持，但我更建议用项目级的，因为团队协作时它跟着仓库走。
在AGENTS.md中加一行引用，告诉 Codex 加载 superpowers：
@superpowers某些版本也支持按路径引用单个技能，比如：
@superpowers/skills/tdd这个引用机制的原理是：每次会话启动时，Codex 会读取AGENTS.md，看到@superpowers之后，会把对应技能文件的内容注入到上下文中。你可以把技能理解成一个"插件"，注册行就是告诉 Codex 去加载这些插件，加载之后它才拥有这些能力。所以如果你装了技能但没注册，Codex 当然一无所知。
2.4 配置后必做的验证清单
我每次装完技能都会做一套固定的验证流程，这里直接分享给你：
- 重启会话。技能只在会话启动时加载，正在运行的旧会话不会自动识别新技能，这个坑我踩了不止一次。
- 直接询问。在 Codex 里问一句"你加载了哪些技能？"，如果它能把 superpowers 的技能清单列出来，说明注册成功；如果它说不知道，那就要回头查路径和注册行。
- 功能实测。别只看清单，让它对一个小功能走一遍 TDD 技能流程，观察它是不是真的先写测试、再跑测试确认失败，最后才写实现。
- 检查路径权限。如果你的
~/.codex目录权限不对，Codex 读取技能文件时可能直接失败，但又不会报错很明显的提示，这是很容易被忽略的地方。
3. 核心技能拆解：这些"超能力"具体能干什么
3.1 Brainstorm：先想清楚再动手
很多开发者让 Codex 干活时的典型场景是这样的：甩一句话"给支付模块加个退款流程"，然后等着它输出代码。结果代码出来一看，需求边界没对齐、幂等逻辑没考虑、异常处理也是随手写的。
superpowers 里的 brainstorm 技能就是为了治这个问题。触发它之后，Codex 不会直接写代码，而是先进入需求澄清模式：它会主动列出关键决策点，比如退款时效、幂等策略、是否需要人工审核、退款失败后怎么通知用户。等这些决策都确认完，它再输出一个结构化的任务列表和验收标准，最后才问你要不要进入实现阶段。
我实际用下来的感受是：这个技能最适合需求和架构都不太明确的场景。你把一个模糊想法丢给它，让它先把思考过程补齐，再动手。比起直接生成代码，这个过程多花几分钟，但能省掉后面大把返工时间。如果你提的需求只有一两行，又希望 Codex 有资深架构师那样的追问习惯，这个技能是首选。
3.2 TDD 工作流：让 Codex 先写测试再写实现
要说 superpowers 里对我工作方式改变最大的技能，TDD 必须排第一。
默认情况下，Codex 接到需求后倾向于一次性给你完整的实现代码。功能是能跑，但测试经常缺失。就算你提示它补测试，它也更倾向于在代码写完之后"补一个测试"，而不是真正的测试驱动开发。TDD 技能把这个顺序完全掰过来：先写失败测试、运行测试确认失败（红）、再写最小实现、运行测试确认通过（绿）、最后重构（重构阶段）。
我常用的触发提示词是这样：
使用 TDD 技能为 UserService 增加一个 updatePassword 方法，先写测试，确认测试失败后再实现。执行时你会观察到明显的行为变化：它不会上来就写UserService的实现，而是先创建测试类、写断言、运行一次单测，等看到预期的失败输出后，再开始写实现代码。对于一个已经习惯"AI 直接给答案"的人来说，第一次看到这个过程确实有点意外，但事后想想，这才是工程上更健康的节奏。
3.3 Debug 与 Code Review：改动代码前的两道安全网
Debug 技能解决的是"乱试"问题。人排查 bug 最忌讳的就是没有章法，这里改一下跑一下，那里加个日志再看看，时间全浪费了。Debug 技能会让 Codex 走系统化的二分定位思路：先构造复现条件，再添加关键位置日志，通过日志输出缩小问题范围，最后才是定位根因和修复。
我一般这样触发：
跑一下 debug 技能，帮我定位这个偶发超时问题。另一个高频技能是 code-review。它会逐文件读取当前分支的改动内容，按照可读性、边界条件、安全问题、测试覆盖几个维度给出问题清单。我通常在合并代码前把当前分支丢给它过一遍，它会输出一份带文件位置和严重级别的问题列表。不过要提醒一句：它是"流程参考"，不是"绝对真理"，它不懂你的业务全貌，有些建议需要你自己判断要不要采纳。我的做法是把它当成第一轮 review 的检查员，重点挑那些安全类、边界类的问题修。
3.4 除了这几个，还有哪些值得关注的技能
不同版本的 superpowers 技能清单不完全一样，但以下几个核心方向基本是稳定的，我用表格整理一下：
| 技能名 | 核心作用 | 典型适用场景 |
|---|---|---|
| brainstorm | 需求澄清、架构草案、任务拆分 | 新需求、模糊想法落地 |
| tdd | 红-绿-重构循环、强制先写测试 | 新增功能、逻辑复杂的改动 |
| debug | 系统化定位问题、避免乱试 | 偶发故障、性能问题、疑难 bug |
| code-review | 按维度输出改动问题清单 | 合并前代码审查、质量检查 |
| plan | 项目阶段规划、目标拆分 | 新项目启动、大型重构 |
| doc | 生成 README、接口文档 | 交付前文档补齐 |
| security | 安全风险检查 | 涉及鉴权、支付、用户数据的改动 |
我的建议是不要一次全加载。技能越少，Codex 的注意力越集中，执行效果越好。我自己长期保持的技能就四个：brainstorm、tdd、debug、code-review，遇到大项目需要架构评审时，再临时追加 plan 和 architecture 这类技能。
4. Java 场景实战：为什么"superpowers java"搜索量这么高
4.1 Java 项目对流程约束的需求天然更重
之前看到热搜词里"superpowers java"排得挺靠前，我当时就反应过来：这是 Java 开发者在用脚投票。
Java 项目和其他语言的项目有一个很大的差别：工程约束重。构建工具（Maven/Gradle）、测试框架（JUnit）、模块边界（module-info 或者包结构规范）、对象关系映射，这些约束会让 Codex 的自由度被严重压缩。如果你不给它明确的流程约束，它很容易写出"能编译但不合规范"的代码，比如测试没写、Controller 里塞了一堆业务逻辑、异常处理到处 try-catch。
还有一个更实际的问题：Java 项目的上下文非常碎。一个典型 Spring Boot 项目里有大量配置文件、注解、依赖声明，Codex 需要读的东西比脚本项目多很多。没有技能包的流程引导，它很可能会只盯着某个类，忽略了项目整体的分层规范。所以 Java 场景是最需要"先规划再动手"的，superpowers 的价值在这里体现得格外明显。
4.2 Java 技能怎么用：一个 Spring Boot 的实操例子
假设你现在要在一个 Maven + JUnit 5 的 Spring Boot 项目里，给OrderService增加一个createOrder方法。最健康的调用方式是在提示词里把技能、项目工具链、目标说清楚：
项目是 Maven + JUnit 5。 使用 TDD 技能为 OrderService 添加 createOrder 方法。 先写测试，用 mvn test 验证失败后，再写实现，最后再跑一次 mvn test 确认通过。注意我把"用 mvn test 验证"这个约束写进去了，这是关键。因为 Java 项目的测试必须放到项目自己的构建工具闭环里才有意义，而不是让 Codex 单独运行某个测试文件。加了这条之后，它就会主动读取pom.xml、确认依赖，然后按照 Maven 生命周期的节奏跑测试，而不是自己另搞一套执行方式。
另外一个我在 Java 项目里经常配的技能扩展是"编码规范提示"。你可以在 superpowers 的技能文件里加一条约定，比如"Controller 层只做参数校验和路由转发，业务逻辑放到 Service 层；Repository 层禁止出现业务分支判断"。这样 Codex 在生成代码时就会自动遵守项目分层，而不是把 Service 层代码塞进 Controller。
4.3 Java 场景的三个坑
第一，依赖下载问题。国内网络环境下，一个全新 Maven 项目首次拉依赖可能非常慢，Codex 执行mvn test会长时间卡住，它可能误判为命令失败。我的做法是：在新项目里先自己手动构建一次，把依赖缓存到本地仓库，再让 Codex 跑测试命令。这能省掉大量无意义的等待和误报。
第二，类路径和模块化问题。如果项目用了module-info.java或者复杂的类路径配置，Codex 的判断经常出错。我在技能里会加一条前置步骤提示："开始之前先查看 pom.xml 和现有的测试目录结构，确认类路径和模块配置。"这句话能显著降低它乱写 import 和包结构的概率。
第三，测试框架版本差异。JUnit 4 和 JUnit 5 的写法完全不同，Codex 有时候会混用。如果你在技能文件的测试规范里明确写好"本项目使用 JUnit 5，测试类使用 @Test 注解，断言使用 org.junit.jupiter.api.Assertions"，这个问题基本就不会再出现。
5. WorBuddy 等图形化客户端怎么用 Superpowers
5.1 这类客户端和命令行是什么关系
看热搜里有人问"worbuddy 怎么用 superpowers"，我估计提问者是拿 WorBuddy 这类 Codex 的图形化客户端在干活，想在界面里获得同样的技能加持。
WorBuddy 这类客户端的定位，本质上是给 Codex CLI 包了一层图形界面：你能看到文件树、可视化 diff、会话管理，有的还带上下文面板，体验上确实比纯命令行舒服。但你得明白一个底层事实：它调用的是同一个 Codex 运行时，技能加载的逻辑不会因为是图形界面就改变——配置文件还是那份配置文件，AGENTS.md 还是在同一个目录里被读取。
所以结论先说：你的 superpowers 只要能在一个终端环境里生效，在 WorBuddy 这类客户端里大概率也能生效，前提是它们指向同一个 Codex 运行时和同一个配置目录。
5.2 在图形化客户端里启用技能包的步骤
我在 WorBuddy 这类工具里折腾过一阵，总结下来步骤很清晰：
- 先把技能包在命令行环境里跑通。别直接进图形界面，在终端里验证一遍：技能能加载、流程能触发。
- 检查客户端的设置项里有没有"Codex 路径"或者"Runtime"选项，确保它指向的就是你命令行里用的那个 codex 可执行文件。有些客户端自带一个 Codex 运行时，配置目录可能不是
~/.codex，这一步最容易踩坑。 - 确认客户端的工作目录。如果你的客户端以项目文件夹为工作根目录，记得
AGENTS.md要放在这个根目录下，注册行@superpowers要写在里面。 - 在客户端里新建会话，而不是复用旧会话。原因之前说过了，技能只会在会话启动时加载。
- 在会话里直接问"你有哪些可用技能"，确认加载成功。
注意：有些图形化客户端在启动时会自己拼接上下文，不一定会读取项目根目录的
AGENTS.md。如果技能不生效，先去客户端配置里找"运行时指令文件"或者"上下文注入"之类的设置，看看它到底读哪个文件。
5.3 图形界面下的实测差异
我自己的体会是：图形化客户端对技能加载的过程没有命令行那么透明。命令行里你能看到完整的日志，失败原因一目了然；图形界面经常只是静默加载，技能没生效你也看不到具体报错。
所以我的排查策略是"先命令行、后客户端"：如果在客户端里技能不生效，先返回终端跑一遍同样的会话，确认命令行环境是正常的。然后再回到客户端查运行时和配置路径。这个顺序能帮你快速排除"到底是客户端配置问题还是技能本身的问题"，不用在界面里瞎点半天。
另外，如果你的客户端有"会话上下文"面板，一定要利用起来。它能直接显示这次会话里注入了哪些文件和指令，是验证技能加载结果最直观的工具。比起反复问 Codex"你有没有加载技能"，看一眼注入文件列表反而更可靠。
6. 常见问题与避坑实录
6.1 技能不生效的排查思路
这是被问得最多的问题，我直接整理成一个速查表：
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| Codex 完全不知道 superpowers | 技能目录放错位置 | 检查是否在~/.codex/skills/下 |
| 文件放对了但不加载 | AGENTS.md 缺注册行 | 在项目根目录的 AGENTS.md 里写@superpowers |
| 配置也写了还是不生效 | 会话没有重启 | 新开会话，技能只在启动时加载 |
| 命令行生效但客户端不生效 | 客户端指向了别的运行时 | 检查客户端 Codex 路径配置 |
| 技能文件存在但读不了 | 目录权限问题 | chmod检查或调整目录权限 |
这五条能覆盖我遇到过的九成问题。还有一个很多人忽略的点：如果你改了技能文件的内容，旧会话也不会加载新内容，必须重启会话。我一开始老是被这个问题迷惑，感觉明明改了文件行为却不变，其实还是会话没重启。
6.2 技能内容被截断导致流程执行不完整
技能文件本质上是一段注入到上下文的文本，上下文窗口是有限的。如果你的技能文件写得很长，Codex 很可能只读取了开头部分，然后就"以为自己知道全部内容"，实际执行到后面流程时会走样。
我自己踩过的坑是：一开始用了一个非常完整的 TDD 技能文档，里面从项目初始化到重构技巧写了大概四五百行。结果 Codex 执行时还记得前两步"先写测试、确认失败"，但到后面重构那一步就忘了。解决方式是把技能文件拆分得更小、更专注，一个技能只解决一个问题。我现在的经验是：单个技能文件控制在 200 到 400 行之间，效果最好。如果流程太长，就拆成多个技能按需触发，而不是塞在一个文件里。
6.3 加载技能太多导致会话变慢
每加载一个技能，都要消耗一定的上下文 token。如果你把整套技能全部注册进 AGENTS.md，每次会话都会带着这一大堆内容，反映出来的结果就是：响应变慢、注意力分散、该用的技能反而不突出。
我现在的策略是"核心常驻 + 按需引用"。AGENTS.md 里只默认注册三到四个核心技能，比如 brainstorm、tdd、debug、code-review。其他的像 architecture、security 这类比较重的技能，只有在特定任务里才会被单独引用，这样既不会拖慢日常会话，又能在需要时随时调用。
6.4 我的最终使用建议
写了这么多，最后分享一点我现在实际的工作方式。每接到一个新的开发任务，我的会话第一句通常是"使用 brainstorm 技能，帮我拆一下这个需求"，等任务清单确认之后，再紧跟一句"按照拆分结果，用 tdd 技能逐个实现"。在准备提交合并前，会让 Codex 跑一遍 code-review 技能。这套流程运行了两三周，最直观的改变不是我手上的代码变多了，而是 Codex 交付代码的过程质量明显稳定了：测试覆盖率不再是靠提醒才补，大改动不再是无脑上手，遇到复杂问题也终于有了章法。
还有一个心得想多说一句：技能包只是流程参考，它不是不可违背的圣旨。你完全可以在提示词里补充自己的业务约束，覆盖技能文件里的通用建议。我经常这么做——比如我们团队明确要求某个模块不允许引入额外依赖，我就会在触发技能的时候加上这句话。工具是死的，流程是活的，最终决定权始终在你自己手上。superpowers 能帮你把基础的工作习惯立起来，但真正让 AI 编程工作流跑顺的，还是你在实操中不断调整的那些细节。
