我最近一直在折腾一个叫 superpowers 的技能扩展方案拿它给 Codex 编程助手做了一整套能力增强尤其在 Java 项目里顺手了很多。先说它是干嘛的superpowers 本质上是一组高度结构化的“技能包”包含任务规划、测试优先、重构规范、代码审查、异常排查等工作流让 Codex 这类 Agent 从“你说一句它写一段”的被动应答变成“先拆解需求、再选技能、按步骤落地、最后自检”的主动执行者。这套东西特别适合正在用 Codex 写 Java、又嫌它“代码能跑但总缺那么点味道”的开发者。下面这篇文章就是一份从安装到 Java 实战的 superpowers 使用指南。1. superpowers 项目到底在解决什么问题1.1 一个“代码写出来却不敢交”的典型现场不瞒你说我最早用 Codex 写代码时效率确实高但心里一直不踏实。比如我让它“改一下订单状态流转”它会立刻生成一段可以编译、逻辑看着也对的代码可仔细一检查缺了状态边界校验、没有操作人记录、异常场景也没覆盖。你说它错了吗不一定错。你说它能上线吗我是不敢。这个问题不是 Codex 不够聪明而是它缺少一套“工作方法”。普通对话式的 AI 编程助手进入代码库以后最常见的行为是猜根据你的上下文和它训练时见过的模式直接输出一个最大概率的答案。它没有真正的“岗位习惯”也不知道你所在团队有哪些规范、哪些步骤是必须走的。superpowers 想解决的正是这个问题把好的工程实践沉淀成可调用的技能包让 Agent 在动手前先按流程走一遍。它的名字很贴切普通人和超级英雄的差距往往不在身体素质而在于“有没有一套合适的能力激活流程”。superpowers 就是给 Codex 装上的那套能力激活系统。1.2 技能包的核心设计拆解superpowers 不是一个大而全的单体工具它由四块组成技能库、工作流、校验规则和钩子。技能库是最核心的部分。每个技能是一份带结构化元信息的 Markdown 文档里面写明触发条件、输入参数、执行步骤、验收标准。比如说tdd-create-workflow这个技能触发条件是“开发新功能”执行步骤是先写测试、再跑红测试、再实现、再跑绿测试、最后重构。Codex 读到这个技能以后行为方式会整个变掉。工作流负责把多个技能串联起来。比如一个典型的 Java 新功能开发可以先调用plan-and-execute做需求拆分再进入tdd-create-workflow写代码最后用code-review做自检。校验规则是一组 JSON 或 YAML 文件用来约束输出比如包名不能写错、接口不能直接返回实体类、禁止使用System.out.println这种硬编码输出。钩子则是一些可执行脚本可以在关键节点上触发一些外部操作比如跑一遍mvn test。这四块加起来相当于给 Agent 配了一本“岗位手册”外加一套“质检员”。1.3 为什么用“技能文件”而不是塞进一条大 prompt有人可能会问这些规范为什么不直接写进 Codex 的 prompt 里我也这么写过但很快就后悔了。一条把全部规范都塞进去的 prompt又长又乱每次调用都要烧掉大量 token而且只要某条规则要改整条 prompt 都要跟着重写维护成本极高。技能文件的思路更像“按需加载”。Codex 拿到任务后先去一个技能目录里搜索相关文档只把会用到的那个技能读进上下文。这种方式既有检索的能力又不会把整个代码库和所有规范一股脑塞进对话里。类比一下你不需要把整本百科全书背下来才能回答问题只需要知道哪一章写的是你需要的内容然后翻开那一页。superpowers 做的就是这个“翻书”的动作。2. superpowers 安装实战从零搭好一套可复用的技能台2.1 环境准备清单开始安装之前先把环境摸一遍。我这套脚手架目前依赖这几个基础组件Git、Node.js用来跑 CLI 工具链、Codex CLI以及一个 Java 项目的标准构建环境。不用都装最新的但要保证版本别太老。Java 建议直接上 JDK 17 以上配合 Maven 或 Gradle 都行测试框架优先用 JUnit 5。建议先把这几条命令跑一遍确认环境没有暗坑node -v git --version codex --version java -version mvn -version这里有个很容易忽略的点Codex 项目和 Java 项目如果不在同一个终端环境变量路径下后面调用 Maven 包装器时Codex 的子进程可能找不到mvn。我的习惯是统一用mvnw脚本并且在一开始就把它加入 PATH避免后面排查半天。2.2 安装与初始化步骤拿到 superpowers 的发行包后我先执行初始化命令让它在当前目录生成一套默认的技能目录结构sup init my-superpowers cd my-superpowers sup doctorsup doctor会检查环境的兼容性比如 Node 版本够不够、有没有找到 Codex CLI、Java 版本是否满足技能包要求。我第一次跑的时候就发现它提示缺少java-style.json校验规则原因是当时只初始化了通用技能库没有加载 Java 专项配置。补一下就行sup install --profile java这个命令会拉取 Java 相关的技能文档、规则文件和一些需要预置的测试模板。它不会覆盖你的业务代码只会往技能目录里新增内容。整个过程大约一分钟。如果 GitHub 网络环境不稳定可以提前把发行包下载到本地再执行sup install --offline --profile java。这个参数我后来用得很多尤其在公司网络限制比较严格的情况下。2.3 目录结构与配置文件说明初始化完成后目录结构大概长这样my-superpowers/ ├── skills/ │ ├── plan-and-execute.md │ ├── tdd-create-workflow.md │ ├── java-refactoring-workflow.md │ ├── java-code-review.md │ └── debug-nullpointer.md ├── rules/ │ ├── java-style.json │ └── commit-message.json ├── workflows/ │ └── feature-java.yaml ├── hooks/ │ └── pre-commit.js ├── AGENTS.md └── sup.config.json别看目录多真正需要手工维护的是skills和rules两个目录。skills下面的 Markdown 文件头部会有 YAML 格式的元信息我习惯把触发条件写得尽量明确。举个例子--- name: tdd-create-workflow trigger: 新功能开发、新增业务方法 language: [java] inputs: - 需求描述 - 测试框架 steps: - 生成测试用例 - 运行测试确认失败 - 实现最小代码 - 运行测试确认通过 - 重构并保持绿色 ---这份元信息就是所谓“技能封面”。Codex 在调用技能时会先读元信息判断要不要用这个技能真正执行时再读正文步骤。所以技能封面必须简洁正文可以详细但封面别写太长否则对 Agent 来说也是噪音。2.4 把 superpowers 挂载到 Codex目录搭好之后最关键一步是让 Codex 知道它存在。现在版本的 Codex CLI 支持项目级说明文件也就是仓库根目录下的AGENTS.md。我会在生成的AGENTS.md里写清楚# 项目约定 - 所有 Java 代码生成前先执行 sup plan 生成任务清单。 - 新功能开发使用 tdd-create-workflow 技能。 - 代码完成后使用 java-code-review 技能进行自检。这一步做完Codex 每次启动会话时都会读到这些约定然后在合适的时候主动去技能目录里查找对应文件。我用下来最明显的感受是它开始“自己知道要先拆任务”了不用我一件事一件事地催。挂载完成后可以用一条命令做个冒烟测试codex exec sup skill list如果 Codex 能输出技能清单说明已经打通。这里有个小细节不要在AGENTS.md里塞一段又长又复杂的指令越是简洁的命令式约定Codex 的执行率越高。复杂逻辑应该放进技能文件而不是堆在说明文件里。3. codex superpowers 的 Java 实操把技能包用在刀刃上3.1 Java 场景下的技能选型思路Java 开发的痛苦点和其他语言不太一样代码量大、构建链长、框架约定多而且团队规范一旦被破坏后期维护成本会直线上升。superpowers 在这种场景下最值钱的不是让 Codex 多写几行代码而是让它按照 Java 社区的主流实践去写。我一般备着四个核心技能plan-and-execute用来处理复杂需求tdd-create-workflow用来生成新代码java-refactoring-workflow用来重构存量代码debug-nullpointer用来排查具体异常。每次接到一个新的 Java 任务先不要急着让 Codex 写实现而是先让它把需求拆成几个可验证的小步骤这样后面每一步都聚焦在一个小范围里出错率会低很多。选技能时还要考虑模块边界。比如说改一个订单状态流转功能通常会涉及到领域模型、仓储接口、应用服务三层。如果这些层在同一个任务里一股脑全改代码生成容易跑偏。更好的做法是分三次调技能每次只生成一层分别做完再整合。3.2 实操一用 TDD 工作流生成订单状态流转代码我用一个最常见的订单状态流转场景来演示。需求是订单状态只能从CREATED迁移到PAID或者CANCELLED已经取消的订单不能再支付。按传统做法直接让 Codex 生成一堆 getter/setter 加 if 判断就完事了但那样代码质量全看运气。现在换成 superpowers 的流程。我先让 Codex 调用tdd-create-workflow它会生成一个 JUnit 5 测试类内容大致是class OrderStatusTest { Test void shouldMoveFromCreatedToPaid() { Order order new Order(OrderId.generate(), new Money(100)); order.transitionTo(OrderStatus.PAID, Operator.system()); assertEquals(OrderStatus.PAID, order.status()); } Test void shouldRejectTransitionWhenOrderCancelled() { Order order new Order(OrderId.generate(), new Money(100)); order.transitionTo(OrderStatus.CANCELLED, Operator.system()); assertThrows(IllegalStateException.class, () - order.transitionTo(OrderStatus.PAID, Operator.system())); } }这个测试类是技能根据需求描述自动生成的它先定义好了行为边界。接下来 Codex 才会去写实现类目标只有一个让测试跑绿。以这个测试为约束实现时就不太可能漏掉“已取消订单不能再支付”这种边界条件因为测试用例把它钉死了。这套流程最爽的地方在于Codex 不再需要我反复提示“先想清楚再写代码”技能本身已经把“先写测试”变成了它的执行习惯。3.3 实操二用重构技能清理一段“能跑但难看”的老代码重构存量代码比写新代码更容易翻车。老代码往往没有测试保护直接让 Codex 重写文件一旦行为发生变化你根本看不出哪里出了问题。superpowers 的好处是会把“重构”和“重写”分开。你这个 skill 会先把目标文件拆成若干小步骤。比如一段典型的烂代码public void cancelOrder(Integer id, String reason) { Order o orderRepository.findById(id).orElseThrow(); if (o.getStatus() OrderStatus.CREATED reason ! null reason.length() 3) { o.setStatus(OrderStatus.CANCELLED); orderRepository.save(o); } }这段代码的问题很明显id用了包装类reason的校验规则散落在业务方法里状态流转用 if 完成后面如果再加一个状态流转分支这个方法会越来越胖。重构技能会建议把这段逻辑抽成领域模型方法并引入值对象。重构后的代码大概是public class Order { private OrderId id; private OrderStatus status; public void cancel(CancelReason reason) { if (!status.canTransitionTo(OrderStatus.CANCELLED)) { throw new IllegalStateException(当前状态不允许取消); } this.status OrderStatus.CANCELLED; } }这个过程中Codex 不会一次把所有文件都改完而是先改领域模型再改应用服务每一步之间都有“编译通过 测试通过”的检查点。这种执行方式虽然看起来多花了几轮但安全系数高了不是一点半点。3.4 参数调整与上下文管理的几条经验我见过很多人一上来就问“温度调多少合适”。在代码生成这件事上与其调温度不如控制好上下文。superpowers 的工作流默认会让 Codex 每次先生成一小段代码而不是一次性输出整个文件。因为 Codex 一次能带走的上下文是有限的你把整个大文件全部拽进会话里再让它改一小处它反而容易把手伸得太长。所以我的经验是先在计划阶段把大任务切成多个编译单元每个编译单元只包含一个类或者一个方法然后逐个生成、逐个验证。如果你在 API 层面有temperature、top_p这样的参数可调建议代码生成类任务使用较低的温度和较高的top_p宁可输出保守一些。但更关键的还是“会话长度”。一旦发现 Codex 开始重复执行同一个技能或者答非所问多半是上下文被拖太长了这时候不是继续问而是开一个新的会话把上一步的结果作为输入继续。Java 项目还有一个特殊点编译反馈等待时间比较长。建议在日常项目里配置好 Maven 的本地仓库缓存并把 superpowers 的pre-commit.js钩子指向./mvnw test这样每次代码生成完会自动触发一次真实构建问题暴露得越早越好。4. 常见问题排查与避坑速查4.1 技能加载失败、生成结果“没内味”这是遇到最多的问题明明安装成功Codex 却不用 superpowers依旧用自己的方式回答。我排查这种问题时第一反应是看AGENTS.md是否真的被放到了项目根目录而不是某个子目录。Codex 只认启动目录下的项目说明文件放错了位置等于没放。另一个常见原因是指令写得不够“硬”。比如你写“可以优先使用某个技能”Codex 会把“可以”当成可选项改成“必须严格遵循”之后执行率立刻上来了。还有一个原因和技能封面有关如果trigger写得太模糊比如“遇到问题时”Codex 不知道什么时候算“遇到问题”自然就不会触发。把触发条件写成“新增业务方法时”“状态字段变更时”识别率会高很多。4.2 Java 构建与依赖诊断Java 项目里Codex 生成的代码经常出现编译错误但这不代表它能力不行很多时候是项目构建上下文缺失。比如它不知道你用的是Version Catalog或者项目里用了 Lombok但生成代码里没有加注解处理。遇到这种问题我先去查pom.xml或者build.gradle把关键依赖和插件版本写进AGENTS.md。比如项目使用了 Lombok 和 MapStruct我会在说明文件里标注“生成实体类时如果涉及 getter/setter 请使用 Lombok 注解”。这些看似琐碎的上下文恰恰决定了生成代码是否一次编译通过。还有一类问题是 Maven 构建太慢导致 Codex 不知道代码有没有编过。我的建议是在技能工作流里把验证步骤从“完整跑一次测试”改成“先跑单类测试”这样一个用例的反馈周期从两分钟压缩到十几秒迭代体验完全不一样。4.3 Codex 上下文爆炸与技能重复执行长会话里Codex 比较容易“忘事”它可能执行到一半又从头开始规划或者同一个技能被连续触发两三次。我第一次遇到时还以为技能文件有问题后来才发现是上下文被大量工具输出塞满了。解决办法有两个层面。一个是给技能文件加“幂等”约束在每份技能文档开头写明“执行前先检查是否已经完成已完成则跳过”。另一个更实用每次一个完整步骤结束后让 Codex 输出一份简短的“步骤状态摘要”下一步在新的会话里直接贴这段摘要。这比在同一个会话里硬撑到底要稳定得多尤其适合 Java 这种多文件、长编译链的项目。4.4 常用排查命令速查表把这些问题整理成一张速查表日常排查照着走就行症状可能原因排查命令处理建议Codex 不调用技能AGENTS.md 缺失或放错位置ls -la AGENTS.md把说明文件放到项目根目录技能加载但行为不明显触发条件写得太模糊head -20 skills/xxx.md改精确定义 trigger 条件Java 代码总是编译失败缺少项目构建上下文codex exec cat pom.xml | head -50把关键依赖写进 AGENTS.mdMaven 反馈太慢测试全量执行mvn -DtestOrderStatusTest test工作流中只跑单类测试技能重复执行上下文过长sup log会话重启粘贴上一步摘要生成代码风格不符合规范校验规则未加载sup validate --dirsrc/main/java加载对应的 rules 配置我自己用下来superpowers 最像样的地方不是它有多少炫酷命令而是它把“工程方法”这件事变得可配置、可复用。对 Java 这个领域来说代码能力的上限往往不是语法问题而是方法问题。skill 文件里写下的每一步都在帮 Codex 建立更接近团队标准的行事方式。如果你也在折腾 Codex 和 Java 项目建议从一份最头疼的存量代码开始用一个重构技能跑一遍亲身感受一次“先拆解、再动手”的差别比看多少教程都管用。
