最近在折腾 Codex CLI 和 Claude Code 这类 AI 编程代理的时候，我频繁听圈子里的人提到一个名字：superpowers。一开始我以为是某个“一键让 AI 变聪明”的玄学工具，直到自己手动装了一遍、跑了几个真实项目之后才意识到，superpowers 本质上是一套以“技能（skills）”为核心的 AI 代理增强框架。它不改变底层模型，却能让模型按照预设的工作流程去思考、拆解任务、执行检查，甚至自动遵循 TDD、代码评审、安全扫描这些本该由人工反复强调的工程规范。
这篇文章我打算把自己从安装、初始化、日常使用到和 Codex CLI 配合调教的全过程写出来，包括那些文档里没有写的坑。适合刚听说 superpowers 想入门的同学，也适合已经在用但总觉得“AI 还是不够听话”的开发者。我会尽量用白话来解释它到底解决了什么问题，并给出一套可以直接抄的 Java 项目实操路线。
1. Superpowers 到底是什么：不是超能力，是给 AI 编程助手的“技能系统”
1.1 一个被严重低估的 AI 辅助层
很多人会把 superpowers 和普通的“提示词模板”混为一谈，这是最大的误解。提示词模板只是给模型一段固定的上下文提示，而 superpowers 做的是更底层的“行为约束”。安装之后，它会在你的项目里生成一个专用的技能目录，每个技能对应一份 Markdown 格式的流程文档。当你在对话中明确请求某个技能（比如“用 brainstorming 技能帮我梳理需求”），AI 就会去读取这份文档，并且严格按文档里定义的阶段、输入输出格式、甚至检查清单来执行。
换句话说，superpowers 提供的是“过程管理”，而不是“答案生成”。它让 AI 编程代理从一次性问答机器，变成了一个会走流程、会自我检查、会在关键节点停下来等你确认的执行者。这种设计思路在工程上非常重要，因为大模型最难控制的就是“发散”——它可能三秒钟就给你一个看似完整其实漏洞百出的方案。而技能系统本质上是给模型套上了一根“流程轨道”，让它只能沿着轨道走。
1.2 它解决的核心痛点：AI 不会“主动干活”
用过 Codex CLI 或者 Claude Code 的人应该都有体会：你问一句它答一句，你不要求的它绝对不会多做。比如你让它“修复这个 bug”，它很可能直接改完代码就结束，不会主动跑测试、不会检查是否引入了回归问题、也不会更新相关文档。这不是模型笨，而是缺少“任务拆解和完成度定义”。superpowers 的核心价值就在于把这套工程习惯固化成技能文件，让 AI 每接到一个任务就自动套用相应的工作流。
举个例子，我用它内置的 debugging 技能处理一个 Java 空指针异常时，AI 会先要求我描述复现路径，再让我提供堆栈日志，然后它才会开始分析可能原因。分析完之后，它还会按照技能要求补上“根因说明”、“修复方案对比”、“验证步骤”三个小节。整个过程像极了一个高级工程师在带新人，而不是一个只知道给代码的工具。
2. 安装与初始化：三分钟跑通基础环境
2.1 安装前的环境检查
superpowers 本身是一个 Node.js 命令行工具，所以第一前提是机器上有 Node.js 环境。我建议使用 Node 18 以上版本，因为底层需要比较新的fs和pathAPI。如果是 Windows 用户，建议用 WSL 2 或者 Git Bash，否则在接下来的技能文件路径解析上可能遇到盘符和反斜杠的问题，别问我怎么知道的，都是泪。
需要确认的还有你的 AI 编程代理版本。如果你打算配合 Codex CLI 使用，请确保 codex 在 0.4 及以上版本，因为早期的版本对自定义指令的加载机制不完善。如果是 Claude Code，则建议 1.0.20 以上。检查方式很简单，直接在终端跑对应命令的--version就行。
2.2 安装步骤与命令
推荐使用 npm 全局安装，这样之后在任何项目目录下都能直接调用。安装命令如下：
npm install -g @superpowers/core装完以后，进入你的项目目录，执行初始化：
superpowers init这一步会在当前目录生成.superpowers/文件夹，里面包括skills/、templates/、config.json三个部分。skills/是存放技能 Markdown 文件的地方，templates/放着技能文件的模板，config.json则是控制技能加载行为和模型适配的配置文件。
初始化完成后，可以用superpowers list查看当前可用的技能列表。正常情况能看到 brainstorming、planning、debugging、code-review、security-audit、test-driven-development 这一批内置技能。如果你的列表为空，大概率是安装路径的权限问题，把.superpowers文件夹改成用户可读写即可。
superpowers list2.3 初始化配置的注意事项
这里有个关键点：superpowers init只会创建配置目录，它不会自动修改你的 Codex CLI 或 Claude Code 的配置文件。你需要手动把.superpowers/skills/路径加入你的 AI 代理的指令加载目录。
以 Codex CLI 为例，编辑~/.codex/config.toml，添加如下内容：
[instructions] files = [".superpowers/skills"]改完之后重启 codex，让配置生效。很多同学在这里栽跟头，以为装上 superpowers 就能用，结果 AI 完全不理它，就是因为没有做这一步。我建议初始化后立刻检查一下 AI 代理能否读取技能文件，方法是直接在对话里问一句“你知道 superpowers 的 brainstorming 技能吗？请用一句话概括它的流程”。如果 AI 能准确说出来，说明加载成功；如果答非所问，就去检查路径配置。
3. 核心用法：技能清单、模式匹配与 Java 项目实操
3.1 内置技能清单解读
我把最常用的几个技能做了一个表格，方便你快速理解每个技能是干什么的、适合什么场景：
| 技能名 | 触发方式 | 核心流程 | 适合场景 |
|---|---|---|---|
| brainstorming | 我说“用 brainstorm 技能” | 背景收集 → 问题重述 → 多方案生成 → 优劣对比 | 需求方案设计、架构选型 |
| planning | “按 planning 技能拆分任务” | 目标定义 → 任务拆解 → 依赖分析 → 里程碑划分 | 复杂功能落地前 |
| debugging | “用 debugging 技能排查问题” | 复现路径确认 → 日志分析 → 根因假设 → 验证计划 | 线上 bug、疑难杂症 |
| tdd | “按 tdd 技能开发” | 红 → 绿 → 重构，先写失败测试再写实现 | 新功能开发、单元测试 |
| code-review | “帮我 code review，用技能” | 逐文件检查 → 按规范打分 → 给出修改建议 | 合并请求自查 |
| security-audit | “执行安全审计技能” | 依赖扫描 → 边界输入检查 → 越权路径审查 | 上线前的安全检查 |
这六个技能基本覆盖了日常开发的高频场景。但要注意，superpowers 的技能不是“魔法指令”，不是说你说一句“用 brainstorming 技能”它就自动开始群聊式发散。它还是会希望你先提供必要的背景信息。技能文档里其实定义了 AI 需要向用户提问的清单，所以很多时候你会发现 AI 反而会“反问”你更多问题，这是正常的。
3.2 在 Codex CLI 中启用 superpowers
要在 Codex CLI 里真正用上 superpowers，除了前面说的配置config.toml之外，还有一件事值得做：自定义启动提示词。我习惯在 Codex 的AGENTS.md文件末尾追加一段：
当你需要执行复杂任务时，请先查看 .superpowers/skills 目录下的技能文档，并遵循其中定义的流程。 如果用户提到某个技能，请使用该技能对应的完整流程，而不是仅凭常识泛泛响应。这样做的原因是，虽然技能文件已经加入指令目录，但模型在普通对话中未必会主动去翻技能文档。加上这段提示词，相当于给模型一个“路由开关”，让它遇到任务时先判断该调哪个技能。我实测下来，加了这段之后，AI 调用技能的频率明显提高，回答质量也更稳定。
另外，Codex CLI 的非交互模式（即通过-p传递一次性任务）同样支持技能调用。比如我可以直接在终端里跑：
codex -p "用 tdd 技能为这个项目新增一个登录接口"它会先读取 tdd 技能文档，然后输出一个包含测试代码、实现代码、运行说明的完整方案。这个能力在写自动化脚本时特别有用。
3.3 Java 项目里怎么用：一个 Maven 工程示例
不少人问 superpowers 是不是只能配合 JS/TS 项目，其实完全不是。它和语言无关，因为技能文件里写的是“流程要求”，不是具体的代码规则。我拿手上的一个 Spring Boot 3 + Maven 项目做了实验，效果很理想。
先看项目结构，我提前建好了标准的 Maven 目录：
my-app/ ├── pom.xml ├── src/main/java/com/example/ ├── src/test/java/com/example/ └── .superpowers/我在pom.xml里只引入了 Web 和 Test 两个 starter。然后打开 Codex CLI，输入：
codex -p "用 tdd 技能实现一个简单的用户注册接口，要求用户名和密码不能为空，使用 Maven 项目结构"接下来有意思的事情发生了。AI 没有直接给我Controller代码，而是先在src/test/java/com/example/下生成了UserControllerTest.java，内容是一个针对空参数返回 400 的测试。测试跑当然会失败，因为这时候还没有 Controller。然后它又生成了UserController.java，实现了一个@PostMapping("/api/users")接口，用@Valid配合@NotBlank完成了参数校验。最后它输出了运行指令：
mvn test我按照这个流程跑了一遍，测试确实从红变绿。这个例子虽然简单，但很能说明问题：superpowers 的 tdd 技能不是嘴上说说，它会强制 AI 按照“先测试后实现”的顺序来，并且生成的代码会严格匹配你项目的构建体系。这就是流程约束的价值。
4. 常见问题与排查技巧实录
4.1 命令找不到 / 安装失败
最常见的问题是superpowers: command not found。原因通常有两个：npm 全局安装的 bin 目录没有加入 PATH，或者安装过程中权限不足导致命令没写到 bin。
排查步骤我建议这样走：先执行npm ls -g @superpowers/core看包是否装上了，再执行which superpowers看命令位置。如果包在但命令不在，就用：
npm config get prefix把返回的路径加入环境变量 PATH 即可。如果是 EACCES 权限报错，多半是 npm 全局目录的写权限问题，别直接改权限，最好用nvm管理 Node，把全局包装到用户目录下。
4.2 技能不生效 / 上下文被覆盖
技能文件加载了，但 AI 就是不用，大概率是上下文窗口被其他指令占满了。Codex CLI 会先加载AGENTS.md，再加载config.toml里指定的指令文件。如果AGENTS.md很长，技能文件的描述可能被模型忽略。我遇到过一种情况：项目根目录有一个巨大的AGENTS.md，描述了一堆业务规则，superpowers 技能文件放在后面，结果模型完全“看不见”。
解决方案是把技能加载路径尽量前置。在config.toml的[instructions]中，可以在files列表里把.superpowers/skills放在最前面，只留AGENTS.md在后续。另一方面，也可以在对话中用更明确的指令，比如：
请严格参考 .superpowers/skills/debugging.md 文件里的流程执行。这样模型会强制去读指定文件，绕过上下文干扰。
4.3 模型版本兼容性
superpowers 对模型版本其实有一定要求。在 Codex CLI 里，如果你使用的是比较老的gpt-4系列，模型对长文档的遵循能力偏弱，技能流程经常执行到一半就“跑飞”。我实测下来，gpt-4o和o3系列表现稳定，尤其是o3，几乎每次都会严格按技能文档的检查清单走。
如果是 Claude Code，我建议至少用 Claude 3.5 Sonnet 以上。掉到 3.0 Opus 时，技能中的多阶段任务拆分经常会出现遗漏，比如跳过了“失败测试”直接写实现。这不是 superpowers 的问题，而是模型指令遵循能力的差异。遇到这种情况，最简单的解决办法是在技能文档的首行加一句强约束：
> 你必须在完成阶段1并得到用户确认后，才能进入阶段2。任何情况下都不允许跳步。亲测有效，能够明显减少流程跳变。
5. 进阶技巧与个人心得
5.1 自定义技能：把团队规范变成 AI 的肌肉记忆
内置技能覆盖面有限，真正好用的是自定义技能。superpowers 的项目模板给了非常清晰的结构，我建议直接在.superpowers/templates/custom-skill.md基础上改。一个技能文件通常包含以下几个部分：技能描述、触发条件、执行流程、输入要求、输出格式、检查清单。
我举个例子，最近我们团队要求每次合并请求前必须补充接口压测报告。我就写了一个perf-check技能，流程是这样的：
- 询问用户当前接口的 QPS 预期和延迟要求
- 生成 JMeter 脚本或一个简单的压测类
- 执行压测并收集结果
- 输出一份包含吞吐量、P99 延迟、结论建议的报告
写好后放到.superpowers/skills/perf-check.md，然后在 Codex 里说“用 perf-check 技能检查这个接口”，AI 就会严格执行这四步。团队规范再也不会靠人肉提醒了。
5.2 与团队共享配置：把技能文件纳入版本管理
因为.superpowers/就是一个普通目录，完全可以提交到 Git。我建议直接把整个.superpowers/目录纳入版本管理，这样新同事拉下代码后，只需要运行superpowers init --use-existing或者直接让 AI 代理读取已有技能文件，就能保持一致的行为标准。注意，config.json里的模型适配参数可能因人而异，建议把公共技能文件提交，但把config.json加入.gitignore。
如果你所在团队同时用 Codex CLI 和 Claude Code，技能文件完全可以共用，因为它们都是 Markdown 格式，只是加载方式不同。这比分别维护两套提示词要高效得多。
5.3 一些避免翻车的忠告
我用了几个星期之后，最大的感受是：superpowers 不是“自动驾驶”，而是“副驾驶的检查单”。它能把 AI 的行为拉回正轨，但不能替你做技术判断。比如 debugging 技能可能会引导你分析日志和堆栈，但最终的根因确认还是需要你拍板。该review的代码还是得review，该跑的性能测试还是得跑。
还有一点。不要过度依赖内置流程。我见过有人给所有任务都用 planning 技能，结果一个两小时的活拆出了十几个阶段，AI 每走一步都在问“是否需要继续”，效率反而低了。我的经验是：小型改动直接用普通对话就行，只有多文件、跨模块、需要回归验证的任务才值得上技能。学会判断什么时候用、什么时候不用，才是真正把 superpowers 用出“超能力”味道的关键。
最后分享一个小技巧：如果你发现某个技能在一次任务中跑得特别漂亮，可以把这一次的完整对话记录保存到.superpowers/examples/目录下，并在技能文档底部加一个“参考案例”链接。下一次 AI 执行同一技能时，它会多一个高质量范例可以模仿，输出质量会肉眼可见地提升不少。这个习惯让我在复用自己项目里的各种技能时省了大量时间，希望对你也有帮助。
