最近给 Codex 配了一套叫 superpowers 的增强技能库，实测几周下来，效果比我想象中要明显得多。如果你跟我一样，重度依赖 AI 编码助手写代码、做重构、补测试，那你大概率也遇到过同一个问题：AI 确实能写，但它写出来的东西总差那么一口气——不是不能用，而是离“可直接合入生产仓库”的标准还差着一大截。superpowers 这套东西，就是专门用来补这个差距的。

先说清楚它能干什么：本质上，它是一套为 AI 编码助手设计的技能包与工作流配置，覆盖需求拆解、方案设计、编码规范、代码审查、测试生成、重构建议等环节。安装之后，你在 Codex 里输入一个指令，它就不再是“即兴发挥”，而是按照一套成熟的开发 SOP 去执行。它解决的核心问题不是“AI 能不能写”，而是“AI 怎么写得像你团队里那个最靠谱的资深工程师”。

如果你正在用 Codex、或者打算引入 AI 编码助手但觉得效果一般，这篇文章就是给你写的。我会从设计思路讲起，再完整过一遍安装、配置、Java 项目里的落地实践，最后把这几个月踩过的坑和排查技巧一并交出来。内容偏实操，可以直接照着做。

1. 先搞清楚 superpowers 到底是什么

1.1 从“AI 原生输出”到“专家级交付”的差距

很多人第一次用 Codex 的感受是“惊艳”，用了一个月之后变成“还行”，再往后就开始觉得“也就那样”。原因很简单：Codex 本身的代码生成能力很强，但它的默认行为更像一个聪明但缺乏经验的实习生。你跟它说“帮我写个用户列表接口”，它会给你一个能跑的 Controller，但不会主动想到分页边界、参数校验、统一异常处理、日志规范、DTO 隔离、单元测试覆盖这些事。

这不是模型能力不行，而是 AI 在默认状态下缺少“上下文约束”。你给它一个任务，它默认只会做一个任务；你给它一套完整的工作流，它才会按工作流走。superpowers 做的事，就是把你脑中的那套“专家级工作流”显式地写出来，让 AI 在干活之前先读到规则，再按规则输出。

我打个生活化的比方：你让一个厨师“做一道鱼”，他可能随便煎一煎就上桌了；但你给他一份完整的菜谱，写着选什么鱼、去腥几步、腌多久、哪一步下锅、配什么酱汁、装盘有什么讲究，他做出来的东西就是另一个水准。superpowers 就是那份菜谱，而且它比普通菜谱更狠——它能根据不同项目类型切换菜谱，还能让你随时往菜谱里加自己的私房步骤。

1.2 superpowers 的三层结构

我拆过几个常见的 superpowers 实现，虽然不同版本的目录结构有差异，但核心设计基本都逃不开三层：

第一层是技能库（Skills）。这一层是一堆结构化的 Markdown 文件，每个文件描述一种能力，比如 code-review、test-generation、refactoring 这类。AI 在执行任务时，会像查手册一样读取对应技能文件，然后按照里面写的步骤和规则处理问题。技能文件写得越具体、越可执行，AI 输出的质量就越稳定。

第二层是工作流编排（Workflow）。这一层解决的是“什么时候该用什么技能”的问题。比如你输入/superpowers plan，它会按“需求澄清 → 技术选型 → 步骤拆解 → 风险清单 → 验收标准”的顺序推演；你输入/superpowers implement，它会先定位相关代码、分析依赖，再动笔。这一层本质上是把人对任务的思考过程显式拆成步骤，让 AI 不再跳步。

第三层是环境感知配置（Context）。这一层把项目根目录下的说明文件、代码规范、技术栈信息、甚至团队约定都收编成 AI 能读懂的上下文，让技能执行时贴合你项目的实际情况。这一层做得越完善，AI 的输出就越不像“通用答案”，而像“专门为你的项目写的代码”。

这三层缺一不可。只有技能库没有工作流，AI 知道该做什么但不知道按什么顺序做；只有工作流没有技能库，流程再完整 AI 也没有具体执行方法；而少了环境感知，前面两层再强也接不上你项目的地气。

1.3 适用场景与选型分析

从我实际使用的经验看，superpowers 最适合这几类场景：

第一类是重复度高的业务开发。比如 CRUD 接口、消息队列消费逻辑、定时任务这类场景，技能包里一旦明确出“分层、校验、日志、异常”四件套，AI 每次输出的代码质量都相当稳定，基本不需要人工返工。

第二类是存量项目的重构与维护。技能包可以把“保持现有风格”“不要大范围改动公共方法”“必须补充单元测试”这类约束内置进去，AI 就不会动不动给整个项目“重新发明轮子”。

第三类是团队协作开发。当一套技能库被放进 Git 仓库，所有成员共用同一套 AI 行为规范，每个人用 Codex 产出的代码风格会出奇地一致，Code Review 的争议能明显减少。

但它也不是万能的。如果你的项目非常特殊，比如强依赖一套内部封闭框架，或者历史代码完全没有规范，那你就需要先自己写技能包，直接把团队规范喂给 AI。这个投入是值得的，但你得预留一两天时间来做技能定制，别指望拿来即用。

2. 安装与初始化：从零开始把超能力跑起来

2.1 安装前的环境准备

先讲环境依赖。虽然不同分发版本的 superpowers 要求略有差异，但下面这几项几乎是通用的：

首先是 Node.js。当前主流的 Codex CLI 和配套工具链都跑在 Node 运行时上，建议 Node 版本不低于 18，版本太低会遇到一些新语法不兼容的问题。你可以用node -v快速检查，如果没有装，去官网下载 LTS 版即可。

其次是 Codex CLI。superpowers 是外挂层，它本身不参与模型推理，只是增强 Codex 的上下文与行为，所以你得先把 Codex 跑起来。安装方式很简单，全局装一个 npm 包，或者用官方提供的安装脚本，装完在终端输入codex能正常进入交互界面就行。如果你常用的是 Claude Code 或其他兼容 OpenAI 协议的编码助手，思路也类似，先确保主工具能用，再加挂技能库。

然后是 Git 和本地的项目环境。Git 用来拉取技能库仓库；本地项目环境指的是你日常开发的那一套 JDK、Maven、Gradle 或 Node 环境。superpowers 本身不依赖这些，但 AI 在分析项目时会调用你机器上的工具来验证命令，比如 Java 项目里它可能会跑mvn test或mvn dependency:tree，这些命令能正常工作很重要。

2.2 安装与初始化实操步骤

我用的是 GitHub 上社区维护比较活跃的一个版本，整体流程分三步，我把每一步都拆开讲。

第一步，克隆技能库到本地固定目录。我很不推荐把技能库放进某个临时目录，因为你会频繁修改里面的技能文件，路径越稳定越好。我的做法是放到~/.superpowers下：

git clone <你选定的superpowers仓库地址> ~/.superpowers cd ~/.superpowers

第二步，运行安装脚本。不同版本的安装入口名可能不一样，常见的有install.sh、setup.sh、bootstrap.sh，你进仓库后先列一下目录：

ls -la

看到脚本之后直接跑：

./install.sh

这一步的作用主要是把技能库中的 Skills 目录、默认配置文件、init 模板链接到 Codex 的配置目录下，同时向你的全局配置里写入一些默认指令。跑完通常会有输出提示，告诉你了下一步该看哪份文档。注意如果报权限错误，查看一下脚本文件是否有执行权限，chmod +x install.sh之后再跑。

第三步，初始化你的项目。这个步骤各个版本差异最大。有的版本会提供superpowers init命令，直接在项目根目录执行，帮你生成一份项目的说明文件；有的版本需要你手动把模板文件复制进项目。我见过最简单的方式是这样：

cd your-project ~/.superpowers/bin/superpowers init

执行完之后，项目根目录会出现一个说明文件，AI 每次在该目录下工作时都会自动读取它。这个文件的作用相当于给 AI 一份“项目体检报告”，写清楚技术栈、目录结构、编码约定、常用命令、容易踩的坑等信息。

2.3 初始化完成后必须做的三件事

装完不是结束，而是开始。我自己踩过坑之后，总结了初始化完成后必须立刻做的三件事。

第一件事，确认技能库已经被 Codex 正确加载。你可以直接在 Codex 里输入一个斜杠命令，比如/superpowers skills或/skills，看有没有列出当前可用的技能清单。如果啥都没有，说明路径配置不对，或者配置文件没被读到，这时候先别急着使用，回到上一步检查。

第二件事，把项目的说明文件补全。init 生成的文件只是模板，里面关于技术栈、目录结构、命令的字段可能还是占位符。你需要手动把关键信息填进去。这一步非常重要，因为技能的执行效果高度依赖项目上下文，说明文件写得越认真，AI 在项目里表现越好。我通常会把“构建命令”“测试命令”“代码风格要求”“禁止做的事”四类内容写满。

第三件事，跑一个最小任务验证效果。比如让 AI 用一个 review 技能检查项目里某个文件的代码，或者让它用 plan 技能拆解一个刚提的需求。跑通了，说明整套链路没问题；跑不通，趁早排查，别等到真需求下来才临时抱佛脚。我试过跳过验证直接上真实任务，结果 AI 完全没按技能约束执行，白白浪费了半天时间。

3. 核心配置文件与技能包机制拆解

3.1 配置文件的目录结构与作用

搞清楚 superpowers 的原理，就不能绕开它的目录结构。我以实际使用的一个版本为例，安装完之后整个技能库是这样组织的：

~/.superpowers/ ├── SKILL.md ├── skills/ │ ├── bootstrap/ │ │ ├── SKILL.md │ │ └── examples/ │ ├── code-review/ │ │ ├── SKILL.md │ │ ├── rules.md │ │ └── examples/ │ ├── test-generation/ │ │ ├── SKILL.md │ │ └── examples/ │ └── project-analysis/ │ ├── SKILL.md │ └── examples/ ├── commands/ │ ├── plan.md │ ├── implement.md │ └── review.md ├── scripts/ │ └── install.sh └── templates/ └── project-context.md

我逐个说。根目录的SKILL.md是总入口，里面声明了整个技能库支持哪些能力、每个能力的触发方式，AI 会在任务开始时读它，来判断自己“会什么”。skills/目录下每个子目录是一个独立技能，子目录里的SKILL.md是技能的详细定义，rules.md是可选的强化规则文件，examples/放的是示例产物，AI 可以照着示例的格式来输出。

commands/目录定义了一组业务流程。每个文件并不一定是具体的代码逻辑，而是用 Markdown 写的“行动指令序列”。AI 读到/superpowers plan时，就会按plan.md里写的顺序逐步执行。templates/目录存的是初始化项目时用到的模板文件，相当于给新成员发的工作手册底稿。

这套目录设计有一个很精妙的地方：它把“人怎么理解一个系统”和“AI 怎么理解一个系统”统一起来了。你不需要写复杂的程序逻辑来让 AI 执行某个流程，你只需要用最朴素的 Markdown 把规则写清楚。规则写得越好，AI 越能稳定遵循。

3.2 技能文件的格式与写法

技能文件是这套体系的核心。一个合格的技能文件通常分两大部分：头部 YAML 元信息和正文步骤说明。

我以一个代码审查技能为例做解析。头部长这样：

--- name: code-review description: 对指定代码执行多维度审查，输出结构化审查报告 trigger: review model: all ---

name是技能名，description告诉 AI 这个技能是干嘛的，trigger是触发词，model限定支持的模型范围。AI 在匹配技能时，会优先扫这些字段，所以描述必须写清楚，不能含糊。

正文部分要写三块内容。第一块是执行流程，比如：

执行步骤： 1. 先读取目标代码文件，理解其所属模块及上下游调用关系。 2. 按以下维度依次检查：接口设计、数据校验、异常处理、日志记录、性能风险、测试覆盖。 3. 每个维度输出结论与修改建议，修改建议必须指明具体行号。

第二块是输出格式要求，直接定义审查报告的 Markdown 模板，包括总体结论、按严重程度分级的问题清单、优先处理建议。AI 最擅长套格式，你把格式给它，它输出的东西直接就能贴到 Review 评论里，不需要二次排版。

第三块是禁忌项，比如“不要对业务逻辑进行大范围重写”“不要给出与代码风格无关的纯理论建议”。这块往往是最容易踩坑的地方，AI 在没有禁忌约束时特别喜欢自由发挥，把一次代码审查变成架构改造方案。写清楚禁区，输出立刻收敛很多。

3.3 如何把技能接入 Codex 的工作流

技能文件写好了，怎么让 Codex 在真实对话中主动调用？这一步很关键，做法也不复杂：把技能库里的命令文件声明到项目根目录的说明文件里。

具体来说，你在项目根目录的AGENTS.md或 Codex 读取的说明文件中，加一段类似下面的内容：

## 可用命令 本仓库配置了 superpowers 技能库，可通过斜杠命令触发： - /superpowers plan —— 需求澄清与实现方案设计 - /superpowers review —— 对指定文件执行代码审查 - /superpowers test —— 为指定功能自动生成测试 触发后，AI 必须严格按照对应命令文件中的步骤执行。

AI 在每次进入项目时会自动读取这个文件。它知道有哪些斜杠命令可用，也知道这些命令对应哪些技能文件。之后你在对话里输入/superpowers review并附带文件名，AI 就会自动去技能库的skills/code-review/SKILL.md里读完整规则，然后照着执行。

我在实际使用中的体会是，接入之后还要做一次“命令测试”。比如让 AI 执行/superpowers plan拆解一个需求，如果它输出的步骤依然是泛泛而谈，而不是按照命令文件里的流程逐条走，就得检查一下是不是项目说明文件里的声明写错了，或者技能文件里的指令本身写得太抽象。AI 对“必须按步骤执行”这类强约束的执行力，取决于你写的步骤是否足够具体。

4. Java 项目里的 superpowers 落地实践

4.1 Java 场景的典型痛点

说实话，superpowers 在不同语言项目里的表现差别很大。在 Python、TypeScript 这类动态语言项目里，AI 的自由发挥空间大，技能库主要是用来约束风格。但在 Java 项目里，情况完全不同——Java 项目的痛点不在“AI 不会写”，而在“AI 不知道你的项目约定”。

我举个最典型的例子：一个 Spring Boot 项目，Controller 层调用 Service 层，Service 层调用 Mapper 层，中间还有 DTO、VO、Entity 三套对象的转换。这类结构本身不复杂，但如果 AI 不清楚你的项目约定，它就会自己发明一套，比如直接在 Controller 里写业务逻辑、让 Entity 直接暴露给前端、异常处理散落在各个方法里。

superpowers 在 Java 项目里最大的价值，就是把这些约定固化下来，变成 AI 每次写代码前都必须遵守的规则。我在项目说明文件里写了三角色、三层结构、异常处理规范、命名规范、日志格式规范，之后 Codex 的输出风格跟团队主力开发写出来的代码高度一致。

4.2 一次真实任务的完整演示

我挑一个实际任务来演示完整流程。需求是：“给用户管理模块新增一个分页查询接口，按创建时间倒序，支持根据用户名模糊过滤。”

我先在 Codex 里输入：

/superpowers plan 需求：给用户管理模块新增一个分页查询接口，按创建时间倒序，支持根据用户名模糊过滤。

它按流程跑了需求澄清、技术选型、步骤拆解，输出了一份方案。方案里明确了几件事：使用 Spring Data 的 Pageable 做分页、Service 层返回 Page 对象、Controller 层转成统一分页返回体、DTO 只暴露必要字段、模糊查询用姓名关键词拼接条件。

确认方案没问题后，我再输入：

/superpowers implement 按方案实现，注意遵循项目约定。

它接着做的事情让我印象很深。它先去读了已有的 Controller、Service、Mapper、DTO 文件，理解了现有的命名习惯和返回体结构，再动笔写代码。生成的文件包括：Controller 端点、Service 接口与实现类、Mapper 的 XML 语句、DTO 与 VO 类。它还顺手补了分页参数的校验逻辑，处理了排序字段白名单。

整个过程中它没有再问任何问题，因为实现方案在 plan 阶段就已经敲定了，它只是按图施工。而且因为技能文件里明确规定了“禁止在 Controller 中编写业务逻辑”，Codex 写出来的代码结构是标准的，团队成员 review 时基本没有语义层面的争议。

4.3 Java 技能包的最佳实践

在 Java 项目里把 superpowers 用顺之后，我总结了三条最佳实践，算是我个人踩坑换来的。

第一条，必须给 AI 提供示例产物。只写规则还不够，AI 对“好”的标准没有感知，你需要给它看“你期望它写成什么样”的示例。我在skills/code-generation/examples/里放了一个完整的 Controller、Service 实现和 Mapper XML 示例，格式与团队规范一一对应。此后 AI 生成的代码在格式和结构上非常稳定。

第二条，把公共模块的扫描规则写进技术栈描述。很多 Java 项目里有 common、utils、base 这类公共模块，AI 如果不了解，就会自己去复制一份相似代码，制造大量重复。我专门在项目说明文件里写了公共模块清单、每个模块提供什么能力、标准引入方式，AI 遇到类似需求时会优先复用，而不是重新发明。

第三条，把构建命令写清楚，让 AI 能自校验。我在技能里加入了这样一条指令：“代码生成完成后，必须运行mvn -q compile，有编译错误则自行修复后再输出。” 这一条极大地减少了“AI 交付的代码能看但编译不过”的情况。代码生成后自校验，是 Java 项目里效果最实在的一条配置。

5. 常见问题与排查技巧实录

5.1 技能不生效怎么办

这是使用 superpowers 遇到最多的问题。你明明装了技能库，也声明了命令，但 AI 就是不管不顾，依然按默认方式回复。这种问题我从大到小排查过一圈，最常见的原因有三个。

第一个是项目说明文件没有被 AI 读取。Codex 在项目里工作时，会读取特定名称的说明文件，比如AGENTS.md。如果你把内容写进了别的文件，AI 根本不会看。解决办法是在项目根目录执行ls -la确认文件存在，并打开 Codex 的会话日志确认它是否加载了该文件。

第二个是命令名与技能名不匹配。AI 触发命令时，会拿你的输入和技能文件里的trigger字段做匹配。如果你在说明文件里写的命令名是/superpowers:review，但技能文件里的trigger是review，就可能匹配不上。这种问题经常在大小写和分隔符上翻车。

第三个是技能文件写成了一堆空话。AI 会优先执行描述清晰的步骤，如果你的技能正文只是一些“要保证代码质量”“要严格遵守规范”这类正确的废话，AI 大概率会跳过步骤直接发挥。我见过不少这种情况，把技能文件改成可执行的步骤描述之后就正常了。

5.2 上下文超额与模型差异

superpowers 本质上是靠大量上下文来引导 AI 的，这就带来一个现实问题：上下文窗口消耗很快。技能文件、项目说明、历史代码、用户输入，全部要占 token。在长对话中，后面的技能约束可能会因为上下文超限被截断，导致 AI 又回到默认状态。

我的应对方法是把执行力强、token 消耗大的技能放在对话早期使用。比如在开始写代码之前，先用/superpowers plan把方案确认下来，之后进入实现阶段就不需要再带完整的计划规则了，只需在每次请求中简短引用实现方案，AI 就能按计划执行。

模型差异也值得提。在 GPT-4 级别的模型上，技能库的执行力通常很稳定；但在轻量级模型或某些本地模型上，复杂技能文件的指令遵循能力会明显下降。如果你感觉“同样的技能，换了个模型就废了”，不一定是配置问题，可能是模型能力不够。这时候就建议把技能文件里最关键的规则单独提出来，写进全局指令里，确保每次对话都能读到核心约束。

5.3 路径与环境变量类问题

Java 项目里还经常出现另一类问题：技能正确加载了，但命令执行失败。比如技能要求 AI 生成代码后跑mvn test，结果 AI 反馈找不到命令，或者报错说 JAVA_HOME 没设置。

这类问题看似是 AI 的问题，实际上是你本机环境的锅。Codex 执行本地命令时用的是你的 shell 环境，如果 JAVA_HOME 没有配置在全局环境变量里，而是只在某个终端会话里临时导出，AI 就感知不到。解决办法是把 JDK、Maven 这类工具路径写入全局环境变量，而不是只写在.bashrc或.zshrc的某个分支里。

还有一类路径问题是关于技能扫描范围的。有些技能的规则里写了“扫描src/main/java下的所有文件”，如果在 Windows 或某些特殊目录结构下，AI 可能会把路径解析错。我建议在技能文件里统一使用相对路径，并在项目说明文件中明确写出根目录的绝对路径。别小看这个细节，AI 在长对话里对相对路径的解析能力并没有你想的那么稳。

5.4 一个通用避坑清单

上面这些问题是高频的，但还有一些零散的坑，我直接整理成一个清单放在下面，便于你排查时逐项对照：

这些问题基本覆盖了我现阶段遇到的大部分故障。说实话，用 superpowers 的过程就是不断跟 AI 对规则的过程，每一次问题排查，都是对技能库本身的一次完善。用到后期，你会越来越清楚哪条规则该怎么写、写到什么程度，AI 才会毫不走样地去执行。

6. 更进一步：把 superpowers 变成团队协作规范

6.1 技能库的团队共享

如果你只是一个人用，把 superpowers 当个人生产力工具就够了。但如果你在带团队，我强烈建议把整套技能库纳入团队仓库统一管理。原因是：AI 编码助手的输出风格高度依赖于你喂给它的规则，如果每个成员各自维护一套技能库，大家用 AI 写出来的代码风格会再次分叉，Code Review 时还是会有聊不完的风格争议。

我们团队的做法是建立一个独立的ai-workflow仓库，把技能库、项目模板、命令文件、示例代码全部收进去。任何人新接入一个项目，只需两步：克隆仓库、运行初始化命令。同时我们在项目仓库里固定引用该仓库的某个版本，而不是每次拉取最新的主分支，这样保证所有人产出的一致性。

这个做法还有一个好处：技能库本身是可 review 的。成员如果发现 AI 在某类任务上输出不佳，可以直接提一个修改建议，修改技能文件后发起合并请求。技能库的每一次变更都留痕，谁改的、为什么改、改了之后效果如何，都看得清清楚楚。

6.2 版本管理与持续优化

最后聊聊迭代。superpowers 这类东西不是装完就一劳永逸的，它应该跟项目代码一样，持续演进。我个人的习惯是每两周做一次效果回顾，挑几个代表性的 AI 生成任务，对比产出与团队期望的差距，然后针对性修改技能文件。

比如有一段时间我们团队发现 AI 生成的单元测试覆盖率总是偏低，仔细一看，是测试生成技能文件里没有写覆盖率标准。后来我在规则里加了一条强制要求：“测试必须覆盖正常流程、边界条件、异常路径三类场景。若存在未覆盖分支，必须明确标注原因。”再加上把覆盖率报告命令写进自校验步骤，这个问题基本就消失了。

还有一次发现 AI 写 SQL 时频繁使用select *，加了一条禁忌项之后效果立竿见影。这个迭代过程也让团队对 AI 的使用越来越有信心，因为规则不是死的，而是跟着项目的实际需要一起成长的。

我在实际使用中最深的体会是：superpowers 不是某个工具给你的固定能力，它只是一套把“你的专业经验”转译给 AI 的表达框架。你越清楚自己想要什么，越能把想要的东西写清楚，AI 给你的反馈就越接近你想要的标准。如果你刚上手，我的建议是先装一套社区维护好的技能库跑通流程，然后从第一个不满意的输出开始，动手改规则。用不了两周，你就能把 AI 调教成你想要的样子，而且是真正长在你团队规范上的那种“超能力”。