我不止一次被问到你天天让 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 加载 superpowerssuperpowers某些版本也支持按路径引用单个技能比如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系统化定位问题、避免乱试偶发故障、性能问题、疑难 bugcode-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 等图形化客户端怎么用 Superpowers5.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 编程工作流跑顺的还是你在实操中不断调整的那些细节。