1. Superpowers 是什么：它不是魔法，是一套给 AI 的工作手册

先说结论：我理解的 Superpowers，并不是某个需要你反复折腾的“重型框架”，也不是那种装完就吃灰的“神器”，它是一个给 AI 编程助手加载的标准化技能包——目前社区里最流行的形态就是 Codex Superpowers 这类提示词库。

说白了，它解决的是很多人在用 Codex、Cursor、Claude Code 时都会遇到的一个痛点：AI 确实能写代码，但它不知道怎么“干活”。你以为你给了它一个任务，它会像高级工程师一样先问清需求、再拆任务、写测试、做回归，最后才动代码。实际上它可能上来就甩给你一段改了一半的代码，或者自信地告诉你“已经修好了”，但内存泄漏和边界条件全被忽略了。Superpowers 这套东西，本质上就是给 AI 塞了一本“工作手册”，告诉它遇到问题应该先做什么、再做什么，什么时候该停下来问人，什么时候该自己查日志。

我当初第一次看完它的使用文档时，第一反应是：这不就是我们平时给新人同事准备的 SOP 吗？只不过这份 SOP 是专门写给“AI 程序员”看的。它的核心不是在技术层面做什么黑魔法，而是把一套比较好的工程习惯，用 AI 能理解的方式固化下来。

1.1 为什么叫 superpowers？

这里说到“超能力”，我更愿意把它理解成一种“结构性能力”。给你举一个很生活的例子：如果你是团队里的老程序员，带过一个刚毕业的实习生，你会发现，实习生缺的往往不是编程基础，而是“遇到事情怎么处理”的经验——先分析需求，再设计接口，再写文档，最后才动手改代码。AI 编程助手更像一个“跑得特别快的实习生”，你如果没给它明确的流程约束，它就会凭着训练数据里的“平均行为”来输出，结果就是平庸、碎片化、没有项目意识。

Superpowers 的做法，就是把这些隐形经验写成“技能”。比如有一项技能叫“planning”，它会让 AI 在动手之前先输出一个实施计划，包括目标、风险、依赖、测试策略。还有一项技能叫“collecting context”，它会让 AI 在大型项目里先梳理相关文件和调用链，再回答你的问题。每一项技能都能单独使用，也可以组合起来，这就让它像瑞士军刀一样，不改变底层模型，却大幅改变输出质量。

我自己的经验是，装上这套东西之后，最大变化不是 AI 一次就写对代码，而是它开始会“边写边思考”了。你会看到它先列出几个关键问题，然后自己检查代码里有没有遗漏的 import，最后补上测试。这种“过程感”，恰恰是普通提示词很难激发出来的。

1.2 哪些人值得装这套技能包

如果你只是偶尔让 AI 帮你写个脚本、翻译一段代码，那说实话没必要折腾。但如果你是下面几类人，我非常建议试一试：

• 重度使用 Codex、Cursor、Claude Code、Windsurf 的开发者，尤其是希望通过命令行让 AI 完成稍复杂一点工程任务的人。
• 做 Java 项目维护、重构的工程师，被一堆历史代码和依赖关系搞得焦头烂额，想让 AI 帮你梳理调用链和生成测试。
• 团队里负责制定编码规范的架构师，想统一团队中“AI 协作开发的流程”，而不是让每个人都靠感觉写 prompt。
• 对 token 比较敏感的人，希望 AI 能更有目的地查询、阅读代码，从而减少无意义的来回追问。

我特别想强调一下 Java 场景。很多教程都拿 Python 或 JavaScript 举例，但 Java 项目因为类型系统复杂、依赖多、构建工具链重，AI 经常“理解不了上下文”。Superpowers 里有一套偏向“项目理解”的技能，它会引导 AI 先看 pom.xml 或 build.gradle，定位入口类和接口定义，再去找实现和测试。这套流程放到 Spring Boot 项目里尤其好用，后面我会用单独一节专门演示。

2. 安装前准备：环境、版本和一条铁律

如果你在网上搜“Superpowers 安装”，可能会看到各种版本的仓库名，有的叫 codex-superpowers，有的叫 superpowers-cli，还有的只是某个 IDE 插件。这里我要先给你吃一颗定心丸：它们背后的思路几乎一致，都是“加载一套技能提示词到你的 AI 命令行工具里”。所以我下面的安装步骤，是以最常见的开源版本为例来写的，你实际操作时只需要把仓库地址换成你找到的那一个就行。

不过在开始之前，我想强调一条铁律：永远不要跳过环境验证这一步。很多人装完没反应，不是安装步骤错了，而是 AI 命令行工具本身没配好。Superpowers 只是“润滑油”，发动机不转，加再多润滑油也没用。

2.1 先确认你的 AI CLI 已经能跑起来

目前社区里大部分 Superpowers 都是配合 OpenAI Codex CLI 用的。所以你先得确保自己的命令行里能正常调用 Codex。安装 Codex CLI 的方式通常是用 npm 安装：

npm install -g @openai/codex

装完之后，先跑一下codex --version，能看到版本号再继续。如果你连这个都还没装好，那问题大概率不是出在 Superpowers 上。接下来你还需要登录或者配置 API Key，这一步每个版本的 CLI 各有不同，但通常都会在交互式引导里完成。我的建议是，先用一个最简单的 prompt 测试一遍，比如codex "print hello"，能输出结果了，再做下一步。

这里有个小坑：如果你的 Node.js 版本太老，npm 安装可能会报权限错误或者找不到命令。我踩过这个坑，最后是通过升级 Node 到 LTS 版本解决的。需要注意的是，不要用系统自带的旧 Node，最好用 nvm 来管理版本，这样以后切换版本也方便。

2.2 下载 Superpowers 的三步操作

第一步，把项目克隆到本地：

git clone https://github.com/unlikelyhero/codex-superpowers.git

第二步，进入目录并查看安装脚本或说明：

cd codex-superpowers ls -la

大部分仓库会提供一个install.sh脚本，或者 README 里有一段手动配置说明。运行安装脚本前，我习惯先看一眼脚本内容，把 curl 的地址、目标路径都确认一遍，避免装错地方。你可能会觉得我太谨慎，但这类提示词项目的安装路径非常敏感，装错目录会导致 AI 根本加载不到技能。

第三步，运行安装命令。如果是脚本安装：

./install.sh

如果是手动安装，一般就是把仓库里的.superpowers.md或skills/目录软链到你的用户目录下，然后在 Codex 的配置里指定加载路径。以我常用的版本为例，我会在自己的~/.codex/config.toml里加一段指令指向技能目录，具体配置每个仓库会略有差别。

安装完成后，你最好再跑一下codex --get-superpowers（如果有这个命令）或者直接打开配置文件，确认路径指向的是真实存在的目录。这一步如果你跳过，后面技能不生效再来排查，成本会高很多。

2.3 安装后立刻验证

验证方法非常简单，不需要写任何真实代码，直接问你的 AI 助手一句：

请阅读你的 superpowers 系统提示词，然后把你能执行的全部技能列给我。

如果它输出了一串有编号的技能列表，比如planning、collecting context、implementing、debugging、reviewing、testing，那就说明安装成功了。如果它只是泛泛地回答“我可以帮你写代码”，那就说明技能没有被加载，你需要回头检查路径和版本。

我自己还会再做一个小验证：故意让它用planning技能来回答一个“给函数加参数”的任务。如果它真的先输出计划、再列风险、最后才写代码，那就说明技能确实生效了。这个验证看似简单，但非常关键，能让你从一开始就分清楚“装了”和“生效了”是两码事。

3. 核心技能拆解：这 5 个能力最常用

安装只是开始，真正让 Superpowers 发挥价值的是你得像使用工具箱一样去调用它。我用了大概两周之后，发现实际高频场景基本固定在 5 个技能上。下面我把每个技能的用法、prompt 示例以及我踩过的坑逐一讲清楚。

3.1 技能一：规划先行（Planning）

这个技能几乎可以应用到所有开发任务里。它要求 AI 在动手写代码之前，先输出一份简短的实施方案，内容包括：任务目标、技术方案、改动范围、潜在风险、测试计划。听起来很简单，但实际效果非常明显。

我常用的触发方式是直接说：

使用 planning 技能，帮我把“为订单模块增加定时取消”这个需求拆成实施计划。先不要写代码，把关键问题列出来，比如是否需要事务、是否需要幂等、任务调度器选型。

这时候 AI 会像真正的技术负责人一样，先跟你确认需求范围，再给出计划，甚至提醒你注意分布式部署下的重复执行问题。如果你不加载这个技能，它可能直接就开始写@Scheduled注解了，完全不管你的项目是不是集群部署。

注意一点：planning 技能不是让你每次都在对话里说“请使用 planning 技能”，有些版本的 Superpowers 是自动启用的，只要你让它完成稍微复杂一点的任务，它就会触发规划行为。如果你发现它没有自动触发，那就说明你的提示词中缺少“当任务复杂度超过某个阈值时，必须启动 planning 流程”这样的规则。我后来在自定义配置里手动加了一句，效果才稳定下来。

3.2 技能二：上下文收集（Collecting Context）

这个技能是处理大型项目的救命稻草，尤其是 Java 项目。AI 编程助手最大的问题是，它对你的项目了解有限，只会根据当前 prompt 里的内容来回答。你如果直接问它“帮我重构 payment 模块”，它可能完全不知道 payment 模块在哪里、涉及哪些类。上下文收集技能会引导 AI 首先去分析目录结构、关键配置文件，然后定位到相关类，再理解调用关系，最后才回答问题。

实际使用中，我常这样发起：

使用 collecting context 技能，先不要给我写代码。请先查看项目里的pom.xml、Application.java和controller目录，帮我梳理支付接口从 Controller 到 Service 再到 Mapper 的调用链，并用简单的文字描述出来。

如果没有这个技能，AI 可能会随便抓一个文件名就开始展开，甚至可能因为找不到上下文而拒绝回答。有了上下文收集技能后，它会一步一步地查找，并在最终回复里附上“我查看了哪些文件、为什么查看它们”的路径列表。这实际上让 AI 的思考过程更可见，对排查问题很有帮助。

3.3 技能三：测试生成（Test Generation）

让 AI 写测试是很多人最初动力的来源，但要写好测试其实比写代码本身还难。Superpowers 里的测试生成技能会约束 AI 在写测试之前先明确测试目标、边界条件、依赖 Mock 策略，然后才动手生成单测。它还会要求生成的测试遵循项目里已有的测试风格，而不是想当然地用一套全新的写法。

我在一个 Spring Boot 项目里试过让它给一个订单服务类生成 JUnit 测试。没有 Superpowers 时，它生成的测试很“幼稚”，几乎全是 happy path，而且直接 new 了一大堆依赖对象，看得我血压升高。激活测试生成技能后，它先问我“需要 Mock 支付网关吗？数据库用 H2 还是自研 Mock?”然后生成了一套结构清晰的@MockBean测试，连异常路径都覆盖了。

使用测试生成技能时，我有个私人心得：最好在 prompt 里清晰告诉 AI 项目的测试框架版本，比如 JUnit 5、Mockito 4。否则它可能生成旧版写法，编译直接失败。这不算 bug，但在实际使用中非常常见。

3.4 技能四：代码审查（Review）

代码审查技能和你想的可能不太一样，它不会只是简单说“没有问题”。它会要求 AI 从代码规范、潜在缺陷、性能隐患、安全风险四个维度去检查代码，并给出严重等级标注。比如它会输出“P0：未处理空指针风险；P1：循环里调用了数据库查询，建议批量处理；P2：变量命名不规范”。这个输出格式对于团队 code review 非常友好。

我通常在让 AI 改完代码后，立刻追加一句：

使用 review 技能，检查你刚才修改的代码，重点看是否有事务缺失、资源未关闭、并发安全问题。

这时候 AI 确实会“回过头来”审查自己的代码，经常能发现它自己刚犯的错误。有一次它在实现文件上传时忘记检查文件大小就写入了内存，review 技能直接给它打了一个 P1 风险，它马上改成了流式处理。这种自我纠错能力，是普通模式很难做到的。

3.5 技能五：自定义扩展（Custom Skills）

Superpowers 不只是固定的一套技能，它允许你自己定义新的技能。这就像给 AI 增加公司专属规范。举个例子，如果你所在团队要求所有对外接口必须包含requestId用于链路追踪，你可以写一个自定义技能，让 AI 在生成 controller 时自动加上该字段，或者在做 code review 时自动检查。

自定义技能一般需要在一个.md文件里定义，格式大约是这样的：

# Skill: request-id-check ## Trigger 当用户要求创建或审查 Controller 接口时触发 ## Instructions 1. 检查接口是否需要 requestId 参数 2. 如果缺失，在 DTO 中加入该字段 3. 在响应头中注入 requestId 4. 确保使用 UUID 格式

把这个文件放进 Superpowers 的技能目录后，在对话里输入“使用 request-id-check 技能”就会生效。我觉得这是最值得投入时间去做的事情，因为通用的技能教不会 AI 你们团队的“特殊规矩”，而自定义技能正好补上这一环。

4. 在 Java 项目里实测：从“听不懂”到“能干活”

前面讲了一堆理论，这一节我想拿一个真实场景来演示。我手头上有一个还算老的 Spring Boot 项目，代码量大概几万行，里面涉及订单、支付、库存、消息队列几个模块。我用它来测试 Superpowers 在 Java 工程里的实际表现，并且看到了非常明显的差别。

4.1 场景：遗留 Spring Boot 项目的依赖梳理与测试补写

我给了 AI 一个任务：“帮我梳理订单取消接口的完整调用链，并为它补上单元测试。”在没有 Superpowers 的情况下，它一上来就尝试搜索OrderController，然后直接生成了一堆看起来像那么回事的测试代码。但仔细看，那些测试根本没真正理解项目里的OrderService是接口还是实现，也没有 mock 掉OrderStatusUpdateEventPublisher这类异步依赖，结果就是测试根本跑不起来。而且，它在梳理调用链时只能根据文件名猜测，并没有真正去读pom.xml里的依赖关系，对@Qualifier的处理也是一塌糊涂。

用了 Superpowers 之后，我先让它用 collecting context 技能分析项目。它先读了pom.xml，确认用到的核心框架版本，然后查看了controller包里的OrderCancelController，再从 Controller 的方法签名找到OrderCancelService的实现类，顺着实现类里的方法调用，找到了OrderRepository和MessageSender。整个梳理过程花了不到两分钟，但它在这两分钟里不断地在日志里输出“正在查看 xx 文件，确认 xx 依赖关系”，让我确信它不是在胡猜。

接着我要求它补测试。它先问了我三个问题：数据库用 H2 还是 Mockito 模拟？消息队列发送器是否需要验证发送成功？订单状态机流转是否要覆盖非法状态？我回答之后，它才生成测试代码。生成的测试里，该 mock 的都 mock 了，还额外用ArgumentCaptor验证了事件发布参数。运行一遍，全部绿灯。

4.2 有/无 Superpowers 的对比表格

为了让你直观看到差别，我把那次实测整理成了表格：

这个对比不是要说明 Superpowers 有多神，而是想说明：大量看起来是“模型能力不够”的问题，其实是因为你没有给 AI 一套合理的工作流程。它会写代码，但它不知道你的项目规矩，也不知道测试该怎么设计。Superpowers 恰恰是补上了这部分“工程常识”。

4.3 token 消耗观察和绕过方式

用 Superpowers 会不会很费 token？我的观察是：前期要稍微多花一点，但从整个任务闭环来看，反而更省。因为它会引导 AI 做更精准的文件搜索和代码定位，减少大量无意义的长篇回复。比如在梳理调用链时，没有技能的模式下 AI 可能会反复追问“你能不能贴一下代码片段”“这个类的路径是什么”，这些来回消耗也不少。有了技能之后，AI 自己就知道去哪里找，一次到位。

不过，如果你的项目特别大，还是要注意上下文窗口的问题。我一般会明确告诉 AI：“只分析订单取消相关的模块，不要打开支付和库存的代码。”有意识地限制搜索范围之后，token 消耗能下降不少，回答速度也更快。这里没有银弹，关键还是任务拆分。

5. 常见问题与排查技巧实录

折腾这类工具，最容易让人劝退的不是概念难懂，而是各种莫名其妙的“不生效”。我把过去半个月里遇到的高频问题和排查思路整理一下，希望能帮你省点时间。

5.1 安装失败：五个高频报错

• codex: command not found：这个最基础，说明 Codex CLI 没装好，或者 npm 全局路径没加到 PATH。先用npm root -g查全局路径，再把它加到.bashrc或.zshrc里。
• EACCES: permission denied：npm 全局安装遇到权限错误，八成是因为用了系统 Node 而不是 nvm。我建议重装 nvm，避免用sudo npm install这种暴力办法，后患无穷。
• No such file or directory: ~/.codex：Superpowers 要写入配置目录，但这个目录还没创建。手动执行mkdir -p ~/.codex就能解决。
• Failed to load skills directory：一般是因为你克隆下来的仓库路径里有空格，或者目录层级太深。把仓库挪到~/codex-superpowers这种全英文短路径下，问题就消失了。
• Git clone 超时或失败：如果你所在网络访问 GitHub 不稳定，可以选择用代理或镜像，但这不是我们这里的重点。另一个可行办法是直接在浏览器下载 zip 包再解压，效果一样。

5.2 技能不生效：先查这三件事

如果安装没报错，但 AI 始终不认技能，我的排查顺序是先确认版本是不是太新或太旧。Superpowers 依赖 Codex CLI 的某些启动行为，如果 CLI 版本升级了，旧的技能加载方式可能失效，此时可以去仓库看更新记录。

其次，检查你的配置文件和技能目录路径是否真的被读取。你可以故意在技能目录里放一个只有自己能认出来的词，然后问 AI“你看到了哪些新技能”。如果它回答了，说明路径没问题；如果没回答，那就证明加载路径根本没配置对。

最后，确认 prompt 里是否明确提到了“按照系统提示词中的技能列表工作”。有时候你确实加载了技能，但 AI 没有主动触发它，这时候你需要在指令中加入技能名，比如“使用 planning 技能”。当然，如果你希望它每次自动触发，就得在系统提示词里把“自动判断复杂度并启动技能”作为一项规则写清楚。

5.3 输出质量突然变差怎么办

我用着用着就发现，如果 AI 总是在同一个会话里不断报错，它的回复质量会肉眼可见地下降。这通常不是技能失效，而是上下文被污染了——前面太多失败日志和错误猜测让模型失去了方向。

我的处理办法很简单：新开一个会话，把任务背景、目标、约束用寥寥几句话重新描述，然后直接调用对应技能。不要尝试在同一个会话里“纠正”它超过两次，那样只会越陷越深。还有一个技巧是给 AI 设置“思考模式”，比如让它“只输出分析和计划，不要写代码”，这样能缓解它在纠结中的混乱。

5.4 排查速查表

说实话，Superpowers 不是一个“装完就一劳永逸”的工具，它更需要你根据自己的项目去调教和维护。但反过来说，正是这种可自定义、可扩展的形态，才让它比单纯的“提示词模板”更有生命力。

最后分享一个我自己的使用习惯吧：我不再把它当作一个需要刻意记命令的功能库，而是把它理解成“给 AI 建立工作习惯”的模板。每次接手一个新项目，我会花十分钟把项目里的目录结构、编码约定、依赖清单简单写进一个自定义技能文件里。这样后续不管让 AI 写什么，它都会自动遵循这个上下文，很少再犯“把接口当实现类”这种低级错误。如果你也想让自己的 AI 助手真正从“会写代码”变成“会干活”，我建议你从一个小项目开始，只启用三个技能：规划、上下文收集、测试。先跑通流程，再慢慢加其他技能。这种循序渐进的方式，比一次性安装所有技能然后不知所措要有效得多。