开篇先聊点实在的。superpowers 这个名字乍一听像游戏里开了作弊码但在 AI 编程助手的语境里它其实是一套“技能增强机制”通过一组结构化的技能卡片让 Codex、Claude Code 这类命令行编程助手在执行任务时不再靠裸模型自由发挥而是按照你预先定义好的流程、规范和模板去干活。我最初是在给一个 Java 老项目做重构时入坑的。项目有一堆历史遗留代码测试覆盖几乎为零直接丢给 Codex 让它“帮我重构”结果它给我输出了一堆看起来合理、实际上连编译都过不了的方案。后来我把 superpowers 的技能包装进去给它配了“先梳理依赖、再写测试、最后改代码”的三段式流程效果立刻不一样。这篇文章就把我这段时间的安装、配置、实战经验梳理一遍包括 Java 场景的适配、在 WorkBuddy 这类可视化客户端里的玩法以及我踩过的几个坑给想上手的同学一份能直接照着做的指南。1. 先说清楚superpowers 到底是什么1.1 不是魔法而是给 AI 编程助手的“技能说明书”很多人第一次看到 superpowers 这个名字会以为它是一个类似 Copilot 那样的独立插件装上之后 AI 立刻变强。实际上它更像是一套“技能包管理框架”技能以 Markdown 文件为载体里面写的是针对某一类任务的详细操作指令。比如“如何给一个模块写单元测试”“如何生成符合规范的 Git 提交信息”“如何做一次代码审查”每个技能文件里都包含触发条件、执行步骤、输出模板和注意事项。核心思路是大模型本身确实有很强的代码生成能力但模型并不知道你所在团队、你这个项目的具体约束。你直接把需求丢给它它生成的代码大概率是“通用正确、具体错误”。superpowers 要解决的就是把这个差距补上。它通过加载技能文件把“项目上下文”和“最佳实践”显式地注入到模型的工作流程里。我打个比方裸的 Codex 相当于一个刚毕业的高材生底子好但不知道你们公司的编码规范、不知道哪些历史模块不能乱动。superpowers 就是一份入职培训手册告诉它遇到什么情况走什么流程、什么能做、什么不能做。它的价值不是提升模型智商而是降低项目的“不确定性”。1.2 为什么需要它同样是写代码差距在流程我自己实测下来有 superpowers 和没有 superpowers差别最明显的不在单次生成的代码质量而在“连续多轮任务”的执行稳定性。举个例子让 Codex 给一个新模块写完整功能没有技能包它会先把所有代码一股脑生成出来然后你让它补测试它补的测试又来了一堆新逻辑最后提交信息写得乱七八糟。有技能包它会在动手前先输出一份实现计划按“接口定义→核心逻辑→边界测试→提交信息”顺序执行每一步完成之后才进入下一步而且提交信息会自动套用你预设的 Conventional Commits 模板。前者是“突击式”码代码后者是“工程化”码代码。对于个人项目、一次性脚本前者可能够用但只要是协作项目、长期维护的代码库、有 CI 流程的仓库后者几乎是必需品。superpowers 做的就是这件事把 AI 的“码力”约束到一条可预期的轨道上。2. 安装与基础配置2.1 环境准备把依赖提前装好省得后面折腾在安装 superpowers 之前需要先把基础环境准备好。我这边用的是 macOS Node.js 环境核心依赖就两样Node.js建议 18.0 以上和 Codex CLI或者 Claude Code二者选其一即可。很多人在安装阶段就卡住往往不是 superpowers 本身的问题而是 Node 版本太老、或者 Codex CLI 没登录。安装步骤我整理成了下面的顺序检查 Node 版本终端执行node -v如果低于 18建议用 nvm 装一个新版本不要直接在老版本上硬跑后面会出各种奇怪的兼容问题。安装 Codex CLI执行npm install -g openai/codex安装完成后运行codex --version确认。获取 superpowers 技能包从项目仓库 clone 或者直接下载 tar 包到本地目录例如~/superpowers/。将技能包注册到你的 AI 编程工具里方式有全局注册和项目级注册两种下面细说。提示如果你平时用的是 Claude Code它的加载机制类似只是配置文件的位置和格式略有不同。本文以 Codex 为主Claude Code 用户看第 2.3 节做对应替换即可。2.2 全局配置与项目级配置选对作用范围很重要superpowers 的配置核心是一个superpowers.json或其他等价配置文件里面定义了技能包路径、启用的技能列表、以及针对不同代码库的规则。配置分两个层级作用范围完全不同全局配置放在用户主目录下比如~/.superpowers/superpowers.json。适合放通用的技能比如“代码格式化检查”“提交信息模板”“代码审查通用清单”因为这些技能在任何项目里都用得上。项目级配置放在某个仓库的根目录比如your-project/.superpowers/superpowers.json。适合放项目专属的约束比如“这个模块禁止修改”“测试必须使用 JUnit 5”“数据库迁移文件只能统一脚本生成”。我的建议是通用技能全部放全局项目约束全部放项目级。如果反过来你会在 A 项目里看到 B 项目的规则AI 执行的混乱程度会让你怀疑人生。配置文件的写法大概是这样的{ version: 1, skillDirectories: [ ~/.superpowers/skills, .superpowers/skills ], skills: { enabled: [write-tests, review-code, write-commit-message], disabled: [refactor-plan] }, projectRules: { java: { testFramework: junit5, packageStructure: com.example, codeStyle: google-java-format } } }这里面skillDirectories告诉程序去哪找技能文件skills.enabled/disabled控制启停projectRules给项目特定语言或框架设定规则。注意配置改完之后通常要重启 Codex 会话才能生效不要问为什么问就是缓存。2.3 Java 项目适配别让它用 Python 的思维写 Java搜“superpowers java”的同学大概率是遇到了这个痛点AI 生成的 Java 代码要么 import 路径不对要么测试框架用成了 pytest 风格要么没有遵从标准的 Maven 目录结构。这些问题不是说模型不会写 Java而是它缺少你项目的“局部知识”。在 superpowers 里适配 Java 项目我总结了四个必加的设置显式指定构建工具在projectRules.java里写明buildTool: maven或gradle这样 AI 在生成依赖管理指令、编译命令时才不会乱来。锁定测试框架老项目用 JUnit 4新项目用 JUnit 5必须写清楚。不然它默认识别成 JUnit 5结果你的类路径里根本没有对应的依赖。指定包名和目录结构packageStructure字段非常关键。默认情况下 AI 会按照它自己理解的包名生成代码一旦和你的groupId不一致整个项目立刻编译失败。配置代码风格检查器我习惯把 checkstyle / spotless 的规则文件路径写进去让 AI 在生成完之后自检一遍。配完这些我那个老项目的重构就顺畅多了。它生成的新代码至少能一次通过mvn compile而不是每次都留一堆红色的报错让我收拾。所以如果你用 Java强烈建议在配置阶段多花十分钟把项目信息喂给 superpowers这十分钟能省下后面几小时的排错时间。3. 核心技能解析与实战3.1 技能卡片的运行机制触发词 流程 输出模板superpowers 里的每个技能本质上是一个 Markdown 文件文件里通常有三部分内容触发条件、执行步骤、输出模板。触发条件决定了 AI 在什么情况下调用这个技能执行步骤是核心规定了 AI 必须按顺序完成哪些动作输出模板则规范了最终交付物的格式。举个例子一个“写单元测试”的技能文件它的逻辑结构大致如下--- name: write-tests description: 为指定类生成单元测试 triggers: - 写测试 - 补充单测 - add tests steps: 1. 识别被测类的 public 方法 2. 根据方法的输入输出构造测试用例覆盖正常路径、异常路径、边界值 3. 使用项目配置的测试框架生成测试代码 4. 运行测试命令确认全部通过 template: | ## 测试摘要 - 覆盖的方法... - 测试用例数... - 测试结果...AI 在执行“给 xx 类写测试”这个请求时会先判断有没有命中的技能有的话就按技能里定义的步骤一步步来而不是自己天马行空地生成一堆断言。我一开始不理解为什么非要 Markdown 这种“人也能读”的格式后来想通了技能的编写者可以是任何懂项目的人不需要会写代码只要能把流程说清楚AI 就能执行。这就把“技能库”的维护门槛拉低到了纯文档层面。3.2 高频实战场景从我踩过的坑里提炼出来的三个用法用了一段时间之后对我帮助最大的三个技能场景分别是“自动生成规范提交信息”“代码审查前置检查”“新增功能前的实现计划”。第一个场景自动生成规范的提交信息。以前我每次提交代码都要手写 commit message而且风格时常不一致一会儿用fix:一会儿用fixed一会儿干脆不写类型。后来我在技能库里放了一个 commit 技能规定它必须按 Conventional Commits 规范生成提交信息并且在信息末尾加上关联的 issue 编号。现在 Codex 每完成一段代码改动会顺手帮我把提交信息写好格式统一了看着神清气爽。第二个场景代码审查前置检查。这是一个让我非常意外但收益极大的用法。我让 Codex 在提交 PR 之前先充当审查者角色检查是否有硬编码的密钥、是否有被注释掉的死代码、是否有直接调用废弃 API 的情况。它能查出的问题不算多但每次查出来的都是实打实的问题等于多了一道免费的前置审查关卡。第三个场景新增功能前的实现计划。以前我开发新功能喜欢直接写代码写到一半发现数据结构设计有问题推倒重来。现在我会让 AI 先按技能流程输出实现计划包括数据模型、接口签名、修改文件列表、影响范围。看着像是多了一步但能避免大量“写到一半返工”的悲剧。Java 项目里尤其明显因为 Java 的类型系统约束强改接口牵一发动全身提前做设计规划的价值特别大。3.3 如何编写自己的技能文件其实比想象中简单如果你不想只用社区现成的技能包完全可以自己写。我自己写过一个“为 HTTP API 添加参数校验”的技能整个过程不超过二十分钟。编写时注意三个要点触发条件要清晰触发词不能太宽泛。比如“校验”“参数校验”这种词容易出现误触发建议把触发条件写得具体一点比如“给 PostMapping 接口添加参数校验”。步骤要可执行不要写“编写健壮的校验逻辑”这种模棱两可的话。要写成“先检查参数类上的注解再为每个制定字段添加 NotNull/Size 注解最后在 Controller 层补充异常处理”。输出模板要固定AI 生成的最终结果尽量要求它输出固定结构比如“修改的文件xxx新增的依赖xxx测试结果xxx”。这样你一眼就能看到关键信息不用在一大段 AI 自述里找重点。技能文件写好之后放入项目的.superpowers/skills/目录重启 Codex 会话它就会自动识别。一个项目里有七八个针对性的技能文件AI 基本就能从“乱来”变成“熟练工”了。4. 工具链联动在 WorkBuddy 等客户端里使用 superpowers4.1 为什么要把 superpowers 接到 WorkBuddy 里很多读者在搜“worbuddy 怎么用 superpowers”我推测你用的是类似 WorkBuddy 这样的桌面端 AI 编程客户端。这类工具本质上是把命令行 AI 编程助手包装成了图形界面把对话区、文件树、终端输出整合到一个窗口里。直接使用 Codex CLI 当然也能跑 superpowers但在 WorkBuddy 里操作更直观比如可以直接在商谈区看到 AI 正在执行哪条技能步骤、在文件树里看到它改了哪些文件。我在这类工具里使用 superpowers 的整体感受是省去了来回切换终端的麻烦AI 的思考过程肉眼可见地变成了一条条任务清单心理上会觉得更有掌控感。有一个细节值得提一下WorkBuddy 这类客户端通常支持自定义指令区你可以在会话开始时输入类似“加载 superpowers 技能包并初始化项目上下文”的指令它会自动读取配置并进入技能驱动模式。4.2 在 WorkBuddy 中配置 superpowers 的几个要点如果你准备在 WorkBuddy 里用 superpowers下面几个配置点比较关键设置技能包根目录在客户端的配置页或者启动指令里指定技能包路径。我习惯把所有技能文件放在统一的目录下比如~/superpowers/skills所有项目共用一套通用技能再用项目目录下.superpowers里的覆盖项目专属配置。调整权限策略这类客户端通常会询问 AI 是否有权限自动执行终端命令。为了 superpowers 技能能自动运行测试或执行构建建议对项目的指定命令如mvn test、git commit开放自动执行权限对其他命令保留手动确认。善用客户端的历史记录技能执行过程中如果出现意外结果客户端会保留完整会话记录排查问题的时候非常有用比在终端翻日志好用得多。注意给 AI 自动执行权限的边界要自己想清楚。我建议只对测试、构建这类低风险命令放权对于git push、依赖安装、文件删除这类操作保持手动确认。这不是不信任工具而是良好的操作习惯。5. 常见问题排查与避坑实录5.1 问题速查表遇到问题先对着查我把自己和身边朋友遇到过的问题整理成了一张速查表按“现象 → 原因 → 解法”的方式列出来大家可以先对着查一下现象可能原因解决办法技能完全不生效AI 还是自由发挥技能文件路径没配对或者文件没有放在受支持目录下检查superpowers.json里的skillDirectories路径是否准确确认技能目录存在且文件名以.md结尾AI 调用了技能但没按步骤执行技能文件里步骤描述不够具体或者模型上下文太长被截断精简技能文件把步骤控制在五条以内每条步骤尽量动作明确Java 项目生成代码编译失败构建工具、测试框架或包结构配置缺失在projectRules.java里强制指定 Maven/Gradle、JUnit 版本、包名前缀终端命令执行时报权限错误客户端权限策略下没有允许对应命令在权限配置中给测试、编译等命令增加自动执行授权改了配置但没有任何效果配置缓存导致没有重新加载重启 AI 编程会话或者客户端确保配置被重新读取多个技能同时被触发不同技能文件里的触发词互相重叠把重叠的触发词改成更具体的表达或者在配置里禁用掉其中一个技能这张表基本覆盖了我遇到过的绝大多数问题。如果还是查不到就去看客户端或 CLI 的详细日志superpowers 这类工具一般都会在 debug 模式下打印技能加载情况能很清楚地看到哪一步出了问题。5.2 避坑心得三个让我印象深刻的教训第一个教训别过度堆砌技能数量。我一开始觉得技能越多越好一口气往技能目录里塞了二十多个技能文件结果 AI 在判断该用哪个技能时产生了大量不必要的开销甚至出现多个技能同时触发、互相打架的情况。后来我砍到十个以内每个技能都能精准命中效率反而大大提升。技能这种东西贵精不贵多。第二个教训技能文件也要版本管理。技能文件是纯文本的完全可以放进 Git 仓库。很多人包括我自己刚开始直接把技能文件丢在本机目录里改来改去没有版本记录改坏了都不知道是哪个版本开始坏的。把技能库纳入版本管理之后每次调整都能留痕回溯问题非常方便。第三个教训不要把安全关键操作写进技能里。这里指的是那些“自动删除文件”“自动推送代码”“自动修改数据库”的操作。技能文件一旦被 AI 执行它的行为可能超出你对文本描述的理解范围风险很高。superpowers 适合做“生成、检查、分析”类工作不适合做“变更、删除、发布”类工作。这两者之间的界限最好在技能设计阶段就想清楚。写在最后的一个实操建议如果让我给刚接触 superpowers 的读者一个建议那就是先从一个小到不能再小的场景开始比如只配置一个“规范提交信息”的技能跑通整个流程再逐步增加其他技能。我见过很多人一上手就试图配置一整套完整流程结果因为某个环节没调通整体没法用最后就放弃了。小步快跑稳扎稳打才能真正把这套工具用起来。等它在你手边稳定运行两周以上你会发现 AI 编程助手从“一个会写代码的问答机器”真正变成了“一个懂规矩的远程同事”。
