我最早看到 superpowers 这个词是在一堆英文 issue 讨论里当时没太当回事。真正决定上手是在一次给老 Java 系统做模块拆分的时候。那段时间我重度使用 Codex CLI命令能跑、代码能生成但总觉得差在最后一步它不熟悉项目的构建规范不熟悉接口命名习惯也不知道哪些目录绝对不能乱动。superpowers 解决的就是这件事。它不是把 AI 模型换掉而是在 AI 后面挂一层可维护的“项目常识层”用技能包和规则文件告诉代理该怎么工作。如果你也遇到过以下情况这篇文章应该能帮你省不少折腾时间每次开新会话都要重新粘贴项目规范换个目录 AI 就“失忆”团队里每个人调教出的 Codex 风格完全不一样。这篇文章我会从安装、初始化、Java 技能包配置到日常使用流程和排错链路完整分享一遍我的实操记录。内容基于我自己的反复测试尽量把能直接抄作业的命令和配置都写在下面。1. 为什么我会在 Codex 之外再装一套 Superpowers先说结论superpowers 解决的不是“能不能用”的问题而是“好不好用”的问题。Codex CLI 本身已经能完成不少编码任务但它是通用模型对具体项目的业务约束、代码风格、目录结构一无所知。你每次开始干活都得花大量提示词去“教育”它。我用了一段时间后明显感觉到自己变成了一个翻译器把项目文档翻译成提示词再把 Codex 的话翻译回项目语境。superpowers 的定位就是帮你把这一层翻译工作固化下来。1.1 裸 Codex 的最大问题会话即失忆CLI 工具本身并没有长期记忆每次新会话都是一张白纸。哪怕你在上一个会话里明确说过“所有 Service 层必须面向接口Controller 不做业务逻辑”下一个会话只要换个目录它又会按最普通的方式写出带业务逻辑的 Controller。我实测的例子一个 Spring Boot 项目里裸 Codex 生成的代码经常把Transactional直接放在 Controller 方法上还把异常处理散落到各个业务方法里。不是我要求高而是项目里早就有现成规范事务必须放在 Service 层异常必须走全局处理器。这些规范写在 README 里但每次都要重新告诉它实在太累。superpowers 把这类规范写进技能包后Codex 每次调用前都会主动加载对应规则效果基本等同于“AI 会长久记忆了”。1.2 什么时候该上 Superpowers我也不是一开始就推荐所有人装。如果你只是拿 Codex 写点临时脚本或者代码随手一丢不维护那确实没必要。但如果你满足下面任意两条我建议你认真考虑一下项目有明确的分层结构、命名规范和模板代码希望 AI 每次生成都符合这些规范团队里多个人共用同一个 CLI 工作流想统一提示词和代码风格经常要跨目录、跨项目切换希望在切换后 AI 能自动理解新项目的上下文有固定的任务模板比如“写接口”“加数据库迁移”“修测试失败”希望 AI 能按模板执行。我当时主要的需求是 Java 项目的日常开发。所以后面整个配置过程我都以 Java 技能包为主线来展开其他语言用法逻辑是相通的。2. Superpowers 安装与初始化两条路都走了一遍安装这部分我踩过不少小坑尤其如果你机器上同时有多个 Node 版本、多个包管理器很容易装出一个“看着成功实际命令不存在”的假象。下面是我完整跑通的两条路任选其一都行。2.1 前置准备先把环境理顺superpowers 本质上是基于 Node.js 的 CLI 工具所以环境里必须有 Node 和 Git。版本上我实测 Node 18 以上都正常Node 16 也能跑起来但部分技能包的模板解析器对中文路径支持不太好所以建议能升就升。检查方法node -v npm -v git --version如果你本机装过多个 Node 版本比如用 nvm 或 fnm 管理这里有个容易踩坑的点superpowers装到哪个 Node 版本下启动时就必须用同一个版本。我一开始用 nvm 默认版本装了全局包后来又切换到另一个版本跑命令结果提示superpowers: command not found。这不是工具问题而是 PATH 没指向当前 Node 版本的全局目录。另外Git 的用途不是托管代码而是技能包仓库。安装技能包时工具会从远端仓库拉取对应的模板和规则文件。如果你处于离线环境或者 Git 拉取受限安装技能包会卡住。这种情况我在 5.1 节专门讲。2.2 安装命令与首次初始化全局安装很简单npm install -g superpowers安装完成后先看版本确认真的装上superpowers --version如果这一步报错说明全局 bin 路径不在 PATH 里把 Node 全局目录加进去就行。装好之后第一次使用前必须初始化它会生成配置文件、技能缓存目录和日志目录superpowers init初始化过程会问几个问题包括默认的工作目录、默认模型、是否开启自动技能匹配。我的建议是第一遍先用默认配置跑起来等熟悉之后再修改。别一开始就想着把所有选项都配完美否则很容易被配置文件搞晕。初始化完成后可以用一个简单命令验证核心链路是否正常superpowers doctor这个命令会检查配置、技能目录、日志目录的读写权限以及 Codex CLI 是否在 PATH 里。我自己的经验是doctor不是简单显示“OK”它会把每项检查的来源路径和可能的问题列出来值得仔细看一遍。2.3 安装后的目录结构不看会后悔初始化完成之后你会得到这样一个目录结构~/.superpowers/ ├── config.json ├── skills/ │ ├── builtin/ │ └── custom/ ├── templates/ ├── logs/ │ └── runtime.log └── cache/config.json是核心配置文件控制所有默认行为。skills/builtin放的是工具内置技能skills/custom放团队或自己写的技能。templates是代码模板目录Java 项目骨架通常就来自这里。logs目录看起来不起眼但后面排错全靠它。我建议你像看自己家的水电表一样至少读一遍config.json。因为里面有几个字段对工作流影响很大特别是技能匹配的白名单和黑名单。配置文件长什么样我会在后面 Java 部分展开。3. 给 Java 项目配置技能包从模板到自定义规则Java 技能包是我觉得最能体现 superpowers 价值的部分。Java 项目天然就爱讲规范分层、命名、依赖管理都有约定这些约定恰好是“规则文件”最擅长表达的。我把 Java 技能包装好之后Codex 生成代码的质量提升非常明显至少不会再把Autowired写在私有字段上。3.1 Java 技能包里到底有什么安装 Java 技能包可以直接用命令superpowers skill add java如果还想用 Spring Boot 相关的脚手架模板还可以加superpowers skill add java-spring装完之后在~/.superpowers/skills/custom/java/下面会看到一组 Markdown 文件这些就是技能包本体。它们不是代码而是给 AI 看的“操作手册”。我挑几个核心文件说一下文件作用rules.md项目通用规则比如分层规范、事务边界、异常处理约定api.md接口设计规范比如 URL 命名、参数校验、统一返回体build.md构建流程说明比如 Maven 还是 Gradle多模块怎么处理spring-template.mdSpring Boot 项目骨架模板的调用说明task-templates.md常用任务模板比如“新增一个查询接口”“写一个定时任务”这些文件不是摆设每次 Codex 调用时只要任务关键字匹配到java或springsuperpowers 就会把对应内容作为上下文注入。所以你在里面写什么AI 就按什么干这比在对话里反复强调规范要稳定得多。3.2 按照项目规范调整规则文件技能包安装完是不能直接照搬的。默认规则是通用 Java 规范不一定符合你们团队的习惯。比如有的项目用 Lombok有的项目明确禁用 Lombok有的项目用Result统一返回有的项目直接返回ResponseEntity。这些差异必须写进rules.md里否则技能包只是“有”而不是“适配”。我在rules.md里加过这么一段- 所有 Controller 层类命名以 Controller 结尾只负责参数接收和响应返回 - 业务逻辑禁止出现在 Controller事务和业务逻辑必须集中在 Service 层 - DTO 入参必须使用 javax.validation 注解禁止手写参数校验判断 - 数据库操作必须通过 Mapper 接口禁止在 Service 里直接用 JdbcTemplate - 禁止在循环中调用远程服务如需调用需批量处理或异步聚合。改完之后重新运行一次技能加载或者用superpowers cache refresh刷新缓存。否则修改内容可能不生效。这个细节很容易被忽略我就因为没刷新缓存多折腾了半天。3.3 用模板直接生成 Spring Boot 骨架配置技能包之后生成一个新的微型服务特别快。以前我会手工照网上教程搭项目或者从一个老项目里复制出来改现在可以直接用 superpowers 的模板机制。superpowers generate java-spring --name order-service --package com.example.order这个命令会生成一个 Spring Boot 工程的完整骨架结构大概是order-service/ ├── pom.xml ├── src/main/java/com/example/order/ │ ├── OrderApplication.java │ ├── controller/ │ ├── service/ │ │ └── impl/ │ ├── mapper/ │ ├── dto/ │ └── config/ ├── src/main/resources/ │ ├── application.yml │ └── mapper/ └── src/test/java/骨架不等于完整业务我拿到之后通常还会让 Codex 按task-templates.md里的接口模板去补具体接口。但底子是对的分层、包结构、基础依赖都符合技能包规则省去了最开始那段最容易写乱的搭建工作。4. 实测 Superpowers 的日常使用流程配置完成之后真正的重头戏是日常使用。很多朋友以为 superpowers 是一个独立对话工具其实不是。我的用法是把它当作 Codex CLI 前端的“增强层”启动时自动加载技能上下文然后在同一个终端里继续自然的编码对话。4.1 我跑通的日常流程我现在的习惯是每接一个任务就在项目目录下启动一次新的 Codex 会话但启动之前会额外跑一条命令superpowers attach --project ./ --skill java-springattach是 superpowers 提供的核心命令之一作用是扫描当前项目目录结构匹配对应的技能包并把技能内容注入到 Codex 的会话上下文里。执行之后会有一段回显告诉你当前命中了哪些技能、加载了哪些规则文件、最后生成的上下午文大概多大。如果回显里没有出现java-spring说明技能匹配没成功得排查原因。进入会话后我给 Codex 的描述方式也会有些变化。比如现在我不会说“写一个订单查询接口”而是直接说按 task-templates 里的查询接口模板给订单模块加一个分页查询接口 返回结果用统一 Result 格式Mapper 用 XML 方式写完补一个基本的单元测试。因为技能包已经把大部分细节写进规则所以描述可以精简到“做什么 按哪套模板”不需要再重复“Controller 还是 Service”“要不要校验”“测试写在哪”这类信息。从实际效果来看这比纯靠临场提示词要稳定太多。4.2 给 Codex 的指令我刻意加了三类约束用了一段时间后我发现如果你想在 CLI 工作流里把 superpowers 的优势发挥到最大提示词不能只告诉它“做什么”还要告诉它“边界在哪”。我一般会额外加三类约束第一类叫“位置约束”。明确指定生成文件放在哪个包、哪个目录甚至文件名都讲清楚。AI 一旦自由发挥路径后面合并代码时就会出现一堆不该出现的文件。第二类叫“风格约束”。虽然技能包里写了规范但实际生成时仍可能被模型偏好带偏。比如团队约定接口 URL 用中划线模型却喜欢下划线这时候我就在提示词里加一句“URL 命名遵守 skills/rules.md 中的 api 规则”。第三类叫“改动约束”。如果是改已有代码最好说“只改动 Controller 层不动 Service 实现”或“不要重构现有命名”。没有边界限制的 AI 改代码可能顺手给你重写半个类这是我最头疼的情况。4.3 有技能包和没技能包的差别我用一个例子说话为了验证 superpowers 的效果我做过一次对照测试。同一个 Java 项目、同一个需求“新增一个带分页的用户查询接口”分别用裸 Codex 和带 java-spring 技能包的 Codex 生成。裸 Codex 生成的结果是Controller 里直接写了UserMapper注入分页逻辑写在 Controller 方法里返回对象直接用了实体类User没做 DTO 转换。从功能上讲代码能跑但从项目规范讲这代码很难不被人反推。带技能包的版本则是Controller 只负责接收PageQuery参数并调用UserService.queryPage(...)Service 里做了参数校验、调用了 Mapper 的分页方法返回的是PageResultUserVO异常统一交给全局处理器。最让我惊讶的是测试文件和 SQL 片段也一并生成了虽然测试写得比较简单但骨架是对的。这个对照让我彻底把 superpowers 当作日常必备工具而不是锦上添花的玩具。5. 我在实际使用中遇到的三个坑附排查链路工具再顺手也免不了出问题。下面这三个坑是我自己真正踩过的我把排查链路完整写出来希望能帮你少走弯路。5.1 坑一技能加载卡在 skill matching有一次运行superpowers attach回显一直停在matching skills...等了十几秒没反应。当时我第一反应是网络问题因为技能包远端仓库需要联网但反复 ping 又完全正常。后来我看logs/runtime.log发现日志里有很多条关于git ls-remote超时的记录。问题出在 superpowers 匹配技能包时会先去远端 Git 仓库检查技能包是否有新版本而这个检查过程在特定网络环境下很慢导致超时。解决方法是给匹配过程加上本地优先配置{ skillMatch: { mode: offline-first, remoteCheckTimeout: 3000 } }offline-first会让它优先读本地cache目录里的技能包缓存命中后就不再等远端。改完之后卡顿问题几乎没再出现过。如果你也遇到加载卡住千万先去看日志文件别急着卸载重装。5.2 坑二Java 模板生成的代码和本地 JDK 版本对不上Java 技能包自带的 Spring Boot 模板默认用的是 Java 17而我本地项目环境是 Java 11。结果生成出来的代码里用了不少record、var和switch新语法放进老项目一编译就报错。这个问题的根因在模板文件不在超能力本身。我打开~/.superpowers/templates/java-spring/pom.xml看到java.version写死成 17。我把它改成 11同时把 Spring Boot 版本从 3.x 降到 2.7.x因为 Spring Boot 3 最低要求 Java 17。改完之后我还需要在spring-template.md里补充一段说明本模板基于 Java 11 和 Spring Boot 2.7 构建 生成代码时禁止使用 Java 11 以上新增语法如 record、var、switch 表达式 时间日期统一使用 java.time 包避免使用 java.util.Date。这样 AI 在生成代码时就会主动避开高版本语法。这个告诫写完后重新生成的代码基本能直接编译通过。遇到版本不符先改模板再改规则描述两步都要做少一步都会复发。5.3 坑三跨项目配置互相污染我在项目 A 里定制了 Java 技能包写了很多针对电商系统的规则比如“订单模块禁止使用分布式事务”之类的。后来在项目 B 里也用了同样的技能包生成代码时就把项目 A 的规则带过来了项目 B 根本不需要这些约束甚至和项目 B 的设计冲突。superpowers 的技能包分为全局和项目级两种全局的放在~/.superpowers/skills/custom/项目级的放在项目根目录的.superpowers/skills/。如果不想互相污染项目特有的规则应该放到项目级目录里别图省事直接塞全局。我给项目 B 建了自己的技能目录/path/to/projectB/.superpowers/ ├── skills/ │ └── java-local/ │ ├── rules.md │ └── api.md └── config.json然后在项目 B 里运行 attach 时指定项目本地技能superpowers attach --project ./ --skill java-local这样项目 B 就不会再加载全局那份电商专属规则。如果你发现 AI 的行为“莫名其妙地符合上一个项目的习惯”八成就是技能包串了按这个思路去查准没错。6. 几个值得长期坚持的进阶用法到这里superpowers 的基础使用和排错就完整了。最后分享几个我目前还在用的进阶玩法算是给这篇文章收个尾。第一个是把技能包当团队文档用。以前新同事上手项目要看 README、架构文档、代码规范信息都在不同地方容易遗漏。我后来把服务分层、接口约定、数据库访问规则都整合进rules.md再让 superpowers 在任何新会话里自动加载。这样 AI 的生成风格稳定新同事看代码时也会发现“每个类都长得很像”项目可维护性提高得很快。第二个是把自己的技能包版本化。我会把~/.superpowers/skills/custom/目录纳入 Git 仓库每次规则修改都提交一次并写上原因。这个做法特别好用比如某次 AI 生成风格突然变奇怪我可以直接 Git 看规则差异找到是哪条配置改出来的问题回滚也只需要一条git revert。技能包本质上就是代码该有版本管理就必须有。第三个是善用superpowers cache refresh。如果你发现改了技能包AI 还是按旧规则干活十有八九是缓存没刷新。刷新之后重启 Codex 会话这个问题基本能解决。另外社区里也有人问“WordBuddy 这类文档或文字处理相关的工具能不能接 superpowers”原理上和 Codex 一样只要对方支持外部注入技能文件或上下文提示你就把对应的规则文件导出成普通文本放进去不需要等官方适配。总之先把当前这个项目用顺再做扩展比一开始就追求全场景覆盖要靠谱得多。