最近很多搞AI编程的朋友都在聊一个东西：superpowers。不管你是用Codex、Claude Code还是其他AI编程助手，只要你见过这个词，大概都会好奇——这到底是个插件、一个框架，还是一套提示词？我最初也是一头雾水，直到把一个开源项目克隆下来跑了一轮，才搞清楚它到底是什么。简单说，superpowers是一套给AI编码助手加buff的“技能包”，它不是替代现有工具，而是让你手头的AI从“会聊天、会写代码片段”变成“能按流程干活、能复盘验证”的工程助手。
这篇文章我会从真实使用体验出发，讲清楚superpowers的定位、安装方式、核心工作原理，并用一个Java项目作为实例演示完整流程，最后把我在实操中踩过的坑和排查方法一并整理出来。不管你用的是Codex还是其他支持AGENTS.md机制的AI编程工具，这套思路都适用。
1. 为什么AI编程助手需要“超能力”
1.1 Codex这类工具在当前的真实短板
先聊一个很多人在实际工作中都有的感受：Codex、Claude Code这类终端编程助手，单看代码生成能力确实很强，你让它“写一个二分查找”“实现一个REST接口”，它一分钟内就能给你整段代码。但真把它丢进一个有几千个文件、有历史包袱、有规范约束的真实项目里，问题就出来了。
我遇到过几次很典型的场景：让它加一个功能，它直接把相关文件改了，但没跑测试；让它重构一段逻辑，它改了实现却发现其他模块在依赖老接口；让它修bug，它只改了表面问题，根因没碰。问题不在模型能力，而在它没有一套稳定的工作流程。模型本质上是一个“单步推理”工具，你问一步它答一步，如果没人帮它规划“先做什么、后做什么、做完怎么验证”，它很容易一头扎进去就乱来。
这就像你让一个很聪明但没受过训练的实习生去负责一个模块：他代码写得出，但你得告诉他“先看需求文档，再列改动清单，改完要跑测试，提交前要自测”。AI编程助手也一样，缺的就是这套“操作手册”。
1.2 superpowers提供的是一套“行为准则”
superpowers的核心思路不是给你写更多的提示词，而是通过在项目里注入一组结构化的技能定义文件，告诉AI：你在什么场景下应该走什么样的流程。它把常见工程实践拆成了多个可复用的“技能”（skill），比如：
- 动手改代码之前先做方案调研和头脑风暴；
- 遵循测试驱动开发（TDD），先写失败的测试再写实现；
- 执行命令前后主动检查影响范围；
- 完成一批修改后主动跑测试、做代码审查。
听起来不复杂，但关键在于它把这些流程写成了AI能持续读取并调用的规则文件，并且把“调用技能”的动作内化到你的工作流里。每次启动Codex这类工具，它会自动加载一套技能说明，你只需要告诉它“按superpowers的方式来做”，它就会按流程拆解任务，而不再是一问一答式的短平快。
1.3 适合谁用、解决什么实际问题
从我自己的经验看，以下人群收益最大：
- 已经在用Codex、Claude Code等AI编程工具，但感觉“生成代码还行，改项目不靠谱”的人；
- 想用AI做完整功能开发，又不想每次都要手写一大段“你必须是资深工程师、注意测试、注意边界”之类提示词的人；
- 团队里希望统一AI协作规范，让不同成员用AI时行为一致的人；
- 做Java、Python等后端项目，需要AI理解工程规范而不是只会写算法题答案的人。
它解决的不是“AI写不出代码”的问题，而是“AI写出来的代码能不能可靠地落到项目里”的问题。后者才是真实开发里最耗精力的部分。
2. 安装与环境准备
2.1 前置条件与版本要求
在装superpowers之前，先确认环境。以我当前用的“Codex + superpowers”组合为例，下面这些是硬性条件：
- Node.js 18及以上版本。大多数安装脚本和交互式配置都依赖Node运行时，老版本会有兼容性问题。
- Codex CLI或Claude Code等支持AGENTS.md机制的AI编程工具。Codex是OpenAI的命令行编程助手，安装后通过
codex命令唤起；Claude Code则需要Node环境和对应的npm包。 - Git。安装superpowers本质上是克隆一个开源仓库到本地，所以Git是基础工具。
- 一个干净的项目目录。不建议直接在系统目录或根目录下跑安装，最好新建一个工作目录，或者在你的实际项目根目录里操作。
我自己最开始在Windows的PowerShell环境里装，遇到了一些路径权限问题，后面换到Git Bash里就顺畅了。如果你用的是macOS或Linux，原生终端环境会更省心。
2.2 完整安装流程
整个安装过程分三步走。第一步是克隆仓库：
git clone https://github.com/你的源/your-superpowers-repo.git cd your-superpowers-repo安装脚本一般是setup.sh，有的版本叫install.sh。执行前建议先看一眼脚本内容，确认它做什么操作：
./setup.sh脚本运行时会问你几个问题，主要是：你用的是哪个AI工具（Codex、Claude Code还是其他），以及你的项目路径在哪里。回答完毕后，脚本会自动把技能文件复制到对应的配置目录里。
以Codex为例，安装完成后你的项目根目录下会多出一个AGENTS.md文件，里面有对技能系统的说明；同时你的用户目录下（比如~/.codex/或~/.config/superpowers/）会存放各个技能文件的副本。
如果你不愿意跑脚本，也可以手动把skills目录下的Markdown文件复制到~/.codex/skills/目录，并在AGENTS.md里引用它们。两种方式最终效果差别不大。
2.3 验证安装是否成功
安装完之后，别急着开干，先验证一下。最简单的办法是在项目根目录启动Codex，问它一句话：
你知道项目里有哪些superpowers技能吗？列出来。
如果AI能像背书一样说出几个技能名称，比如“plan”“brainstorm”“review”“test-driven-development”，说明安装成功。如果它一脸茫然，大概率是AGENTS.md没被正确加载，或者技能文件路径不对。
还有一个更直接的验证方法：直接对Codex说“请使用brainstorm技能，和我讨论一下这个需求”。如果它开始反问需求细节、列选项、分析取舍，而不是直接撸代码，说明技能已经生效。
提示：每次安装或更新superpowers后，建议重启你的Codex会话。AGENTS.md通常是在会话启动时加载的，不重启的话，AI可能还是旧的行为模式。
3. 核心机制拆解：技能系统到底怎么工作
3.1 AGENTS.md是“总开关”
superpowers之所以能对AI起作用，关键在AGENTS.md这个文件。很多用过Codex的人都知道，AGENTS.md是Codex读取项目说明的入口，里面可以写项目背景、编码规范、常用命令等。superpowers等于把这个机制用到了极致：它在AGENTS.md里声明“本项目启用了一套superpowers技能，你应当根据任务类型调用对应技能”，然后把每个技能的详细说明放在独立文件中。
在AI的实际推理过程中，它会先读到AGENTS.md，知道“有技能系统这回事”，然后在具体任务发生时，依据AGENTS.md的指引去读取对应技能文件，按照里面写的步骤执行。这相当于AI的工作流被拆成了模块，而不是一次性塞给它大量上下文。
我刚开始不理解为什么不能直接把所有内容写进AGENTS.md，后面想明白了：如果全部堆在一个文件里，上下文太长，模型反而会忽略关键信息。分模块按需加载，既省token，又提高了指令被遵循的概率。
3.2 技能文件的结构与设计逻辑
每个技能文件本质上是给AI看的一页“操作SOP”。以brainstorm为例，它的内容大致包括：
- 技能名称和适用场景：什么时候应该用brainstorm；
- 操作目标：明确该技能要达到的结果；
- 执行步骤：比如先理解需求、再列出可选方案、分析每个方案的优劣、最后给出推荐；
- 输出格式：要求AI以结构化方式输出结论。
这种设计有一个明显的好处：AI不再自由发挥，而是按标准流程执行。就像工厂里的作业指导书，虽然工人可以有自己的经验，但核心步骤必须按规程来。
3.3 关键技能盘点与适用场景
从我实际看过的技能清单来说，下面这几个是日常用得最多的：
| 技能名称 | 触发场景 | 核心作用 |
|---|---|---|
| brainstorm | 接需求、设计功能 | 先讨论方案再动手，避免上来就写代码 |
| plan | 任务复杂、改动面大 | 生成分步实施计划，明确依赖关系 |
| test-driven-development | 写新功能、修bug | 先写失败测试，再写最小实现，最后重构 |
| review | 代码完成后 | 按审查清单过一遍代码，检查边界和隐患 |
| git-workflow | 提交代码、合并分支前 | 规范提交信息，检查状态再操作 |
每一类技能背后都对应一个真实开发痛点。brainstorm对应的是“AI理解需求有偏差”；plan对应的是“AI忽视全局影响”；TDD对应的是“AI改完不验证”；review对应的是“AI自产的代码没人把质量关”。
你完全可以按团队情况增减技能，比如加上security-review、performance-check之类的自定义技能。对我来说，这套体系最大的价值就是让AI的行为变得可预期，这比它偶尔灵光一现写出漂亮代码重要得多。
4. Java项目实战：让superpowers跑一个完整功能开发
4.1 实战场景与项目背景
为了方便说明，我用一个典型的Java后端项目走一遍流程。假设场景是：在一个Spring Boot项目中新增“用户注册”接口，需求包括邮箱注册、密码加密存储、用户名唯一性校验。这个需求本身不复杂，但涉及Controller、Service、Repository、实体类、异常处理、参数校验等多个层次，而且项目里已有类似的编码规范。
没有superpowers的时候，我如果直接让Codex实现这个功能，它大概率会一次性生成所有代码，看起来结构完整，但它不会主动检查项目里已有的异常处理类和统一响应结构，结果生成的代码全是“新风格”。等到编译才发现一堆问题，再来回改，血压就不稳了。
有了superpowers，流程就变成下面这样。
4.2 第一步：用brainstorm技能对齐需求
我先在Codex里输入：
使用brainstorm技能，讨论一下用户注册接口的技术方案。
Codex这时不会急着写代码，而是反过来问我：注册方式有哪些？密码策略是什么？是否需要邮箱验证码？用户名唯一性是数据库约束还是业务校验？要不要做登录限流？
这个过程看起来“效率变低了”，但实际作用非常大。它逼着我把需求想清楚，也帮我发现了一个之前忽略的点：项目现有的异常处理统一返回ResultCodeEnum，新接口必须复用同一套枚举和全局异常处理器，否则前后端对接会出问题。这些信息在后续实现阶段会大大减少返工。
4.3 第二步：用plan技能生成任务清单
需求对齐后，我让AI基于brainstorm的结论继续：
使用plan技能，输出用户注册接口的实施计划。
AI给出的计划基本长这样：
- 在数据库中确认用户表结构，必要时新增唯一索引；
- 创建
UserEntity实体类及对应的Mapper； - 编写
UserRepository接口，定义findByEmail和existsByUsername方法； - 在
UserService中实现注册逻辑，包含密码加密和异常抛出； - 新增
RegisterController，定义请求和响应参数； - 复用全局异常处理器处理业务异常；
- 编写单元测试。
这条计划的价值在于：它把任务拆成了可验证的小步骤。每一步做完，AI都可以自查或让我检查，而不是一口气塞一大坨代码。你会发现，当AI被要求“分步走”时，输出质量明显提高——因为每步的上下文更聚焦，出错率自然降下来了。
4.4 第三步：按TDD流程实现功能
接下来我让它执行具体的编码任务：
按照TDD技能，实现用户注册功能。
这里它先做的事情是：读取项目中已有的测试约定，然后为UserService的注册方法编写一个会失败的单元测试。测试覆盖三种情况：注册成功、邮箱重复、用户名非法。
果然，第一次跑测试是红的，因为Service和Repository根本还没实现。然后它再逐步写出实体、Repository和Service代码，让测试变绿。整个过程没有直接触碰Controller。直到Service层测试全绿之后，它才补Controller层代码，并追加一个MockMvc的接口测试。
这个习惯如果靠人肉提示，每次都要写很长的prompt，而且不一定每次都严格执行。但当它变成“技能”之后，执行概率高了不少，至少在我实验的几次里，它都会自觉地“先写测试再实现”，这个变化是很直观的。
4.5 第四步：用review技能做质量复盘
功能代码完成后，我执行：
使用review技能，复查这次用户注册功能的代码。
AI会按照审查清单逐个检查：参数校验是否完整，密码是否只存哈希值，数据库操作有没有处理唯一约束冲突，接口返回值是否符合统一响应规范，异常处理有没有覆盖邮箱格式错误，测试是否覆盖了边界条件。
检查结果帮助我发现了一个隐患：代码里对邮箱格式校验放在了Service层，但Controller层没有使用@Email注解，导致非法请求会一直打到Service才被拦截。虽然最终也能返回错误，但违反了项目里“参数校验尽量前置”的约定。如果没有review这一关，这个细节就漏过去了。
整个流程走下来，我的体感是：代码本身的生成速度没有变快，但代码被推倒重来的概率明显变小了。原本需要反复调试的边界问题，在流程中就被提前消化掉了。
5. 常见问题与排查技巧实录
5.1 安装后AI完全识别不到技能
这个问题我遇到过一次，原因很土：AGENTS.md没有放在项目根目录。Codex默认只读取当前工作目录下的AGENTS.md，如果目录弄错了，它自然读不到。
排查思路是按链路逐层确认：先看AGENTS.md在不在项目根目录；再看文件内容里有没有skills相关说明；最后在Codex会话里用“列出你知道的技能”来验证。如果文件都在但AI还是不认，大概率是会话没有重启，退出重进就好。
5.2 项目原本就有的AGENTS.md和superpowers冲突
很多项目里开发者已经写了自定义的AGENTS.md，里面可能有项目的编码规范。直接覆盖会丢失原有内容，不覆盖又担心冲突。
我自己的做法是把两份内容合并：把superpowers的技能说明追加到原文件里，并显式增加一段“启用技能系统”的说明。要注意顺序，把superpowers的声明放在前面，项目规范放在后面，这样AI先知道有技能可用，再了解项目细节。实测下来两者可以共存。
5.3 技能执行不稳定，有时不走流程
得说实话，superpowers不是魔法，它只是提升了AI遵循流程的概率，没有办法100%保证。当任务描述比较模糊时，AI还是可能“跳过”技能直接给结果。我的经验是：在下达任务时显式加上技能名，比如“使用plan技能……”，比依赖AI自动识别要可靠得多。对于关键步骤，该人肉把关的地方还是要把关。
5.4 在worbuddy等工具中怎么用superpowers
如果你用的是worbuddy这类自带工作区/技能管理界面的工具，思路是一样的：确认你的AI工具能读取项目中的AGENTS.md，或者显式指定技能目录。worbuddy里一般有“工作区设置”或“项目配置”入口，可以把superpowers的技能目录挂进去，或者在配置中指定AGENTS.md位置。流程上注意先确认工具的文档，有些工具会默认忽略隐藏文件夹中的Markdown规则，需要手动开启。
5.5 多项目与多AI工具共用一套技能
superpowers的技能文件本身是通用的，可以同时给Codex和Claude Code用。只要把技能目录复制到各自工具对应的配置目录，并确保每个项目根目录的AGENTS.md都引用了这套技能即可。要注意的是，不同工具对技能描述文件的优先级和命名可能不同，建议在每个工具里都单独验证一次，不要想当然“这套规则在A工具里生效，B工具里就一定生效”。
6. 我的一些实操体会与扩展建议
用了一段时间后，我最大的体会是：superpowers改变的不是AI的“智商”，而是它的“工作习惯”。以前用Codex，我总有一种在赌的感觉，赌它这轮会不会记得跑测试、会不会想到边界问题。现在这个随机性小了很多，因为这些被固化成了流程。
如果你也想尝试，我的建议是不要一上来就把所有技能都装上。先选两三个最贴你痛点的技能，比如plan和review，跑通一个项目之后再加TDD、git-workflow。等沉淀一段时间，你会发现AI输出的代码风格其实也在悄悄变化——它会更接近你们团队的约定，而不是每次都给你一份“教科书写法”。自带AI工具的协作方式，确实值得重新审视一遍。
