第一次听说 Superpowers我以为又是一个游戏引擎的名字——毕竟这词在编程圈被用得太泛滥了。直到我把 Codex 的会话开到第 20 轮AI 开始反复念叨同一个错误修复思路、完全想不起前面定下的架构约束时我才意识到自己真正缺的是一套能把“长期记忆”和“执行技能”注入 AI 工作流的外挂。Superpowers 就是这个外挂。它不是某个语言的框架也不是云端服务而是一组围绕 AI 编码助手设计的能力集通过技能文件、回调脚本、进度反馈机制让 Codex 从一个“只会聊天的问答机器”变成“能自己规划、自己验证、自己纠错的项目成员”。这篇文章我会从安装、目录结构、核心机制讲起再重点聊 Java 项目里怎么用它最后把我踩过的坑和排查思路完整写出来。适合正在用 Codex 写实际项目、又觉得输出不够稳定的人。1. 为什么需要 SuperpowersCodex 原生命中短板在哪先别急着装搞清楚它解决什么问题比敲命令重要得多。很多人的预期是“装上 Superpowers 之后 Codex 就变强了”这个说法对但不完整。它真正补的是三块短板。1.1 短期记忆的极限问题Codex 这类模型天生有上下文窗口限制。一个大型 Java 项目里Controller、Service、Mapper、DTO 层层叠加轮次一多AI 就会慢慢忘记最初的架构约定。你第 3 轮告诉它“所有数据库操作必须走 repository 层”第 15 轮它可能就已经直接在 Service 里写 JDBC 了。Superpowers 的解题思路很直接把重要的约定、项目结构、编码规范固化到CLAUDE.md文件里让 AI 每次会话开始都能重新读取。相当于给模型配了一个可持久化的“项目笔记本”而不是靠它脑内保存。1.2 缺乏外部验证手段普通对话模式下AI 给你一段代码它自己并不知道这段代码能不能编译通过。你复制到 IDE 里跑一遍报错再贴回去让它改来回效率极低。Superpowers 引入了回调机制。技能执行到关键节点时可以调用本地的 shell 命令比如mvn -q compile或java -jar app.jar把真实运行结果返回给模型。这就把一个“纯生成模型”升级成了“生成-执行-校验-修正”的闭环系统。1.3 没有任务拆解和进度控制意识面对“给我实现一个用户积分系统”这种需求原生对话往往会一次性输出一大坨代码。表面上很爽实际改起来很痛苦。Superpowers 的brainstorm、plan等技能会强制 AI 先拆解任务、明确接口边界、列出风险和验证步骤再开始动手。这套流程对有多年开发经验的人来说并不新鲜但它能把这种工作习惯“传染”给 AI。注意Superpowers 不是模型本身它只是给模型提供结构化的提示词和工具入口。真正生成代码的还是底层模型所以不要指望它能把 GPT-4 的能力凭空升级到下一个版本。2. 安装前置准备先搞清楚这套东西的依赖边界很多人装 Superpowers 失败不是因为命令敲错而是前置环境没理清楚。它依赖的并不是“一个解释器”那么简单而是一条完整链路上的几个环节。2.1 环境要求Node 版本、Codex CLI 版本与 shell 差异官方安装脚本是 bash 写的核心逻辑只是把仓库克隆到本地、创建符号链接。但后续的sk命令是 Node.js 脚本所以环境里必须有 Node。我建议 Node 版本不低于 18否则回调脚本里的某些语法会报错。Codex CLI 本身需要是较新的版本。Superpowers 的某些技能依赖 Codex 对 MCP 或外部工具调用的支持老版本根本不认这些协议装了也白装。判断方法很简单执行codex --version如果你连这个命令都没有那得先去把 Codex CLI 装好再来。Shell 方面macOS 默认的 zsh 和 Linux 的 bash 都行。但我强烈建议不要用 Windows 的 CMD 或 PowerShell 直接跑安装脚本路径处理和符号链接都很容易出问题。Windows 用户用 WSL 2 会省心非常多。2.2 Superpowers 的目录结构装完以后你会看到什么安装完成之后你的用户目录下会出现一个类似superpowers的文件夹里面有skills和skills_bin两个关键目录另外还有一个CLAUDE.md入口文件。理解这三者的关系很重要路径作用类比CLAUDE.mdAI 每次会话读取的“初始说明书”新员工入职时发的手册skills/存放各种技能定义Markdown 格式手册里的“标准作业流程”skills_bin/技能配套的可执行脚本执行流程时用的工具初次看到这个结构很多人会误以为CLAUDE.md是给 Codex 的提示词。这个理解不算错但不够准确。它更像是“路由表”——告诉 AI 遇到什么场景该加载哪个技能以及这些技能之间如何配合。2.3 安装脚本里看似多余的参数安装时你会看到像--yes、--from-github之类的参数。别觉得它们多余。--from-github指定仓库源这决定了你拿到的是官方版本还是第三方分支--yes则是跳过交互确认适合自动化部署。真正值得留意的是一条路径参数默认会安装到当前用户目录下如果你有多个开发账户装错账户会导致后面对不上。3. 一步步完成安装并验证技能可被 Codex 感知安装过程本身不复杂但有几个细节值得展开。我不打算只丢给你一段官方命令了事而是把每一步背后的目的讲清楚。3.1 下载脚本那一两步的坑安装脚本本身需要先下载到本地再执行。这一步有两个经典问题第一你下载的脚本可能被系统安全策略拦住macOS 下会提示“无法打开因为无法验证开发者”第二下载工具的版本差异会导致脚本内容被截断最后执行时出现莫名其妙的语法错误。我的建议是直接用 curl 下载下载之后立刻检查文件头几个字节确认不是 HTML 错误页。然后给脚本加执行权限再运行。官方命令里通常已经把chmod或bash指令整合好了但手动拆开操作能让你在出错时更清楚是哪一步失败。3.2 安装后先别急着用检查符号链接安装脚本会在你的可执行路径里创建一个sk命令链接。这个链接是否建立成功直接决定了后面所有技能调用是否正常。检查方式which sk如果返回了路径说明链接正常。如果提示command not found: sk先别慌看两件事一是安装日志里是否出现过ln相关报错二是你的PATH是否包含了~/.local/bin或安装脚本指定的目录。很多时候只是新加的路径还没有在当前 shell 会话里生效重新开一个终端就好。3.3 用 sk 命令完成第一次启动验证环境就绪后在项目目录下执行一次简单的技能调用比如sk --help正常情况下列出的所有技能名称就是你安装成功的凭证。如果这个命令能跑通说明 Codex 会通过sk这个入口来调用技能。紧接着做第二层验证打开一个 Codex 会话直接问它“你知道你有哪些技能吗”。如果它回答不上来大概率是CLAUDE.md没有被正确加载而不是技能本身的问题。提示官方文档有时会提到某些新增技能需要额外安装 Python 或 Node 依赖。不要因为看到“可选”就跳过等你真正用到bugbuster这类需要跑测试的技能时缺依赖的回报会很痛苦。4. 技能文件到底是怎么工作的从 CLAUDE.md 到回调循环装好之后大部分人的困惑集中在“它凭什么叫 superpowers”。这里我拆一下它最核心的机制技能文件如何被感知以及回调是怎么形成循环的。4.1 技能描述与回调函数是怎么串起来的skills/目录下的每个技能本质上是一份 Markdown 文件。这份 Markdown 有固定结构开头是技能名称和描述中间是触发场景后面是详细的执行步骤。AI 读这份文件时不只是“看一遍”而是会把里面的步骤当作行动指南来执行。举个例子brainstorm技能的文件里会写明收到需求后第一步先列出至少三个实现方案第二步评估每个方案的风险第三步询问用户选择哪个方向。这不是让你照着读而是让模型按这个顺序生成回复。你看到的输出会变得结构清晰因为模型在背后“按剧本表演”。回调函数是另一层。某些技能文件的末尾会有一段指令告诉模型“在完成这一步之后调用skills_bin/xxx.sh并读取输出”。比如verify技能会在你给出代码后自动执行测试脚本测试结果再被塞回上下文。这就是所谓的“回调循环”——模型不再单方向输出而是能主动运行外部命令来获取真实反馈。4.2 一个 bin/sk 命令是如何驱动交互执行的sk这个命令的角色类似于“技能网关”。当模型决定使用某个技能时它并不是直接执行那个技能目录下的脚本而是通过sk命令去调用。这样做的优势在于控制权集中sk能记录调用历史、设置超时、统一处理环境变量。这里我建议你去翻一下skills_bin里的脚本源码。不一定全看懂但看一下它怎么调用 Codex 的接口、怎么传递 prompt 上下文会对后面的自定义技能非常有帮助。很多以为自己装坏了的人最后发现只是某个脚本里的路径写死了自己的环境偏偏不是那个路径。4.3 “超能力”的边界哪些事它做不到诚实地说几个限制。第一它不能直接把 AI 的训练知识升级只能通过结构化的方式引导模型发挥出更强能力。第二回调脚本能访问的是你本机的文件系统没有跨设备的能力。第三如果项目本身设计混乱Superpowers 不会替你重构——它只是让 AI 更容易遵循你给定的规范。我的个人经验是这套机制真正的好处不在于“AI 更聪明了”而在于“AI 更稳定了”。聪明的输出可能偶尔发生稳定的输出则是可持续的。5. Java 项目实战在 Maven 工程里用 Superpowers 推动开发Java 生态和 Python、JavaScript 有个很大的不同编译步骤不可跳过类型系统非常严格而且大部分项目都依赖构建工具。Superpowers 的回调机制天然适配这套流程前提是你按照 Java 工程的习惯去配置技能。5.1 给 Java 项目写技能文件时要注意的匹配规则Java 项目里类路径、模块划分、依赖关系都体现在 pom.xml 或 build.gradle 里。如果你直接在项目根目录让 AI 帮忙改代码它可能会在错误的位置寻找类定义。我强烈建议在你的CLAUDE.md里明确写出项目结构- 服务层位于 src/main/java/com/example/service - 所有数据库操作必须通过 repository 层 - 编译命令统一使用 mvn -q compile -DskipTests这些内容会被 AI 当作硬性约束。它不会再猜测你的代码在哪也不会凭空给你编一个不存在的方法。5.2 常见 Java 工具链集成时的实现顺序实际用下来我觉得最有效的组合是把bugbuster技能和 Maven 的生命周期绑定起来。思路是这样的让 AI 每次修改代码后先跑mvn -q compile编译通过再继续编译失败就把错误信息贴回上下文让它自纠。具体做法是在项目里新建一个自定义技能文件内容大致是分析需求、修改代码、执行编译命令、读取编译结果、根据错误修改、再次编译。这会形成一个“让机器先检查 AI 写的代码”的循环。相比你在 IDE 里手动编译再报错给它速度至少快三倍。我测试过一个小型 Spring Boot 项目大约 40 个类文件。没有用技能之前AI 经常在修改 Controller 时把 Service 层方法签名改坏然后返回一段需要我再手动排查的报错。加了编译回调之后它自己就能在第二轮修正类型错误。原因很简单——它有压力了编译失败的结果就赤裸裸地放在它眼前。5.3 依赖冲突那类问题的处理策略Java 项目最常见的坑是依赖冲突。AI 在分析报错时经常给出“删除某个依赖”这种治标不治本的建议。Superpowers 提供的办法是在技能描述中强制要求 AI 使用mvn dependency:tree命令获取完整依赖树再基于依赖树进行分析。我给自己的技能文件里加了一条规则任何涉及依赖修改的建议必须先输出mvn dependency:tree -Dverbose命令的实测结果再给出结论。这样既限制了 AI 瞎猜又保留了它的灵活性。这条规则执行之后依赖相关问题的“放疗式修复”少了很多。5.4 Java 版本与构建参数容易忽略的最小细节Java 8 和 Java 17 的语法差异、编译参数、目标字节码版本这些信息 AI 其实能猜到但它是“猜”。在技能文件中直接写上项目使用的 JDK 版本和编译目标能避免很多隐性错误。比如Java 版本: 17 Maven 编译器 source/target: 17 编码: UTF-8写清楚这些AI 就不会时不时给你建议用等于 Java 8 时代的 API 风格。它如果尝试用 var 声明也不会因为语法不匹配而编译失败。6. 我踩过的安装与权限相关的坑与排查链路这部分是硬经验。我前前后后在两个环境里折腾过 Superpowers遇到的坑不少其中一半跟技术有关另一半跟环境和习惯有关。6.1 “command not found: sk”的 5 类原因与逐项排查这个错误表面上是单个原因实际背后至少有五类可能症状可能原因排查方法sk在终端里找不到PATH 未包含安装目录检查echo $PATH看是否有~/.local/bin安装时提示链接已存在之前装过旧版本删掉旧链接重新安装执行sk --help报错Node 版本过低用node -v确认版本技能命令运行一半中断脚本权限不足检查skills_bin下脚本是否有执行权限提示 Python 模块缺失某些技能依赖 Python 环境按报错信息安装对应依赖我的建议是不要看一条报错就钻进去先按上表从上到下排查一轮。很多时候只是 PATH 未更新而你把时间全花在读脚本源码上了。6.2 运行次数超限与和大模型上下文相关的信号处理调用技能多了之后Codex 会表现出“上下文接近满载”的症状回复变慢、开始重复之前说过的内容、甚至忘记当前正在执行的步骤。这是上下文窗口本身的硬限制Superpowers 无能为力但你可以主动控制。我的习惯是把一个大任务拆成多个会话。每个会话只做一件事前一个会话把结论写入progress.md或notes.md下一个会话开始时让 AI 读取这份文件。这样既保留了跨会话的连续性又不会让单次上下文爆炸。另外回调脚本产生的输出会占据上下文空间。我遇到过一个场景一条日志文件有几千行AI 读取之后直接把上下文塞满后续所有对话都变得卡顿。解决办法很简单在技能脚本里加上head -100之类的截断命令只给 AI 看日志的关键部分。6.3 覆盖安装后技能文件被重置的教训Superpowers 更新频繁。每次更新大概率会覆盖skills目录下的文件如果你在官方技能文件里直接改过逻辑更新之后你的修改会被抹掉。我吃过一次亏给bugbuster技能加了自定义 Maven 回调更新之后全没了。解决方式自定义技能一律新建文件命名以custom-开头不要改官方技能。如果实在需要改官方行为用额外的脚本去覆盖而不是直接编辑原文件。这是开源工具使用中最重要的一条习惯。7. 给 Superpowers 类工具的未来项目留的一些设计思路用了一段时间以后我对这类“AI 增强外挂”有了自己的判断。它本质上是在给模型搭建一套“脚手架”让模型的能力能在真实项目中落地。未来可能会有更多类似工具出现所以我这里分享几条设计思路也算是个人经验的总结。7.1 技能与项目知识分离是必须的千万不要把项目特有的信息写死在技能文件里。技能应该是通用的“方法论”项目信息只放在CLAUDE.md或项目级配置文件中。这样技能文件可以在多个项目间复用项目信息的变更也不需要修改技能逻辑。我现在的做法是CLAUDE.md里写项目结构、编码规范、关键命令skills/目录下只放通用流程。项目切换时只需要替换前者后者保持不动。这个分离设计不仅合理而且让维护成本降得非常低。7.2 回调必须是可解释的任何回调脚本的输出至少要回答两个问题这个命令做了什么输出结果是什么意思如果回调只是一股脑地把 stdout 塞给 AIAI 很容易被无关信息带偏。好的回调应该在脚本里就做好预筛选只输出与目标相关的部分。比如 Java 项目中跑测试回调脚本应该只返回“测试类名、失败数量、失败原因”这三项而不是把整份 surefire report 都贴出来。这个思路同样适用于任何类似工具的设计。7.3 渐进式引入比一次性铺开更稳妥我不建议第一次接触就立刻给所有技能都用上。比较稳的操作是先只启用brainstorm和plan这类偏思考的技能观察 AI 的回复是否有结构变化确认有效之后再逐步启用带回调的verify、bugbuster等执行类技能。一次性铺开会让问题变得难以定位——你搞不清是技能配置问题还是模型本身输出不稳定。我在第二个项目里就是这么干的。第一阶段只加 brainstorm项目结构约束写进 CLAUDE.md第二阶段加编译回调第三阶段才启用了依赖分析那条自定义规则。每走一步都让我更清楚哪个环节真正带来了收益。7.4 保留一份手动的备用方案最实用的一条——任何时候都不要对工具产生完全依赖。Superpowers 的安装目录、配置脚本、技能内容我都做了备份。一旦更新的版本引入不兼容问题我可以快速回滚到上一版。别嫌麻烦这类工具还处于快速迭代期变化太快没有备用方案很容易被一次更新打乱节奏。我自己的实际操作是把superpowers的整个目录打包压缩放在项目根目录以外的位置。每次更新后跑一次完整验证流程验证通过才删掉旧包。这个方法看起来有点笨但已经帮我避免了两次回滚事故。最后分享一下我个人的习惯技能文件里能用相对路径就不用绝对路径能用环境变量就不用硬编码参数。这一条能让你的 Superpowers 配置在多个设备上无缝迁移。毕竟工具是拿来解决问题的不是拿来伺候的。