Superpowers 插件实战：为 Claude Code 与 Codex 注入可复用的工程技能

最近在折腾 Claude Code 的时候被一个叫 Superpowers 的插件刷屏了。热搜里“superpowers 安装”“superpowers 使用教程”几乎轮着上我还以为是什么游戏外挂结果一查仓库——这是给命令行 AI 编程助手加“技能包”的开源项目。说白了Superpowers 不是某个大模型也不是新框架它是一套可插拔的技能集合把资深工程师的思考流程固化成 AI 能一步步执行的指令。这项目解决了一个很实际的问题Claude Code、Codex 这类工具写点小函数、改个 bug 很利索但一旦遇到“从零设计一个功能”“按测试驱动开发走完整流程”这类复杂任务它们就特别容易自由发挥产出的过程不可控。Superpowers 做的事情就是把这些最佳实践像是“技能”一样附加到 AI 身上让它在合适的时候调用合适的流程。这篇文章我不打算翻译官方文档就基于我实打实的使用经验讲讲它到底怎么装、怎么用、在 Codex 和 Java 项目里怎么落地以及那些文档里不会写清楚的坑。1. 先搞清楚 Superpowers 到底解决什么问题1.1 AI 助手上手容易关键时刻却使唤不动我先说说自己踩过的坑。很早之前我用 Claude Code 做一个内部工具的重构需求写得很明确结果它直接撸起袖子改代码改了十几个文件没有一个测试文件是新增的我 review 的时候完全不敢合并。问题不是模型不聪明而是缺少约束AI 默认的行为是“尽快给出看起来合理的结果”而不是“先想清楚再写测试再最小化实现”。Superpowers 的核心思路是把工作流变成显式的“技能”。每个技能本质上是一个结构化的 Markdown 指令文件里面写清楚了这个技能的使用前提、执行步骤、输入输出和注意事项。当 AI 判断某个任务适合用某项技能时它会先读取这份指令再按照里面的节奏执行。你可以理解成默认的 AI 像是一个刚到项目组的实习生接需求后自由发挥装完 Superpowers 之后AI 背后多了一个技术 leader按 checklist 一点点指挥。1.2 技能包机制把人的经验变成可复用的流程这里有一个关键设计Superpowers 不是把一些提示词拼在一起而是严格区分“核心”和“技能”两层。核心部分负责管理技能之间的依赖关系和加载方式技能部分则是具体的流程说明。我实际打开仓库看的时候里面就是清晰的目录结构比如skills/brainstorming/SKILL.md、skills/test-driven-development/SKILL.md。每个技能文件夹里面除了说明文件还可能会有模板、示例代码甚至配套的提示词片段。这种结构带来的好处是你不用为了调整流程去改 AI 模型本身只需要改技能文本就能改变 AI 的行为。我试过自己写一个“需求澄清”技能把提问顺序、需要收集的信息字段都写好结果同一套 Claude Code 在面对模糊需求时从“瞎猜”变成了“先问清十个问题”这个体验变化非常明显。1.3 哪些人真正适合用它我个人的判断是以下几类人用 Superpowers 收益最大团队里需要统一交付标准的开发者尤其是多人协作时希望 AI 的产物风格一致。使用 Java、Spring、Maven 这类传统技术栈的工程师因为这类项目对测试、构建流程有很强的路径依赖需要 AI 严格遵守。喜欢让 AI 做“体力活”、但自己保留“决策权”的人。Superpowers 的 brainstorming、planning 技能会把 AI 拉回“先讨论、再动手”的节奏而不是一上来就输出代码。反过来如果你只希望 AI 快速生成一段脚本、一行表达式那这个工具的意义不大因为技能加载本身也有上下文成本。它适合的是复杂任务而不是所有任务。2. 装之前要弄清楚的事2.1 环境依赖其实没那么多Superpowers 并不依赖什么特殊的运行时它本质上是一套文件和人需要的前提是你的终端里已经有能跑起来的 AI 编程助手。以我平时的环境为例Node.js 18 以上是必要的因为 Claude Code 和很多 CLI 工具都跑在 Node 生态里然后照着官方 README 装好 Claude Code或者准备好 Codex CLI登录对应的账号。有人会问是不是必须先买 Claude 的订阅我实测下来插件本身是开源免费的但真正调用模型 token 还是要走你自己已有的账号配额。所以不要指望装了这个插件就“免费续杯”它只是改变 AI 的行为方式不改变计费逻辑。2.2 插件市场安装 vs 手动 clone这是新手最容易纠结的地方。Superpowers 目前最常见的安装方式有两种一种是在 Claude Code 的交互界面里用斜杠命令从插件市场安装另一种是手动 clone 到本地插件目录。我更推荐先走插件市场因为它会处理依赖和版本。在 Claude Code 交互界面里直接输入/plugin install superpowerslatest如果这条命令没反应先输入/plugin看看当前有哪些插件确认插件市场是否已经添加。也可以用 CLI 版本在终端里执行claude plugin install superpowerslatest手动 clone 的方式适合需要在多台机器间复制配置的场景或者你想直接看源码、改技能的场景git clone https://github.com/obra/superpowers.git ~/.claude/plugins/superpowers注意不同版本的 Claude Code 对插件目录的识别路径不完全一样clone 完之后一定要重开一次会话让插件管理器重新扫描目录。2.3 与 Codex、Java 项目的集成思路“codex superpowers”和“superpowers java”这两个词在热搜里出现频率很高我单独说一下。Codex CLI 目前没有像 Claude Code 那样完整的插件系统但它支持从 prompt 配置目录加载自定义技能。我实际用的方法是把 Superpowers 仓库里的skills目录链接或者复制到 Codex 的~/.codex/prompts/下然后在对话里直接说“使用 Superpowers 的 tdd 技能处理这个任务”。AI 会把技能文件当作指令上下文来读取效果虽然没有插件式管理那么顺滑但可用。Java 项目则是另一层问题。Superpowers 的核心技能不区分语言但 Java 项目对构建工具、测试框架有强约定。你需要在技能文件里额外声明“使用 Maven、JUnit 5”这类环境信息否则 AI 可能会默认生成 JUnit 4 的测试或者用错误的命令行去跑测试。后面我会专门展开这一块。3. 一步步安装和启用3.1 在 Claude Code 里装一次成功的路径我按自己实测通过的操作顺序整理一下照着做基本不会出错。第一步确认 Claude Code 能正常对话。先建一个临时目录输入claude进入交互界面随便让它写一个 hello world确保账号登录和网络链路没问题。第二步输入/plugin回车看看左下角或者插件列表里有没有 marketplace 信息。如果列表为空就先用命令添加 Ludwig 的插件市场/plugin marketplace add obra/superpowers第三步再执行/plugin install superpowerslatest等待几秒钟它会拉取仓库文件并注册插件。安装完成后建议直接退出当前会话重新进入一次。这一步很关键因为插件的技能索引是在会话启动时加载的不重开的话经常出现“命令认了但技能找不到”的怪问题。3.2 激活常用技能的正确姿势装完插件不代表技能自动生效你需要显式触发。最直接的方法是输入/superpowers这个命令会把当前可用的技能列表展示出来我通常从里面挑选两三个核心技能先启用来试水比如brainstorming、test-driven-development、debugging。启动后AI 会在上下文里加载对应技能的说明后续对话就自然按照这个流程走。还有一种更灵活的方式不通过斜杠命令而是直接用自然语言唤醒。比如你可以在对话里写“请使用 Superpowers 的 Brainstorming 技能先帮我梳理这个需求不要急着写代码。”我实测下来这种方式的成功率很高因为技能本身的描述已经告诉模型什么时候该用它。关键是你自己要克制住“让它直接写代码”的冲动先让它按技能走完前几步。3.3 Codex 与 Superpowers 的联动方式既然热搜里一直有“codex superpowers”我专门说一下在 Codex CLI 下怎么用。我的环境是 macOSCodex 用的是 OpenAI 官方 CLI配置目录在~/.codex/。第一步把技能文件放进去mkdir -p ~/.codex/prompts ln -s ~/.claude/plugins/superpowers/skills/* ~/.codex/prompts/第二步启动 Codex然后在对话里输入类似这样的话“Load the test-driven-development skill from ~/.codex/prompts and follow it for this task.”Codex 会把这个 Markdown 文件内容读入上下文并按照它执行。这种方式虽然不如 Claude Code 原生插件顺滑但在没有插件系统的环境里也算是最务实的方案了。如果你想做得更干净可以把技能文件复制成 Codex 约定的 naming format比如tdd.prompt.md这样更容易被识别。3.4 验证安装是否成功如何判断装没装好我一般用三个办法输入/plugin看到superpowers在列表里状态是 enabled。输入/superpowers能弹出技能列表说明索引加载成功。做一个最小验证让 AI 用 TDD 技能实现一个两数相加的函数。如果 AI 第一轮先写测试、第二轮写实现、第三轮重构说明技能真的生效了。如果它一上来就给你一个add()函数那大概率技能没有加载只是普通的自然语言对话。4. 核心技能使用实操4.1 Brainstorming写代码前先“白板”Brainstorming 是我用得最多的一个技能因为很多需求刚提出时是模糊的直接写代码等于闭着眼睛修路。加载这个技能后AI 会先反过来问你问题这个功能给谁用最核心的输入输出是什么哪些场景可以先不做我建议把这一步当成“白板讨论”不要在对话里急着给它技术方案。你会发现等它问完五六个问题需求描述已经被拆得很细这时候再进入下一步才是写代码。实际操作中有一个小技巧把 brainstorming 产出的方案先写到一个PLAN.md文件里然后再让 AI 按计划执行。这样即使后面对话上下文被截断计划文件仍然可以在新会话里被重新加载。4.2 测试驱动开发流程TDD 技能是 Superpowers 里最硬核的一个它把开发过程拆成非常机械的循环先写一个失败的测试再写最小实现让测试变绿最后重构并保持测试通过。如果你做的是 Java 项目这个技能配合 JUnit 5 和 Maven 用起来非常对味。我实际体验下来的流程大致是AI 先确认测试框架和构建命令比如mvn test。它写一个预期会失败的测试用例并明确告诉你这个测试现在会失败。再写实现代码反复跑测试直到通过。最后进入重构阶段同时保证测试不红。关键点是在技能里显式声明环境信息。我通常会在对话开头补充“使用 Maven 管理依赖JUnit 5测试命令是 mvn test。”没有这句话AI 很可能默认用pytest那套逻辑来理解 Java 项目生成一堆不匹配的测试代码。4.3 子代理驱动开发用并行换速度Subagent-driven development 是 Superpowers 里比较进阶的技能核心思路是把一个复杂任务拆成多个子任务然后分别派出独立的子 AI 去完成最后再汇总。适合重构多模块项目比如 Java 里同时改 service、repository、controller 时串行改会花很多时间拆给子代理并行改能明显加速。但这里我要说一个坑子代理不是免费的它会额外消耗 token而且子代理之间如果共享同一个文件很容易产生冲突。我的经验是拆分工时要按“文件边界”切而不是按“逻辑模块”切。比如 A 子代理只改UserService.javaB 子代理只改UserController.java两者不要碰同一个文件。如果完成了之后需要合并再由主对话统一 review。4.4 Java 项目里的落地要点“superpowers java”之所以会成为一个单独的热搜是因为 Java 生态和 Python/Node 项目差异太大。我总结几个实际注意点测试框架偏好一定要在技能加载时强调 JUnit 5 还是 TestNG否则 AI 可能按 JUnit 4 的注解习惯写Before而不是BeforeEach。构建命令Maven 和 Gradle 的命令差异很大AI 一旦猜错整个 TDD 循环就会卡在“跑不了测试”这一步。提前在项目根目录的CLAUDE.md里写好build_command和test_command效果最好。Java 版本如果项目是 Java 8AI 却写了 Java 17 才有的var或List.of()编译就会失败。我建议在技能流程里加一句“请确认当前 JDK 版本避免使用更高版本的语法”。代码生成速度Java 项目编译慢TDD 循环里每次跑mvn test可能都要等很久。我的做法是让 AI 只针对单个测试类跑命令例如mvn test -DtestUserServiceTest这样反馈周期会短很多整个开发节奏也更舒服。5. 常见问题与排查5.1 插件命令失效怎么办很多人第一步就卡在/plugin install没反应。这个问题的常见原因不是命令拼错了而是会话没有加载到 marketplace 信息。我的排查顺序是先执行/plugin marketplace list看看有没有可用源。如果没有执行/plugin marketplace add obra/superpowers。再执行/plugin install superpowerslatest。最后还不行就手动 clone 到插件目录然后重开会话。插件安装这种操作重开会话真的是万金油很多状态都会在启动时重新读取。5.2 技能列表看不到任何内容装完插件输入/superpowers后只有一句“当前没有可用技能”这种时候先别慌。我只遇到过一次原因是技能目录权限不对。如果你是用root安装插件、用普通用户跑 Claude Code文件权限不一致就会导致技能目录扫描不到。解决办法是把插件目录的所有权改给当前用户chown -R $(whoami) ~/.claude/plugins/superpowers另一个隐蔽的原因是技能文件编码不是 UTF-8。如果你自己复制过技能文件、又用 Windows 编辑器改过可能出现中文乱码或特殊字符导致解析失败。检查一下文件头确保没有 BOM。5.3 上下文变长和限流问题技能加载本身会占用上下文窗口尤其是当你一次性启用五六个技能再跑一个长对话很快就会发现 Claude Code 开始丢失早期的规划信息甚至回答变得答非所问。我的经验是默认只加载当前任务真正需要的技能。比如你在做 Java 项目的 TDD只需要test-driven-development和debugging如果不需要写文档就千万别开文档生成技能。如果上下文还是吃紧可以把任务拆成多个子代理把详细逻辑放在子代理上下文里主对话只保留技能分支和最终结果这个技巧能有效延长一次会话的有效工作时长。5.4 与 Codex 配合时的典型问题在 Codex 里用 Superpowers我遇到最多的问题是技能文件放进去后Codex 根本无动于衷。排查后发现是文件命名的原因。Codex 对 prompt 文件的识别有较强的约定如果你只是丢一堆SKILL.md进去它不一定在默认状态加载。我后来改成类似tdd.prompt.md的命名方式并在对话里明确给出文件路径成功率就高多了。另外一个坑是软链接失效。如果插件后来更新过路径软链接可能指向旧目录。所以与其用ln -s不如直接复制一份到~/.codex/prompts/虽然更新时要手动同步但至少运行稳定。5.5 常见问题速查表症状可能原因处理方式/plugin列表为空marketplace 未添加重新添加插件市场技能加载后 AI 仍不按流程走技能没有在当前会话激活使用/superpowers或自然语言指定Java 测试跑不起来测试命令和构建工具不正确在CLAUDE.md中写明 Maven/Gradle 命令Codex 不识别技能prompt 文件名不合规改成.prompt.md命名并给全路径上下文很快耗尽启用技能过多只保留当前任务需要的两三个技能插件更新后旧配置失效路径或目录结构变了重开会话并重新绑定技能目录我个人在实际使用中的体会是Superpowers 不是一个“装上就能起飞”的魔法它更像是一套约束和引导约束 AI 不要乱来引导它按成熟流程做事。如果你愿意给每个项目写一份清晰的CLAUDE.md把 Java 版本、测试命令、代码风格这些基础信息提前喂给它再配合 Superpowers 的 TDD、Debugging 技能产出的代码质量和可维护性会明显上了一个台阶。最后分享一个小技巧不用每次对话都手动开启技能。你可以在项目的CLAUDE.md或者AGENTS.md里直接写一句“涉及业务逻辑改动时默认使用 Superpowers 的 brainstorming test-driven-development 技能”。之后只要启动对话AI 会在合适的场景自动加载对应技能。这算是把 Superpowers 从“手动技能”升级成“项目级自动化”的土办法但真的很好用。