最近这段时间，AI编程代理（比如 Codex、Claude Code 这类工具）几乎是每个开发者的日常话题。但很多人用下来都会有一个共同的困惑：AI 确实能写代码，但总感觉“不太听话”——让它改个功能，它自己发挥出一堆无关代码；让它跑测试，它跑两下就停；项目一大，它就开始东一榔头西一棒子。如果你也遇到过这种情况，那我强烈建议你看看superpowers这个项目。
superpowers 本质上是给 AI 编程代理预置的一套“专业能力包”，通过文件形式的技能库（skills）、子代理（subagents）和工作流规范，把 AI 从“会写代码的工具”变成“懂工程纪律的协作者”。它能解决的核心问题就是：让 Codex 这类代理在处理大型项目、严格测试、多文件重构时，不再靠模型随机发挥，而是按照一套经过验证的工程路径去工作。适合谁呢？凡是天天跟 Codex 打交道、嫌它不够“稳”、想让 AI 输出质量和可维护性更上一层楼的开发者，都能从这里拿到不小的收益。
我第一次跑通它的时候，最大的感受是：这不是一个插件，而是一整套“AI 协作方法论”的开源实现。下面我尽量把这套东西的来龙去脉、安装过程和实战姿势都讲透。
1. 从“能用”到“好用”：superpowers 到底解决什么问题
1.1 Codex 这类编程代理的真正短板
先说一个很多人都踩过的坑。默认状态的 Codex 或同类工具，本质上是一个“很强但很随性”的结对程序员。你给它一个任务，它确实能理解语义、写出代码，但它缺少三样东西：上下文纪律、执行路径、质量门禁。
什么叫上下文纪律？就是它面对一个大仓库时，经常分不清哪些文件是核心、哪些是边缘，改着改着就偏离了主线。执行路径更明显——你让它“开发一个功能并测试”，它可能直接跳进代码编辑，把测试抛在脑后；或者测试失败了，它就换个方式重写一遍，而不是先定位根因。质量门禁就更别说了，很少有 AI 代理会主动意识到“这行代码不符合项目的代码规范”。
superpowers 的定位就是把这些短板补上。它提供了一系列预先写好的“技能包”，每个技能包都是一段精心设计的系统提示词加工作流说明，引导 AI 按特定方式思考、行动。你可以把它理解成：给 AI 发了一本公司的《新员工入职手册》，里面写清楚了“遇到需求应该先做什么、后做什么、什么情况下必须停下来问人”。
1.2 为什么不是传统插件，而是“技能库”形态
最初的 superpowers 走的是独立 CLI 工具的路子，后来逐步演进成了以skills目录为核心、让 Codex 直接读取的形态。这个转变很关键。
传统插件的问题是：它得侵入工具本身，版本一升级就可能挂掉。而技能库的思路是：我根本不改你的 AI 工具，我只改“喂给 AI 的说明书”。Codex 的配置里支持指定额外的技能目录，superpowers 就把自己所有的技能脚本放到这个目录里，启动时 Codex 会自动读取这些 Markdown 格式的技能说明，并按照里面的指示来调用对应的子代理或执行流程。
这样做的好处非常明显：
- 不锁定特定版本，Codex 升级了，技能库依然能跑。
- 技能本身是纯文本，任何人打开都能看懂、能改，相当于把“AI 调教经验”变成了可版本化、可审查的资产。
- 团队协作时，你可以把同一套技能库放进代码仓库，所有人所有机器共享一套 AI 行为规范。
我自己在团队里推广的时候就发现，这东西最大的价值从来不是某个单一技能多好用，而是它给了团队一套统一的、可以持续迭代的“AI 用法模板”。
1.3 子代理（subagents）机制与“分工”思想
superpowers 的技能库里包含多种子代理，每个子代理都面向特定工作类型。比如处理大型重构的、深度代码审阅的、规划技术方案的、执行测试的，各有各的提示词和约束条件。
为什么要把这些拆开？因为事实证明，让一个代理从头到尾包办所有环节，效果远不如“专业的人做专业的事”。就像你写后端不会让前端工程师去设计数据库表一样，AI 代理也应该有明确分工。每个子代理只在特定上下文启动，并带着一套专门的“工作指令”，这样它的输出质量和稳定性都会明显好于“万能代理”。
举个例子，我让 Codex 给我梳理一个遗留项目的模块依赖，默认状态它可能就是列几个目录结构完事。但升级 superpowers 后，它会主动读取构建文件、扫描代码引用、画出依赖关系图，最后产出一份带证据链的分析报告。这就是技能库给 AI 装上的“流程意识”。
2. 安装与初始化：从零到跑通，十分钟足够
2.1 环境准备与第一步
superpowers 的安装不复杂，但有几个前置条件容易忽略。建议按下面的顺序一步步来，能省掉很多幺蛾子。
首先，你的机器上需要准备这些基础环境：
- Node.js，版本建议不低于 18，很多依赖和脚本会用到现代 API。
- Git，用来拉取项目仓库。
- Codex CLI，并且已经完成了基础配置（能正常对话、能调用模型）。
- 如果是 Java 项目，确保本机有 JDK 和 Maven/Gradle，因为 superpowers 的部分技能会主动调用构建工具。
环境齐了之后，找一个你打算长期存放“AI 工具链”的目录，执行克隆操作：
git clone https://github.com/obra/superpowers.git注意，仓库名会随着项目演进变化，如果地址失效，直接去 GitHub 搜索 "superpowers codex skills" 就能找到最新的入口。克隆完成后，不要急着复制文件，先打开项目的 README，看看当前的安装方式。这类项目迭代很快，README 里的安装说明永远是最准的。
2.2 核心配置：让 Codex 认识 superpowers
代码拉下来之后，需要告诉 Codex 去哪里找这些技能。根据项目当前的做法，一般是在 Codex 的配置文件里增加技能目录的指向。
Codex 的配置文件通常位于用户目录下的~/.codex/config.toml，你需要找到或创建它，然后添加类似下面的内容：
[skills] extra_directories = ["/你的路径/superpowers/skills"]这里有个容易踩的坑：路径一定要写绝对路径，不要用~或环境变量简写。Codex 在读取配置时不会做 shell 级别的路径展开，你写个~/superpowers/skills，它可能就真的去查找名为~的目录了，结果自然是找不到。
配置完保存，重启 Codex 会话，让配置重新加载。然后做一个最简单的验证——直接在对话里问它：
你知道 superpowers 吗？你能使用它提供的技能吗？
如果它回答出具体的技能名称，比如 "Create a plan"、"Execute a researched implementation" 之类的，那就说明加载成功了。如果它一脸懵，先别急，往下看排查部分。
2.3 Java 项目环境的额外配置
如果你和我一样主要做 Java 开发，那安装完基础版之后，还需要关注语言相关的技能是否覆盖到 Java 场景。这部分不同项目差异很大，有的技能库对 Java 的支持是内置的，有的则需要你手动补充。
我的做法是：先检查技能目录里有没有java相关的 Markdown 文件。如果没有，也不用慌，可以自己写一个最小的 Java 技能包。比如创建一个skills/backend-java/README.md，里面写清楚：
# Java 后端开发规范 当你处理 Java 项目时，必须遵循以下步骤： 1. 先读取 pom.xml 或 build.gradle，理解项目依赖和模块结构。 2. 所有新增代码必须放在正确的包路径下。 3. 运行测试使用：mvn test 或 gradle test。 4. 代码风格遵守项目内 checkstyle 配置。就这么简单。superpowers 的核心机制其实就是“用规范的提示词去约束 AI 行为”，你不一定非得用官方预置的那套，完全可以自己长出来一套适合团队的语言包。
注意：技能文件放在 extra_directories 指向的目录下，Codex 就能自动发现。新增技能文件后记得重启会话。
3. 核心玩法：把 AI 从“写手”变成“团队”
3.1 技能包的正确打开方式
superpowers 最有价值的部分就是它预置的那套技能包。我强烈建议你不要只是装上就用，而是花点时间把技能目录里的 Markdown 文件都翻一遍。你会发现每个技能文件都写得像一份非常详细的操作手册，里面不仅说明了使用场景，还写了 AI 应该遵循的具体步骤、可调用的子代理、需要使用的工具等。
我自己用下来，最高频的几个场景是：
- 技术方案规划：在做较大改动前，让 AI 先输出完整方案，而不是直接动手写代码。这个技能会引导 AI 列出问题背景、约束条件、实现路径、风险评估，比默认状态下的“想到哪写哪”靠谱太多。
- 分步实施任务：把大需求拆解成多个阶段，每阶段只做该做的，并且完成后主动停下来等确认。这解决了 AI 最容易犯的“一次性改所有文件，结果到处都是 bug”的毛病。
- 测试与验证：代码写完不是终点，相关技能会要求 AI 主动定位测试文件、运行测试命令、分析失败原因并修复，直到绿灯为止。
注意，使用这些技能时，你需要在和 Codex 的对话里明确指定要调用哪个技能。比如你直接说“帮我做一次深度代码审阅”，它不一定能触发正确的技能，但如果你说“使用 superpowers 的 RECURSE_READ 和 REVIEW 流程，对 modules/order 目录做一次代码审阅”，效果立刻就不一样了。
3.2 让 AI 学会“先规划后执行”
这里展开讲一下我最喜欢的一个工作流。在默认状态下，我给 Codex 提一个需求，它会马上开始改代码，而且经常改出一些我认为“没必要”的内容。superpowers 的技能库里有一套“规划先行”的流程，它强制 AI 在动手之前先输出一份 plan。
具体现象是：你提出需求后，它会先回复一个包含背景分析、实现步骤、涉及文件的计划文本，然后问你是否确认执行。这一步看似多了一次交互，但其实省了后面大量返工。
我自己做一个订单模块改造时，特意对比过两种模式。默认模式下，AI 直接改了四五个文件，其中有三个文件的改动不是任务必需的。而使用规划流程时，它先识别出了订单状态机的核心逻辑，然后列出了每一步要动哪些类、哪些测试，我确认后再执行，结束后它还自动补了一份变更摘要。这个体验上的差距，基本就是“外包临时工”和“资深交付团队”的区别。
3.3 把技能变成团队规范
superpowers 还有一个很妙的使用方式：它不是只能给一个人用。由于技能库是纯文件，你完全可以把它提交到公司的 GitLab/GitHub 仓库里，然后让团队里所有人的 Codex 配置都指向这份共享技能库。
这样做的好处是：
- 团队所有成员与 AI 的协作方式保持一致，不会出现“你的 AI 会这样写，我的 AI 会那样写”的混乱。
- 新人入职后，配好环境，AI 自动按照团队规范工作，相当于 AI 也接受了入职培训。
- 技能库本身可以走代码评审流程，任何人想给 AI 加行为准则，都得提 PR 过评审，而不是自己悄悄改配置。
我在团队内部就是这么干的，把 superpowers 作为基础模板，再叠加我们自己写的几条技能（比如“所有接口必须写单元测试”“数据库变更必须附带迁移脚本”），效果非常理想。AI 的行为越来越像团队里的一个老同事，而不是一个需要盯着的实习生。
3.4 Java 场景下的实战配置参考
因为热词里出现了“superpowers java”，我再多说几句 Java 项目里的具体用法。
如果你日常用 Maven 管理项目，务必在技能里写明这些行为约束：操作前先读取pom.xml；新增依赖时主动检查版本冲突；测试跑mvn test而不是直接用javac去编译；重构时优先使用 IDE 的 safe refactor 模式而不是手动全局替换。
比如在 superpowers 的技能文件里，可以加入这样一段：
# Maven 项目操作准则 使用 Maven 项目时： - 执行构建前先运行：mvn -q compile -DskipTests - 需要运行全部单元测试时：mvn test - 当测试失败时，不要立即修改生产代码，先检查测试代码是否符合业务预期。 - 新增外部依赖时，先检查 dependency:tree 输出，避免版本冲突。这些看起来只是几句话，但对大模型来说是极强的行为锚点。没有这些话，它可能会用mvn package -DskipTests去“验证”代码，导致你本地编译通过但 CI 挂了的情况一再发生。配置了技能之后，这类问题明显减少。我也把自己积累的 Java 技能片段整理成了一个独立文件，直接放进技能目录，所有 Codex 会话都会自动加载。
4. 常见问题与排查技巧实录
4.1 技能没生效：换个思路找原因
很多用户反馈，配置了 extra_directories 之后，Codex 依然不认 superpowers。排查思路如下：
先确认技能目录结构是否对。Codex 加载的不是那个 superpowers 仓库根目录，而是里面的skills目录。如果在配置里写成了.../superpowers而不是.../superpowers/skills，那技能大概率加载不了。
再确认配置格式是否正确。TOML 格式对缩进和类型很敏感，extra_directories需要的是一个字符串数组，即使只有一个路径也要用中括号包住。另外注意，不同版本 Codex 的配置键名可能不一样，有的版本用[skills] extra_directories，有的用[plugins]下的某个字段，一定以官方文档为准。
最后，如果以上都没问题，试着把技能目录改成只有一份测试用技能，比如一个一分钟能写完的test-skill.md，看 Codex 能不能识别。这一步能帮你确认是目录加载的问题，还是技能文件本身的问题。我自己有一次就是技能文件里写了大量的特殊字符，导致解析异常，整个目录都被跳过了。
4.2 设置了技能但 AI 不按技能操作
这是比“加载失败”更挫败的问题：技能明明加载了，AI 也说自己知道了，但实际干活时还是不按规矩来。
这种情况我总结了两个主要原因。一是模型本身能力强但指令遵循能力弱，一些基础模型在长对话中会“忘记”技能里的规则。解决办法是：在使用时明确点名你要用的子代理或技能名称，甚至把关键约束直接写在本次对话里，比如“本次任务必须遵守 superpowers 的测试优先技能”。
二是技能文件写得不够明确。大模型对模糊指令的解读自由度很大，如果你写的技能是“注意代码质量”这种话，那基本等于没写。要写就写能验证的具体动作，比如“代码完成后必须执行mvn -q test并汇报结果，如果测试失败要给出失败原因分析”。AI 对“必须做什么”的遵从度，远高于“应该注意什么”。
4.3 网络与仓库拉取相关的问题
这类开源项目如果托管在 GitHub 上，国内开发者拉取代码时偶尔会遇到网络不稳定。这里不聊任何非正规手段，只讲两个常规办法。
第一个是使用镜像站点，比如 GitHub 的官方镜像服务（如ghproxy这类代理加速前缀）。注意，这类服务是公开的、广泛使用的加速方式，不是违规工具，很多大型项目都在用。你只要把克隆地址前加上加速前缀就行。
第二个是直接在 GitHub 网页端下载项目压缩包，解压后同样能使用。技能库本质就是一堆文本文件，压缩包和 git clone 出来的内容在功能上没有区别，只是后续更新时要重新下载而已。
4.4 常见问题速查表
| 问题 | 现象 | 排查方向 |
|---|---|---|
| 技能未加载 | AI 不识别任何 superpowers 技能名称 | 检查 config 路径是否指向 skills 子目录；检查是否是绝对路径 |
| 技能时灵时不灵 | 有时按流程操作有时不按 | 模型指令遵循力弱，换更先进的模型或在对话中显式点名技能 |
| 技能文件不生效 | 自己写的技能没有触发 | 检查文件名格式是否以 .md 结尾；检查文件内是否有明确触发条件和步骤 |
| Java 项目不被识别 | AI 不读 pom.xml 就动手 | 在技能中明确写死“操作前必须读取 pom.xml” |
| 配置报错 | Codex 启动时提示配置解析失败 | 检查 TOML 语法，确认键名与官方文档一致 |
| 更新后丢失自定义 | 重新拉取 superpowers 后自己的技能没了 | 不要直接在官方技能目录里改，把自定义技能放到独立目录，并在 config 里同时指向两个目录 |
这个表是我在实际团队推行过程中反复遇到的高频问题，建议截图存一份，配置遇到问题先对照着排查，速度会快很多。
5. 写在最后的实操心得
在写这篇文章之前，我特意把几个常用技能重新读了一遍，然后又一次体验了从配置到实际跑通的全过程。老实说，superpowers 这个项目真正吸引我的不是某几个技巧，而是它背后那个很朴素的理念：与其指望 AI 自觉，不如把规矩写在明面上。
我自己现在的工作习惯是，凡是需要让 AI 深度参与的任务，都会先明确“走哪套技能流程”，就像安排工作时先对齐流程一样。这套习惯带来的收益非常直观——AI 产出的代码质量更稳、返工率显著下降，也更适合团队协作。
另外想分享一个实际遇到过的小细节：技能文件里如果写了“执行完成后输出结果”，一定要在文件里同时规定结果格式，比如“用一个列表说明改动文件、测试结果、风险点”，否则 AI 输出很发散。这个坑我踩过，也是后来看文档才明白，大模型对输出格式的约束同样需要显式声明。
最后补充一点，如果你想在 Java 项目里把 superpowers 的价值最大化，建议不要偷懒用现成技能包，而是花半小时写一套贴合自己项目的 Java 技能文件。需求明确、格式清晰、步骤可验证，这套东西用下来，你会明显感觉到 AI 角色从一个“需要盯着的实习生”变成一个“能独立交付的同事”。这大概也是超级能力这个名字真正的含义——它给的不是魔法，而是沉淀下来的工作方法论。
