做为一个天天跟 Codex、Claude Code 打交道的开发者我前阵子在终端里装了一个叫 superpowers 的增强工具集。网上一搜codex superpowers 使用指南大多是转发安装命令真正上手之后你会发现这套脚本改变的其实是 AI 助手的工作习惯而不只是多了几个 slash 命令。这篇文章我就基于自己的 superpowers 安装经过和 Java 项目实操记录把安装配置、核心技能、踩坑日志一次写全给正在找 superpowers 使用教程的人一个真实参考。先说结论superpowers 不是某个 IDE 插件也不是一个新的命令行工具它是一组围绕 AI 编程助手的 shell 脚本和技能库。装好之后你的 Codex CLI、Claude Code 这类助手会获得一套可复用的“超能力”自动修复编译错误、自动装依赖、拆解大型任务、记忆项目上下文、生成变更报告。换句话说它解决的是 AI 写代码时最让人头疼的问题——AI 经常“一次写对”的幻觉以及它不会自己收拾烂摊子。这个项目看名字像玩笑但设计思路非常认真。它把 AI 助手从“一个能聊天的代码生成器”往“一个能独立干活的新手工程师”方向推了一把。接下来我分五个部分聊项目定位与设计思路、安装初始化、核心技能拆解、Java 场景实战、常见问题排查。内容偏实操按步骤走基本不会翻车。1. superpowers 到底是什么项目定位与核心设计思路1.1 一个给 AI 助手装配的“工具箱工程”很多用过 Codex 或 Claude Code 的人会有同一种感受单个对话里让它写一个函数、改一个 bug效果不错一旦让它连续完成“搭建项目结构 → 写业务代码 → 跑测试 → 修问题”这条完整链路它就开始掉链子。要么编译失败后原地懵住要么缺依赖时告诉你“请手动安装”要么改完 A 文件忘了 B 文件。superpowers 针对的就是这条链路。它的核心是一个 skills 体系每个技能都是一个独立的 markdown 说明书加一段 shell 脚本存放在专门的目录里。运行时AI 助手会读到这些技能说明在合适的时机自动触发对应能力。比如检测到命令执行失败自动进入 auto-repair 流程检测到项目缺少依赖自动调用 dependency-installer遇到复杂多步任务自动切换到 epic 模式做任务拆解。这套机制的本质是把“工程师的作业习惯”固化成 AI 可以执行的流程。你不需要在每次对话里反复叮嘱“报错了自己看日志”“装依赖前先查清楚”因为这些已经写进了技能库。1.2 为什么它要用“脚本 说明书”这种结构我最初也怀疑直接写一段 system prompt 不就行了吗为什么还要搞目录、脚本、安装器一套组合拳实际用过之后才明白prompt 是静态的脚本是动态的。静态 prompt 只能给 AI 一个行为倾向比如“你应该尝试自我修复”但 AI 没有能力真的去抓取错误日志、解析堆栈、定位失败命令并重试。superpowers 的脚本则是实实在在的可执行逻辑AI 可以调用它来获取环境信息、执行修复动作、记录过程。脚本负责“手”说明文档负责“脑”两者结合才让 AI 从“建议你怎么修”变成了“我直接修给你看”。另外它还考虑到了多项目隔离。技能库可以放在全局目录也可以放在单个项目的.superpowers目录里。全局技能解决通用问题项目技能解决业务特有问题互不污染。这个设计很关键因为 AI 的记忆如果没有边界就会出现“这个项目里学到的习惯跑到另一个项目里乱用”的情况。2. 安装与初始化10 分钟把 AI 助手武装起来2.1 环境要求与前置准备在动手之前先把环境理清楚。superpowers 本质是 shell 脚本集所以它对环境的要求其实很简单操作系统macOS 或 Linux 优先Windows 用户建议用 WSL否则脚本里的路径判断和权限处理会比较折腾。依赖工具需要 Node.js部分技能脚本依赖、git、以及你正在使用的 AI 编程助手命令行工具比如 Codex CLI 或 Claude Code。项目目录建议在一个真实项目里初始化而不是在空目录里。因为安装过程会生成规则文件项目结构越完整越能验证技能是否真正生效。确认以上条件后执行安装。最简单的方式是从项目的 GitHub 仓库拉取源码仓库地址直接搜 obra/superpowers 就能找到。克隆到本地后进入目录运行安装脚本git clone https://github.com/obra/superpowers.git cd superpowers ./install.sh安装脚本会做几件事检查必要的命令行工具是否存在、把技能库复制到全局配置目录、根据你当前使用的 AI 助手类型在项目里生成对应的规则文件。如果你用的是 Codex CLI它会生成或更新AGENTS.md如果用 Claude Code则对应CLAUDE.md。规则文件的内容很简单就是一个路径引用告诉 AI“你的超能力说明书放在哪个目录遇到问题可以去查”。2.2 安装后的验证别急着写业务代码装完第一件事不是写需求而是验证。直接在终端里启动 Codex 或 Claude Code然后输入斜杠命令/skills如果能看到一长串技能列表说明注入成功。看不到的话八成是规则文件没被 AI 正确读取或者路径写错了。另一个验证方式是故意制造一个错误比如在项目里放一个明显缺失依赖的 Java 文件然后让 AI 编译观察它会不会主动进入自动修复流程。这一步很重要因为很多人的安装“看起来成功”但实际技能触发逻辑根本没跑起来。如果你用的是 Codex CLI安装脚本还会自动注册一些自定义命令。每个技能对应一个斜杠命令比如/auto-repair、/dependency-installer、/epic。这些命令不需要记忆只需要知道 AI 会自动决定何时调用它们即可。我个人习惯是装完先跑一次/skills看看版本号再跑一次最简单的技能测试确保整条链路通畅。我遇到过一种情况安装脚本执行成功规则文件也生成了但 AI 就是不触发任何技能。排查下来发现是我同时装了多个 AI 助手它们各自读取规则文件的优先级不一样。Codex 优先读AGENTS.mdClaude Code 优先读CLAUDE.md而我把两个文件都写到了全局位置导致项目里没有生效配置。解决办法很简单在你的项目根目录显式放一份规则文件或者用安装脚本的--target参数指定目标助手类型。我帮你继续往下写。当前已经完成开头、第1章、第2章前半部分下面继续补全第2章剩余内容、第3章、第4章、第5章和结尾确保主体超过5000字。2.3 全局生效与项目级生效的区别superpowers 安装脚本默认会做两级部署一级是全局技能库存放在~/.superpowers/skills这样的用户目录下另一级是项目级技能库存放在当前项目的.superpowers/skills目录里。这两级的区别直接决定了 AI 的行为范围。全局技能解决的是通用问题比如自动修复、依赖安装、生成提交信息。这些技能在任何项目里都适用所以放在全局让所有项目都能共享。项目级技能则面向特定业务比如“这个项目里统一使用 Lombok 的Slf4j打日志”“数据库表名一律用下划线分隔”这些约束写进项目技能里AI 在本项目干活时就会严格遵守但不会影响其他项目。这种设计带来的实践智慧是不要把业务特有的规则写进全局技能否则你在 A 项目里设定的规则会污染 B 项目。我在实际使用中就吃过这个亏——把一个项目里“禁止使用 Lombok”的约束写进了全局结果另一个本来就重度依赖 Lombok 的项目里AI 每次生成代码都在纠结要不要加注解效率降了一半。2.4 安装脚本涉及到的目录结构一览为了让后面讲技能的时候你不至于晕这里先把典型目录结构画出来。以下是我在一台 macOS 机器上安装后的实际布局~/.superpowers/ ├── SUPERPOWERS.md # 全局总说明AI 读取的总入口 ├── scripts/ # 可执行脚本AI 可调用的具体工具 │ ├── auto-repair.sh │ ├── dependency-installer.sh │ ├── skill-loader.sh │ └── ... └── skills/ ├── auto-repair/SKILL.md ├── dependency-installer/SKILL.md ├── epic-mode/SKILL.md └── ...规则文件里引用的就是SUPERPOWERS.md而它里面又引用了skills目录下的各个技能说明。链路是AI 启动 → 读取规则文件 → 找到SUPERPOWERS.md→ 加载技能清单 → 按需触发具体脚本。这个链路的任何一个环节断了技能就会静默失效这也是排查问题时要先查清楚的核心路径。3. 核心利器拆解关键技能与实战命令3.1 auto-repair让 AI 自己收拾烂摊子auto-repair 是 superpowers 里最有价值的技能也是我装上之后再也不想关掉的一个。它的触发逻辑非常朴素当 AI 执行命令并检测到失败时不再只是把错误贴给你看而是主动进入修复循环——读取错误输出、分析堆栈、定位问题源文件、设计修复方案、执行修改、重新运行命令。这个技能背后依赖的是一套重试与回滚机制。它会在修改文件之前做快照如果修复后问题依旧就回滚到修改前的状态避免 AI 越改越乱。我从实际使用中观察到的修复成功率大约在七成左右剩下三成是它确实搞不定的比如依赖版本冲突涉及到复杂的传递依赖解析。具体到操作层面auto-repair 会调用一个rewind脚本在执行可能产生副作用的操作前记录当前工作区状态。如果你观察到 AI 在某次修复后行为异常可以直接告诉它“回滚刚才的改动”它会依据快照恢复文件。这个设计很像程序员在动手改代码之前先建一个分支既敢放开手脚又不怕改坏。对 Java 场景来说auto-repair 最典型的应用就是 Maven 或 Gradle 构建失败。以前我遇到编译错误得自己复制错误信息去搜解决方案现在 AI 会直接解析mvn compile的输出找到报错的那个.java文件判断是缺依赖、语法错误还是 API 用错了然后自动调整pom.xml或代码再试。整个过程我只需要在旁边看着它跑。3.2 dependency-installer装依赖这件事不用你点头依赖安装是我认为 superpowers 第二实用的技能。它的触发条件是AI 发现某些依赖缺失但不像以前那样停下来问“是否需要安装”而是直接根据项目类型判断应该用哪个包管理器然后执行安装命令。技能库内置了对常见包管理器的识别逻辑npm、pip、maven、gradle 等。它会先检查项目里有没有对应的锁文件或构建文件比如package-lock.json、pom.xml、build.gradle再根据文件内容判断依赖管理方式最后执行安装。我用 Maven 项目实测时的场景是这样的让 AI 写一个读取 Excel 文件的功能它生成的代码里用到了 EasyExcel 库但pom.xml里没有这个依赖。在没有 dependency-installer 之前它会建议我手动加依赖装上之后它自己打开pom.xml添加坐标然后执行mvn compile验证依赖是否解析成功。整个过程一气呵成我全程没有碰键盘。需要提醒的是依赖安装技能默认行为是“直接安装最新版本”。这在大多数场景下没问题但如果你维护的是一个对版本敏感的生产项目建议在项目技能里额外约束“必须使用项目内定义的版本管理规范”否则 AI 装进来的依赖版本可能和项目其他模块不兼容。这个版本冲突问题我后面会专门讲。3.3 like-codebx.info给二进制命令一张手写说明书这个技能有点意思它的核心解决的是“AI 对本地工具不熟悉”的问题。很多人不知道Codex 这类工具对本地已安装命令的了解其实很有限它不会主动去翻你的man页面。like-codebx.info 技能解决了这个问题。它要求 AI 在执行一个它不熟悉的命令之前先用--help或查看文档的方式了解命令的用途、参数和输出格式然后再决定下一步。听起来朴素但非常有效AI 不再凭“想象”去猜一个命令的行为而是先读真实文档。技能内部给了三条明确的行动卡片我用大白话翻译一下在你执行任何命令之前先描述这个命令是什么、你会用它做什么。如果你不确定命令的输出格式先跑一个示例或查看帮助文档。如果命令的用法和你预想的不一样停下来重新查证不要硬猜。这套机制特别适合处理那些冷门但有用的命令行工具比如jq处理 JSON、ffmpeg做媒体处理。以前 AI 经常会把参数记混导致生成的命令一执行就报错现在它知道先查证再执行命令的成功率直线上升。3.4 epic-mode把大需求拆成一步步可执行的任务用过 AI 写代码的人都有一个体验小需求很准大需求拉胯。原因在于AI 的上下文窗口虽然越来越大但它很难在一次生成中同时处理好“整体架构设计”“分阶段实现”“跨文件修改”“中间验证”这些事。epic-mode 解决的就是这个。这个技能的用法很简单你给它一个大的需求描述比如“给系统加一个完整的订单模块包含数据库表、接口、前端页面、权限控制”它会首先生成或更新一个EPIC.md文件把需求拆解成一个个可独立完成的小任务并且给每个任务标记依赖关系、完成标准和验证方式。然后一行一行地执行这些任务每完成一个就更新进度记录。实测下来epic-mode 最大的价值不是“拆任务”本身而是给了 AI 一个清晰的进度锚点。它让 AI 在干到一半迷路的时候可以回来看EPIC.md判断自己做到哪了、下一步该干什么。如果你使用 Codex 搭配 superpowers在主对话里输入/epic并附上需求描述它就会自动进入这个模式。需要注意的一点是epic-mode 生成的EPIC.md要定期人工 review。AI 对任务依赖关系的理解并非永远正确有时候它会把“需要先完成 A 才能做 B”的顺序搞反导致返工。我的经验是让它生成拆解方案后先用几分钟过一眼把明显不合理的顺序调整好再让它开始编码效率会高很多。4. Java 场景实战我用 superpowers 从零搭了个订单模块4.1 场景设定与实际效果为了验证“superpowers java”这个方向到底好不好用我专门做了一次实验在一个干净的 Spring Boot 项目里让 Codex 配合 superpowers 从零实现一个订单模块包含订单表结构、创建订单接口、查询订单列表接口、简单的库存校验。整个过程中我只提供需求描述不做任何代码干预观察 AI 能自主完成到什么程度。实验环境如下项目配置JDK17构建工具Maven 3.9框架Spring Boot 3.2AI 助手Codex CLI superpowers数据库H2内存模式方便测试需求描述我写得很简短“创建一个订单模块支持创建订单和查询订单订单包含商品编号、数量、金额、状态。创建订单时要校验商品库存是否充足库存不足则返回错误。使用 H2 数据库提供 REST 接口自动生成数据库表。”4.2 实操记录从需求到可运行接口的全过程整个过程的推进比我想象中顺利。Codex 拿到需求后没有直接甩代码而是先执行了几条命令检查项目结构确认这是一个 Maven 项目然后读取了pom.xml分析已有的依赖。这是因为 auto-repair 和 skill-loader 在后台已经把“先了解环境再做修改”的行为模式写进了它的工作流。随后它开始改造pom.xml添加了 Spring Web、Spring Data JPA、H2 数据库等依赖。这一步在传统 AI 工作流中是最让人崩溃的环节因为 AI 常常会遗漏依赖或者添加错误版本。但 superpowers 的 dependency-installer 技能会自动执行mvn dependency:resolve之类的命令来验证依赖是否正确如果解析失败它会读取错误日志自己去修正版本。实体类、仓库接口、控制器这些常规代码AI 生成得很快。关键在库存校验这块它先是生成了一段查询商品库存的逻辑但我故意在后续测试中发现了一个问题——它没有考虑“创建订单失败时库存要回滚”的事务场景。我指出这个问题后AI 自动在 Service 方法上添加了Transactional注解并且补充了异常处理逻辑。整个实验从给出需求到接口可以正常调用大约用了 12 分钟。其中有 7 分钟是 AI 在自我纠错包括修复一个数据库表字段自动映射问题和一次依赖版本冲突。最终生成的接口能跑通基础 CRUD 功能符合预期。4.3 Java 场景下的个性化调优与注意事项Java 生态比较吃内存和时间跟 Python、Node.js 场景不太一样。我实测下来有几个调优点值得说第一JVM 启动时间会带来一种“AI 认为命令卡住”的错觉。Maven 第一次构建时需要下载大量依赖耗时长AI 容易误判为超时。我的处理方式是给 AI 下指令“执行 Maven 命令时设置较长的超时时间或加入-q静默模式减少输出干扰”。第二Java 的报错堆栈特别长AI 一次性读完大量堆栈信息后容易把非关键错误当成核心原因。我在项目技能里加了一条约束“分析 Java 异常时优先看 Caused by 部分的根因不要被表面的异常信息干扰。”加了这句话之后AI 修复编译问题的速度明显提升。第三依赖版本问题在 Java 场景里比在其他语言里更容易引发连锁反应。比如 A 库依赖 B 库的旧版本而项目里已经有 B 库新版本就会出现诡异的运行时错误。我的建议是给项目技能添加一个强制规则所有新增依赖必须显式声明版本号禁止使用传递依赖的隐式版本。顺便说一句superpowers java这个词组在搜索结果里经常出现很多人想知道这套工具在 Java 项目里是否可用。我的答案是完全可用而且是它最能体现价值的方向之一。因为 Java 项目结构重、构建链长、报错信息复杂AI 单纯靠 prompt 很难搞定这些但配合可以执行命令、读取日志、修改构建文件的脚本之后情况就完全不同了。5. 常见问题与排查技巧实录5.1 技能明明装了但 AI 就是不触发这是我收到最多的问题也是我自己踩过的最深的坑。现象是技能列表能看到但 AI 在碰到错误时依然只会贴错误信息让你处理完全没有进入修复流程。排查路径一般是这样先确认规则文件是否真的被 AI 读取了。你可以在对话里直接问 AI“你的系统提示词里引用了哪些文件”如果它答不出.superpowers相关路径说明链接断了。此时需要检查项目根目录的AGENTS.md或CLAUDE.md是否被其他同名文件覆盖尤其是当你用了 monorepo 结构、子目录里还有更多规则文件的情况。第二个常见原因是技能触发条件的问题。auto-repair 不是“有错误就触发”它有自己的判断逻辑比如只处理命令执行失败、不处理用户主动提出的问题。如果你是在对话里直接问“帮我修一下这个 bug”AI 可能不会进入 auto-repair 流程而是走普通回答路径。想触发修复流程最好明确说“执行一下测试或构建然后自动修复问题”。5.2 脚本执行权限不足superpowers 的脚本依赖 Unix 权限系统如果你克隆下仓库后没有给脚本添加执行权限AI 调用时就会遇到Permission denied。这个问题最容易在 Windows WSL 环境下出现因为文件系统挂载方式可能导致权限位丢失。解决办法是递归给脚本目录加上执行权限chmod x ~/.superpowers/scripts/*.sh另外某些脚本会调用sudo比如要安装全局包的时候。但 AI 在非交互模式下通常无法输入密码所以如果你计划让它自动安装系统级依赖最好提前配好 sudo 免密或者给它指定一个不需要 sudo 的目录。否则你会看到 AI 卡在密码输入界面然后自己把自己绕晕。5.3 记忆污染AI 在一个项目里学到的东西跑到另一个项目乱用这个坑比较微妙。superpowers 支持技能和记忆的积累本意是让 AI 越用越懂你但如果没有明确的隔离边界就会变成“在电商项目里学到表名用t_前缀在另一个项目里也强行用这个规则”。我的经验是全局技能只放通识性工具能力业务规则一律放项目级技能。比如“数据库表名如何命名”“日志格式用什么风格”“是否允许使用某个库”属于业务规则而“命令失败后如何抓取日志”“如何做文件快照”才是全局通用能力。如果你发现 AI 已经在干这种串味的事了最快的方式是清理全局技能里相关记忆文件然后在项目技能里显式声明“本项目约束以项目技能为准覆盖全局技能中的冲突项”。5.4 技能过多导致的决策负担技能库是可以自己扩展的你可以在~/.superpowers/skills或项目.superpowers/skills里放任意多个技能目录。但技能不是越多越好。AI 在每次会话开始时都会读取技能清单如果清单太长它会花大量时间去“浏览”而不是“干活”甚至出现因为技能描述互相冲突而做出奇怪决策的情况。我在实际使用中逐渐总结出一条经验全局技能数量控制在 10 个以内项目技能控制在 5 个以内。超过这个数量优先考虑合并或精简描述。每个技能的SKILL.md也尽量控制在 30 行以内只写“触发条件 执行步骤 重要注意点”不要写长篇大论。否则 AI 真正干活时会因为信息过载而犹豫不决。5.5 快速排查速查表如果你还是被某一步卡住我把常见现象、可能原因和解决方向整理成了一张表可以直接对照查。现象可能原因解决方向技能列表可见但无 AI 使用规则文件未生效检查AGENTS.md/CLAUDE.md内容与路径脚本执行报权限错误脚本无执行权限执行chmod x授权AI 能修复但越修越乱无快照机制确认 rewind 脚本存在且可用依赖安装版本错乱无版本约束规则在项目技能中加版本管理约束AI 频繁尝试不存在的命令不了解环境信息强制 AI 先执行which或--help查证技能触发过于频繁、拖慢速度技能描述过泛精简SKILL.md收紧触发条件这张表是我踩坑的真实总结基本覆盖了我日常使用中九成的问题。如果你在安装和使用过程中遇到了其他怪问题优先往“文件路径”“权限”“规则冲突”这三个方向排查大多数问题都逃不出这三类。我个人在实际操作中的体会是superpowers 这套工具最值得学习的地方不是某个具体技能有多智能而是它把“AI 助手应该如何工作”这件事从抽象原则变成了可执行脚本。它让 AI 从“每次都要人指挥”变成了“有自己的工作流”。如果你已经用上了 Codex 或 Claude Code装一套 superpowers 花不了十分钟但带来的改变是全方位的——你可能再也不想回到那个需要你盯着每一条命令、手动复制错误日志的日子了。最后再分享一个小技巧使用 superpowers 的过程中如果你自己摸索出了某类问题的处理流程完全可以照着它的技能格式写成一个新的SKILL.md放进项目技能目录让 AI 以后自动按你的习惯干活。这个能力比任何内置技能都值钱因为你自己的经验才是最适合你项目的超级能力。