1. Superpowers 究竟是个什么项目如果你最近混迹在 AI 编程社区的讨论区应该会频繁刷到superpowers这个热词。它不是某个超级英雄电影的周边而是一套非常有想象力的开源技能包专门用来给 AI 编程助手“开外挂”。最早我看到这个名字的时候第一反应是“又一个花哨的插件”但实际跟完整个项目之后我发现它对 AI 协作开发这件事的理解确实比普通提示词工程要高一个层次。简单来说Superpowers 是一组结构化的“技能”文件每个技能对应一种特定的编程能力比如“写单元测试”“做架构规划”“审查代码”“处理调试”等等。这些技能并不是简单的几百字提示词而是一整套带流程、带步骤、带输出格式的“操作手册”。AI 助手加载这些技能之后就能像一位老练的工程师一样按照固定的方法论去执行任务而不是每次对话都靠模型临场发挥。适合谁来用呢第一类是已经在使用 Codex、Claude Code 这类命令行 AI 编程工具的人你大概率会遇到同一个问题模型确实能写代码但遇到复杂任务时它经常东一榔头西一棒子思路不够系统。Superpowers 就是来治这个毛病的。第二类是团队里需要统一 AI 协作流程的人把技能包放进仓库整个团队用同一套“打法”让 AI 干活效率和质量都会明显稳定下来。我自己的感受是这套东西真正解决的不是“AI 不行”而是“AI 太飘”。你让它直接写一个支付模块它可能洋洋洒洒写出一堆代码但你要是给它一个带明确步骤和验收标准的技能它会老老实实按步骤来每一步都检查明白再往下走。本篇我就把安装、配置、Java 实战以及我自己踩过的几个坑全部梳理一遍。2. 核心设计思路与能力矩阵拆解2.1 为什么“技能”比“提示词”更可靠我先说一个很多人没意识到的点单个提示词在 AI 对话里是“一次性”的而技能是“可复用”的。提示词写得再好下次新开一个会话你又要重新组织语言说明背景、指定目标、规定格式……非常累而且每次语气和完整度都有偏差。Superpowers 的设计是把这一整套指令固化成一个 Markdown 文件AI 每次调用技能的时候其实是把这个文件当成“工作手册”来读手册里写清楚了每一步该做什么、产出什么格式、避免什么禁忌。打个比方你带一个刚入职的实习生你口头交代“帮我看看这个代码哪里有问题”他可能随便扫一眼就乱说。但你要是给他一张《代码审查检查表》上面列着“先核对空指针风险”“再检查资源是否关闭”“最后确认并发安全”他就会按表执行产出自然稳定得多。Superpowers 干的就是这件事给 AI 发一张张检查表。从技术实现上看每个技能通常是一个独立的 Markdown 文件文件头部带有name、description、when_to_use这类元信息正文则分为多个阶段phase每个阶段里又有具体动作和输出要求。AI 在对话中根据用户的请求判断哪个技能匹配当前任务然后自动加载并执行。这种“触发器 结构化流程”的机制就是把不可控的模型发挥变成可控的工程流程。2.2 能力矩阵一套完整的工程方法论我在实际使用中整理了一下Superpowers 的核心技能基本覆盖了软件开发的全部生命周期既包括写代码前的规划也包括写代码后的验证。这里列几个我认为最重要的方便后面实战演示时对照着理解。规划类技能比如制定实现方案、拆解功能点、评估技术选型。这类技能通常要求 AI 先问清楚需求和约束条件再输出多阶段实施计划而不是一上来就写代码。它做的是“从 0 到 1”的事。实现类技能包括测试驱动开发TDD、编写通用代码、实现具体功能模块等。TDD 技能特别有意思它会强制 AI 先写失败测试再写实现代码最后跑通测试顺序一步都不许乱。审查类技能代码审查、架构审查、安全检查。这类技能会把审查步骤拆成明确清单比如“先看数据流”“再查错误处理”“最后评估可维护性”AI 按清单逐项检查并输出报告。调试类技能针对 bug 的定位与修复。它包含一套标准的调试循环复现问题、缩小范围、提出假设、验证假设、修复、回归测试。这套流程特别适合那些“AI 修了一个 bug又引入三个新 bug”的灾难现场。文档类技能生成 README、代码注释、API 文档、变更日志。它会约定文档的目标读者和格式规范避免 AI 生成那种看起来很专业但全是废话的文档。这套能力矩阵的思路其实非常清晰把高级工程师脑子里那套“遇到代码任务先规划、再实现、再验证”的思维过程拆成 AI 能读懂的指令文件。你不需要跟 AI 一遍遍强调“先测一下”“注意边界条件”它自己就知道该这么干。2.3 技术原理细节AI 是如何“执行”技能的在深入安装之前有必要搞清楚一个关键机制AI 执行技能时并不是真的像插件系统那样拦截 API 调用而是通过上下文注入的方式工作。当你向 AI 助手发出请求时工具会根据你的消息内容从已安装的技能目录中检索最匹配的技能然后把整个技能 Markdown 文件嵌入到对话上下文里再让模型按照这个上下文里的指令做事。这里有个值得注意的点每个技能文件的大小不能太大。因为 AI 的上下文窗口是有限的技能文件越大留给对话和代码的空间就越小。Superpowers 里每个技能一般控制在一个合理的长度内步骤写得非常精炼每一条指令都足够明确不会用一堆冗余的解释浪费 token。这个设计在实操中明显能感觉到加载了技能之后AI 的响应并没有变得拖泥带水反而因为目标明确回答更干脆。另外一个机制是技能之间的引用。有些复杂技能会引用其他技能比如“代码审查技能”可能会引用“安全清单技能”。这种组合方式有点像是把大的方法论拆成原子模块需要的时候再拼装起来。我在使用中发现当技能出现嵌套引用时AI 反而更不容易遗漏步骤因为它会严格按照参数里指定的路径去加载引用的文件。3. 安装与基础配置从零到一跑通3.1 前置环境检查与依赖准备在动手安装之前先把基础环境捋清楚。Superpowers 本质上是给命令行型 AI 编程工具用的所以你得先有一个主程序。目前社区里最常用的是 OpenAI 的 Codex CLI也有不少人在 Claude Code 里用两者加载技能的方式大同小异都是把技能文件放进指定的目录即可。我以 Codex 为例来讲安装流程因为你在搜索词里提到了codex superpowers大概率是准备在这个环境里用。首先确保你已经安装并配置好了 Codex 本身并且本地有 Node.js 运行环境。不需要额外的数据库不需要注册服务它就是一个纯文件系统层面的配置过程这一点非常友好。另外如果你完全是个新手对命令行工具不太熟请务必先把路径概念搞清楚。技能文件本质上就是一堆 Markdown 文档放在规定的目录下AI 工具启动时会扫描这些目录。目录放错了技能就会静默失效这个问题我后面在常见问题里会重点讲。3.2 下载技能包与目录结构解析Superpowers 的项目在 GitHub 上开源获取的方式一般是直接克隆仓库或者打包下载。你可以在项目文档里找到仓库地址在本地终端执行git clone https://github.com/ 你的技能包地址/superpowers.git克隆完成后你会在superpowers目录下看到类似这样的结构superpowers/ ├── skills/ │ ├── plan-a-feature.md │ ├── implement-tdd.md │ ├── review-code.md │ ├── debug-an-issue.md │ └── ... ├── LICENSE.md └── README.md关键就是skills目录里面每个.md文件就是一个技能。你不需要修改这些文件的内容只需要把它们变成本地 AI 工具能扫描到的位置。对于 Codex通常是把skills目录里的内容复制到 Codex 的技能目录下比如~/.codex/skills/不同版本可能路径有细微差异。如果你看到项目文档里提到“将该目录软链到你的 AI 工具配置目录”那说明它支持直接创建符号链接这样以后更新技能包只需要git pull一次非常方便。我再提醒一个细节技能文件的文件名在调用时往往关联到技能名称所以不要觉得文件名不好看就随便重命名。前面我提到的技能元信息里其实已经有name字段但很多 AI 工具在加载时仍然优先依赖文件名索引。保持默认名称最稳妥。3.3 在 Codex 与工作台工具中加载技能技能文件放好后并不是所有工具都会自动识别你通常需要修改一下工具的配置文件。以 Codex 为例你需要在项目根目录或者用户配置目录下的配置文件中增加技能目录的引用。具体配置项可以在 Superpowers 的 README 里找到标准写法一般格式如下{ skills_dir: ~/.codex/skills }如果你是通过 Worbuddy 这类工作台工具来使用 AI 编程那么加载方式又会不太一样。Worbuddy 这类工具通常提供了一个可视化的技能管理界面你可以在“设置”或者“技能商店”里选择导入本地技能包。搜索词里有worbuddy 怎么用 superpowers我在这里统一给一个思路与其在界面里干找导入入口不如先确认 Worbuddy 的技能目录路径然后把skills下的文件复制过去再重启工作台。大多数这类工具的原理都是扫描特定目录复制进目录就等价于“导入成功”。配置完成后随手测试一下。你可以新建一个会话随便问一句“你现在有哪些技能可以用”正常情况下AI 会报出一串它已加载的技能名称。如果它一个技能都报不出来说明目录配置大概率有问题。如果报出的名称和skills目录里的文件名对得上那安装就成功了接下来就能进入实战环节。3.4 验证安装用会话测试技能调用能力正式开工前我强烈建议你用一个小任务测试技能调用是否正常。比如你可以对 AI 说“请使用 review-code 技能帮我检查下面这段函数的错误处理”。然后给出一段包含空指针隐患的代码。这里关键不是看它能不能指出 bug而是观察它的行为“变没变”它是否主动列出审查步骤它是否在输出里使用了已检查项、风险等级这类结构化字段它是否输出了完整的审查结论而不是一两句话敷衍了事如果以上都是肯定的说明你之前配置的技能真的生效了。这一步非常值得做很多人在安装后直接开始正常聊天根本不知道技能到底有没有加载成功。我自己的几十次实操表明测试这一步能筛掉至少一半的配置问题。4. Java 项目中的实战应用4.1 场景选型拿到需求怎么挑技能很多读者会问Java 项目用 Superpowers 有什么特别之处吗只要对照场景你会发现 Java 项目对“流程规范”的要求其实更高。因为 Java 是强类型语言编译阶段就能拦住一部分错误再加上 Maven/Gradle 这种构建工具的介入每一步操作都有严格的先后关系。如果你让 AI 直接写代码它给出的代码往往编译不过还得来回改。这时候按技能规定的流程走就能省掉大量反复试错的环节。假设现在有一个需求给一个 Spring Boot 项目新增一个用户注册接口要求包含参数校验、异常处理和单元测试。我会在会话里给 AI 下这样的指令“请使用 plan-a-feature 技能来规划用户注册接口的实现”然后补充关键约束框架版本、参数校验规则、代码风格。选技能不是越多越好而是挑“控制粒度最合适”的那一个。计划类技能管全局TDD 技能管实现审查类技能管收尾。如果你一上来就让 AI 直接用 TDD 技能写代码它可能会缺少全局设计容易在接口路径命名和异常处理策略上乱发挥。我的经验是大功能先规划后实现小功能直接 TDD写完再审查。4.2 实战一用 TDD 技能开发用户注册接口我把一次典型的 Java 实战过程记录在这里你可以直接照猫画虎。会话启动后我给 Codex 发送以下指令请使用 implement-tdd 技能为 Spring Boot 项目实现用户注册接口。 需求 - 接收 username, password, email 三个字段 - username 不能为空长度 3-20 - password 不能为空长度 6-32 - email 格式必须合法 - 用户名重复时抛出业务异常 使用项目已有的统一异常处理。接下来AI 激活了implement-tdd技能它的行为就变得非常规律第一步它没有急于写实现代码而是先列出了自己将要遵循的流程写失败测试、运行测试确认失败、写实现代码、运行测试确认通过、重构。第二步它先写了一个UserRegistrationTest测试类包含空用户名、密码过短、邮箱格式错误、用户名重复这几个用例。这里我特别注意了一下它确实先调用了断言而这些断言对应的类和接口都还不存在所以测试阶段编译就会失败。这就是 TDD 技能的核心让 AI “故意”先写失败代码。第三步它才开始创建UserService、UserRepository、UserController和ValidationError等实现代码。因为测试已经定义了调用方式实现代码只需要“把测试变绿”所以接口设计非常克制没有多余方法。第四步它自己执行了测试命令并且把结果反馈到对话里。如果测试没过它会继续回到实现阶段修改代码直到全部通过才结束。这个实战过程给我最大的触动是AI 的产出不再是“一坨能跑但没人敢碰的代码”而是“一套包含验证用例的可交付代码”。作为 Java 开发者你在 review 的时候不再需要担心它漏掉了边界条件因为测试用例替你把这些边界都覆盖到了。4.3 实战二代码审查技能排查隐患完成 TDD 开发之后代码已经能跑通测试了但别急着提交。这时我会再调一个review-code技能对整个修改做一次全面审查。在会话里输入请使用 review-code 技能审查当前分支上用户注册功能的所有改动。 重点检查并发场景下用户名重复的竞态条件、事务边界、密码是否明文存储。AI 启动审查技能后会按预置步骤逐项检查。它先梳理了数据流Controller 接收参数 - Service 校验数据 - Repository 落库。接着检查并发问题它发现用户名重复检查存在“先查后插”的经典竞态条件即两个请求同时查到“用户名不存在”然后同时插入导致一条失败。它给出的建议是在数据库层面加唯一索引并用catch DataIntegrityViolationException兜底。它还检查了事务边界指出当前的 Service 方法虽然注了Transactional但异常处理逻辑可能会吞掉回滚信号建议在捕获异常后重新抛出运行时异常。另外它明确提示了密码字段应该使用 BCrypt 加密后再入库而不是直接存明文。这个结果一下就把代码质量抬升了一个台阶。我自己的体会是如果没有审查技能AI 也会主动提醒一些问题但通常提醒得很零散。而技能驱动下的审查是系统性的、有既定检查项的覆盖面和深入度完全不同。4.4 Java 构建环境下的注意事项在 Java 项目里使用 Superpowers有几个环境相关的细节我在实战中踩过这里提出来供你参考。构建工具选择和技能无关但会决定技能执行效率。如果项目用 Maven技能执行测试时常用mvn test用 Gradle 则是./gradlew test。你最好在项目配置文件中明确写出构建命令否则 AI 可能默认执行错误命令导致测试失败。JDK 版本影响代码生成结果。Java 8、Java 11、Java 17 之间的 API 差异很大AI 默认可能会生成比较新的语法特性。你需要在技能调用时或者项目配置里写明 JDK 版本比如“项目使用 Java 17请勿使用 Java 8 过时 API”。框架特定约束要写得具体。Spring Boot 里非常讲究分层规范Controller 不该包含业务逻辑Service 不该直接操作数据库Repository 不该返回实体对象而应返回 DTO。这些约束如果你不写进配置AI 生成的代码可能分层混乱。我通常会在项目配置中追加一条“遵守 Spring Boot 分层规范禁止跨层调用”。测试框架版本匹配。Java 生态的测试框架JUnit 4 和 JUnit 5 的注解差异挺大技能在执行 TDD 时如果默认用了 JUnit 5而项目实际是 JUnit 4编译就会失败。项目配置里写明“使用 JUnit 5”或者“使用 JUnit 4”能有效避免这类问题。这些注意事项本质上是“给技能提供上下文约束”。技能本身是一套通用流程它不知道你的项目长什么样但你把环境信息喂给它它就能产出完全贴合项目的方案。这也是我认为 Superpowers 最值得称道的一点它不依赖内置的项目知识而是通过运行时配置把具体项目的血肉注入到通用流程骨架里。5. 常见问题与排查技巧实录5.1 “Worbuddy 怎么用 Superpowers”这类工具导入问题我在社区里见过很多此类提问比如搜索词里的worbuddy 怎么用 superpowers。这类问题的核心通常是用户还没搞清楚“Worbuddy 只是前端工作台技能是文件系统层面的东西”这个逻辑。我建议你按三步自查第一步找到 Worbuddy 实际使用的 AI 后端是什么。如果它内部封装了 Codex CLI那你只需要按我在第 3 章说的方式配置 Codex 的技能目录Worbuddy 重启后就会自动加载。第二步查看 Worbuddy 的配置目录有没有skills或plugins之类的文件夹。如果有直接把superpowers/skills下的文件复制过去。第三步如果以上都不行就在 Worbuddy 的输入框里直接问“你现在有哪些已加载的技能”通过 AI 的回答逆推它的加载路径。这类工具导入问题的本质90% 都是路径配置错位。请记住一个原则只要是命令行 AI 编程工具技能文件永远以“能被扫描到的目录”为最终有效位置界面上看不看得到是另一回事。5.2 技能不启用的几个常见原因技能文件明明放好了AI 却完全没有按技能走这是出现频率最高的问题。我排查过大量此类问题总结了几个主要原因技能目录配置未生效。有些工具配置修改后需要重启进程或者需要重新打开会话。不要只修改配置就继续聊天重启一次再测试。请求里没写技能名。绝大多数技能不是“自动唤醒”的而是需要你在指令里显式提到技能名称。比如直接说“请使用 implement-tdd 技能”AI 才会去加载。它不会因为你遇到 bug 就自觉加载调试技能。这个机制的优点是避免误触发缺点是你得了解技能名称。技能描述与请求匹配度太低。如果技能文件开头的description字段写得太泛AI 在判断“要不要加载”时容易犹豫。有些情况下你明明说了“写个单元测试”但技能匹配算法没找到对应的skill-name它就退化成普通聊天模式了。这种情况下明确写出技能名是最稳妥的。上下文被截断。当你同时加载了很多技能或者把技能文件写得很长AI 的上下文窗口塞满后部分技能内容会被截掉。轻则技能执行不完整重则直接忘记前置步骤。这是模型的技术限制只能通过精简技能文件或者减少同时加载的技能数量来解决。5.3 依赖安装与权限报错在安装 Superpowers 时可能会遇到 Git 权限问题或者依赖安装失败。我记得第一次安装时git clone仓库速度非常慢甚至直接卡住。一个比较有效的办法是检查本地网络是否正常同时确认 Git 仓库地址是否拼写正确。这类问题很基础却最浪费大家的时间。如果你在运行技能时看到 “command not found: step” 这类报错说明 AI 在执行技能文件里预设的命令时找不到对应的工具。你需要检查路径里是否已经安装了该工具并加入了环境变量。例如Java 项目里如果技能要跑mvn test但mvn不在环境变量里AI 就会报错。把 Maven 安装好并加入 PATH问题就解决了。还有一类权限问题是技能尝试修改文件但当前用户对该目录没有写权限。这在多用户系统或者容器环境下非常常见。解决办法是检查目录权限把技能目录的所有者改成当前用户或者用管理员权限执行一次chmod。我自己在 Docker 环境里就遇到过类似问题排查了半天才发现是文件挂载目录的权限不对。5.4 多个技能叠加时的冲突与优化进阶一点的用户不会满足于一次只用一个技能。比如你想让 AI“先用规划技能设计方案再用 TDD 技能实现最后用审查技能收尾”这在一个会话里连续切换技能效果怎么样我的实测是能跑但会有一定风险。核心风险在于前一个技能的输出可能会污染后一个技能的判断。规划技能输出的方案文档很长等到调用 TDD 技能时AI 还要分心去理解前面那几十行方案反而削弱了实现技能的执行力。我摸索出来的一个比较顺滑的做法是会话中只让一个技能负责主导。前面用普通对话把设计讨论清楚然后单独开一个新会话在干净上下文里调用实现技能。如果需要审查就再开一个会话调用审查技能。这样做避免了技能之间的上下文干扰每个技能都能从头到尾专注于自己的执行流程。如果你确实想在一个上下文里连续调用多个技能我建议你在不同技能切换时用一条非常明确的指令做标记比如“现在开始执行审查流程丢弃之前的实现细节只关注代码质量”。虽然模型无法真正“丢弃”但这句指令能把它从前面方案的具体约束里拉出来聚焦到新的流程上。实测下来这个技巧确实能让技能的切换更干净。6. 我对 Superpowers 的深度体验与自定义建议6.1 三个让我印象深刻的“反直觉”发现第一个反直觉的发现是技能越短AI 执行得越彻底。我一开始以为技能文件写得越详尽AI 越能面面俱到。但实测结果是技能文件一旦超过一定篇幅AI 在后续步骤中往往开始“偷工减料”因为它要处理的内容实在太多注意力被分散了。精悍的技能文件反而每一步都执行到位。这提醒我技能不是文档它更像“指令卡”每个字都要掂量过才放进去。第二个发现是显式写出技能名的成功率远高于依赖 AI 自动判断。很多技能包的介绍都说“AI 会自动选择合适的技能”但实际用下来自动调用的命中率确实不太稳定。我现在已经养成习惯在关键任务指令里直接点技能名比如“请使用 review-code 技能”绝不跟它含糊。这不是技能包设计不行而是模型对模糊意图的理解上限就在那里我们把意图说明白技能才能发挥出来。第三个发现是技能能显著降低“AI 胡编”的概率。以前让 AI 直接写一段复杂业务它经常在细节上自信地给出错误实现但一旦跑起带步骤的技能它在不确定的地方会停下来追问而不是硬编。这个变化特别微妙也特别重要。技能文件里那些写着“如果遇到 X 情况先确认以下前提”的提示实际上就是在训练模型“先想再做”的习惯。6.2 怎样动手编写自己的“超能力”如果官方技能包用熟练了你一定会有自己的想法比如“我们这个项目每次发版都要跑特定检查”“这个团队接口返回格式有统一规范”。这些内容非常适合沉淀成你自己团队的私有技能。实际上Superpowers 的最大价值不是那预先写好的几十个技能而是它提供了一套“给 AI 编写可复用方法论”的样板。自己写技能一点都不难核心是掌握好 Markdown 格式。下面这个例子是我给一个团队编写的“接口兼容性检查”技能骨架你一看就能明白--- name: check-api-compatibility description: 检查 API 改动是否破坏前后端兼容性适用于修改已有接口时。 when-to-use: 新增请求参数、修改响应结构、调整错误码时 --- # API 兼容性检查流程 ## Phase 1: 梳理改动范围 - 列出本次改动的所有接口路径 - 标记哪些是新接口哪些是修改已有接口 ## Phase 2: 逐项检查兼容性 - 检查是否删除了已有字段 - 检查是否更改了已有字段类型 - 检查新增字段是否设置了默认值 - 检查错误码是否被重新定义 ## Phase 3: 输出兼容性报告 - 输出不兼容项清单及影响范围 - 给出兼容建议如保留旧字段新增版本号这个技能的核心就是“检查表 产出报告”符合技能包的基本设计哲学。我写完之后放入技能目录重新加载 AI 工具就能直接调用。团队其他人如果把这个文件同步到他们的技能目录大家就拥有一套统一的兼容性检查标准了。自己写技能的时候有几个要点必须注意第一description一定要写得具体一点最好包含触发场景的短语比如“当新增接口或修改接口时使用”。这样 AI 判断的时候更容易命中。第二步骤数量控制在 5 到 10 步之间。太少了没有约束力太多了 AI 会虎头蛇尾。第三每个步骤和动作尽量动词开头比如“检查”“输出”“验证”命令式语言对模型指令更强比我慢慢写的啰嗦文字要好得多。6.3 日常使用体感与效率对比说一个比较主观但真实的数据在没有用技能包之前我处理一个中等复杂度的 Java 功能点从发需求到代码入库中间至少要和 AI 来回沟通十几轮。期间还会经常出现“代码编译不过”“测试逻辑错误”“需求漏了边界条件”这类问题每次折返都是时间和耐心的双重消耗。用了 Superpowers 之后典型场景我可以把来回轮次压缩到四五轮以内规划一轮、实现一轮、审查一轮剩下偶尔微调。那个“哎AI 怎么又不听话了”的频率明显低了。以前每次 AI 偏离轨道我都得停下来重新纠正它现在技能文件里就写清楚了每一步AI 从头到尾都是那个流程哪怕某一步做错了它也会根据技能里规定的步骤自动往回修正。另外我还观察到一个意外收益技能包对新人特别友好。刚接触 AI 编程的新手往往不太会组织语言、描述需求导致 AI 输出质量差。技能包直接替你把“如何与 AI 沟通”这件事标准化了。新人只需要说一句“请使用 implement-tdd 技能实现用户注册接口”AI 就会带走流程新人只需要看着它按步骤执行就行。从这个角度看Superpowers 不只是 AI 的超能力也是开发者的“新手保护期”。