我最近一直在折腾一个叫 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 doctor

sup 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 常用排查命令速查表

把这些问题整理成一张速查表，日常排查照着走就行：

我自己用下来，superpowers 最像样的地方不是它有多少炫酷命令，而是它把“工程方法”这件事变得可配置、可复用。对 Java 这个领域来说，代码能力的上限往往不是语法问题，而是方法问题。skill 文件里写下的每一步，都在帮 Codex 建立更接近团队标准的行事方式。如果你也在折腾 Codex 和 Java 项目，建议从一份最头疼的存量代码开始，用一个重构技能跑一遍，亲身感受一次“先拆解、再动手”的差别，比看多少教程都管用。