第一次听说 superpowers 是在一个同事的终端里他让 Claude Code 跑了一个 /plan然后 AI 居然自己先把需求拆成三个方案、列了十几个问题最后还主动说“在动手前建议先补两个测试”。我当时以为他偷偷装了个什么神秘插件追过去一看原来就是 obra 那个开源项目 superpowers。简单说它是一套给 AI 编程助手的“技能包”核心不是加功能而是给 AI 一套结构化的工作方法先想清楚、再写计划、再测试驱动、再复盘。这篇文章我会从 superpowers 的安装、核心技能拆解、Java 项目实战、以及怎么把它用到 Codex 上这几个角度完整过一遍想把它跑起来的人可以直接照着操作。内容偏实操我会把安装命令、触发方式、目录结构、踩坑记录都摆出来不搞云里雾里的理论。1. Superpowers 到底是什么给 AI 编程助手装上“技能包”1.1 为什么叫 superpowers而不是叫“提示词模板”或“常规插件”我最早也是抱着“又一个提示词合集”的心态去打开这个项目的。实际看过代码之后发现它的思路跟提示词模板完全不在一个层面。superpowers 提供的是一整套有目录、有规范、有触发机制的“技能文件”每个技能都是一份结构化的 Markdown里面写清楚了适用场景、执行步骤、检查清单和输出格式。AI 在对话过程中会根据用户请求自动匹配合适的技能然后按流程走。换句话说提示词模板是“告诉 AI 这一次怎么做”而 superpowers 是“让 AI 形成一套怎么做的方法论”。前者是一次性的后者是可复用的。这个项目由资深工程师维护在社区里讨论度一直很高。它的名字叫 superpowers我理解有两层意思一是让 AI 助手具备“超级能力”二是让使用者在不改变日常操作习惯的前提下把 AI 从“答题机器”变成“会走流程的工程师”。用一句话概括就是它不是在教 AI 更多知识而是在教 AI 怎么干活。1.2 技能、插件与 MCP三个概念一次讲清很多刚接触的人会对“技能”“插件”“MCP”这几个词犯迷糊我自己刚开始也绕了很久。简单区分一下概念本质类比提示词模板一段文字告诉 AI 这次任务的规则给新员工的一份任务说明技能Skill一份带元信息的 Markdown 文件包含完整工作流程给新员工的岗位 SOP插件Plugin技能、命令、钩子、MCP 配置的打包集合入职大礼包MCP 服务给 AI 提供额外工具能力的进程公司里的 OA、财务、工单系统在 Claude Code 里插件的标准载体是一个目录目录里要有.claude-plugin/plugin.json作为清单里面声明了插件的名字、版本、入口文件、包含的技能路径和 MCP 服务地址。superpowers 的技能则严格遵循 SKILL.md 格式文件开头用 YAML 写 name 和 description正文用 Markdown 写执行步骤。AI 每次收到用户消息会先做一个“技能匹配”——根据 description 判断当前任务该不该调用某个技能、调用哪个技能。这种设计的妙处在于技能不是硬编码的 if-else而是让 AI 自行判断。判断准不准取决于描述写得好不好。这也是为什么我给项目加自定义技能时会在 description 里写清楚“什么情况用、什么情况别用”避免 AI 乱匹配。1.3 适合谁用、解决什么问题我的判断是以下三类人最适合马上尝试第一类是已经在用 Claude Code 写代码、但觉得 AI“答得对但干得乱”的人。没有流程约束时AI 经常直接甩出一大段代码你也不知道它有没有考虑边界情况。有了技能约束后它会先列方案、再写测试、再实现节奏明显不一样。第二类是需要在 Java、Python、Go 等多种语言项目里切换的开发者。技能与语言无关只要你把构建命令和测试框架告诉它同一套 TDD 流程在 Java 和 Python 里都能跑。第三类是在团队里推广 AI 编码规范的人。与其口头规定“必须写单测”不如让 AI 在执行时天然带着测试步骤。代码评审、复盘这些技能也能让团队的协作节奏更统一。换句话说superpowers 解决的并不是“AI 写不出代码”的问题而是“AI 写代码没有章法”的问题。2. 安装与初始化从零开始跑起来2.1 安装前的准备我建议在干净、可控的环境里做第一次安装别一上来就在公司的大仓库里折腾。准备工作按这个清单来本机装好 Node.js 18 以上版本因为 Claude Code 本身依赖它运行。Claude Code 已经登录并能在终端正常对话先用一句 “hi” 确认没毛病。确认网络能正常访问 GitHub安装过程需要拉取仓库。准备一个临时目录比如~/learn-superpowers里面放一个空项目或小型练习项目。为什么建议先用练习项目因为技能一旦生效AI 会严格按照流程走第一次跑 TDD 时可能会创建测试文件、修改源码、执行构建命令。在练习项目里试错成本低你能专心观察 AI 的行为模式而不是一边看它操作一边担心把生产代码搞坏。2.2 标准安装流程如果你的 Claude Code 版本比较新安装插件最省事的办法是在会话里直接输入斜杠命令/plugin install github.com/obra/superpowers命令执行后Claude Code 会去 GitHub 拉取仓库把插件放到它管理的插件目录并自动更新配置。安装完成会有提示你可以在/plugin界面里看到 superpowers 出现在已安装列表。我也用过手动安装的方式。遇到某些网络环境或特殊版本时斜杠命令可能会超时手动 clone 更稳git clone https://github.com/obra/superpowers ~/.claude/plugins/superpowers然后把插件目录的路径配置到 Claude Code 的插件设置里或者直接用/plugin选择“添加本地插件”并指向这个目录。两种方式的结果是一样的本质都是让 Claude Code 能找到插件的 plugin.json。2.3 验证安装是否成功安装完别急着干活先花一分钟验证。我会在会话里问一句你现在加载了哪些技能请列出技能名称和各自的一句话用途。如果安装成功AI 会如实报出 brainstorming、tdd、debugging、code-review 之类的一串技能。如果它回答“我没有额外技能”说明插件没被加载优先检查 plugin.json 路径是否正确、/plugin列表里是否显示 enabled。另一个更直观的验证方式是直接触发技能你对它说“我想给这个项目加一个计算器类先帮我想想方案”。凡是能进入“先列问题、再给方案、最后问你要不要继续”这种节奏的基本就是 brainstorming 技能生效了。如果它直接甩代码那就是技能没匹配上原因大概率是描述没命中后面我会讲怎么排查。2.4 目录结构说明熟悉目录结构对后续自定义很有帮助。以我本地的安装为例superpowers 解压后的结构大致是superpowers/ ├── .claude-plugin/ │ └── plugin.json # 插件清单声明技能与MCP ├── skills/ │ ├── brainstorming/ │ │ └── SKILL.md # 每个技能一个目录一份SKILL.md │ ├── tdd/ │ ├── debugging/ │ ├── code-review/ │ └── ... ├── mcp/ # MCP 服务相关配置与脚本 └── hooks/ # 可选的事件钩子技能目录里除了 SKILL.md有时候还会附带示例模板、辅助脚本。SKILL.md 的 YAML 头部通常长这样--- name: tdd description: 适用于需要先写测试再实现功能的场景。当用户要求新增功能、修复 bug 或重构时优先使用本技能组织红绿重构循环。 ---AI 读 description 做意图匹配正文则是具体的流程拆解。理解了这套结构之后不管是加自定义技能还是调现有技能都有了思路。3. 核心技能拆解与实战用法3.1 Brainstorming先逼 AI 把问题想透我见过太多人让 AI 写代码张口就是“帮我写个用户登录”。superpowers 的 brainstorming 技能专治这种没想清楚就开工的毛病。触发这个技能后AI 不会直接给代码而是反过来问你问题登录用账号密码还是第三方token 存哪失效策略是什么要不要验证码它会把需求拆成场景、边界、风险给定一个方案后会停下来让你确认而不是一条路走到黑。实际用法是直接在对话里说我想给项目加一个登录功能帮我用 brainstorming 技能把问题理清楚。几次用下来我的感受是这个技能最大的价值不是“问问题”而是“把问题分优先级”。AI 会把它认为关键的问题放在前面把次要问题放后面还会标注哪些决策会影响后续架构。这比我凭感觉回答用户需求要系统得多。3.2 TDD让 AI 按红绿重构的节奏写代码TDD 技能是我用得最多的一个。触发后AI 会严格按“先写失败测试、再实现、再重构”的循环推进而且每完成一个循环就停下来跟你确认。我第一次看到它在 Java 项目里先生成 JUnit 测试类、再写实现类的时候还挺震撼的——它不是把测试和代码一起甩出来而是真的按节奏走。一个典型的触发方式是用 tdd 技能给这个工具类补一个解析金额的方法先写测试。执行时 AI 会先确认你用的测试框架和构建命令然后进入红绿循环。这里有个关键点技能的描述里写的是通用流程但它不会自动知道你用 JUnit 5 还是 TestNG用 Maven 还是 Gradle。你最好在项目说明或者对话里提前讲清楚。我自己会在项目根目录的说明文件里直接写一行“测试命令mvn test -DtestXXXX”。3.3 Debugging把“瞎猜”变成“查证据”调试技能是我后来才认真用的。它把调试过程拆成几个阶段复现问题、收集证据、提出假设、验证假设、修复、回归。AI 会引导你提供报错信息、相关日志、最小复现步骤而不是一上来就猜测哪里有问题。比如一个 Java 服务偶发超时如果我直接问“为什么超时”AI 大概率会给一堆可能原因。但用 debugging 技能它会先让你给出超时的日志片段、线程池配置、调用链路的耗时分布再基于证据缩小范围。这种“先取证再下结论”的流程其实就是人类工程师排查问题的标准方法只不过现在被固化成 AI 的技能了。值得一提的是调试技能和 TDD 技能经常配合使用定位到 bug 后AI 会先写一个暴露问题的失败测试再修复最后跑回归。这在修老项目的时候特别实用能防止“修好一个 bug 带出三个新 bug”。3.4 Code Review让 AI 当质检员Code Review 技能适合在完成功能后使用。它的工作方式不是简单说“看看这段代码有没有问题”而是按清单过一遍可读性、命名、错误处理、边界条件、安全性、性能、测试覆盖。用法示例用 code-review 技能审查 src/main/java/com/example/OrderService.javaAI 会逐项给出问题和修改建议并且标注严重程度。我一般不会让它直接改代码而是让它先给报告我筛一遍再决定改哪些。原因很简单AI 的建议有时会过度设计比如把简单逻辑拆成一堆抽象类这对小项目反而是负担。审查报告里标“高优先级”的问题我会认真处理“建议类”的看情况采纳。3.5 其他值得一试的技能除了上面四个superpowers 还带了一些配合使用的技能我列几个常用的技能适用场景我的建议writing-plans大需求落地前的实现方案配合 brainstorming 使用效果更好retrospective一个迭代或一次协作结束后复盘团队用适合沉淀经验research需要查资料、看文档再决策适合技术选型git-workflow提交、分支、冲突处理让 AI 按团队约定执行这些技能不是越多越好。用的时候要有取舍小改动直接写别什么需求都走一遍完整流程否则本来 5 分钟的事会拖到 20 分钟。技能的定位是给复杂任务提供纪律不是给简单任务添麻烦。4. Java 项目里的实操记录4.1 Java 环境下的技能配置把 superpowers 用在 Java 项目上关键词是“先配置再使用”。Java 生态的构建工具、测试框架、模块系统都比较重AI 如果靠猜很容易写出跑不起来的测试。我在一个 Spring Boot Maven JUnit 5 的项目里做了实验。第一步就是让 AI 明确认知项目环境。我在项目根目录的说明文件里写了这样一段项目使用 Maven 构建JDK 17测试框架 JUnit 5。 执行测试命令mvn test 执行单个测试类mvn test -Dtest类名有了这段基本信息TDD 技能生成的测试类会自然地用Test断言库用 AssertJ 还是 JUnit 自带断言也能按项目习惯来。没有这段信息时AI 生成的测试经常会用org.junit.Test但 pom 里根本没加依赖跑一次报一堆红。4.2 一个完整的 TDD 会话示例我拿一个“金额解析工具类”做了完整演练。需求是把字符串“1,234.56”解析成 BigDecimal。对话大致是这样的第一轮我触发 TDD 技能AI 先确认测试框架和命令然后创建了MoneyParserTest写了一个解析正常格式的失败测试。跑mvn test测试失败符合预期。第二轮AI 开始写最小实现让测试通过。它只处理了正常格式没有提前写一堆防御代码。测试变绿后它会主动说“当前实现只覆盖了正常路径建议继续补充异常场景测试”。第三轮它开始补测试空字符串、非法字符、负数、千分位多余空格等。每个用例都走一遍“先写测试再实现”的路子。中途有一次实现没通过它没有直接改实现而是先停下来跟我确认“是需求理解错了还是实现写错了”。整个过程大概用了四十分钟比我手写测试的速度慢但覆盖度很全。说句公道话如果项目对测试质量有要求这种慢其实是值得的——AI 生成的边界用例数量通常比人凭经验想到的多。4.3 与 Maven/Gradle 的配合细节Java 项目跑 AI 生成的测试有几个坑是固定的我踩过之后总结如下依赖缺失AI 在测试里用了某个库但 pom 里没有。解决办法是让 AI 每次新增依赖前先检查 pom 并说明加依赖的理由。模块化问题JDK 9 的 module-info.java 会限制反射和包访问AI 生成的测试有时会踩到。遇到就让它看 module-info别硬改代码绕过。构建太慢大项目跑一次全量测试可能要几分钟AI 反复跑容易等死。建议在说明里写清楚怎么用-Dtest只跑单个测试类。Surefire 版本JUnit 5 需要 surefire 2.22.0 以上老项目经常会在这里翻车。AI 生成的 pom 修改不一定对要人工确认。这些细节都不是 superpowers 自身能解决的它只是流程管理器环境信息还是要你喂给它。你喂得越清楚它跑得越顺。5. 把 Superpowers 用到 Codex 上5.1 Codex 与 Claude Code 的差异“codex superpowers”这个搜索词现在很热很多人想知道这套技能能不能用在 OpenAI 的 Codex 上。结论是能但不是开箱即用。原因在于两者的扩展机制完全不同。Claude Code 有完整的插件系统支持/plugin、SKILL.md、MCP 配置superpowers 是按这套标准写的。Codex CLI 目前主要依赖的是项目里的 AGENTS.md 文件——它相当于一份给 AI 的项目操作手册告诉它代码结构、构建命令、工作规范。Codex 不认/plugin也不会自动读取 skills 目录所以直接把 superpowers 仓库塞给 Codex 是没用的。能力Claude CodeCodex CLI扩展机制技能/插件目录AGENTS.md 约定命令/plugin、/mcp较少工作流SKILL.md 自动匹配需要手动引导MCP支持支持5.2 在 Codex CLI 里复刻技能流程把 superpowers 的思路搬到 Codex 上核心做法是把关键技能的流程写进 AGENTS.md。我之前在一个 Java 项目里试过在 AGENTS.md 里加了这样一段## 开发流程规范 1. 新增功能时先写失败测试再写实现再重构。 2. 测试命令mvn test -Dtest目标类。 3. 动手改代码之前先输出实施计划等待用户确认。 4. 修改完成后用清单自检可读性、边界、异常、性能。这种写法相当于把 TDD、writing-plans、code-review 三个技能的精华压缩成了项目约定。Codex 在每次对话开始时读取 AGENTS.md之后的行为就会受到这些规范的约束。除了 AGENTS.md还可以在项目里维护一个docs/workflows目录放更详细的技能说明。需要的时候在对话里说“按 docs/workflows/tdd.md 的流程做”Codex 会打开文件执行效果接近 Claude Code 的技能触发。5.3 实测效果与感受我实际对比过同样一个需求用 Claude Code superpowers 和用 Codex AGENTS.md 各跑一遍。差别是客观存在的Claude Code 的技能触发更自动上下文更省Codex 则需要你在对话开头就把流程说清楚否则它很容易退化成“直接改代码”模式。但 Codex 的优势是干净、直接配合 AGENTS.md 写出的流程规范在团队协作里反而更容易审查——毕竟规范就明晃晃地放在仓库里每个人都能看到。如果你团队里已经全员用 Codex与其纠结怎么装 superpowers不如花点时间把 AGENTS.md 写成团队的“开发公约”效果是一样的。6. 常见问题与排查技巧实录6.1 技能没生效怎么办这是新手问得最多的问题。技能没生效通常有几种原因插件没启用、技能描述没匹配上、AI 误判了当前会话的上下文。补救步骤我按顺序来先跑/plugin看插件状态再直接问 AI “你现在有哪些技能可以用”如果列表里有但行为不像就在对话里明说“请使用 xxx 技能处理”。大部分情况下把技能名字直接说出口触发率会大幅提升因为这等于把 description 匹配的活儿替你做了。还有一种隐蔽情况你在一个已经聊了几十轮的会话里触发技能AI 容易受历史上下文干扰。这时候开个新会话、把需求重新说一遍往往就好了。6.2 MCP 服务连不上superpowers 的某些能力依赖 MCP 服务比如外部工具调用或持久化记忆。如果对话里报 MCP 连接错误先用/mcp查看服务状态确认对应的服务是否 running。常见原因无非是本地端口被占用、API key 没配、服务没启动。排查时别在会话里反复问 AI直接看服务日志更快。还有一个小经验MCP 服务偶尔会因为网络波动断线重启终端里的服务进程再/mcpreconnect大部分问题都能解决。如果项目里不需要 MCP 能力也可以干脆禁用相关配置减少一个变量。6.3 上下文被“撑爆”的处理技能流程会引导 AI 输出计划和清单对话轮次多了之后上下文容易膨胀。Claude Code 遇到这种情况会提示上下文超限。我的处理办法是分阶段开会话头脑风暴一个会话写计划一个会话TDD 一个会话。每个技能职责单一反而更不容易超限。另外与其把项目背景在对话里反复重申不如写在项目说明文件里AI 需要时读取。这样每次新会话都能快速回到状态还不占对话上下文。这是我从 superpowers 本身学到的文档化比对话记忆可靠。6.4 与团队协作的注意事项最后聊点团队层面的。如果要把 superpowers 引入团队我有几个建议第一技能流程产生的计划、测试、重构步骤都要纳入代码评审AI 的建议不一定是团队的共识第二用插件固定版本别让每个人拉到不同的分支导致体验不一致第三组织一次集体演练让团队先统一“什么任务该走流程、什么任务直接写”的口径。我个人在实际操作中的体会是superpowers 这类工具真正的门槛不是安装而是改变使用习惯。装好插件只完成了 20%剩下 80% 是你要愿意让 AI“多问几个问题、多走几步流程”。一开始会觉得烦但当你看到它在复杂需求里少犯低级错误、测试覆盖更全的时候就会觉得这些步骤是值的。最后分享一个小技巧在项目根目录的说明文件里把构建命令和测试框架写清楚这个动作成本最低收益却最高不管你是用 superpowers 还是 Codex都适用。