在风头正热的时候网上到处都在聊“superpowers”但说实话真正把它讲清楚的中文资料没几篇。我去年底第一次接触这个项目的时候也懵了看名字以为是个花里胡哨的“超能力插件”装上以后才发现它干的其实是另一件事把AI编程助手从“你问一句它答一句”的状态变成“你给它一个目标它按规范干完”的状态。这篇文章我就以自己在真实项目里的使用经验为主线把superpowers是什么、怎么装、怎么在Java项目里用、踩过哪些坑一次性说清楚。不管你是刚听说这个名字、装到一半卡住还是已经装好但不知道怎么用它干活这篇都适合你。1. 它不是一个超能力插件而是一套“AI工作流说明书”1.1 先弄清楚Codex CLI的痛点在哪里superpowers是围绕Codex CLI工作的一组技能包所以先得说Codex CLI本身。Codex CLI是OpenAI出的一个跑在终端里的AI编程助手能读你的代码库、执行命令、改文件、跑测试非常接近一个“住在终端里的结对程序员”。我刚开始用的时候很兴奋但用了一周就发现了几个越来越难受的问题。第一个问题是每次会话都像失忆。你今天让它用TDD方式写一个模块它写得规规矩矩明天新开一个会话让它写另一个模块它可能一上来就先把实现代码写了根本没想着先写测试。不是它变笨了而是你每次教它的“工作方式”没有沉淀下来。第二个问题是上下文一长就跑偏。一个任务聊到二三十轮之后它经常忘了最开始定下的约束比如“不要改公共接口”、“不要引入新依赖”它照样干。第三个问题是缺少标准动作。有经验的开发者拿到需求会先拆解、再写测试、再小步实现但Codex默认没有这套肌肉记忆你说“帮我实现这个功能”它就真的直奔实现去了。这些问题不是Codex本身能力不够而是缺少一层“工作流层”。superpowers就是来解决这个的。1.2 superpowers的本质用Markdown技能包把工作流固化下来superpowers的作者是Jesse Vincent网名obra他做过不少知名开源项目做superpowers的原因也很朴素他在用Codex的时候发现与其每次在提示词里反复教AI“你该按什么流程走”不如把这些流程写成一套可复用的“技能包”让Codex在需要的时候自动加载。这套机制简单说就是每个技能就是一个Markdown文件文件头部有一段YAML格式的元信息包含了技能的名字、描述、适用场景正文部分就是给Codex的详细指令告诉它拿到什么任务后按什么步骤做、每一步有哪些注意点。比如TDD技能正文里会写着类似这样的话“当用户要求你实现一个新功能时先写一个会失败的测试运行它确认失败再写最小实现让测试通过最后做重构。”这个流程对老程序员来说不稀奇但问题是Codex默认不会自动这么做而技能包会把这段“肌肉记忆”直接塞进它的工作上下文里。所以我说它是一套“AI工作流说明书”一点不夸张。它没有改变Codex的底层能力改变的是Codex拿到任务后的执行方式。你可以理解成Codex本身是一个什么都会一点的新人程序员superpowers是给他配的SOP手册告诉他遇到什么情况该按什么流程来。1.3 为什么说它把“被动问答”变成了“主动执行”我用的时间越久越觉得这个区分特别关键。默认状态下你在Codex里说“帮我看看这段代码”它是被动的你说什么它做什么。但当你装了superpowers并且在对话里说了一句“use the review skill”之后Codex会做的就不再是“看一眼然后点评几句”了而是会主动去调用git diff、逐个文件检查变更、按代码审查清单逐项过最后给你一份结构化的审查报告。这背后的原理不玄乎技能包把“做什么、按什么顺序做、做到什么程度”都写清楚了模型把这些指令当成了任务约束来执行。所以superpowers的实际效果是把你的工程经验、团队规范、个人偏好翻译成了AI能稳定遵守的指令。这也是它和普通提示词最大的区别——普通提示词是一次性的技能包是可积累、可复用的。2. 安装superpowers环境要求与三步初始化2.1 前置环境Node.js版本、Codex CLI版本一个都不能错聊安装之前先把环境说清楚。superpowers本身是用npm发布的包所以Node.js是必须的。我个人建议Node.js版本至少1820以上更好因为技能包的安装脚本用到了不少较新的Node特性版本太老容易在安装阶段报错。检查命令是node -v和npm -v不到位的先去把Node环境补上。然后就是Codex CLI它是superpowers的运行底座基本上可以理解成“没有Codex就没有superpowers”。安装Codex CLI很简单官方推荐npm install -g openai/codex装完以后跑一下codex --version确认版本号能正常打印出来。这里我多说一句Codex CLI本身就要求你有一个可用的OpenAI账号并完成登录授权如果codex本身还不能正常对话那superpowers装得再漂亮也没用。所以我的建议是先花十分钟把Codex CLI从安装到首次对话完整跑通再碰superpowers不然出了问题根本分不清是哪层的毛病。如果你已经能正常使用Codex CLI那环境这块就只剩一件事确认有权限在全局目录安装npm包。很多人在这一步踩坑比如在Linux或macOS上直接npm install -g报EACCES权限错误。我的做法是优先用nvm管理Node版本这样全局安装目录就在用户目录下不需要sudo。用sudo装全局npm包短期能解决但后续很容易出现目录权限混乱的问题不建议。2.2 安装与初始化命令详解环境就绪之后安装superpowers就两步。第一步是安装superpowers本体npm install -g obra/superpowers装上以后终端里就有了superpowers这个命令。先别急着用第二步是初始化技能库让它把默认技能包安装到Codex CLI的配置目录里。不同时期项目推荐的具体命令略有变化你以仓库README为准大致是这样superpowers install这个命令会把所有内置技能写进~/.codex/skills目录macOS和Linux是这个路径Windows下会在用户目录的对应位置。执行完之后你可以看一眼这个目录里面应该会出现一堆以技能名命名的文件夹比如tdd、explain-code、review这些每个文件夹里都放着一个Markdown指南文件。看到这些文件说明技能库已经就位了。接下来有个容易忽略的点Codex CLI需要知道技能目录在哪里。有些版本的Codex会自动扫描~/.codex/skills有些版本则需要在Codex的配置文件里指定。我的建议是装完superpowers之后直接打开~/.codex/config.toml看看确认里面有类似skills [~/.codex/skills]这样的配置。如果没有手动补上这一行再重启Codex保守但有效。2.3 验证安装是否成功的两个信号装完以后怎么确认不是“假装装好了”我一般看两个信号。第一个信号是文件层面ls ~/.codex/skills能看到技能文件夹说明superpowers install这一步成功。第二个信号是行为层面在Codex CLI里新建一个会话输入一句“use the explain-code skill”如果它回应的方式明显是“先拆解代码结构、再逐行解释、最后给总结”而不是泛泛地跟你说“这段代码意思是……”那就说明技能已经被加载并且生效了。这里有个很容易安心的判断方法没加载技能时Codex的回答风格和平时闲聊区别不大加载技能后你会明显感觉它做事“有章法”了会主动分步骤、列观察项、按清单走。这个体感差异比看什么日志都来得直观。如果你在验证时发现它完全没有技能加载的样子别急着怀疑人生大概率是配置路径没对上或者版本有差异。这类问题的完整排查思路我放在第5章专门讲这里你可以先回到~/.codex/config.toml检查配置项是否存在。3. 上手实操技能触发逻辑与高频技能拆解3.1 技能怎么被触发自然语言触发词的设计逻辑安装只是开始真正用起来的第一步是理解触发逻辑。superpowers的技能不是像插件那样“装了就自动常驻”而是按需加载。它的工作方式是你在对话里明确提到某个技能Codex会去技能库里找到对应的Markdown文件把里面的内容当作工作约束来执行。最稳妥的触发格式是英文use the 技能名 skill。比如use the tdd skill、use the review skill。这个格式我建议你形成肌肉记忆因为它最不容易产生歧义。我也试过纯中文触发比如“用TDD技能来写”在多数情况下也能被正确识别但如果Codex版本较老或者技能描述里的关键信息是英文中文触发的识别率会下降。你可能会问为什么superpowers不把所有技能全部塞给Codex让它自己判断什么时候用哪个答案很现实技能全部常驻会占用大量上下文窗口反而降低回答质量。而且很多技能之间有隐含的先后关系比如“先解释再审查”和“先审查再解释”结果完全不同。所以按需加载这个设计看似麻烦实际是取舍之后的最优解。3.2 高频技能逐个拆解我在真实项目里用得最多的是这几个逐个说下它们各自解决什么问题。explain-code代码解释让Codex不是泛泛地讲代码“做了什么”而是按“整体结构→关键函数→边界条件→潜在问题”的结构做一次完整讲解。适合接手不熟悉的项目或者做技术评审前快速过代码。tdd测试驱动开发这是我觉得superpowers里最值钱的技能。它强制Codex先写失败的测试再实现再重构。它会把“先红灯、再绿灯、再重构”这个节奏拆成多个小步骤每一步都停下来等你确认。对于追求可维护性的团队这个技能可以说是直接给AI装上了开发规范。review代码审查让Codex基于当前分支的改动做审查它会主动跑git diff检查变更文件按正确性、可读性、安全性、性能等维度给出意见。注意它和你在聊天框里说“帮我看看这段代码”有本质区别——它会先明确“审查范围”是哪些改动再逐条过。git-workGit工作流规范化Git操作流程包括生成符合规范的提交信息、检查分支状态、处理合并冲突前的准备工作。我通常在一个任务开始时先让Codex用这个技能确认当前分支干净避免中途提交把无关文件混进去。这几个技能覆盖了我日常开发流量的八成。剩下的比如brainstorming需求拆解、debugging问题定位我用的频率低一些但同样值得你打开技能文件看一眼它们的触发条件和适用场景。3.3 一次完整的TDD技能实战演示光看解释不如来一次实际操作。我在一个Java项目里曾经让Codex用TDD技能实现一个简单的订单金额计算器需求是“计算含税金额税率10%低于100元的订单免运费”。我在Codex会话里输入的是use the tdd skill 实现一个OrderCalculator方法 calculateTotal(amount) 返回含税金额金额低于100元时额外返回免运费标记。有意思的事情发生了。它没有直接甩给我一个类文件而是先问我“这个需求有没有边界情况需要确认比如金额正好等于100元时要不要收运费税率是固定10%还是可配置”这一步就是技能包里的“需求澄清”步骤在起作用。我补充说“等于100元也免运费税率先固定”。然后它就按TDD流程来了先在src/test/java下写了OrderCalculatorTest写了一个会失败的测试运行测试确认红灯再新建OrderCalculator.java用最简实现让测试通过最后跑一遍全量测试做了一次小的重构把重复计算抽成方法。整个过程它都会停下来告诉我下一步是什么、为什么要这么做。这个体验和我平时用裸Codex完全不同。裸Codex大概率会一次性写完实现类然后“好意”地问你要不要补个测试。而TDD技能是反过来的测试先行每一步都有明确节奏。这就是技能包的价值。4. Java项目里的使用心得从代码审查到测试生成4.1 Java场景下最该先启用的三个技能如果你和我一样主要写Java那superpowers里最值得你先用起来的是这三个组合review、tdd和explain-code。先说为什么是这三个组合。Java项目普遍比脚本语言项目更讲究结构和规范类职责、接口边界、异常处理这些事默认状态的Codex不会主动去管。开了review技能之后你每次提交前让它过一遍变更它给出的审查意见会更贴近“有经验的Java同事在看你的代码”这种感觉比如会提醒你“这里应该用Optional而不是返回null”、“这个异常不应该吞掉”、“流式处理可以简化这段循环”。tdd技能在Java里尤其好用因为Java生态的测试框架成熟JUnit 5配AssertJ已经成了标准配置。技能让Codex自动生成测试类时它会按Maven/Gradle的标准目录结构来放测试代码不会把测试塞到main代码里。我第一回看到它自动建src/test/java目录的时候还挺感慨这就是技能包内置的工程意识。explain-code技能则适合你刚接手一个老模块时使用。我有个维护了三年的支付模块接手时完全没有文档我就是让Codex用这个技能把核心链路逐行过了一遍半小时后就对整个模块的时序和风险点心里有数了。4.2 处理Java特有问题Lombok、泛型、依赖版本但Java场景不是没有坑。我用了几个月下来有几个和Java特性相关的细节想单独提醒你。第一个是Lombok。review技能经常会对Lombok生成的代码表示困惑因为它看的是源码文件上的Data注解看不到生成后的getter/setter。有几次它甚至建议我“手动补全getter和setter”我直接拒绝了然后在技能描述里加了一句“项目中使用了Lombok生成的方法不需要手动实现”后续审查意见就正常多了。所以我的经验是Java项目用superpowers越早把项目上下文告诉它它后续的产出越不容易跑偏。第二个是泛型和类型擦除。explain-code在解释复杂的泛型嵌套时偶尔会陷入“看起来说了很多、实际没说到点子上”的境地。我的处理办法是让它“解释的时候给出具体类型示例”而不是停留在泛型符号层面。比如解释List? extends T时我会让它用List? extends Number举两个实际例子来说明限制。第三个是依赖版本。Codex生成的代码有时候会引入它“记忆里”的依赖版本而这个版本可能和你项目里的其他依赖冲突。我后来在自定义技能里明确加了一条“生成代码时不要自动添加新依赖如果需要新依赖先列出建议的artifactId和groupId等确认后再修改pom.xml。”这个约束帮我省了很多处理依赖冲突的时间。4.3 用自定义指令补足Java团队规范说到自定义技能这里展开讲一讲。superpowers最被低估的能力不是它自带的那些技能而是你能自己写技能。在~/.codex/skills下新建一个文件夹比如叫java-project-rules在里面创建一个Markdown文件文件头写上技能的元信息正文就是你希望Codex遵守的规则。我自己就写了一个核心内容大概是这样--- name: java-project-rules description: Use when working on Java backend projects in this repository --- - 所有新类必须放在 src/main/java 下对应的包结构中 - 所有测试必须放在 src/test/java 下测试方法使用 JUnit 5 注解 - 禁止在代码中直接 catch Exception 后不做任何处理 - 新依赖必须经确认后才可加入 pom.xml - 代码中不允许出现 System.out.println日志请使用 SLF4J写完之后在会话里说一句use the java-project-rules skillCodex就会把这套规则加载进上下文。之后你再让它写代码它会默认遵守这些团队规范。对我来说这才是superpowers的真正用法——它不是给你一套固定的超能力而是给了你一套定义超能力的语法。有时候我会觉得这个东西的本质是“把团队里隐性的开发约定显性化成AI能读的文档”。以前带新人要把这些规矩口头说一遍现在直接写成技能文件新人和AI都在同一条起跑线上。5. 我踩过的坑与完整排查思路5.1 技能不生效先查Codex配置再查技能文件最常见的问题就是明明说了use the review skill但Codex根本没进入审查状态回答得像普通聊天。遇到这种问题我建议你按下面的顺序排查不要乱试。第一步看~/.codex/config.toml里有没有配置技能目录。这是最容易被忽视的。技能装好了不代表Codex知道去读它配置项缺失的话它安安静静地“假装没看见”也不是没可能。确认配置里存在技能路径后重启Codex会话再试一次。第二步看~/.codex/skills目录下的文件结构。每个技能文件夹里指南文件必须在正确的位置。如果文件缺失或者文件名不对同样会导致技能加载失败。可以对比一下技能文件夹里的结构和项目仓库的示例是否一致。第三步看措辞。use the review skill这个格式之所以我推荐是因为它包含两个关键信息触发动词use、目标技能名review。如果你只说了“帮我看看这个改动”Codex可能没有足够信号把review技能调起来。这时候换个说法明确提技能名然后再试一次。这一步一步走下来绝大多数“技能不生效”的问题都能定位到上面三个环节之一。5.2 版本不兼容导致的行为异常第二个坑和版本有关。superpowers迭代很快Codex CLI的更新频率也不低两边版本差距大了之后会出现一些“说不上哪里坏但就是不对劲”的异常。我自己遇到过一次升级Codex CLI之后原来能用的TDD技能突然不触发TDD流程了它的回答变得像普通代码生成。当时我第一反应是技能文件损坏检查半天发现文件好好的。后来排查到这一步我本地的superpowers包版本还是几个月前的而Codex已经升了两三个大版本两者之间有些技能调用方式已经变了。解决办法不复杂重新安装最新版superpowers包重新执行初始化命令把技能文件刷新一遍。我后来养成了一个习惯每隔几周看一眼superpowers和codex是否发布了新版本升级时两边一起动别只升一边。用npm outdated -g可以一次看到全局包的更新情况比较省事。5.3 “更新后行为变了”的应对方法和5.2紧密相关的是另一种情况你没有主动动任何东西但某一天突然发现同一个技能的行为变了。这通常不是你的配置出了问题而是技能包的内容被上游更新了。技能本质上是Markdown指令文本上游项目完全可以调整正文里的步骤顺序和措辞这些改动不需要你重新安装也会被拉取。我遇到过的一次变化是review技能增加了“安全漏洞检查”环节之后每次审查都会多出一节专门讲安全问题范围比之前广了。如果你对特定项目的产出要求很严格不想让技能行为悄悄变化我的建议是在确认技能稳定后把当前版本记录在项目README里或者干脆复制一份技能文件到项目目录并改为引用本地版本。前一种做法适合大多数场景后一种更“锁死”。我自己是两种结合快速项目用默认技能长期维护的核心项目用本地锁定版本。5.4 兜底方案不用技能关键词也能调用技能最后说一个兜底技巧。万一你无论如何都触发不了某个技能还有一个土办法直接把技能文件的内容告诉Codex。你不需要会说use the xx skill你只需要打开技能文件把正文里的指令原样复制粘贴到对话里。这不是绕路而是有用意的。当你粘贴完整技能内容时Codex同样会把那套步骤当作约束来执行效果和正常触发几乎一样。我用这个方法扛过好几次版本不稳定的时期也用来排查过“到底是技能没加载还是技能本身写得不好”的问题。如果你复制了完整的技能内容之后Codex的表现依然不理想那问题就不在加载机制上而在技能本身的指令质量上。这个方法还有一个变体把自己的工作流写成一段150字以内的简短指令不建技能文件直接贴在对话里。对临时性的任务这个轻量方式比建一个完整的技能文件更快。6. 关于“worbuddy怎么用superpowers”这类问题的统一回答6.1 worbuddy这类平台上的superpowers是什么这半年来我看到不少朋友在worbuddy之类的内容聚合或导航平台上搜“superpowers怎么用”然后越搜越糊涂。这里我想统一说清楚你在大多数内容平台上看到的superpowers指的基本上还是同一个开源项目也就是围绕Codex CLI的那套技能包。它不是一个独立软件更没有所谓的“worbuddy专用版”。那些平台只是内容的搬运工把GitHub上的项目说明和社区教程做了二次整理。所以如果你是在某个博客站或导航站看到“superpowers使用指南”内容大概率是换了个说法介绍同一件事。判断方法很简单看文章里提到的安装命令是不是npm install -g obra/superpowers如果是那就是同一个东西。6.2 图形界面工具调用superpowers的基本链路也有人问我不想在终端里操作有没有图形界面能直接用superpowers答案是最终链路还是绕不开Codex CLI但你可以换一个操作入口。比如在支持Codex的编辑器集成环境里打开终端在集成面板里启动一个Codex会话然后在会话里使用技能。本质上你做的事情和前面讲的没有区别启动Codex会话→输入use the xx skill→开始干活。我理解大家想要“图形化”的真实需求大多是希望减少在终端和编辑器之间切换的割裂感。这个可以通过把Codex会话窗口固定在编辑器侧边栏来解决。我在VS Code里就是拉了一个终端面板专门跑Codex写代码在主编辑区看Codex输出在侧边体感上已经非常接近“IDE内置AI助手”了。6.3 在博客教程平台上检索superpowers资料的技巧最后分享几个检索技巧。第一搜索时带上codex前缀搜“codex superpowers”比只搜“superpowers”精准得多因为后者会混进来一大堆和“超能力”有关的无关内容。第二搜“superpowers安装”或“superpowers使用教程”时优先看发布时间超过半年的教程要留意命令是否过时。第三看到任何教程先看它有没有给出可以验证的步骤比如“检查~/.codex/skills目录是否出现技能文件夹”——一个可被验证的步骤比十句“很强大、很好用”都值钱。按这个方式去检索和筛选你基本能在十分钟内判断一篇教程对你的版本有没有参考价值不至于跟着过时命令白折腾半天。我个人用了superpowers大半年最大的体会是它真正的价值不在于让AI变得更“聪明”而在于让AI变得“守规矩”。每次打开Codex之前我会想清楚这次任务该用哪个技能、希望它按什么步骤执行而不是像以前那样含糊地丢一句话。这个习惯一旦养成了产出的质量提升是肉眼可见的。最后再分享一个小技巧如果你在某个项目里反复让Codex做同一套流程把它写成一个自定义技能文件放进~/.codex/skills你会发现——整理指令的过程其实也是在帮你自己理清楚日常工作里哪些步骤是真正必要的。 
长河君 · 2026/10/17 4:42:58 · 阅读 1.2k superpowers实战指南：把Codex CLI从被动问答变成主动执行
在风头正热的时候网上到处都在聊“superpowers”但说实话真正把它讲清楚的中文资料没几篇。我去年底第一次接触这个项目的时候也懵了看名字以为是个花里胡哨的“超能力插件”装上以后才发现它干的其实是另一件事把AI编程助手从“你问一句它答一句”的状态变成“你给它一个目标它按规范干完”的状态。这篇文章我就以自己在真实项目里的使用经验为主线把superpowers是什么、怎么装、怎么在Java项目里用、踩过哪些坑一次性说清楚。不管你是刚听说这个名字、装到一半卡住还是已经装好但不知道怎么用它干活这篇都适合你。1. 它不是一个超能力插件而是一套“AI工作流说明书”1.1 先弄清楚Codex CLI的痛点在哪里superpowers是围绕Codex CLI工作的一组技能包所以先得说Codex CLI本身。Codex CLI是OpenAI出的一个跑在终端里的AI编程助手能读你的代码库、执行命令、改文件、跑测试非常接近一个“住在终端里的结对程序员”。我刚开始用的时候很兴奋但用了一周就发现了几个越来越难受的问题。第一个问题是每次会话都像失忆。你今天让它用TDD方式写一个模块它写得规规矩矩明天新开一个会话让它写另一个模块它可能一上来就先把实现代码写了根本没想着先写测试。不是它变笨了而是你每次教它的“工作方式”没有沉淀下来。第二个问题是上下文一长就跑偏。一个任务聊到二三十轮之后它经常忘了最开始定下的约束比如“不要改公共接口”、“不要引入新依赖”它照样干。第三个问题是缺少标准动作。有经验的开发者拿到需求会先拆解、再写测试、再小步实现但Codex默认没有这套肌肉记忆你说“帮我实现这个功能”它就真的直奔实现去了。这些问题不是Codex本身能力不够而是缺少一层“工作流层”。superpowers就是来解决这个的。1.2 superpowers的本质用Markdown技能包把工作流固化下来superpowers的作者是Jesse Vincent网名obra他做过不少知名开源项目做superpowers的原因也很朴素他在用Codex的时候发现与其每次在提示词里反复教AI“你该按什么流程走”不如把这些流程写成一套可复用的“技能包”让Codex在需要的时候自动加载。这套机制简单说就是每个技能就是一个Markdown文件文件头部有一段YAML格式的元信息包含了技能的名字、描述、适用场景正文部分就是给Codex的详细指令告诉它拿到什么任务后按什么步骤做、每一步有哪些注意点。比如TDD技能正文里会写着类似这样的话“当用户要求你实现一个新功能时先写一个会失败的测试运行它确认失败再写最小实现让测试通过最后做重构。”这个流程对老程序员来说不稀奇但问题是Codex默认不会自动这么做而技能包会把这段“肌肉记忆”直接塞进它的工作上下文里。所以我说它是一套“AI工作流说明书”一点不夸张。它没有改变Codex的底层能力改变的是Codex拿到任务后的执行方式。你可以理解成Codex本身是一个什么都会一点的新人程序员superpowers是给他配的SOP手册告诉他遇到什么情况该按什么流程来。1.3 为什么说它把“被动问答”变成了“主动执行”我用的时间越久越觉得这个区分特别关键。默认状态下你在Codex里说“帮我看看这段代码”它是被动的你说什么它做什么。但当你装了superpowers并且在对话里说了一句“use the review skill”之后Codex会做的就不再是“看一眼然后点评几句”了而是会主动去调用git diff、逐个文件检查变更、按代码审查清单逐项过最后给你一份结构化的审查报告。这背后的原理不玄乎技能包把“做什么、按什么顺序做、做到什么程度”都写清楚了模型把这些指令当成了任务约束来执行。所以superpowers的实际效果是把你的工程经验、团队规范、个人偏好翻译成了AI能稳定遵守的指令。这也是它和普通提示词最大的区别——普通提示词是一次性的技能包是可积累、可复用的。2. 安装superpowers环境要求与三步初始化2.1 前置环境Node.js版本、Codex CLI版本一个都不能错聊安装之前先把环境说清楚。superpowers本身是用npm发布的包所以Node.js是必须的。我个人建议Node.js版本至少1820以上更好因为技能包的安装脚本用到了不少较新的Node特性版本太老容易在安装阶段报错。检查命令是node -v和npm -v不到位的先去把Node环境补上。然后就是Codex CLI它是superpowers的运行底座基本上可以理解成“没有Codex就没有superpowers”。安装Codex CLI很简单官方推荐npm install -g openai/codex装完以后跑一下codex --version确认版本号能正常打印出来。这里我多说一句Codex CLI本身就要求你有一个可用的OpenAI账号并完成登录授权如果codex本身还不能正常对话那superpowers装得再漂亮也没用。所以我的建议是先花十分钟把Codex CLI从安装到首次对话完整跑通再碰superpowers不然出了问题根本分不清是哪层的毛病。如果你已经能正常使用Codex CLI那环境这块就只剩一件事确认有权限在全局目录安装npm包。很多人在这一步踩坑比如在Linux或macOS上直接npm install -g报EACCES权限错误。我的做法是优先用nvm管理Node版本这样全局安装目录就在用户目录下不需要sudo。用sudo装全局npm包短期能解决但后续很容易出现目录权限混乱的问题不建议。2.2 安装与初始化命令详解环境就绪之后安装superpowers就两步。第一步是安装superpowers本体npm install -g obra/superpowers装上以后终端里就有了superpowers这个命令。先别急着用第二步是初始化技能库让它把默认技能包安装到Codex CLI的配置目录里。不同时期项目推荐的具体命令略有变化你以仓库README为准大致是这样superpowers install这个命令会把所有内置技能写进~/.codex/skills目录macOS和Linux是这个路径Windows下会在用户目录的对应位置。执行完之后你可以看一眼这个目录里面应该会出现一堆以技能名命名的文件夹比如tdd、explain-code、review这些每个文件夹里都放着一个Markdown指南文件。看到这些文件说明技能库已经就位了。接下来有个容易忽略的点Codex CLI需要知道技能目录在哪里。有些版本的Codex会自动扫描~/.codex/skills有些版本则需要在Codex的配置文件里指定。我的建议是装完superpowers之后直接打开~/.codex/config.toml看看确认里面有类似skills [~/.codex/skills]这样的配置。如果没有手动补上这一行再重启Codex保守但有效。2.3 验证安装是否成功的两个信号装完以后怎么确认不是“假装装好了”我一般看两个信号。第一个信号是文件层面ls ~/.codex/skills能看到技能文件夹说明superpowers install这一步成功。第二个信号是行为层面在Codex CLI里新建一个会话输入一句“use the explain-code skill”如果它回应的方式明显是“先拆解代码结构、再逐行解释、最后给总结”而不是泛泛地跟你说“这段代码意思是……”那就说明技能已经被加载并且生效了。这里有个很容易安心的判断方法没加载技能时Codex的回答风格和平时闲聊区别不大加载技能后你会明显感觉它做事“有章法”了会主动分步骤、列观察项、按清单走。这个体感差异比看什么日志都来得直观。如果你在验证时发现它完全没有技能加载的样子别急着怀疑人生大概率是配置路径没对上或者版本有差异。这类问题的完整排查思路我放在第5章专门讲这里你可以先回到~/.codex/config.toml检查配置项是否存在。3. 上手实操技能触发逻辑与高频技能拆解3.1 技能怎么被触发自然语言触发词的设计逻辑安装只是开始真正用起来的第一步是理解触发逻辑。superpowers的技能不是像插件那样“装了就自动常驻”而是按需加载。它的工作方式是你在对话里明确提到某个技能Codex会去技能库里找到对应的Markdown文件把里面的内容当作工作约束来执行。最稳妥的触发格式是英文use the 技能名 skill。比如use the tdd skill、use the review skill。这个格式我建议你形成肌肉记忆因为它最不容易产生歧义。我也试过纯中文触发比如“用TDD技能来写”在多数情况下也能被正确识别但如果Codex版本较老或者技能描述里的关键信息是英文中文触发的识别率会下降。你可能会问为什么superpowers不把所有技能全部塞给Codex让它自己判断什么时候用哪个答案很现实技能全部常驻会占用大量上下文窗口反而降低回答质量。而且很多技能之间有隐含的先后关系比如“先解释再审查”和“先审查再解释”结果完全不同。所以按需加载这个设计看似麻烦实际是取舍之后的最优解。3.2 高频技能逐个拆解我在真实项目里用得最多的是这几个逐个说下它们各自解决什么问题。explain-code代码解释让Codex不是泛泛地讲代码“做了什么”而是按“整体结构→关键函数→边界条件→潜在问题”的结构做一次完整讲解。适合接手不熟悉的项目或者做技术评审前快速过代码。tdd测试驱动开发这是我觉得superpowers里最值钱的技能。它强制Codex先写失败的测试再实现再重构。它会把“先红灯、再绿灯、再重构”这个节奏拆成多个小步骤每一步都停下来等你确认。对于追求可维护性的团队这个技能可以说是直接给AI装上了开发规范。review代码审查让Codex基于当前分支的改动做审查它会主动跑git diff检查变更文件按正确性、可读性、安全性、性能等维度给出意见。注意它和你在聊天框里说“帮我看看这段代码”有本质区别——它会先明确“审查范围”是哪些改动再逐条过。git-workGit工作流规范化Git操作流程包括生成符合规范的提交信息、检查分支状态、处理合并冲突前的准备工作。我通常在一个任务开始时先让Codex用这个技能确认当前分支干净避免中途提交把无关文件混进去。这几个技能覆盖了我日常开发流量的八成。剩下的比如brainstorming需求拆解、debugging问题定位我用的频率低一些但同样值得你打开技能文件看一眼它们的触发条件和适用场景。3.3 一次完整的TDD技能实战演示光看解释不如来一次实际操作。我在一个Java项目里曾经让Codex用TDD技能实现一个简单的订单金额计算器需求是“计算含税金额税率10%低于100元的订单免运费”。我在Codex会话里输入的是use the tdd skill 实现一个OrderCalculator方法 calculateTotal(amount) 返回含税金额金额低于100元时额外返回免运费标记。有意思的事情发生了。它没有直接甩给我一个类文件而是先问我“这个需求有没有边界情况需要确认比如金额正好等于100元时要不要收运费税率是固定10%还是可配置”这一步就是技能包里的“需求澄清”步骤在起作用。我补充说“等于100元也免运费税率先固定”。然后它就按TDD流程来了先在src/test/java下写了OrderCalculatorTest写了一个会失败的测试运行测试确认红灯再新建OrderCalculator.java用最简实现让测试通过最后跑一遍全量测试做了一次小的重构把重复计算抽成方法。整个过程它都会停下来告诉我下一步是什么、为什么要这么做。这个体验和我平时用裸Codex完全不同。裸Codex大概率会一次性写完实现类然后“好意”地问你要不要补个测试。而TDD技能是反过来的测试先行每一步都有明确节奏。这就是技能包的价值。4. Java项目里的使用心得从代码审查到测试生成4.1 Java场景下最该先启用的三个技能如果你和我一样主要写Java那superpowers里最值得你先用起来的是这三个组合review、tdd和explain-code。先说为什么是这三个组合。Java项目普遍比脚本语言项目更讲究结构和规范类职责、接口边界、异常处理这些事默认状态的Codex不会主动去管。开了review技能之后你每次提交前让它过一遍变更它给出的审查意见会更贴近“有经验的Java同事在看你的代码”这种感觉比如会提醒你“这里应该用Optional而不是返回null”、“这个异常不应该吞掉”、“流式处理可以简化这段循环”。tdd技能在Java里尤其好用因为Java生态的测试框架成熟JUnit 5配AssertJ已经成了标准配置。技能让Codex自动生成测试类时它会按Maven/Gradle的标准目录结构来放测试代码不会把测试塞到main代码里。我第一回看到它自动建src/test/java目录的时候还挺感慨这就是技能包内置的工程意识。explain-code技能则适合你刚接手一个老模块时使用。我有个维护了三年的支付模块接手时完全没有文档我就是让Codex用这个技能把核心链路逐行过了一遍半小时后就对整个模块的时序和风险点心里有数了。4.2 处理Java特有问题Lombok、泛型、依赖版本但Java场景不是没有坑。我用了几个月下来有几个和Java特性相关的细节想单独提醒你。第一个是Lombok。review技能经常会对Lombok生成的代码表示困惑因为它看的是源码文件上的Data注解看不到生成后的getter/setter。有几次它甚至建议我“手动补全getter和setter”我直接拒绝了然后在技能描述里加了一句“项目中使用了Lombok生成的方法不需要手动实现”后续审查意见就正常多了。所以我的经验是Java项目用superpowers越早把项目上下文告诉它它后续的产出越不容易跑偏。第二个是泛型和类型擦除。explain-code在解释复杂的泛型嵌套时偶尔会陷入“看起来说了很多、实际没说到点子上”的境地。我的处理办法是让它“解释的时候给出具体类型示例”而不是停留在泛型符号层面。比如解释List? extends T时我会让它用List? extends Number举两个实际例子来说明限制。第三个是依赖版本。Codex生成的代码有时候会引入它“记忆里”的依赖版本而这个版本可能和你项目里的其他依赖冲突。我后来在自定义技能里明确加了一条“生成代码时不要自动添加新依赖如果需要新依赖先列出建议的artifactId和groupId等确认后再修改pom.xml。”这个约束帮我省了很多处理依赖冲突的时间。4.3 用自定义指令补足Java团队规范说到自定义技能这里展开讲一讲。superpowers最被低估的能力不是它自带的那些技能而是你能自己写技能。在~/.codex/skills下新建一个文件夹比如叫java-project-rules在里面创建一个Markdown文件文件头写上技能的元信息正文就是你希望Codex遵守的规则。我自己就写了一个核心内容大概是这样--- name: java-project-rules description: Use when working on Java backend projects in this repository --- - 所有新类必须放在 src/main/java 下对应的包结构中 - 所有测试必须放在 src/test/java 下测试方法使用 JUnit 5 注解 - 禁止在代码中直接 catch Exception 后不做任何处理 - 新依赖必须经确认后才可加入 pom.xml - 代码中不允许出现 System.out.println日志请使用 SLF4J写完之后在会话里说一句use the java-project-rules skillCodex就会把这套规则加载进上下文。之后你再让它写代码它会默认遵守这些团队规范。对我来说这才是superpowers的真正用法——它不是给你一套固定的超能力而是给了你一套定义超能力的语法。有时候我会觉得这个东西的本质是“把团队里隐性的开发约定显性化成AI能读的文档”。以前带新人要把这些规矩口头说一遍现在直接写成技能文件新人和AI都在同一条起跑线上。5. 我踩过的坑与完整排查思路5.1 技能不生效先查Codex配置再查技能文件最常见的问题就是明明说了use the review skill但Codex根本没进入审查状态回答得像普通聊天。遇到这种问题我建议你按下面的顺序排查不要乱试。第一步看~/.codex/config.toml里有没有配置技能目录。这是最容易被忽视的。技能装好了不代表Codex知道去读它配置项缺失的话它安安静静地“假装没看见”也不是没可能。确认配置里存在技能路径后重启Codex会话再试一次。第二步看~/.codex/skills目录下的文件结构。每个技能文件夹里指南文件必须在正确的位置。如果文件缺失或者文件名不对同样会导致技能加载失败。可以对比一下技能文件夹里的结构和项目仓库的示例是否一致。第三步看措辞。use the review skill这个格式之所以我推荐是因为它包含两个关键信息触发动词use、目标技能名review。如果你只说了“帮我看看这个改动”Codex可能没有足够信号把review技能调起来。这时候换个说法明确提技能名然后再试一次。这一步一步走下来绝大多数“技能不生效”的问题都能定位到上面三个环节之一。5.2 版本不兼容导致的行为异常第二个坑和版本有关。superpowers迭代很快Codex CLI的更新频率也不低两边版本差距大了之后会出现一些“说不上哪里坏但就是不对劲”的异常。我自己遇到过一次升级Codex CLI之后原来能用的TDD技能突然不触发TDD流程了它的回答变得像普通代码生成。当时我第一反应是技能文件损坏检查半天发现文件好好的。后来排查到这一步我本地的superpowers包版本还是几个月前的而Codex已经升了两三个大版本两者之间有些技能调用方式已经变了。解决办法不复杂重新安装最新版superpowers包重新执行初始化命令把技能文件刷新一遍。我后来养成了一个习惯每隔几周看一眼superpowers和codex是否发布了新版本升级时两边一起动别只升一边。用npm outdated -g可以一次看到全局包的更新情况比较省事。5.3 “更新后行为变了”的应对方法和5.2紧密相关的是另一种情况你没有主动动任何东西但某一天突然发现同一个技能的行为变了。这通常不是你的配置出了问题而是技能包的内容被上游更新了。技能本质上是Markdown指令文本上游项目完全可以调整正文里的步骤顺序和措辞这些改动不需要你重新安装也会被拉取。我遇到过的一次变化是review技能增加了“安全漏洞检查”环节之后每次审查都会多出一节专门讲安全问题范围比之前广了。如果你对特定项目的产出要求很严格不想让技能行为悄悄变化我的建议是在确认技能稳定后把当前版本记录在项目README里或者干脆复制一份技能文件到项目目录并改为引用本地版本。前一种做法适合大多数场景后一种更“锁死”。我自己是两种结合快速项目用默认技能长期维护的核心项目用本地锁定版本。5.4 兜底方案不用技能关键词也能调用技能最后说一个兜底技巧。万一你无论如何都触发不了某个技能还有一个土办法直接把技能文件的内容告诉Codex。你不需要会说use the xx skill你只需要打开技能文件把正文里的指令原样复制粘贴到对话里。这不是绕路而是有用意的。当你粘贴完整技能内容时Codex同样会把那套步骤当作约束来执行效果和正常触发几乎一样。我用这个方法扛过好几次版本不稳定的时期也用来排查过“到底是技能没加载还是技能本身写得不好”的问题。如果你复制了完整的技能内容之后Codex的表现依然不理想那问题就不在加载机制上而在技能本身的指令质量上。这个方法还有一个变体把自己的工作流写成一段150字以内的简短指令不建技能文件直接贴在对话里。对临时性的任务这个轻量方式比建一个完整的技能文件更快。6. 关于“worbuddy怎么用superpowers”这类问题的统一回答6.1 worbuddy这类平台上的superpowers是什么这半年来我看到不少朋友在worbuddy之类的内容聚合或导航平台上搜“superpowers怎么用”然后越搜越糊涂。这里我想统一说清楚你在大多数内容平台上看到的superpowers指的基本上还是同一个开源项目也就是围绕Codex CLI的那套技能包。它不是一个独立软件更没有所谓的“worbuddy专用版”。那些平台只是内容的搬运工把GitHub上的项目说明和社区教程做了二次整理。所以如果你是在某个博客站或导航站看到“superpowers使用指南”内容大概率是换了个说法介绍同一件事。判断方法很简单看文章里提到的安装命令是不是npm install -g obra/superpowers如果是那就是同一个东西。6.2 图形界面工具调用superpowers的基本链路也有人问我不想在终端里操作有没有图形界面能直接用superpowers答案是最终链路还是绕不开Codex CLI但你可以换一个操作入口。比如在支持Codex的编辑器集成环境里打开终端在集成面板里启动一个Codex会话然后在会话里使用技能。本质上你做的事情和前面讲的没有区别启动Codex会话→输入use the xx skill→开始干活。我理解大家想要“图形化”的真实需求大多是希望减少在终端和编辑器之间切换的割裂感。这个可以通过把Codex会话窗口固定在编辑器侧边栏来解决。我在VS Code里就是拉了一个终端面板专门跑Codex写代码在主编辑区看Codex输出在侧边体感上已经非常接近“IDE内置AI助手”了。6.3 在博客教程平台上检索superpowers资料的技巧最后分享几个检索技巧。第一搜索时带上codex前缀搜“codex superpowers”比只搜“superpowers”精准得多因为后者会混进来一大堆和“超能力”有关的无关内容。第二搜“superpowers安装”或“superpowers使用教程”时优先看发布时间超过半年的教程要留意命令是否过时。第三看到任何教程先看它有没有给出可以验证的步骤比如“检查~/.codex/skills目录是否出现技能文件夹”——一个可被验证的步骤比十句“很强大、很好用”都值钱。按这个方式去检索和筛选你基本能在十分钟内判断一篇教程对你的版本有没有参考价值不至于跟着过时命令白折腾半天。我个人用了superpowers大半年最大的体会是它真正的价值不在于让AI变得更“聪明”而在于让AI变得“守规矩”。每次打开Codex之前我会想清楚这次任务该用哪个技能、希望它按什么步骤执行而不是像以前那样含糊地丢一句话。这个习惯一旦养成了产出的质量提升是肉眼可见的。最后再分享一个小技巧如果你在某个项目里反复让Codex做同一套流程把它写成一个自定义技能文件放进~/.codex/skills你会发现——整理指令的过程其实也是在帮你自己理清楚日常工作里哪些步骤是真正必要的。