1. superpowers 是什么：先把它从“玄学”拉回工程
想聊 superpowers，我先说个真实场景。我自己的主力工具是 AI 编程助手，这几年换了好几轮，从补全工具一路用到能自主执行命令的 CLI 助手，工具越来越强，但有个毛病一直没治好：对话一长，它就“失忆”。上午刚敲定的接口设计，下午改了一个函数，它就开始自由发挥；明明说好了先写测试，它经常一口气把实现代码也写完，等测试挂了再回头补。后来看到 superpowers 这个项目热度突然涨起来，热搜词里全是“superpowers 使用指南”“superpowers 安装”“codex superpowers”，我第一反应是又有人起了一个很唬人的名字。实际用了两周之后，我理解它为什么能火：它不是一个具体功能开关，而是一套面向 AI 编程助手的“技能包体系”。这篇内容，我按实际使用顺序来写：先讲它到底是什么，再讲怎么装，怎么用，怎么结合 Java 项目做定制，最后是我踩过的一堆坑。想入坑的朋友可以直接照着我这条路径走。
1.1 从一次 AI 写代码翻车说起
在展开 superpowers 之前，得先还原一下我遇到的典型翻车现场。需求很简单：给现有用户模块加一个“修改密码”的接口。这种任务对 AI 助手来说算很常规了。我把它描述清楚，提交给它。前几步看起来都很正常，生成了 controller、service、mapper，甚至顺带把异常处理也写好了。但越往后越不对劲：它没有按项目里现有的参数校验风格来写，自己发明了一套返回结构；更麻烦的是，它完全没有跑测试，甚至没有检查原本的UserService里是不是已经有一个类似方法。我让它重新看一遍代码之后，它才说“确实已经存在，我改一下就好”。
这个翻车过程暴露出来一个问题：AI 助手本身不缺少生成代码的能力，它缺的是一个稳定的“工作流程”。人写代码时，会先看现有代码，再决定是新增还是修改，改完会编译、跑测试；但模型默认不会主动做这些事。你如果不把流程写进提示词，它就会按最“顺”的路径走——直接生成一段看起来差不多的代码。superpowers 解决的就是这个：把“先探测、再计划、后实现、必须测试”这类工作方法固化成一个个技能文件，让模型在任务开始时先调用技能，按技能里定义的步骤走。哪怕每一步看起来平平无奇，组合起来以后，整个行为就稳定得多。
1.2 技能包是怎么运转的
superpowers 的核心机制，说穿了一点都不神秘。它的主体是若干 Markdown 文件，每个文件描述一个“技能”。技能文件通常带 YAML 格式的头信息，里面写技能名称和描述；正文则是一段完整的操作流程，有时还会附带脚本。模型在与用户交互时，会根据当前任务的性质，去匹配技能描述，选中对应技能后，把技能内容当作高优先级指令来执行。
可以把它理解成给厨师一本菜谱：AI 助手不是一条狗，你给不给他“先放油再下锅”的随机提醒，它都能做菜，但做出来的东西是否稳定，完全看有没有标准化的流程。技能包的价值不是让模型变聪明，而是把“这次碰运气”变成“每次按固定套路来”。在 superpowers 之前，我试过把自己的工作规范写成一段很长的系统提示词，塞进每个新对话里。那样做有效，但很难维护，提示词一长，模型就开始“选择性忽略”，甚至把不相关的规则也套用。技能包的方式是把规则拆开，按任务类型触发，每次只加载当前需要的那一份。这样指令更聚焦，指令被“无视”的概率也小很多。
1.3 和普通 Prompt 的本质区别
很多朋友第一次听到 superpowers，会觉得这不就是“更长的 Prompt 吗”。不少技能文件确实读起来像 Prompt，但它们的形态和作用有本质区别。我做了一张对比表，看完应该就明白了：
| 对比维度 | 普通 Prompt | superpowers 技能 |
|---|---|---|
| 生命周期 | 当前对话窗口内一次性生效 | 独立文件，随时复用 |
| 触发方式 | 每次重新描述一遍 | 用技能名调用，或由模型按描述自动选择 |
| 流程控制 | 靠模型自由发挥 | 拆成明确步骤，带检查点和验收标准 |
| 调试方式 | 无法追踪哪段提示引发了问题 | 每个技能文件可单独 review、改版 |
| 团队协作 | 复制粘贴进聊天记录 | 入库 Git，走 Code Review 合并 |
我自己的体验是：普通 Prompt 适合一次性小任务，比如“帮我把这段 JSON 转成 Java 类”；superpowers 这种技能包适合高频且必须保证顺序的任务，比如测试驱动开发、代码审查、改动需求落地。它把“方法论”从对话里抽出来，变成工程资产。以前新人来了要翻聊天记录学流程，现在直接读技能文件就行。
2. 安装与初始化：我实测过的操作路径
安装 superpowers 的过程网上说法很多，有些教程写得特别复杂，又是配环境变量，又是改权限。我实测下来其实没那么夸张，关键是搞清楚它到底装了什么。下面是我在 Mac 上完整跑通的安装步骤，以及我在 Windows 用户那边收集到的典型问题。
2.1 环境准备：先确认三件事
在跑安装命令之前，先花两分钟检查环境。千万不要安装到一半发现基础工具缺失，再回头折腾。需要确认的地方有三个：
- Node.js 版本最好在 18 以上。直接执行
node -v看版本号，如果低于 18，建议先升级，否则后面有些脚本跑不起来。 - Git 装了没有。执行
git --version，没有输出就需要先安装。 - 网络环境是否顺畅。这里要特别提一句：git clone 是从 GitHub 拉代码，如果网络不稳定，很容易出现“下载到一半卡死”或者
RPC failed的情况。我踩过一次，代码拉了 200MB 左右直接断掉，重新 clone 才解决。
还要注意一点：如果你的终端里有多个 shell 配置文件，比如同时存在.zshrc、.bashrc，superpowers 的安装脚本通常只会改当前正在用的那一个。我建议安装前先执行echo $SHELL确认你当前用的是 bash 还是 zsh，避免装完换个终端就找不到命令。
2.2 安装步骤：克隆、执行、验证
环境检查没问题之后，打开终端，依次执行下面的命令。以安装到用户目录下的superpowers文件夹为例：
git clone https://github.com/your-repo/superpowers.git ~/superpowers cd ~/superpowers ./install.sh注意仓库地址要替换成官方实际提供的地址。我这里刻意不写死完整 URL，是因为 superpowers 相关的派生仓库很多，不同作者维护的版本在细节上会有差异，最好去项目主页复制官方地址。
这个install.sh大概会做三件事：把技能文件复制到 AI 工具的默认技能目录；把可执行命令写入 shell 配置；生成一个用户级配置文件，方便后续自定义。整个过程通常几十秒就完成了。
安装完成后，重启终端，然后验证一下：
superpowers status如果没有报“command not found”，说明安装成功。如果提示找不到命令，先不要急着重装，检查.zshrc或.bashrc尾部有没有多出 export 的路径。常见原因是你开了多个终端窗口，新窗口没重新加载配置。手动执行一下source ~/.zshrc再试。
2.3 安装阶段最容易踩的三个坑
我帮几个朋友排查过安装问题，总结下来高频出问题的主要是这三个点：
第一，在 Windows 上直接用 PowerShell 跑.sh脚本。这个基本必挂，因为脚本里会有软链、export这类 Unix 命令，PowerShell 语法不一致。建议优先用 Git Bash 或 WSL，如果只能用 PowerShell，也要先调整执行策略为RemoteSigned，再用bash ./install.sh的方式调用，而不是尝试直接双击运行。
第二，安装目录带空格或中文。有些用户喜欢把代码放在C:\Users\我的文档\Code这类路径下。技能文件加载时，很多 AI CLI 工具对路径中的空格和中文处理得并不好，会出现“技能明明装了，但模型读不到”的症状。我建议把 superpowers 放在一个纯英文、无空格的路径下，省掉后面一堆麻烦。
第三，安装脚本改坏 shell 配置。因为脚本会自动向配置文件中追加路径，如果它判断失误，可能在你原有的alias、环境变量里插入重复内容。我自己的习惯是：安装前先复制一份.zshrc备份，万一出了问题还能回滚。这不是 superpowers 特有的问题，所有自动修改 shell 配置的安装工具都一样，备份永远是对的。
3. 核心用法：把“聊天式编程”改成“流程式编程”
安装只是开始，真正有意思的是使用方式。superpowers 和普通 AI 助手最大的体验区别在于：它鼓励你不要直接丢需求，而是先“调技能”，让技能去驱动你和模型的对话。这一节我讲几个最常用的技能，再给一条完整的工作流示例，最后说一下 Codex 集成时的注意点。
3.1 最常用的几个技能
superpowers 自带的技能集在我的项目里高频使用的有这几个（名称可能随版本调整，但作用范围是稳定的）：
| 技能名称 | 适用场景 | 核心作用 |
|---|---|---|
| brainstorming | 需求还算模糊，需要先聊清楚 | 通过提问清单收集约束条件，避免模型一上来就写代码 |
| plan | 需求明确，但实现路径风险高 | 先生成改动方案，列出影响面，再动手 |
| test-driven-development | 实现类功能 | 强制先写失败测试，再写实现，再重构 |
| code-review | 完成一段代码后自查 | 按规范逐项检查代码质量，输出问题清单 |
| debugging | 测试失败或线上报错 | 先定位根因，再给修复建议，禁止直接乱改代码 |
我自己用得最多的是test-driven-development和code-review。前者解决“没测试就写实现”的老毛病，后者解决“写完一堆代码没人把关”的问题。如果你是第一次尝试，我建议先只用一个技能来跑一个简单的需求，不要同时挂好几个，否则体验上会有明显的“割裂感”。
3.2 一条完整工作流示例
我拿一个真实需求举例：“给订单模块增加导出功能”。如果直接丢给普通 AI 助手，它大概率会在一个回复里把 controller、service、Excel 工具类全部写出来，中间没有任何确认。用 superpowers 的方式，过程就不一样了。
第一步，我会说：
调用 brainstorming 技能，帮我分析“订单导出”这个需求。模型会先抛出几个问题：导出格式是 Excel 还是 CSV？数据量大概多少？对导出结果有没有权限要求？是否需要异步处理？这些问题不是它凭空想的，而是技能文件里定义好的检查清单。这一个动作，就避免了“需求都没对齐就开写”的尴尬。
第二步，回答完问题之后，我输入：
调用 plan 技能，生成本次改动方案。它会列出新增文件清单、改动文件清单、影响范围、风险点。我把方案发给同事看一眼，确认没问题再继续。
第三步，动手实现：
调用 test-driven-development 技能实现导出功能。这时候模型才会开始写代码。它先写一个测试，运行一次看它失败，再写实现代码，等测试通过后再做重构。我在旁边只需要看它执行的命令和输出结果。
整条流程走下来，给我的感觉是：我不是在和 AI 对话，而是在“指挥”一套装配流水线。每一段都有验收点，每一段都可以单独喊停。项目越复杂，这套方式的优势越明显，因为它把开发过程拆成了可控的节点，而不是一次性生成一坨代码。
3.3 与 Codex 集成时要注意什么
热搜词里有一个“codex superpowers”，有必要单独说一下。Codex CLI 是 OpenAI 系模型在终端里的入口，superpowers 的技能机制同样可以作用到 Codex 上。只要把技能文件放到 Codex 能读取的目录，然后在对话里用技能名触发即可。比如：
codex exec "调用 test-driven-development 技能，为 PaymentService 的退款方法补充测试"但实测下来，同一个技能在不同模型上的“听话程度”是有差异的。Claude 系模型对长流程和步骤的执行更稳定，Codex 在同一个 TDD 循环里，偶尔会跳过“先看到测试失败”这一步，直接进入实现。遇到这种情况不用太纠结，把它当成模型的风格差异即可，你可以在技能描述里追加一句“不要跳过运行测试并观察失败结果”来强制校正。简单说，技能是通用的，但调教是每个模型都需要做一遍的。
4. 在 Java 项目里落地 superpowers：一次 Spring Boot 实践
前面讲的都是通用用法，接下来是我觉得最有价值的部分：把 superpowers 用进 Java 后端项目。为什么单独拿出来说？因为通用技能是“不分语言”的，但真实项目总有技术栈约束，比如 Java 项目要区分 Maven 和 Gradle、JUnit 5 和 TestNG、Controller 层的返回结构等。如果不做定制，技能就只能在“大类流程”上发挥作用，落不到你项目的具体约定上。这一节我就用 Spring Boot + Maven + JUnit 5 的组合，演示一次定制过程。
4.1 为什么通用技能在 Java 项目里会“失灵”
我最初直接拿默认的 TDD 技能去跑一个 Spring Boot 接口开发任务。技能的逻辑我认可：先写测试、再看失败、再实现、再重构。但它生成的测试类用的是默认的 JUnit 4 风格，而项目里是 JUnit 5；它还不认识项目里已有的Result统一返回类，导致测试断言里写了一大堆它自己定义的返回结构。技能流程没错，错在流程里的“操作细节”没有和项目对齐。
这个问题本质上和“新同事入职”很像：方法论可以通用，但项目私有约定必须单独培训。superpowers 的自定义技能体系，就是用来做这个培训的。你不用改它自带的通用技能，只需要在自定义技能里覆盖项目细节就行。
4.2 自己写一个 java-spring-tdd 技能
在自定义技能目录下新建一个文件，比如叫java-spring-tdd.md。内容我贴一个精简版：
--- name: java-spring-tdd description: 在 Spring Boot 项目中进行测试驱动开发。使用 JUnit 5 和 Maven Surefire。当 Java 后端的 Service、Controller 或 Repository 需要新增功能或修改逻辑时使用。 --- 步骤说明： 1. 先阅读 pom.xml，确认项目依赖；如果项目使用 Gradle，则阅读 build.gradle。 2. 根据业务包名，在 src/test/java 对应目录下创建测试类。 3. 测试类统一使用 JUnit 5（org.junit.jupiter.api.Test），断言使用 Assertions。 4. 对于 Web 层使用 MockMvc，对 Service 层使用 Mockito 模拟依赖。 5. 编写一个会失败的测试，运行 mvn test -Dtest=你新建的测试类。 6. 观察到失败结果后，再开始编写实现代码。 7. 实现完成后重新运行测试，直到全部通过再做重构。 8. 重构过程中持续运行 mvn test，确保任何一步都不会破坏已有功能。注意开头的name和description字段。模型判断什么时候该用这个技能，主要就看description里有没有匹配到当前任务的关键词。我特意写入了“Spring Boot”“Java”“Service”“Controller”“Repository”，就是为了让模型在这类任务出现时能自动选中它。如果你团队的包名有特殊前缀，建议也写进描述里，召回率会更高。
4.3 实测一个“用户注册接口”开发
有了上面的java-spring-tdd技能之后，我再丢同样类型的需求，流程就顺了很多。我在一个 Spring Boot 2.7 项目里试过“用户注册接口”。任务提交后，模型首先读了一遍pom.xml，确认是 Maven 项目，再去src/main/java里看了现有的User实体和UserRepository。然后它没有直接写实现，而是先建了一个UserServiceTest，用 Mockito 模拟 Repository，写了一个会失败的测试。执行mvn test -Dtest=UserServiceTest，输出一片红色。接着它才开始写UserService的实现代码，修到测试变绿。
整个过程没被我打断过一次。对比之前直接用普通提示词，最大变化是：它不会“跳步”了。过去经常出现的情况是“代码一次性生成完毕，结果编译都过不去”，现在它把验证拆进了每一步里，错误的成本被压到最小。
这里再提醒一句：临时把技能描述写得很详细，不等于一劳永逸。如果你后面换了 JDK 版本、从 Maven 切到 Gradle、或者把测试框架从 JUnit 5 换成了 TestNG，技能文件也要跟着更新。技能是活文档，不是写完就不管的。
5. 实操踩坑记录：按症状、原因、解法整理
我用了大约三周，中间翻过不少车。这一节我把遇到过的问题按“症状、可能原因、处理方法”的格式整理成表，方便你直接对照排查。每一个问题我都在项目里实际遇到过，不是从文档里抄出来的。
| 症状 | 可能原因 | 处理方法 |
|---|---|---|
| 我明确说了“调用某技能”，模型却说没有这个技能 | 技能目录放错了，或者文件名和name字段不一致 | 检查技能文件所在目录，确认 frontmatter 中name与实际文件名对应 |
| 技能内容被读了，但模型执行到一半偏离流程 | description太短，模型没有理解技能的约束力 | 尽量写详细的描述，用祈使句强调关键步骤，比如“必须”“先”“再” |
| 上下文越来越长，token 消耗翻倍 | 一下子加载了过多技能文件，模型把无关技能也读进来了 | 不要把所有技能都放在默认加载目录，只在需要时显式调用 |
| 模型自动执行了破坏性命令，把文件删了 | 权限没有限制，默认允许了所有工具调用 | 调整 CLI 工具的权限模式，改成需要人工确认后再执行 |
| 官方更新后，我自定义的技能被覆盖了 | 自定义技能和上游文件放在同一个目录，更新时合并冲突 | 把自己的技能单独放一个目录，和官方技能区分开 |
git pull之后，命令直接失效了 | 版本升级，命令名或配置文件路径发生了变化 | 升级后先看官方 Changelog，再重新执行一遍安装脚本 |
5.1 技能识别不出来？先查name和文件名
我遇到过最诡异的一次：模型一直说“找不到技能”，但我确认技能文件就在目录里。后来发现，文件名是java-spring-TDD.md，而 frontmatter 里的name写的是java-spring-tdd。在某些实现里，模型是靠目录扫描加 frontmatter 匹配的，文件名和name不一致，匹配时就会掉链子。我当时的解决办法是：参数统一命名。
5.2 上下文管理：不要把你所有的技能都挂上去
技能包一多，我一开始觉得每个技能都很有用，索性全部放在加载目录里。结果对话长度以肉眼可见的速度膨胀，输入 token 费用也涨得厉害。最亏的是，很多技能在本次任务里根本用不上，白白挤占了上下文空间。经过一段时间的观察，我发现最佳实践是：只保留几个高频核心技能在自动加载目录，其余的都收进“按需调用”的清单里。
5.3 权限控制不是小事
superpowers 会授权模型执行 bash 命令，这是它能自动跑测试的基础。但如果权限不设限制，模型真的可能误删文件。我在一个实验中让它重构工具类，它直接把旧文件rm了，好在有 Git 历史才找回来。后来我把 CLI 工具的执行权限改为“每次执行命令前必须先询问”，并且把rm -rf这类高危命令明确禁止。权限松一点是为了效率，但破坏性操作必须加保险栓。
5.4 升级官方的“姿势”
superpowers 的更新频率不算低。我一开始图省事，直接git pull，结果和本地自定义技能产生了文件冲突，一堆CONFLICT标出来，看起来非常头疼。后来我学聪明了：把自己的自定义技能全部挪到独立目录，和官方内容隔离；更新的时候只更新官方部分，自己的目录不动。这样既拿到了新技能的修复，也不用担心旧配置被冲掉。
6. 自定义技能：把团队规范固化成代码
到了进阶阶段。如果你已经用了 superpowers 一段时间，大概率会想写自己的技能。这件事做对了，收益极大：团队里散落在文档和口头约定里的“潜规则”，可以全部变成 AI 助手可执行的技能。做错了，则会产生一堆互相冲突的“伪技能”，反而拖累效率。
6.1 技能文件的目录结构和启用规则
在我的电脑上，技能目录结构大致是这样的：
~/.superpowers/ ├── skills/ │ ├── official/ # 官方技能，更新时只动这里 │ ├── team/ # 团队自定义技能，独立目录 │ └── personal/ # 个人私有技能 ├── config.yml # 用户级配置 └── logs/official、team、personal这个三个目录是我自己划分的，官方没有强制要求。但分目录管理的价值在于升级时互不干扰。你只需要在配置里把team和personal目录注册进去，模型就能读到。
6.2 一个最容易落地的自定义技能：代码审查
代码审查技能特别适合做成自定义技能，因为每个团队的审查标准都不一样。比如我们团队要求：所有返回结构必须统一走Result类；Service 层禁止直接操作 HttpServletRequest；新增 OpenAPI 文档注解等等。写成技能后，每次代码写完后，直接让模型走一遍审查流程。
下面是我团队实际用的一段简化版：
--- name: team-code-review description: 对 Java 后端代码进行团队规范审查。当代码完成且需要合并前使用。检查统一返回结构、分层规范、异常处理和命名规则。 --- 1. 先阅读项目目录结构，定位本次新增或修改的 Java 文件。 2. 对照下面的规则逐项检查： - Controller 返回类型必须使用 Result<T> 统一结构，禁止直接返回 Map。 - Service 层禁止依赖 HttpServletRequest / HttpServletResponse。 - 所有外部调用必须处理异常，禁止吞掉异常后继续执行。 - 新增的对外方法必须有 OpenAPI 注解，描述含义。 3. 输出审查结果，按“严重错误 / 建议修改 / 可忽略”分类。 4. 对每一项问题给出文件路径和行号，并附修改示例。这个技能的效果，远比我们把规范写成一份几十页的 Wiki 文档要好。因为 Wiki 是给人看的，AI 助手不会主动去翻；技能是直接注入到工作流里的，到了该用的时候它就会被加载。
6.3 什么时候该写自定义技能？两个判断标准
自定义技能也不是越多越好。我自己有一个判断标准，两条都满足，才值得写：
第一，这个任务出现的频次足够高。如果一个任务一个月才出现一次，写技能花的时间可能比直接手动干还要长。
第二，任务的执行顺序必须固定。如果每次做的时候流程都会大变，技能的作用就打了折扣。
比如“部署上线”流程虽然一个月可能只出现一次，但步骤极其固定，就不能全靠手工，必须技能化。反过来，“帮我把这段代码翻译成 Python”这种一次性散活，直接一条 Prompt 就搞定了，没必要做成技能。
6.4 技能维护的“度”
技能数量变多以后，要避免一个倾向：把所有做事习惯都技能化。我见过一些朋友，技能文件写了一百多个，结果是模型在自动选择时频繁误报，经常点错技能。原因是新技能和已有技能描述里的关键词冲突了。技能系统本身是“按描述匹配”，不是“按目录分类”，描述写得越多，互相干扰的概率就越大。我的做法是：描述里尽量写“这个技能管什么”，而不是写一大堆“这个技能不管什么”。维持每个技能的边界清晰，比堆数量重要得多。
7. 用完之后的一些个人体会
把 superpowers 用进日常工作之后，我对“AI 编程”这件事的看法变了一点：真正拉开体验差距的，往往不是模型生成代码的质量，而是流程本身是否可靠。骨架搭得越清晰，模型的发挥越稳定；流程模糊的时候，哪怕是同一个模型、同一个需求，结果都可能天差地别。
现在我带新人用这套工具，很少让他们跟着聊天记录学，而是让他们先把 TDD 技能的流程读熟，再用真实 Ticket 走一遍。过去培训一个新人上手团队规范，最快也要两三天；现在技能文件写清楚之后，新人的工作状态第一天就能像老手一样稳定。这也让我意识到，superpowers 能做的远不止“给 AI 加技能”，它其实是把团队多年积累的工作经验，从人脑里、Wiki 里，搬进了 AI 助手可以直接执行的格式里。
说到底，所谓“超能力”，不是让 AI 一步登天，而是把开发者本来就应该遵守的流程，从“靠自觉”变成“靠机制”。如果你正在被长对话失控、代码不做测试、模型自己乱改结构这些问题困扰，找个周五下午，把它装上，挑一个小需求完整走一遍。试完你大概也会同意：真正值钱的不是那一串命令，而是终于有办法让 AI 助手按你认定的方式干活了。
