你有没有过这种经历在终端里打开 Codex新建一个会话然后花了十分钟把项目背景、技术栈、代码规范、本次需求重新讲一遍。等它终于进入状态你发现上一次踩过的坑又踩了一遍因为 AI 完全没有记忆。我最近一直在折腾一套叫superpowers的命令行技能包说白了就是给 Codex 这类终端 AI 编程助手加装的一套可复用能力层。装完之后最大的感受是终于不用每次从零开始教 AI 做人做事了。这篇文章我直接把安装过程、核心机制、Java 项目里的实战用法以及我踩过的几个坑完整写出来希望对正在研究 Codex 增强玩法的朋友有点参考价值。无论你是刚听说这个概念的小白还是已经在终端里玩了一阵子 Codex 的老手这篇文章都能给你一些能直接抄作业的东西。1. superpowers 到底是什么给 AI 编程助手装一套技能大脑1.1 一个让我决定折腾它的场景先说个实际场景。我手上有个维护了两年的 Java 老项目代码里充满了各种历史包袱命名不规范、utils 类堆了三千行、controller 层到处是重复的参数校验。某天领导让我重构其中一个模块我打开 Codex 想让它帮忙分析代码结构结果它在没有上下文的情况下给出了非常教科书的建议——比如建议使用设计模式优化这种正确的废话。后来我把自己的重构规范和代码约定贴进去效果立刻好了很多。这件事让我意识到一个核心问题Codex 本身是一个很强的执行引擎但它默认是无状态的。每次会话它只从当前对话里理解需求你不知道的上下文它也不知道。superpowers 解决的正是这个痛点——它把如何理解一个项目如何遵循你的代码规范如何执行一次标准的重构流程这些知识打包成一套可复用的技能组随时注入到 Codex 的会话上下文里。1.2 它的核心定位不是替代 Codex而是给 Codex 加外设从技术架构上看superpowers 做的事情其实不复杂它维护了一套技能声明文件和命令模板在你启动 Codex 时自动加载进去相当于给 AI 助手预先装备了一套操作手册。打个比方原生 Codex 像一个刚入职的天才程序员聪明但不懂你们公司的规矩superpowers 就是这个程序员入职第一天拿到的新人手册——里面有编码规范、常用命令、团队约定、项目结构说明。这里要特别强调一点superpowers 本身不调用任何模型也不代替你写代码。它是一层配适层最终执行的还是 Codex 背后的模型能力。所以你可以把它理解成一个Prompt 编排系统 工作流模板库价值和具体代码生成质量无关而在于让 Codex 每次都在正确的上下文里思考。1.3 哪些人值得花时间研究它日常重度使用 Codex 的开发者如果你每天在终端里和 Codex 打交道超过半小时配置一次 superpowers 的回报率非常高。团队技术负责人可以把团队的编码规范、评审要点、发布检查清单固化到技能组里新老成员共用同一套 AI 协作标准。正在做 Java 等语言老项目维护的人这类项目上下文复杂特别需要技能包来补充背景知识和约定。反过来如果你只是偶尔让 Codex 写个正则表达式、解释一段代码那确实用不上它装完大概率还会觉得配置过程有点繁琐属于低频需求配不上高投入。2. 安装与首次配置把 superpowers 跑起来的完整过程2.1 环境准备先确认你的 Codex 版本在动手之前先确认基础环境。superpowers 的安装前提是你本地已经有一个能正常工作的 Codex CLI 环境。我测试时的环境是 macOS zshNode.js 版本 18Codex CLI 的版本在 0.x 的较新版本上。如果你是用 Windows大部分操作是等价的只是路径分隔符和 shell 写法稍有差异。验证 Codex 是否可用直接在终端执行codex --version如果你还能看到版本号输出说明环境基本 OK。这一步不能省我见过不少朋友装完 superpowers 说没效果最后发现是 Codex 本身就从来没跑起来过。2.2 获取项目并安装复制粘贴级别的操作superpowers 本身是一个开源命令行工具安装方式通常是直接把仓库克隆到本地然后执行安装脚本让它自动识别 Codex 的配置目录并建立链接。# 1. 克隆仓库到本地建议放到一个固定的工具目录里 git clone https://github.com/你的仓库路径/superpowers.git ~/tools/superpowers # 2. 进入目录查看安装说明 cd ~/tools/superpowers ls -la # 3. 执行安装脚本指定 Codex 配置目录默认是 ~/.codex ./install.sh --codex-dir ~/.codex安装脚本做的事情一般就是三件备份你现有的 Codex 配置以防万一、把 superpowers 的技能目录软链到配置目录下、往配置文件里追加一段加载技能组的声明。所以整个过程是可逆的出现任何不适可以直接删掉软链、还原备份。如果你不想跑脚本也可以纯手动。以常见的~/.codex目录为例你只需要做两件事一是把仓库里的skills/目录拷贝到~/.codex/skills二是在config.toml里加入一行指向技能目录的配置。手动方式的好处是你能完整知道每一步发生了什么坏处是升级 superpowers 时容易漏文件所以我个人还是推荐脚本方式。2.3 验证安装一行命令确认全家桶就位安装完不要急着开干先验证一下技能组有没有被正确加载。superpowers 一般会提供一个自检命令或者你直接启动 Codex输入/看看命令列表里有没有多出技能相关的项。# 在 Codex 会话里输入下面这个命令看是否有技能列表输出 /skills如果输出里列出了java-refactor、code-review、commit-message这类技能名就说明安装成功了。我当时的自检输出里大概有十几个技能组扫一眼就能确认哪些是默认启用的。2.4 安装过程中最容易翻车的三个地方配置目录找错有些人用的是旧版 Codex配置目录在~/.config/codex而不是~/.codex脚本如果默认写死路径就会装错位置。解决办法是先用codex login或codex init看一眼实际生成的目录在哪里。软链权限问题在某些受限环境里创建软链会提示权限不足。一般加sudo能解决但如果你不想让工具目录变成 root 所有可以改为直接拷贝代价是升级时麻烦一点。版本兼容性我遇到过安装完技能组后Codex 启动报 unknown command 的情况后来发现是 Codex 版本太老不支持配置文件里的某项设置。遇到这种问题别急着骂脚本先看 Codex 的更新日志把 CLI 升级到较新版本再试。3. 核心机制拆解技能、命令、上下文三件套3.1 技能组Skills把做事的经验结构化superpowers 最核心的抽象是技能组。一个技能组可以理解成一份针对特定任务的完整操作指南里面不只有 Prompt还会有几个子步骤、注意事项、输入输出规范。举个例子一个java-refactor技能组可能包含以下内容先分析代码结构、识别坏味道、给出重构方案、分步骤执行、最后运行测试验证。整个流程会被组织成结构化的说明Codex 在需要时按步骤执行。技能组的文件通常用 YAML 或 Markdown 编写格式类似name: java-refactor description: 对 Java 老旧代码进行安全重构的标准流程 steps: - 扫描目标类的依赖和调用关系 - 识别重复代码、过长方法、循环依赖等坏味道 - 生成重构方案并列出风险点 - 按最小粒度逐个实施重构 - 运行项目测试确保行为无回归这样做的好处是技能不再是藏在开发者脑子里的经验而是可以被任何 Codex 会话调用执行的公共资产。团队里的高级工程师把经验沉淀成技能文件初级工程师也能让 AI 按同样标准干活。3.2 命令组Commands你的终端快捷键除了技能组superpowers 还会注入一批斜杠命令。这些命令和技能组的关系是命令是入口技能组是内部逻辑。比如你输入/reviewsuperpowers 就去调用code-review技能组自动把项目规范、评审清单注入上下文然后让 Codex 按清单对当前改动做审查。我实际使用中比较高频的几个命令/review对暂存区或当前分支的改动做代码评审输出问题列表和修改建议。/explain让 Codex 结合项目背景解释一段代码而不是只做字面翻译。/refactor调起重构技能组分步骤对目标代码做安全重构。/commit根据 diff 内容生成符合团队规范的提交信息。这里要注意命令是可以叠加的。比如我先/explain理解了一段逻辑再接着/refactor让它重构整个会话上下文是连续的前一命令产出的结论会被后一命令当作输入依据。这个特性在复杂任务里价值非常大。3.3 上下文管理AI 的记忆是怎么实现的这可能是 superpowers 最容易被忽略、但我认为最值得研究的部分。现代对话式 AI 的上下文窗口是有限的你不可能把整个项目都塞进去。superpowers 的做法是通过技能声明精准地把与当前任务最相关的项目信息加载进来。具体机制我拆成三点来看静态上下文在会话开头注入项目全局约定比如语言版本、目录结构、代码风格。动态上下文根据用户输入的命令和参数按需加载某一部分细节比如重构某个类时才读取这个类的依赖关系。持久化上下文把上一次会话的结论写到本地文件下次会话开始时可以恢复实现跨会话记忆。真正跑起来之后你会发现AI 变得像是一个真正参与过项目的人而不是每次失忆的新同事。3.4 定制自己的技能文件动手扩展一套私有技能默认技能组是通用的但实际工作中你一定会有自己的偏好。我建议每个人、每个团队都维护一个私有技能目录。做法很简单在技能目录里新建一个.md文件把你希望 Codex 遵循的事写清楚。我举个例子。我们团队有个约定提交信息必须用英文且要包含模块前缀和工单号。我写了一个名为team-commit-policy的技能文件# Team Commit Policy - 提交信息使用英文 - 格式: [Module] Short description (#ticket-id) - 示例: [auth] fix token refresh race condition (#3241)写完后不需要重新安装重启 Codex 或者重新加载配置即可生效。这个能力意味着 superpowers 本质上是一个可以持续积累的组织知识库用得越久你的 AI 就越懂你的团队。4. Java 项目实战在终端里用 superpowers 完成一次模块重构4.1 我选了一个什么样的任务光讲机制有点空洞我拿一个真实做过的 Java 任务来演示。目标模块是一个订单服务里的OrderValidator类700 多行里面塞了库存校验、用户状态校验、优惠券校验、收货地址校验全部堆在几个大方法里。这个类长期被业务方抱怨改一处崩三处典型的坏味道集中营。我选这个任务有两个原因一是 Java 重构是个非常需要项目上下文的工作如果 AI 不了解模块边界和依赖关系给出的方案基本没法用正好检验 superpowers 的上下文注入能力二是这个任务可量化重构前后有测试用例可以做回归验证效果一目了然。4.2 实际操作过程从技能调用到测试回归第一步先让 Codex 加载java-refactor技能并分析目标类/refactor --target src/main/java/com/order/validator/OrderValidator.javaCodex 在技能组的引导下先扫描了类的依赖关系列出了所有调用方并输出了一个初步评估该类当前承担了四类校验职责方法平均长度超过 80 行且存在大量重复的参数判空代码。它把重构方案分成三步提取校验策略接口、按职责拆分策略类、用枚举或工厂统一注册。第二步我没有直接让它动手改而是先让它生成一份重构安全性检查清单。这一步得益于技能组内置的风险控制步骤Codex 列出了需要关注的兼容性问题比如某些外部调用直接依赖了OrderValidator的 public 方法签名拆分后需要保留兼容层。这些信息如果靠我口述至少要多花十分钟。第三步确认方案后让它按最小粒度逐类实施。Codex 一次只抽出一个校验职责到一个新类中每完成一步就跑一次项目测试。整个重构过程被拆成了 9 个提交每个提交都有明确的说明。最终测试全部通过OrderValidator从 700 多行降到了 120 行左右。4.3 Java 场景下的几个特定技巧用了一段时间 superpowers 跑 Java 项目我总结出几个针对性的小技巧普通通用教程里不太会写技巧一让技能组先读 pom.xml 再动手Java 项目里依赖版本和构建配置直接决定你某些手段可不可行比如能不能用某个库的 API。我会在技能文件里加一条强制约定任何任务开始前的第一步必须读取pom.xml或build.gradle确认项目使用的 Java 版本、构建工具和关键依赖。这条约定让 AI 少犯用了项目里根本不存在的库这种低级错误。技巧二利用 Maven 或 Gradle 测试输出校准 AI 的行为重构类任务最怕行为回归。superpowers 的java-refactor技能组里如果加入了每个步骤后执行mvn test -Dtest相关模块AI 就能在改错的瞬间发现问题而不是累积到最后爆一个巨大的错误列表。在终端里我实际感受是单步测试确实拖慢了速度但对比重构完根本跑不起项目的情况这点时间成本完全可以接受。技巧三自定义一个项目地图技能Java 老项目往往目录层级深包名又长AI 很容易迷失。我自定义了一个project-map技能让 Codex 在会话开始时输出当前模块的目录树和核心类的职责说明。有了这张地图后续任务出现时 AI 能更快地定位到相关代码位置也不会在无关的地方翻来翻去。4.4 实际效果值得花这一个下午配置它这次重构我全程在终端里操作没有打开 IDE。配置 superpowers 花了一个下午真正用来重构的时间是两天里断断续续的几个小时。如果让我自己手工做我估计要一周因为拆类和兼容层设计太耗精力。虽然一次性配置成本确实存在但我只需要做一次后续所有 Codex 会话都能受益。5. 高频问题排查三个踩坑实录与完整解决链路5.1 技能加载不生效配置没进对目录第一次装完我兴冲冲开了个新会话输入/skills结果提示未知命令。排查过程是这样的先确认安装脚本有没有改动 Codex 配置文件结果发现config.toml里根本没有加载技能的字段。原来安装脚本拿到的是一个旧的配置路径而当前 Codex 读的是新路径。解决链路很简单先找到当前 Codex 真正读取的配置目录然后手动把技能目录路径加进去。这个坑的教训是永远不要盲目信任安装脚本对你的环境的假设装完第一步必须是验证实际加载情况而不是看脚本输出几个 success 就放心。5.2 命令冲突我的/commit被拦截了另一个让我头疼的问题是输入/commit时调出来的不是我自定义的技能而是某个内置的默认命令。我排查了很久最后发现是配置加载顺序的问题——superpowers 的技能命令被加载在默认命令之前但某些默认命令的优先级更高覆盖了同名的技能命令。解决方法是改技能命令的名字或者调整配置文件里的加载顺序让自定义命令排到默认命令后面。这个事给我一个启发命令命名要留前缀空间比如我后来把所有私有命令都改成了带模块前缀的格式比如/sp:commit彻底避免了和生态内其他命令撞名。5.3 上下文过长技能包太厚让响应变慢有一次我配置了十几个技能组全开会话后 Codex 的响应明显变慢而且经常答非所问。原因是所有技能描述的文本都被塞进了上下文挤占了大模型的注意力空间。排查后发现默认加载的技能数量过多和注入上下文的初衷背道而驰。解决方案是设置技能组的懒加载策略只把高频基础技能设为全局加载其他技能通过命令触发时才注入。调整后响应速度恢复正常而且其实大多数任务只需要少数几个技能没必要全量常驻。5.4 顺带回答一个热搜里的问题worbuddy 怎么用 superpowers最近总在热搜和社区里看到有人问 worbuddy 怎么用 superpowers。我一开始也很懵后来才明白大家在问什么worbuddy 是另一款偏向团队工作流管理的工具有人想把 Codex 的 superpowers 技能包引入到 worbuddy 的流程里让 AI 在团队协作场景下也用上这些技能。我的看法是如果你用的是这类工作流管理工具核心思路不是让 worbuddy 去执行技能而是让 superpowers 的技能声明文件成为中间格式——在 worbuddy 里录入一条任务时把技能名和命令参数写进去真正执行时由 Codex 按技能组完成。这和把规则沉淀成配置让实际执行层去调用是一个思路。具体到 worbuddy 怎么配置不同版本差异较大建议你按照外部命令输入的入口去查找一下它的集成文档然后把 superpowers 的命令行路径填进去一般就能跑通。5.5 排查工具本身的思路如果你遇到的是从未见过的新问题我的通用排查路径是先关闭所有技能组跑一次 Codex确认问题是否由 superpowers 引入再逐步开启技能组做二分定位直到找出有问题的那个技能最后检查技能文件本身的语法和路径引用。这套思路适用于绝大多数问题不需要靠猜。6. 写在最后我的使用习惯和一些建议文章到这里superpowers 是什么、怎么装、核心机制、Java 实战、踩坑记录都写得差不多了最后分享一点我自己的使用心得。我现在每天在终端里的工作流已经离不开这套技能组了早上打开电脑先开一个 Codex 会话让它加载project-map看一眼项目当前状态然后根据当天任务调用对应的/refactor、/review或/explain。周末我会花十几分钟维护技能文件把这一周学到的项目经验沉淀到技能组里。这件事坚持了两个多月最大的感受是AI 的使用体验不是由模型决定的而是由你给它的上下文品质决定的——superpowers 就是那个把上下文品质变得稳定的工具。如果你也想折腾我给你三个建议第一不要一次配置太多技能从两三个最常用的场景开始跑顺了再加第二团队使用的话技能文件一定要放进版本管理让所有人共用一套配置第三给自己的私有技能建立统一命名规范你后