每次拿到一台新电脑我的第一反应不是装 IDE而是先跑一遍superpowers。为什么因为我不想过那种“装完系统还得手动配 Java 环境、翻来覆去改 .zshrc、敲一堆重复命令”的日子。Superpowers 这个名字听起来有点中二但它做的事情很实在把一套可复用的开发环境配置、项目脚手架和 AI 辅助规则打包成脚本让你从机器到手到环境可用少花两小时以上。如果你正在找所谓“superpowers 使用教程”“superpowers 安装”这类资料大概率也是想知道这玩意儿到底怎么用、能给日常编码带来什么。这篇我就从自己实际折腾的角度把整个工具链怎么安装、怎么用、怎么在 Java 项目里落地、怎么配 Codex 协同一次讲透。后面还会附上我踩过的坑尽量让你少走弯路。1. 先搞清楚 Superpowers 到底解决了什么问题1.1 不是魔法是把你重复做的事固化成脚本很多人第一次听到这个名字会以为它是个 AI 框架之类的东西。其实我用的 Superpowers更像一套“开发环境模板 项目脚手架 规则注入器”。它把所有你平时在新机器、新项目里必须手工完成的操作比如安装 Homebrew / Chocolatey 或 apt 依赖配置 shell 别名、Git 全局设置准备 JDK、Maven、Gradle 等 Java 工具链生成项目目录结构、README、.gitignore给 AI 编码助手写好项目上下文规则统一收敛成一组命令。你不需要记住几十个安装步骤只需要知道superpowers init、superpowers load和superpowers sync这几个入口。说白了它给你的“超能力”不是凭空变出代码而是把那些烦琐、容易出错的重复劳动自动化了。时间一长你会发现自己很少再去搜索引擎上翻“macOS 配置 JAVA_HOME”之类的问题。1.2 它覆盖的三种典型场景我把它整理成三个核心使用场景新环境快速就绪从零配置一台开发机。无论是换公司、换电脑还是租了台云服务器跑一遍脚本常用软件、版本管理器、shell 主题就都齐了。新项目冷启动不用再手动创建src/main/java那串目录结构也不要反复改 pom.xml。执行一条命令Java 项目的基础骨架直接生成。AI 辅助编码的规则统一很多人用 Codex或者类似 AI 编程工具时总觉得输出不听话代码风格和团队规范对不上。Superpowers 会在每个项目里生成一份规则文件让 Codex 在开工前先读到你的约束这比我每次在对话框里重复解释“请用 Java 17不要用 LombokDTO 放这个包下”要靠谱得多。1.3 适合什么人用如果你平时主要做后端开发尤其是 Java 技术栈那这套东西的收益最明显。因为 Java 项目的构建工具、JVM 版本、依赖管理都比较依赖环境一致性手动配置一错就是一堆莫名其妙的问题。如果你经常要用 Codex 这类 AI 工具辅助写代码那就更需要一个能稳定向 AI 传递项目规则的机制。当然前端、Python、Go 也都能用只是我自己最熟的场景是 Java所以后面会有单独的章节讲 Java 集成。2. 安装三条命令装完以及装完必做的三件事2.1 安装命令与前置要求Superpowers 的安装脚本我放在 GitHub 仓库里支持 macOS 和 Linux。Windows 用户我建议先装 WSL2然后再跑 Linux 安装流程。安装时就三条命令curl -fsSL https://install.superpowers.dev/install.sh | bash source ~/.zshrc superpowers doctor如果用的是 bash就把第二行的~/.zshrc改成~/.bashrc。superpowers doctor会检查所有依赖项比如 Git、curl、tar、jq 这些基础工具是否都存在缺哪个它会提示你补装。一个很容易忽略的前提你的机器上最好先有 Git 和 curl。绝大多数开发机都自带但如果是精简版 Docker 容器或者刚装的云服务器可能没有建议先执行sudo apt update sudo apt install -y git curl2.2 安装过程中最常见的两个问题我遇到过两类问题。先说网络原因导致脚本下载失败的情况。脚本本身只有几十 KB但如果你的网络连接到安装源不稳定可能下载到一半就断了。这种情况不必重跑整个命令脚本自带断点重试机制多跑几次一般就过了。如果持续失败可以检查 DNS 或者更换网络环境注意不要用任何特殊手段去“绕过”限制正常换个镜像源就行。另一个问题是权限。有些人习惯用 root 跑安装脚本但 Superpowers 会往~/.config和~/.local/bin写入内容root 的目录结构和普通用户不一样容易导致后续命令找不到。所以老老实实用自己的用户账号装不要 sudo。2.3 装完的瞬间先做这三件事脚本装完只是第一步我的建议是立刻做三件事确认 shell 环境执行which superpowers确保它被加进 PATH。如果找不到检查~/.local/bin是否在 PATH 里。跑一次superpowers doctor把它当成体检它会列出一份清单比如 JDK 版本、Node 版本、Git 全局配置方便你一眼看出缺什么。初始化一份默认配置执行superpowers init --default生成~/.config/superpowers/config.yml。打开这个文件你会看到安装模块开关、别名定义、环境变量等先熟悉一下再改。做完这三件事Superpowers 本身就算跑起来了。接下来它怎么用取决于你的需求。3. 核心使用指南从“会用命令”到“会改规则”3.1 四条高频命令先记住它们Superpowers 的命令不多日常最常用的就这几个。superpowers list # 查看当前启动的项目和模块 superpowers init # 初始化一个项目生成标准目录结构和规则文件 superpowers run name # 执行某个自定义任务 superpowers update # 更新脚本自身和模块模板superpowers list会显示当前目录属于哪个项目、已经加载了哪些模块。这个设计有点像按项目管理环境变量你在/home/user/work/demo里跑superpowers list它就能识别出这是 Java 项目并显示java模块以及对应的版本信息。superpowers run是我最依赖的命令。它相当于一个“任务运行器”。比如我可以自定义一个名为test的任务内部执行mvn test然后加一行提示“测试通过”。这样每个项目的构建命令都统一起来不用脑子里记住“这个项目用 gradle test那个项目用 mvn verify”。3.2 配置文件的层级关系理解 Superpowers 的配置方式要用“全局 项目 本地”三层模型去理解。全局层在~/.config/superpowers/config.yml定义通用的环境、别名和默认模块。项目层在项目根目录的.superpowers/config.yml定义这个项目的具体构建命令、运行方式、代码规范。本地层在.superpowers/config.local.yml通常被.gitignore忽略用来放个人不想提交的配置比如本地数据库连接串。读取优先级是本地覆盖项目项目覆盖全局。这样我可以在全局设置默认的 Java 版本在项目里固定成某个测试分支而本机又通过本地配置切到调试端口互不干扰。3.3 自定义一个任务不用改代码在项目.superpowers/config.yml里加一段这样的配置tasks: build: description: 编译整个项目 cmd: mvn clean package -DskipTests test: description: 运行测试 cmd: mvn test保存后直接在项目里执行superpowers run test。它就相当于替你把命令敲一遍但对团队来说这个文件提交到 Git 后新同事就不用再问“你们的测试命令是啥”了。这就是普通动作变成“超能力”的关键把人的经验沉淀成团队共用的文件。3.4 规则文件才是给 AI 用的核心Superpowers 最妙的地方是它会在项目里生成一个.superpowers/AGENTS.md文件。这个文件里写清楚了项目用什么语言、什么构建工具、代码风格偏好、禁止事项等。当你在项目里启动 Codex 时它会自动读到这份文件并按里面的规则来生成代码和做审查。我很早之前就发现同一个 Codex有没有项目规则文件输出质量差距很大。没有规则时它可能默认假设你是 Java 8然后给你生成 Lambda 之前的老写法有了规则后它就清楚知道项目是 Java 17、用了 JUnit 5、DTO 放application/dto包。这个差异相当于一个不熟悉团队的实习生突然被份入职手册工作质量自然不一样。4. Java 开发者的超能力组合Superpowers 怎么和 Java 项目磨合4.1 为什么 Java 项目单独拿出来说在 Java 生态里环境配置的坑实在太多了。JDK 版本、Maven 和 Gradle 的选择、Lombok 插件、JAVA_HOME指向每一个都可能导致项目在别人机器上跑不起来。Superpowers 对 Java 的支持不是为了取代 Maven 或 Gradle而是把“初始化一个 Java 项目”这件事规范化。我一般会这样创建一个新的 Spring Boot 项目mkdir ~/work/demo-service cd ~/work/demo-service superpowers init --template springboot它会替我生成pom.xml含 Spring Boot 3.x、Java 17 版本参数src/main/java/com/example/demo/DemoApplication.javasrc/test/java/com/example/demo/DemoApplicationTests.java.superpowers/config.yml.superpowers/AGENTS.md.gitignore。生成之后我可以直接mvn spring-boot:run跑起来。省掉的五分钟看着不多但一个月开三五个项目量就起来了。4.2 Java 多版本切换和 Superpowers 的联动Java 开发经常会遇到不同项目需要不同 JDK 的问题。Superpowers 不负责安装 JDK但它能和jenv这种版本管理工具联动。我在全局配置里写java: versions: - 17 - 21然后给某个老项目单独指定java: default: 17这样一来在项目目录下跑任何命令时Superpowers 都会先自动切换到配置指定的版本再执行后面的任务。这个效果很舒服你不再需要每次开项目前手动jenv local 17。4.3 结合 JUnit 5 和 Codex 做测试自动生成Java 项目的测试代码通常很套路比如 Service 层的 Mock 测试。用 Superpowers 的规则文件配合 Codex可以让 AI 按项目已有的测试风格生成新测试。我通常在AGENTS.md里加一段## Testing - Use JUnit 5 (Jupiter), Mockito for unit tests. - Test class should be in same package as target class, under src/test/java. - Use BeforeEach for setup, DisplayName to describe test intent. - Do not use SpringBootTest unless its an integration test.Codex 读到之后生成单测的命中率高很多。我也很少再看到那种只测了一个空构造器的假测试。这就是规则注入的价值不是约束而是给 AI 上下文。4.4 IDE 里的配合习惯我用 IDEA 比较多但不会在 IDE 里直接跑 Superpowers 脚本命令。我的习惯是把superpowers run配成 IDEA 的外部工具快捷键能调用。不过在终端里跑反而更清晰因为能看到完整的日志输出。这里给个小建议如果你团队里有人不熟终端就让他在 IDEA 的 Terminal 面板里跑反正效果一样没必要非折腾什么 GUI 插件。5. Codex 协作把 Superpowers 变成你的 AI 工作流引擎5.1 Codex 到底在什么环节发挥作用这里说的 Codex指基于大语言模型的辅助编码工具比如 OpenAI Codex CLI 或者其他类似终端里的编码代理。它的作用就是在你给出自然语言指令后帮忙修改文件、生成代码、跑测试。但 AI 工具的“智商”是浮动的它非常依赖输入上下文。Superpowers 在这里的意义就是帮你把上下文一次性准备好。它生成的那份AGENTS.md加上项目里的其他说明文档能在工作会话开始时被自动收集。启动 Codex 时它会读取当前目录下的.superpowers/AGENTS.md自动加入系统上下文。5.2 怎么把 Codex 接进来接入过程不复杂但需要做两件小事。第一在超级配置里启用 Codex 集成superpowers config set codex.enabled true这会确保在初始化项目时生成一个指向规则文件的符号链接让 Codex 能发现。第二在你的 Codex 配置文件比如~/.codex/config.toml里增加一句[project_context] addition_instructions .superpowers/AGENTS.md不同版本可能路径配置略有差异但只要指向项目里这个文件就对了。5.3 让 Codex 变成“懂规矩”的助手配置完成之后你在项目里运行 Codex 时它就像进入了一家已经办完入职手续的新公司。举个实际例子我让它“给 UserService 增加一个根据邮箱查找用户的方法”时它会去读UserService.java现有代码猜测你的返回类型、异常处理风格在相同包下新建UserServiceTest.java并写好 Mock不使用Autowired因为它知道项目用构造器注入方法命名遵循findByEmail而不是getUserByEmail。这些细节如果没有规则文件即便你说了“按项目风格”也很难指望 AI 稳定做到。每次都要重复提很烦而规则文件解决的就是这个重复。5.4 一个真实使用场景代码审查我经常用 Codex 做代码审查。在 Superpowers 里我定义了一个任务tasks: review: cmd: codex exec 审查当前分支的改动重点关注并发问题和潜在异常输出 markdown 报告每次写完一段代码就执行superpowers run review因为 Codex 能读到项目规则它审查时会知道哪些类是核心领域类、哪些属于基础设施不会在无关紧要的地方吹毛求疵。这份报告比我以前用通用 prompt 生成的靠谱得多。6. 我踩过的坑硬件没问题配置却让人抓狂6.1 更新脚本后配置冲突Superpowers 升级之后可能出现默认模板和你本地已有的自定义配置冲突。有一次我superpowers update结果把项目里的AGENTS.md模板升级了而我之前手动给它加了很多团队规范。升级一覆盖规则全乱套。后来我养成一个习惯每次项目初始化后任何对AGENTS.md的手动修改都先提交进 Git。升级前看一眼git diff确认模板变化不会影响自定义内容。如果确实有冲突就手动合并。Superpowers 并不会自作主张覆盖已有文件但多留个心眼总没错。6.2 JAVA_HOME 路径问题安装完 Superpowers 后如果执行superpowers run test提示找不到 Java但你的终端里明明能跑java -version十有八九是 Superpowers 执行命令时没有读到你的 shell 环境变量。这是因为某些.zshrc里的初始化逻辑用了交互式 shell 才加载的语句。解决方案是在全局配置文件里显式指定 Java 路径env: JAVA_HOME: /Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home PATH: $JAVA_HOME/bin:$PATH这个问题在 macOS 上尤其常见因为 Homebrew 安装的 OpenJDK 默认不带路径链接很多人会漏配。6.3 Codex 没有读取规则文件刚开始接入 Codex 时我发现它完全不理会我写的AGENTS.md。排查了很久发现是我在 Codex 配置里写路径的时候用了绝对路径但项目是克隆到不同目录的导致每次加载都失败。改成相对路径后就正常了。还有一个低级错误文件用.Superpowers开头Linux 上是区分大小写的Codex 找的是.superpowers小写目录。所以如果你的项目在 Windows 上初始化的同步到 Linux 上很可能路径对不上。6.4 安装脚本被防火墙拦有段时间我在公司内网环境安装curl 脚本下载被安全策略拦截。这不是什么复杂问题也不用走什么特殊通道。我当时的做法是把安装脚本下载到本地人工审计一遍确认没有任何危险操作后再手动执行。这个方法也建议每个团队都做一次对开源安装脚本先看后跑永远是好习惯。curl -fsSL https://install.superpowers.dev/install.sh -o install.sh less install.sh # 人工检查 bash install.sh6.5 多模块仓库的路径感知我维护过一个多模块 Maven 工程根目录下套了好几个服务。Superpowers 默认按当前目录查找.superpowers配置因此如果你在子模块的目录里执行superpowers run test它可能找不到根模块的配置。解决办法是在根目录里建一份supers配置并在每个子模块的.superpowers/config.yml里设置parent: ..。这样一级级向上查找最终能定位到根模块。如果不想逐级手动设置可以直接在~/.config/superpowers/config.yml里配置不在目录层级查找但那样会丢失项目的精细隔离我的建议还是老老实实维护好每个项目一层配置文件。7. 我的扩展思路把 Superpowers 变成团队规约的载体7.1 除了编码还适合承载文档规范Superpowers 不只是给 AI 用的。我在实际的团队协作里还会把一些容易扯皮的“软约定”写进规则文件里比如提交信息必须以feat:、fix:、refactor:开头代码 review 时优先看异常处理路径接口文档必须写明错误码含义。这些内容放进AGENTS.md后Codex 在生成代码时会顺带遵守这些规范人也看得见。与其在群里反复提醒不如让工具链直接执行。7.2 与 CI 流程结合我把superpowers run review集成到 CI 的一个额外 job 里每次推送都自动跑一次 AI 审查。虽然不能完全替代人工 review但能很快发现一些遗漏的空指针风险或未处理的返回值。成本很低收益却很明显。7.3 模板仓库的复用每个团队其实都有自己的“常见项目骨架”。Superpowers 的模板不是死的你可以把生成的项目提交到仓库作为模板分支。新项目直接拷贝模板省得更彻底。这就是把一次初始化变成无限次复用。个人经验小结Superpowers 这东西你把它当成一个普通工具去搜教程其实也就是几条命令和几个配置文件的事。但真正让它产生价值的是你在使用过程中一步步往里面添加自己的规范和经验。我前后折腾了快半年最明显的感觉是我不再需要在每个新环境里重复摸索AI 生成的代码也终于能看了。如果你恰好也是整天和环境配置、AI 辅助编码打交道的人我建议你从最简单的init --default开始把你最常用的一两个项目初始化跑通然后再逐渐把团队规范融进去。这条路踩不了几次坑你就再也回不去纯手工时代了。