★ FEATURED ARTICLE 1. Superpowers 到底是做什么的先聊聊 Codex 的“哑巴”痛点如果你用过 OpenAI Codex CLI大概率遇到过这种情况明明是同一个需求换个说法它就能听懂换个说法它就彻底“失忆”。比如你让它“给这个 Controller 加个参数校验”它可能给你写出一堆完全不符合项目规范的代码。这不是模型不够聪明而是 Codex 默认状态下只知道“怎么用代码回应”并不知道你的项目里有哪些约定、哪些文件必须遵守、哪些历史包袱不能碰。Superpowers 解决的就是这个问题。它本质上是一个面向 Codex CLI 的技能库skills library把你在日常开发中反复叮嘱模型的那些“规矩”做成了结构化的技能文档。安装之后Codex 在开始干活前会先读取这些文档像入职培训一样理解你团队的编码规范、提交信息格式、测试要求再做具体任务。我第一次接触 superpowers 这个项目时最大的感受是它不是给 Codex“加功能”而是给 Codex“补常识”。默认的 Codex 像一个天才但莽撞的新人Superpowers 则是老员工整理出来的工作手册。两者结合之后代码质量、commit 规范、错误处理这些“软素质”明显提升你敢让它干的活也越来越多。这篇博文适合谁如果你正在用 Codex CLI但觉得它在真实项目里“差点意思”或者你听过 superpowers 但不知道它怎么和 Java 项目结合这篇文章能帮你把安装、配置、实战链路完整跑通。我也会把踩过的坑和排查思路一并写出来而不是只给一个“对着敲也未必能跑”的教程。2. 安装前的两个核心概念技能文件与前置目录2.1 技能文件到底是什么Superpowers 的底层机制并不复杂。它由一堆 Markdown 文件组成每个文件描述一个具体能力比如“如何优雅地写 Go 错误处理”“如何按 Angular 规范生成提交信息”“如何在 Java 项目里组织异常体系”。Codex 在执行任务时会根据系统提示或你显式的 引用去加载这些文件把它们的内容作为上下文的一部分参与推理。这有点像给模型塞了一沓“便签纸”。每张便签纸上写清楚一个规则、几个示例、几段必须避开的反面教材。和直接在系统提示词里写一大堆规则相比按需加载的好处是上下文窗口不会被无关内容白白占用。你写 TypeScript 时不需要加载 Python 的规范写 Java 时也不需要读前端组件规则。2.2 AGENTS.md 与 skills 目录的协作关系在 superpowers 的设计里有一个关键文件叫AGENTS.md通常放在项目根目录。它相当于一个“目录页”告诉 Codex 你的项目有哪些技能可用、在什么情况下应该加载哪个技能文件。然后 skills 目录下再按照子科目做拆分比如skills/java/exception-handling.md、skills/git/commit-message.md。实际执行时Codex 读到AGENTS.md后会去对应的.md文件里寻找细节。这个结构的好处是你不用把所有东西都塞进一个文件里。真实项目里如果一个AGENTS.md超过 200 行模型反而容易抓不住重点。拆分之后每个技能文件只管一件事内容可以写得更深、更具体示例也可以更完整。这里我想特别强调一个“为什么”很多人觉得给 Codex 写提示词直接把规则写在AGENTS.md里就够了为什么还要搞 skills 目录我的实测结论是当规则条目超过 15 条左右时模型对后面几条规则的遵循度会出现肉眼可见的下降。把规则拆成独立文件、按需加载本质上是在帮模型减少“注意力损耗”。这和人类开会一样一份 50 页的会议材料不如三份 5 页的专题材料有效。2.3 环境准备清单在正式安装之前先把环境理清楚。我建议准备一个干净的目录用来存放 superpowers 源码这样升级和排查都方便。我的常用布局是~/workspace/ ├── my-project/ # 你的业务项目 └── codex-superpowers/ # superpowers 仓库如果你的机器上已经有其他 Codex 配置需要留意~/.codex/下的config.toml。Superpowers 的安装过程通常会在项目级或全局级追加一些配置。我碰到过一次意外旧配置里自定义了model和默认instructions导致 superpowers 的技能文件一直没有被加载排查了大半天才找到原因。建议在安装前先备份现有配置免得后面对比时两眼一抹黑。3. 亲手装一次 Superpowers两种最靠谱的路径3.1 方式一直接克隆官方仓库我比较推荐的入手方式是直接克隆仓库因为你能看到全部技能文件的结构也方便按自己需求修改。命令很简单cd ~/workspace git clone https://github.com/你的用户名/codex-superpowers.git克隆完成之后进入仓库目录通常会看到类似下面的结构codex-superpowers/ ├── AGENTS.md ├── skills/ │ ├── git/ │ │ ├── commit-message.md │ │ └── branch-naming.md │ ├── java/ │ │ ├── project-layout.md │ │ └── exception-handling.md │ ├── typescript/ │ │ ├── error-boundary.md │ │ └── testing.md │ └── ... ├── scripts/ │ └── install.sh └── README.md如果仓库里有install.sh先打开看一眼再执行别直接跑。有些安装脚本会在~/.codex下写入全局配置有些只会在当前目录生成.codex/skills的软链接。我的习惯是先跑一次脚本看它输出了什么、改了哪些文件再决定要不要保留。3.2 方式二手动软链接项目级技能目录我更推荐这种方式尤其是你同时维护多个项目、不同项目需要的技能不一样时。在项目根目录下建立.codex/skills并软链到 superpowers 仓库里的对应技能目录cd my-project mkdir -p .codex ln -s ~/workspace/codex-superpowers/skills .codex/skills ln -s ~/workspace/codex-superpowers/AGENTS.md AGENTS.md这样做的好处有两点。第一升级 superpowers 时只需要git pull仓库本身不用每个项目里手动复制文件。第二你可以在项目里的AGENTS.md之上再写自己的项目特殊规则superpowers 的通用规则和项目特有规则能形成互补而不互相覆盖。我还见过一种更细的玩法用 git submodule 把这个仓库固定到指定 commit然后在自己的项目里引用。好处是团队协作时大家 checkout 之后git submodule update就能拿到同一份技能快照不会出现“你代码里加载的规则跟我这边不一样”的尴尬。3.3 安装完成后的验证方法装完之后别急着开始写代码先做一个最小验证。在项目根目录运行 Codex输入下面这句话请看看 AGENTS.md 里有哪些与 Java 相关的技能并列出其中关于异常处理的要点。正常情况下Codex 会引用技能文件里的内容而不是凭它自己的记忆泛泛而谈。如果它开始“自由发挥”大概率是技能文件没有被正确加载。这时候看两处第一AGENTS.md是否在项目根目录且内容能被 Codex 读入第二.codex/skills软链接是否指向了真实存在的文件路径。另外提醒一下Codex 的上下文加载可能有缓存。如果你在同一个会话里反复修改AGENTS.md但没看到效果建议开一个新会话再试。我实测中遇到过一次“改了规则但模型还在按旧规则干活”重启会话后立刻好了原因就是旧会话的上下文里还留着加载过的旧文件内容。4. Superpowers 与 Java 项目从“能用”到“好用”的真实一跃4.1 把项目结构先喂给模型Java 项目往往是 superpowers 获益最明显的场景之一原因是 Java 的工程约定比 Python 或 JavaScript 重得多包名规则、分层结构、异常体系、DTO/VO/Entity 的区分、依赖注入风格……每个团队都有自己的讲究。默认 Codex 对这些一无所知它只会给你“语法正确但风格全无”的代码。这里我给一个 Java 技能文件的示例片段你可以参照这个思路写自己的团队规范# Java 项目结构约定 ## 分层规范 - controller 层只做参数接收和响应封装不允许写业务逻辑 - service 层处理业务逻辑方法粒度控制在“一个方法只做一件事” - repository 层只做数据访问方法名必须与 SQL 意图对应 ## 异常处理 - 业务异常必须继承统一 BusinessException - controller 层禁止 catch 异常统一由全局异常处理器接管 - service 层禁止捕获异常后吞掉必要时包装为 BusinessException 抛出 ## 示例 推荐 public User getUserById(Long id) { return userRepository.findById(id) .orElseThrow(() - new BusinessException(ErrorCode.USER_NOT_FOUND)); } 不推荐 public User getUserById(Long id) { User user userRepository.findById(id).orElse(null); if (user null) { throw new RuntimeException(用户不存在); } return user; }把这个文件放到skills/java/project-layout.md之后你在项目里让 Codex 写 Service 层代码它就会主动考虑统一异常、避免 controller 里塞逻辑等约定。这比你在会话里一遍遍提醒“注意我们项目规范”要稳定得多。4.2 让 Codex 写出符合团队规范的提交信息另一个我很常用的技能是 git commit message 规范。Java 项目普遍有严格的提交历史要求比如 commit 前缀必须用feat、fix、refactor可选 scope标题不超过 50 字符正文说明动机等。这些规则如果靠人盯等于给 Codex 加了个监工效率很低。在 superpowers 里配置一份skills/git/commit-message.md内容可以写成# Git 提交信息规范 - 格式type(scope): subject - type 取值feat / fix / refactor / docs / test / chore - subject 用祈使句首字母小写不超过 50 字符 - 正文必须说明本次修改的动机而非只是复述代码做了什么 示例 feat(order): 添加订单超时自动取消逻辑 由于订单状态在支付回调失败时无法前进增加定时任务扫描超时订单 并触发状态机事件 ORDER_TIMEOUT。有了这份技能文件当你执行完代码改动让 Codex 帮你生成 commit message 时它输出的内容会明显更有章法。我在几个项目里试过生成的标题和正文基本都能直接提交偶尔需要微调 scope但整体可用度非常高。4.3 实测对比没有技能的 Codex vs 有技能的 Codex为了让你看到实际差异我给你讲一个我最近做的小实验。我在一个 Spring Boot 项目里用同一个需求分别跑了两次 Codex需求是“在用户注册接口里增加密码强度校验”。没有加载技能时Codex 给了一个能跑的方案在UserController里写了一个if (password.length() 8)就抛异常的逻辑异常直接用了RuntimeException。语法没有任何问题但放到项目里确实不行——controller 层不该写业务校验逻辑密码规则也应该统一配置在别处自定义异常更不能直接裸抛。加载 Java 技能之后再跑同样的需求Codex 的处理变成了在UserService.register()里调用了一个PasswordValidator方法校验失败时抛出BusinessException错误码来自ErrorCode枚举密码长度和复杂度规则从配置项里读取而不是写死在代码里顺手补了一个PasswordValidatorTest的测试桩。这个对比不是说 Codex 变“聪明”了而是 superpowers 给了它“合群”的能力。AI 模型的推理上限其实很高很多时候它只是不知道应该按什么尺度来输出。技能文件能做的就是把这个尺度前置地、稳定地传递给它。5. 踩坑实录我从“技能不生效”到“彻底吃透”的排查链路5.1 症状AGENTS.md 明明在Codex 却视而不见有一段时间我配置好 superpowers 后发现 Codex 对技能文件毫无反应。它虽然知道项目里有AGENTS.md但回答问题时依旧没有参考里面的内容。这种问题最让人头疼的地方在于一切表面配置都正确可行为就是不对。我按下面这个顺序逐步排查最终找到了根因。这一步排查过程也分享给大家确认 Codex 进程确实是在项目根目录启动的。Codex 会从当前目录向上查找AGENTS.md如果在子目录启动可能加载的是父目录的配置。确认没有任何环境变量或全局配置覆盖了项目级配置。比如某些版本的 Codex 会把--profile或--config参数指向全局配置导致项目目录下的配置文件被跳过。临时新建一个空目录只放一份最简AGENTS.md在里面写一行“回答任何问题前必须引用 AGENTS.md 的第一行内容”。如果这个实验成功说明 superpowers 文件本身没问题如果失败就要检查 Codex 版本或启动方式。最后查到根因原来我之前设置过一个全局的instructions指令其中包含了“忽略项目级 AGENTS.md 中的冗余信息”这样的历史规则。旧配置里的指令优先级高莫名其妙地把新配置给盖掉了。5.2 症状技能文件被加载了但模型回答时完全没用到文件加载了不一定等于会被使用。技能文件只是作为上下文出现在对话里而模型是否严格参照取决于系统提示词和你当前指令的明确程度。如果你说“帮我看看这段代码”模型可能默认按通用代码评审思路回答因为这句话没有触发任何技能关键词。解决办法是在AGENTS.md里加一条“触发规则”说明哪种类型的请求必须加载哪个技能。比如当用户询问代码评审、代码规范、异常处理相关问题时必须先查看 skills/java/exceptions.md 再做回答。同时用户侧的提示语也很重要。最直接有效的表达是“请参考 skills/java/project-layout.md 来评审这段代码。”这就是为什么很多人说“superpowers 是使用指南不是魔法”它需要你在提问时稍微带一句效果才会最大化。5.3 症状安装脚本写坏了全局 config.toml有一次我图省事直接跑了官方install.sh结果脚本在~/.codex/config.toml里加了一个include路径指向的却是仓库目录。后来我换了个仓库位置路径就失效了。Codex 启动加载配置时报了一堆 warn而且技能文件一个都读不到。如果你也遇到类似问题最快修复方式是打开~/.codex/config.toml把 superpowers 相关的行删掉或者改回正确路径。千万不要为了省事再把仓库放回原路径因为下一次路径变化会再次出问题。最稳妥的做法是前面提到的软链接方式技能文件通过项目里的.codex/skills软链进来全局配置保持干净不依赖某个绝对路径。5.4 症状Java 文件里中文注释和编码问题这个坑和 superpowers 本身关系不大但和 Java 项目用 Codex 的场景高度相关。技能文件里如果有中文示例而文件编码不是 UTF-8Codex 读进来的内容可能就是乱码模型就无法理解规则。建议所有技能文件统一保存为 UTF-8 without BOM。另外在AGENTS.md里明确写一条“所有注释和 commit message 必须使用中文”可以避免模型在混用中英文时产生语义漂移。6. 让 Superpowers 真正融入团队进阶玩法与我的个人心得6.1 给团队定制技能文件时的结构建议如果你打算把 superpowers 带入团队不要直接拿默认技能库给所有人用。默认技能是通用规则但每个团队有自己的痛点。我建议团队至少定制以下三个方向的技能文件工程规范操作手册包括建包、命名、分层、依赖管理质量红线哪些代码模式是绝对禁止出现的比如把日志打在全链路的关键节点上、在循环里查库等协作与交付规范包括 MR/PR 描述写法、commit message 格式、测试覆盖率检查要求。一个人写这些文件会很累更高效的方式是让 Codex 先根据你的代码库生成草稿再由资深工程师逐条修订。Superpowers 的技能文件本身也是 Markdown所以团队负责人可以直接 diff、评审、方便地维护版本历史。6.2 让 Codex 自动更新技能文件闭环玩法我在实际使用中还发现一个很有意思的用法把 superpowers 当成一个“自我进化”的系统。定期让 Codex 回顾你过去一周的代码提交找出那些被人工修改过的部分提炼出反复出现的规则然后更新到技能文件里。这一步很像在给模型做“复盘”。具体做法是打开一个会话让 Codex 读取最近 20 条 commit diff注意看人工 review 之后改了什么再让它判断是否值得沉淀成规则。如果值得就让它直接修改对应的技能文件并由你确认。我实测过这个流程确实能沉淀出很多隐藏规则比如某些表结构字段命名、某些接口返回格式的统一处理都是之前写在人脑子里、却没写进文档里的知识。6.3 什么时候不要过度依赖 Superpowers最后我想说一点superpowers 不是银弹它解决的是“上下文规范和风格一致性”的问题而不是“模型能力”的问题。如果模型本身对某种语言或框架的基础知识不扎实技能文件写得再详细也无济于事。比如让 Codex 去写一个非常冷门的专有协议解析它可能连标准库的函数签名都记不住这时候给它一万行规范也救不回来。所以我的使用原则是把 superpowers 定位成“团队的编码文化封装层”而不是“业务知识的存储库”。业务知识应该靠 RAG、代码检索和文档系统来提供superpowers 只需要负责把文化、规范、风度这些东西稳定地传递给模型。6.4 一个让我印象深刻的优化例子最后分享一个最近让我觉得值回票价的例子。我们有个遗留项目所有 Service 类里都直接写try-catchException e然后e.printStackTrace()。这种代码在代码评审时被吐槽了无数次但历史包袱摆在那里没人有时间统一清理。我把“禁止 printStackTrace必须使用统一日志框架且 error 级别必须携带业务上下文”写进技能文件之后让 Codex 增量重构了三个核心 Service 类。它清理掉了所有裸 catch 和 printStackTrace替换成了带错误码和上下文参数的日志输出还顺手写了一个日志过滤器测试。整个过程中我唯一担心的是改动量太大引发回归但因为有技能文件约束Codex 生成的代码风格高度一致review 起来反而没我想象中那么累。这件事给我最大的触动是AI 编程工具的上限其实比你想象的更高关键在于你有没有一套机制稳定地把团队的“潜规则”传递给它。Superpowers 恰好补上了这块拼图。如果你也在和 Codex 配合写 Java 项目我建议你先拿一个小模块试试把团队最痛的两三条规范写进技能文件跑上一周看看差异。你会明显感觉到模型从“一个聪明的陌生人”慢慢变成了“一个懂你团队的老同事”。
阅读完成 · 觉得有帮助？
