上周在一个技术群里看到有人问superpowers 到底怎么装怎么配合 Codex 用Java 项目里能不能用群里七嘴八舌回答得特别散我索性把官方仓库和一堆 issue 翻了一遍又在一个真实的 Java 服务上跑了三天才把整个链路理顺。这篇文章就是那次折腾的记录送给所有一看到 superpowers 这个词就一脸懵的朋友。先说结论superpowers 不是一个普通插件它是一套用来给 AI 编程模型提供结构化技能和上下文的开源方案。它可以跟 Codex、Claude Code 这类命令行 Agent 配合也能在 Java、Go、Python 等项目里使用。网上资料少是正常的因为这项目本身就很新且更新速度极快照搬旧教程的人反而容易翻车。1. superpowers 到底是个什么东西1.1 为什么最近到处都是这个词最近一个月不管是在推特还是国内技术社区经常能看到 superpowers 这个词。但如果你点进去看会发现大家讨论的场景五花八门有人跟 Codex 绑在一起用有人在问 Java 项目里怎么配还有人拿着一个叫 worbuddy 的工具折腾半天。我一开始也以为它们是三个不同的东西后来才搞清楚superpowers 其实是一个开源技能包项目核心思路是把编程中那些老师傅知道但文档没写的规矩变成大模型能直接读取的指令集。你把它想象成一个经验库就很好理解。同样是让 AI 写一个接口裸奔模型只会按训练数据里的通用模板写但加载了 superpowers 的模型会先去看你项目里是否已经存在类似代码再决定用 Maven 还是 Gradle最后还会主动补测试。这就是有没有超能力的区别。1.2 它在 AI 编程链路里扮演的角色现在的 Codex、Claude Code 这类 AI 编程工具已经很能写代码了但实际干活的时候你会发现一个问题它们更像是代码生成器而不是工程师。给你一个需求它唰唰写完就停手不会主动考虑如何组织提交、如何补测试、如何遵循你项目的既有架构。superpowers 就是来解决这个问题的。它不替换模型而是在模型启动前注入一层技能上下文相当于给模型戴上一副能看见项目全局的眼镜。这个定位很重要——它不是一个 IDE 插件也不是一个编译器它是一堆 Markdown 文件加少量脚本的组合体。你甚至可以打开它的肚皮看看那些技能文件写了什么。这也是当初我决定入坑的原因代码和提示词都是公开的没有黑盒。1.3 打开仓库技能包里到底有什么从仓库结构上看它比我预期的朴素很多。顶层目录大概分三块prompts里放的是系统提示词用来定义模型的基础人设skills里是一堆按场景拆分的技能文件比如代码审查、测试驱动、Git 工作流templates里则是一些项目脚手架方便你在开新项目时直接套用。这种设计最大的优点是可插拔。你不需要一次性加载所有技能只需要在跑不同类型的任务时让模型读取对应目录即可。我经常干的骚操作是在 Codex 里只加载skills/code-review让它单独帮我审查代码而不是又写又审避免角色混乱。2. 安装 superpowers这步最容易翻车2.1 安装前要准备什么首先要明确一个事superpowers 不像普通软件那样下一步下一步就能装完。它本质上是一个代码仓库所以最基本的依赖是 Git。如果你的环境里还没有 Git请先装好。其次仓库里有不少辅助脚本是用 Python 写的如果你的电脑上有 Python 3.10 最好没有也别慌大部分场景下只读技能文件不需要执行脚本。我实际测试下来在 macOS 和 Linux 上安装比较顺Windows 下需要借助 WSL 或者 Git Bash否则很多路径处理和符号链接会出问题。还有一点值得提前说明如果你打算跟 Codex 配合Codex CLI 本身要能正常工作。这一步不能跳过因为很多人 superpowers 装好了却忘了 Codex 还没登录花了一晚上排查最后发现是鉴权没过。2.2 安装操作和两种常见姿势从 GitHub 上把仓库克隆下来这是最直接的方式。我习惯把它放在用户名目录下方便后续引用。git clone 官方仓库地址 ~/superpowers cd ~/superpowers ./install.sh如果你的网络访问 GitHub 有困难可以找一些镜像站点或者直接下载压缩包解压。不过我强烈不建议你把解压出来的目录随手扔在桌面上就完事因为之后所有工具都要引用这个路径路径一旦变动排查起来很痛苦。还有另一种只读姿势不运行 install 脚本只把仓库克隆到一个固定的位置然后在 Codex 或 worbuddy 的配置里直接指向这个目录。这种方式最适合喜欢手动控制一切的人升级的时候只需要git pull不会产生额外文件。我自己的选择是第一种因为官方脚本会做好目录结构和环境变量的映射省心。但这里要提醒一下不同版本的 install 脚本行为差异很大有的只建立目录链接有的还会自动修改 shell 配置。你真要跑的时候建议先less install.sh看一眼别闭眼执行来历不明的脚本。2.3 安装完必须验证的三件事装完之后不要急着写需求先花五分钟确认三件事命令能找到。打开一个新的终端窗口输入superpowers --version如果能输出版本号说明可执行文件已经进入 PATH。如果找不到大概率是~/.superpowers/bin没有被加入 PATH手动加一下就行。技能目录能读取。执行superpowers list应该能看到一堆技能名称比如code-review、test-driven、git-workflow。如果列表为空检查仓库是否真的在指定位置。Codex 配置能加载。这条放到下一节细说但你在集成前至少应该确认 Codex 的配置文件没有语法错误否则两个工具都白搭。2.4 Windows 用户特别提醒我在 Windows 上踩的坑比 macOS 多得多。如果你用的是原生 Windows而不是 WSL有几个点要先想清楚路径分隔符问题。superpowers 内部的技能文件里全是 Linux 风格的/路径如果你手动配置了 Windows 路径Codex 读配置时经常会将C:\Users里的反斜杠当成转义符导致路径直接失效。符号链接权限。Git for Windows 在默认情况下不会启用符号链接支持而 install 脚本里可能会创建软链接你需要用管理员权限打开终端或者开启开发者模式。终端编码。技能文件里如果有中文字符在旧版 PowerShell 下面会乱码导致模型读取出错。建议直接用 Windows Terminal UTF-8 编码。如果你的团队里有人用 Windows又有人用 macOS我强烈建议把 superpowers 的配置统一放到仓库里通过.env或者 config 文件管理不要依赖各自机器的绝对路径。3. 和 Codex 集成让 AI 从建议员变成执行者3.1 接入思路与配置Codex 在启动时会读取用户目录下的config.tomlsuperpowers 的集成思路就是让 Codex 在每次对话时额外加载 superpowers 里的提示词文件。不同 Codex 版本支持的方式不太一样有的是在配置里加extra_prompts有的是支持--prompts参数。我用的是后者因为更灵活可以按项目切换。一个典型的流程是这样codex --prompts $HOME/superpowers/prompts/base.md 帮我把 UserService 里那段逻辑抽成独立服务如果你希望所有任务默认都带上技能包可以直接改配置。在~/.codex/config.toml里加入一行extra_prompts [$HOME/superpowers/prompts/system.md]注意这里的路径要写绝对路径否则 Codex 在工作目录下找不到文件但它又不会报错只会静默忽略——这也是我踩过的最深的坑之一。你回过头怎么查都查不出问题直到你直接在对话里问它你能读到 /superpowers/prompts/system.md 吗它说不能你才意识到是路径没对。3.2 集成前后一个真实任务的推进过程为了让你直观感受集成前后的差别我复述一个实际任务在一个已有的 Spring Boot 项目里给订单模块增加一个导出 CSV 的接口。没有 superpowers 的 Codex拿到需求后通常会直接生成一个 Controller 和 Service然后就没有然后了。它甚至不会检查项目里是否已经有 Excel 工具类也不会考虑导出的字段顺序是不是你想要的更不会主动补单元测试。集成之后表现完全不同。它先读取backend-coding技能文件里面明确要求在生成代码前先扫描项目依赖和现有工具类接着它会用mvn dependency:tree查看有没有可用的 CSV 库如果没有它会建议引入 OpenCSV 而不是自己手写解析器写完代码后它还会自动跑一遍mvn test如果失败会回头修。整个过程就像有一个初级工程师在你旁边虽然还得你牵着走但至少不会把项目搅乱。3.3 我的提示词 项目约束 技能三层配置单独用 superpowers 已经比裸奔强了但我后来发现更好的组合方式是分三层第一层是基础技能包也就是 superpowers 仓库里那些通用技能负责传递编码规范、测试习惯、Git 提交规范第二层是项目级提示词每个项目根目录放一个AGENTS.md或.superpowers/project.md里面写清楚这个项目特有的约束第三层才是具体任务指令也就是你在对话里发出的需求。这三层在 Codex 里是叠加生效的任务指令最具体优先级最高项目提示词其次通用技能包兜底。这样做的好处是通用技能包可以长期不变项目提示词跟着仓库走换台新电脑也能快速恢复环境。4. 在 Java 项目里用 superpowers从环境验证到实际开发4.1 Java 开发者最容易踩的认知误区我身边的 Java 同事听说 superpowers 能配 Codex第一反应往往是这玩意不是给前端用的吗跟 Java 有啥关系实际上superpowers 的核心是 Markdown 技能文件语言无关。Java、Go、Python 都能用关键是你要让技能包知道你的构建工具和测试框架。真正让我意外的是Java 生态反而是最有收益的领域。因为 Java 项目通常结构复杂、约定多——Maven 的坐标、包命名、异常处理、Lombok 的使用这些东西模型靠通用训练数据很难准确匹配但技能文件可以精确写进去。比如我在技能包里加了一条业务代码中禁止使用裸线程统一用线程池注解之后每次生成的代码都符合团队规范这在以前几乎不可能。4.2 一个 Maven 项目的具体集成案例我在一个标准的 Spring Boot Maven 项目里做过测试。项目用的是 Java 17、JUnit 5、Lombok。我在仓库根目录放了这样的项目提示词# 项目约束 - JDK 版本17 - 构建工具MavenJDK 17 - 测试框架JUnit 5 - 禁止使用 Lombok 生成 equals/hashCode业务类必须手写然后把 superpowers 的java技能目录也加到 Codex 的提示词列表里。效果非常明显。给定一个需求新增加一个用户查询接口支持分页和排序它生成的代码会自动带上RestController、RequestMapping(/api/users)、Pageable参数测试用的也是SpringBootTest而不是 JUnit 4 的老写法。你会说这不就是模型本来就懂吗对但问题在于本来懂不代表每次都懂。技能包的作用是把这些约束变成每次必看的上下文从根本上减少这次忘记加分页这种随机性。4.3 和 Gradle 项目的差异点如果你的项目用的是 Gradle集成方式跟 Maven 大同小异但有几个地方要特别给技能包写清楚依赖坐标写法不同。同样的库Maven 是groupId:artifactId:versionGradle 是implementation groupId:artifactId:version。如果技能里只有 Maven 示例模型生成 Gradle 配置时会照着 Maven 输出一编译就报错。插件配置位置不同。Maven 的插件在pom.xml里的pluginsGradle 在build.gradle里的plugins {}。本地缓存机制不同。模型跑mvn test跑惯了遇到 Gradle 项目会下意识找~/.m2其实 Gradle 用的是~/.gradle。所以我会在项目级提示词里多花一百字把这些差异写清楚。不然 superpowers 帮你生成一个构建脚本不仅要调半天还容易误导人。4.4 与 IDE 搭配使用我建议这样做superpowers 和 Codex 都是命令行工具但大部分 Java 开发还是离不开 IntelliJ IDEA。我的做法是用 IDEA 写代码用 Codex superpowers 来跑 Agent 任务。两个工具之间不需要做特殊桥接因为 Codex 本身就是直接操作文件系统的。只要你的 IDEA 没有开文件变更自动格式化之类的插件两边即使偶尔同时改一个文件也不会出大问题。不过我建议你给技能包加一条规则凡是要修改已有文件先在任务开始时用git diff看一眼当前改动避免把还没保存的本地修改覆盖掉。这个经验是从一次事故里学到的Codex 在没提示的情况下直接格式化了我还没提交的代码差点把两天的活儿冲掉。5. worbuddy 与 superpowers提示词管理的新思路5.1 worbuddy 到底是干什么的如果你经常在网上搜 superpowers 的教程大概率会看到有人提到 worbuddy。我最初以为这是某个游戏外挂后来才发现它是一款 AI 对话管理工作台用途是把不同场景下的提示词、技能包、模型参数统一管理起来。简单说Codex 是干活的人superpowers 是技能库worbuddy 就是负责把技能库按项目分发给干活工具的那个调度台。我在 worbuddy 里的用法比较简单为每个项目建一个配置卡片卡片里关联这个项目需要的 superpowers 技能目录和项目提示词。这样我不用每次敲一长串--prompts参数也不怕不同项目之间的技能冲突。5.2 多项目多技能包的管理实践如果你的工作环境里同时有 Java 后端、React 前端、Python 数据处理三个项目你的痛点一定是每次切项目都要换提示词。用 worbuddy 之前我维护着一堆 shell 别名切换项目时手动 export 环境变量经常搞混。后来我把所有提示词和技能配置都收到了 worbuddy 的模板里切项目就是一个点击的事。它和 superpowers 的关系你可以理解成superpowers 提供了标准件worbuddy 负责装配。如果你不是重度多项目用户不一定需要这个工具但如果是强烈建议试一下。我甚至试过在同一个会话里给前端项目配 TS 语言技能给后端项目配 Java 技能互不干扰。5.3 一套可复制的组合工作流这里分享一下我现在比较稳定的组合流程在 worbuddy 里创建好项目模板关联 superpowers 的通用技能目录项目仓库里放一份自己的project.md包含团队特有的编码约定启动 Codex 时通过 worbuddy 一次性传入所有提示词路径每次任务结束后让 Codex 把 AI 的修改总结同步到项目文档里。这套流程我已经持续用了两周最大的感受是AI 的产出一致性明显变高了尤其是代码提交信息之前每个 commit 风格都不一样现在会严格遵循 Conventional Commits。这种细微的变化恰恰是很多团队不敢用 AI 编程的顾虑所在。6. 高频翻车现场与排查清单6.1 一张表解决 80% 的问题我把这段时间自己和群里朋友踩过的坑整理成了一张表建议直接收藏。现象可能原因排查与解决superpowers命令找不到可执行文件没加进 PATH检查~/.superpowers/bin是否存在再把路径加到.zshrc或.bashrc后重新打开终端Codex 启动后没有任何变化extra_prompts里的路径不对或文件未生效用ls核实文件存在改成绝对路径删除 cache 后重启技能文件读取成功但不生效提示词里没有强制要求必须阅读在系统提示词中加入先阅读技能文件再执行任务的硬约束Java 项目生成代码编译失败技能包缺少项目构建约束在项目project.md里写明 JDK 版本、依赖管理、测试框架模型把已有文件格式化了缺少尊重现有改动的规则在基础技能中加入修改文件前先git diff不格式化非本次任务涉及的代码worbuddy 加载配置时报错配置文件使用了过时的字段名查看官方更新日志把字段改成新版本对应的写法6.2 最典型的两个坑的完整排查链路第一个坑是Codex 明明配置了 superpowers但它就是不用。我当时排查的顺序是先在对话里直接问 Codex你能看到 /superpowers/prompts/system.md 吗它说看不到。然后我检查配置发现extra_prompts写成了相对路径Codex 在工作目录里找不到文件但也不报错只是当作没看见。改成绝对路径后再问一次它就能准确复述技能文件的核心要求了。所以路径问题永远是第一位要排除的。第二个坑是Java 项目里模型总是生成 JUnit 4 的测试项目用的是 JUnit 5。这个问题表面上是模型知识过时实际上是技能包没写清楚。我在技能里补了一条本项目测试请使用 JUnit 5避免出现 RunWith、org.junit.Test 等旧 API之后生成的测试就全部规范了。所以当 AI 行为不符合预期时第一反应应该是查技能文件里有没有相应约束而不是怪模型笨。6.3 升级前的备份与回滚策略superpowers 迭代速度很快我基本每周都要git pull一次。但有一次更新后某个技能文件的结构变了导致 Codex 加载失败。所以升级前一定要先把当前版本打个 tagcd ~/superpowers git tag backup-$(date %Y%m%d%H%M%S) git pull如果更新后出了问题直接git checkout回到之前的 tag 即可。这个习惯我是在被折腾了一整晚之后养成的强烈建议你也保留。别忘了你项目里的project.md是和 superpowers 的通用技能分开的两个不要放在同一个目录里管理否则回滚时会连项目自定义内容一起覆盖。6.4 如何把团队规范沉淀进技能包最后我想重点说一下沉淀的问题。很多人用 superpowers 只是下载官方技能包效果有但总觉得隔了一层。更进阶的玩法是把你团队自己的 review 意见、编码规范、常见坑都写进项目级技能文件里。比如我们团队在 code review 时反复要求所有新增 API 必须加分页参数以前靠人在 PR 里提醒现在直接写进 superpowers 的技能文件AI 生成代码时就自动带了。我一般每周花半小时整理一次本周 AI 犯过的错。把那些重复出现的问题比如没处理空指针没加日志消息 key 命名不统一逐个补充进技能文件。这样 superpowers 会越来越像你们团队里的老员工。这种持续迭代带来的复利远比安装一个工具来得大。最后还是分享一点个人看法。superpowers 不是银弹它更像是一个纪律养成器。我用了两周之后最直观的感受是它把 AI 编程工具从每次全凭运气变成了至少稳定达到及格线。这种稳定对于一个追求可复现的工程团队来说价值远大于偶尔的惊艳发挥。所以我的建议是不要只盯着怎么安装和集成多想一步你自己的项目里有哪些人人以为大家都知道但每次都有人会忘的规范把它们写进技能文件这才是 superpowers 真正的威力所在。