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但它们的形态和作用有本质区别。我做了一张对比表看完应该就明白了对比维度普通 Promptsuperpowers 技能生命周期当前对话窗口内一次性生效独立文件随时复用触发方式每次重新描述一遍用技能名调用或由模型按描述自动选择流程控制靠模型自由发挥拆成明确步骤带检查点和验收标准调试方式无法追踪哪段提示引发了问题每个技能文件可单独 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、.bashrcsuperpowers 的安装脚本通常只会改当前正在用的那一个。我建议安装前先执行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 5org.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 -DtestUserServiceTest输出一片红色。接着它才开始写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 返回类型必须使用 ResultT 统一结构禁止直接返回 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 助手按你认定的方式干活了。