最近不少同事问我：明明 Codex CLI 这工具本身很聪明，可为什么让它改个跨模块的功能，改着改着就跑偏了？我一开始也困惑，直到我认真用上了一个叫 Superpowers 的开源增强方案，才算把这些毛病治得七七八八。这篇就把我实际安装、配置，以及用它驱动 Java 功能开发的完整过程写出来，希望能帮你少走一点我踩过的弯路。
Superpowers 的作用一句话就能说清：它给 Codex CLI 装上了一套可复用的“工程方法”——任务拆解、计划制定、子代理分工、测试驱动开发、上下文持续管理，这些从“提示词技巧”变成了项目里的实体文件。适合的人群很明确：日常用 Codex 写业务代码、但觉得结果不够稳定的开发者，以及想在团队里把 AI 编程规范固化下来的技术负责人。下面直接进入正题。
1. 为什么原生 Codex CLI 干活“飘”：先看看 Superpowers 要解决的问题
1.1 裸 Codex 的典型翻车场景
我最早用 Codex CLI 时，最挫败的不是它不理解需求，而是它太“就事论事”。比如我让它给一个已有 Spring Boot 项目加一个 REST 接口，它确实能写出 Controller，但它不会主动去看这个项目的分层结构、不会去翻已有 Service 的命名风格、更不会意识到我应该先写测试再写实现。等你追问一句“你怎么没加 Service 层”，它才会补一个出来，然后你又发现 Mapper 那块也没对。
这种体验总结起来就三个字：不省心。明明每一次对话里它都听懂了，但把几次对话串起来看，它缺乏一个完整的、贯穿始终的“任务观”。它不知道当前改动属于哪个大目标，不知道项目里有哪些约定必须遵守，也不会在动手之前给自己列一个检查清单。
1.2 Superpowers 给出的补强思路
Superpowers 的处理方式很有意思：它不尝试让模型本身变得更聪明，也不靠一段神奇的提示词去“唤醒”推理能力，而是把工程经验拆成一堆能被模型反复读取的文件——技能文件、命令脚本、子代理角色、项目级指引文件。
以前你每次开新对话都要手动跟 AI 交代“我们项目是 Maven 管理的”“Service 层要写接口和实现”“代码要遵守项目已有的风格”，现在这些内容都变成了文件，AI 在开始干活前会自动去读。以前 AI 做完一个步骤就等着你下一条指令，现在它跟着技能文件里的步骤清单走：先分析、再规划、后实现、最后验证。
这个思路本质上是把 AI 编程从“对话式问答”改造成“流程式协作”。就像你带一个能力很强但没什么经验的新人，与其每次都口述要点，不如给他一本操作手册和一张检查卡，让他按着跑。Superpowers 在我看来，就是给 Codex 准备的那本手册。
1.3 一句话读懂这个项目的架构
如果你去看 Superpowers 的仓库，会发现它的核心其实是三个部分：命令、脚本、技能。命令是你在 Codex 里直接斜杠调用的入口，比如/code、/superpowers；脚本负责完成一些自动化操作，比如提取变更摘要、更新规范文件；技能则是一组带描述和步骤说明的 Markdown 文件，每个技能都对应一类常见开发任务。
它们之间的关系可以这么理解：命令负责把任务领进门，技能负责告诉 AI 具体怎么做，脚本负责顺手把收尾工作做掉。我用的版本里，最常用的就是/code这个入口，它会自动加载规划技能，让 AI 先把任务拆成待办清单，再逐个去执行。下面我会把这套运行机制展开讲，但先别急，先把环境装起来再谈原理会更直观。
2. 环境准备与安装：按我的步骤走，二十多分钟能跑起来
2.1 前置依赖清单
安装之前，先把底下的环境确认好，避免装到一半才发现版本不对。
| 检查项 | 我的建议 | 说明 |
|---|---|---|
| Codex CLI | 已安装且能正常运行 | Superpowers 是增强层，依赖 Codex 本体 |
| Node.js | 18 及以上 | 仓库里的脚本和安装器依赖 Node 运行时 |
| Git | 已安装 | 拉取仓库和后续更新都需要 |
| 终端 | Bash 或兼容环境 | Windows 用户建议用 Git Bash 或 WSL |
我自己用的是 macOS 环境，Codex 是 npm 全局装的，Node 版本是 20。如果你还没装 Codex CLI，先去把它装好、确认codex命令能在终端里跑起来，再继续下面的步骤。
2.2 安装流程与关键路径
Superpowers 的安装方式很简单：把仓库克隆到本地，然后执行仓库里的安装脚本。脚本做的事情说白了就是复制文件——把命令文件复制到~/.codex/commands，把脚本复制到~/.codex/scripts，把技能目录复制到~/.codex/skills。不同版本的目录命名可能有细微差异，一切以官方仓库的 README 为准。
我当时操作的流程大致是这样的：
- 找一个你常用的工作目录，把仓库克隆下来；
- 进入仓库目录，执行安装脚本（一般是
./install.sh，有的版本也支持 npm 方式）； - 脚本结束后，检查
~/.codex/commands下是否多了一堆.md文件； - 重启终端里正在运行的 Codex 会话，输入
/help确认新的斜杠命令已经出现。
这里有一个细节需要特别注意：安装脚本只会把文件复制到位，不会自动帮你重启 Codex 会话。如果你安装完发现/code命令不存在，先别怀疑装错了，大概率是会话没重启。
2.3 装完怎么验证
装好之后，我建议你不要急着上真实项目，先做一个快速验证。启动 Codex，输入/code，然后随便给一个很小的任务，比如“帮我在当前目录生成一个 README.md，内容概述这个目录里的文件”。
观察 AI 的行为：正常情况下，它不会马上动手写文件，而是会先创建或更新一个待办清单（通常是todo.md），然后逐步打勾执行。你还会看到它尝试读取或生成AGENTS.md这个文件，里面是它对这个项目协作约定的理解。这个现象出现，基本就说明 Superpowers 生效了。
2.4 安装阶段最容易踩的三个坑
路径问题：~/.codex/commands里的文件需要有读权限，如果之前你以 root 身份装过 Codex，目录属主可能是 root，会导致当前用户读不到命令。解决办法很简单：sudo chown -R 你的用户名 ~/.codex一下。
版本兼容：Codex CLI 升级到新版本后，Superpowers 的旧命令文件不一定兼容。我遇到过升级 Codex 后/code命令报错的情况，最后是把 Superpowers 仓库更新到最新版、重新执行安装脚本才恢复。建议你用一段时间后就git pull一下仓库再装一遍。
Windows 路径差异：如果你在 Windows 上用 Git Bash 安装，脚本里写的很多路径是 macOS/Linux 风格的，可能会碰到路径转换问题。折中的办法是直接改用 WSL 环境，我在 Windows 机器上试下来 WSL 比 Git Bash 稳得多。
3. 技能文件、子代理与工作流：Superpowers 的底层运转逻辑
3.1 SKILL.md 与技能目录：把“经验”变成 AI 能读的文件
Superpowers 里最核心的概念是“技能”。什么叫技能？你可以把它理解成一个带有身份说明、使用场景和操作步骤的 Markdown 文件包。每个技能占一个目录，里面最重要的文件是SKILL.md，它规定了这个技能在什么情况下启用、按什么顺序执行哪些步骤、有哪些禁用事项。
举个我在 Java 项目里用到的例子：仓库里有一个专门负责“按项目规范编写单元测试”的技能。它的SKILL.md会写明“前置条件是新写的业务代码已完成”“步骤包括——确认测试框架是 JUnit 5 还是 4、检查已有测试的命名风格、为新类生成对应测试类、运行测试命令验证”，还会写“禁止直接跳过测试运行步骤”。AI 在接到相关子任务时，会去读取这份文件，而不是凭它自己的经验瞎猜。
这套设计的精妙之处在于：技能文件是团队经验和工程规范的可执行化载体。你不需要每次对话都重复“测试要跑到全绿”，只要技能文件里写了，AI 就会当成硬性约束去执行。
3.2 子代理与命令系统：谁负责想，谁负责做
Superpowers 还引入了一组“子代理”的概念。/code命令会先调用规划类子代理，让 AI 先做任务分解和方案设计；接着进入执行阶段时，又会调用执行类子代理去写具体代码；在验证阶段，还有专门的审查类子代理去检查结果。
这种分工的价值在于减少角色混乱。如果你让同一个智能体既当“架构师”又当“搬砖工”还当“质检员”，它的行为会有倾向——很容易急着写代码而跳过思考和验证。拆成不同角色后，规划阶段只输出计划和待办项，不写代码；执行阶段才写代码；审查阶段才挑毛病。整个流程更像一个真实团队的分工。
我用一个生活类比来解释：这就像你写了一台自动售货机，消费者投币之后，机器内部先判断商品在哪个货道、再联动传送带出货、最后亮灯提示取货。每一步有专门的模块负责，而不是让一枚硬币同时干所有事。
3.3 上下文保持与 AGENTS.md 的自动更新
Superpowers 另一个让我觉得靠谱的地方，是它把“项目记忆”固化了。Codex 的对话窗口是有限的，每条消息都会消耗上下文。如果你做了二十步修改，AI 很可能会忘记第十步之前的约定。Superpowers 的做法是维护AGENTS.md——一个项目根目录下的协作说明文件，里面记录着项目结构、命名规范、构建命令、测试方式等关键信息。
AI 每次开始任务前会先读这个文件，每次完成一个重要阶段后又会主动更新它。等于把“短期记忆”不断转存成“长期记忆”。我一开始还担心这个文件会被 AI 写得乱七八糟，实战跑过几次后发现，只要初始模板给得清楚，它维护出来的内容基本准确，偶尔有冗余，但整体可靠。
3.4 一次完整技能调用的生命周期
把上面这些串起来，一次/code驱动的完整开发流程大致是这样的：
- 读取项目根目录的
AGENTS.md和已有技能文件，理解项目约定； - 创建或更新
todo.md，把需求拆成可执行的小步骤； - 按优先级规划执行路径，确定哪些子任务需要调用哪些技能；
- 对每个子任务，按对应技能的
SKILL.md步骤执行； - 完成一项就更新一次待办清单，并同步刷新
AGENTS.md； - 全部完成后，做一次全局检查，确认没有遗漏或风格不一致的地方。
这个过程和裸 Codex 的最大区别是：它不再是一个“问一句答一句”的对话，而是一个有始有终、有清单、有验证的项目执行流程。这也是为什么它对复杂任务的效果提升远大于简单任务——简单任务你不需要这套流程，复杂任务没有这套流程就容易翻车。
4. Java 项目实战：一次完整的驱动式开发过程
4.1 任务设计与初始状态
说了这么多原理，拿真实项目跑一遍最直观。我挑了一个不算简单的任务：在一个 Maven 管理的 Spring Boot 项目里，新增一个“根据用户 ID 查询详情”的 REST 接口。项目的初始状态是有User实体类、UserRepository，但还没有 Service 层，也没有 Controller。
我启动 Codex，输入/code，然后写下需求：新增GET /api/users/{id}接口，要求包含 Service 层，使用已有的UserRepository，响应格式遵循项目里已有的统一返回结构，并补上单元测试。
这个需求本身就包含了不少隐含约束：要不要建 Service 接口、异常怎么处理、测试用 Mockito 还是直接用内存数据库。换作裸 Codex，我可能得追加好几条指令才能让它把细节对齐，而这次我全程没有干预。
4.2 技能串联的执行路径
任务提交后，我观察到的执行路径非常清晰。
第一步，AI 读取项目结构，更新todo.md，列出类似这样的小项：检查现有实体和 Repository 的方法、设计 Service 接口与实现、创建 Controller、补充 Service 层单元测试、运行 Maven 测试命令验证。
第二步，AI 并没有立刻写代码，而是先找到了我提到过的“按项目规范编写单元测试”技能，先写了UserServiceTest的骨架。这一步我当时愣了一下——正常直觉是先写实现再补测试，但技能文件里的流程是先确认测试目标、写失败测试、再写实现让它通过。这就是典型的 TDD 节奏，而这一整套节奏都被固化在了技能文件里。
第三步，实现阶段。AI 按AGENTS.md里记录的命名规范完成了接口和实现类，Controller的返回类型也自动套用了项目已有的ApiResponse<T>结构，没有出现“跑偏”的情况。整体代码风格和项目原有代码保持一致，我审查起来省了很多力。
第四步，运行mvn test验证。这一步让我很满意的是，AI 没有在测试还红着的时候就说“完成了”，而是真的把测试跑绿了才更新待办清单。整个过程我零介入，任务完成后它还在AGENTS.md里追加了一条关于 Service 层结构约定的记录。
4.3 实测表现与原生模式的对比
我把这次表现和以前裸 Codex 的结果做了个对比，差异非常明显：
| 维度 | 裸 Codex 的典型表现 | 使用 Superpowers 后 |
|---|---|---|
| 任务拆解 | 一次性生成全部代码 | 先列待办，逐项执行 |
| 测试行为 | 容易跳过或只写“看起来对”的测试 | 先写失败测试，再跑绿 |
| 项目风格 | 大概率忽略已有约定 | 自动读AGENTS.md，遵循规范 |
| 文档维护 | 不主动更新 | 主动刷新项目协作说明 |
| 多步骤一致性 | 长任务容易前后矛盾 | 通过待办和文件固定上下文 |
我特别想强调的是“多步骤一致性”。裸 Codex 在长任务里经常出现前后矛盾，比如前面用了某个工具类，后面又重新定义了一遍；Superpowers 模式下这类情况明显减少，核心原因是每一步都有文件可以参考，AI 不需要靠上下文记忆硬撑。
当然，它不是万能药。遇到业务逻辑特别模糊、需要大量领域判断的任务，它依然会卡壳。这时候我不会怪 Superpowers，因为流程和方法只能保证“做得对”，不能替我做“该做哪个”的决策。
5. 调优建议与真实使用边界
5.1 哪些场景收益最大
用了一阵子之后，我明显感觉到 Superpowers 的收益是分场景的。收益最大的是三类任务：
第一，跨多文件的新功能开发，比如上面这种新增接口、新增模块的任务，流程化带来的收益非常明显； 第二，需要严格遵守团队规范的任务，比如必须遵循特定分层、特定命名、特定测试风格的项目，技能文件比口头交代靠谱得多； 第三，需要反复迭代修改的任务，比如你让 AI 改完这轮还要改下轮，待办清单和AGENTS.md能帮它记住上一轮是怎么处理的。
收益相对有限的场景包括：单文件小改动、纯研究性或探索性任务、对实时性要求极高的对话式问答。这种场景里 Superpowers 反而显得有点“重”，因为它再怎么也得先读文件、建待办，这些动作会拖慢响应速度。
5.2 自定义 Java 技能的正确姿势
如果你想把 Superpowers 真正用成自己的工具，光靠内置技能是不够的，自定义技能是绕不开的一步。我调试了无数次之后总结出的经验是：不要一上来就写大而全的技能，而是从一个你反复做过、经常嫌 AI 做得不好的真实任务开始。
比如我团队里有个项目要求“新增数据库表时必须同时生成对应的 Flyway 迁移脚本和实体映射”。以前每次都要手工提醒 AI 两三次，后来我写了一个专门的技能，把步骤拆成：检查迁移脚本目录命名规则、按照版本号生成新的 SQL 文件、编写实体映射、运行迁移验证命令。技能文件写好后，这个任务我基本可以放手了。
写技能文件有几个关键点：描述要写清楚使用条件，让 AI 能判断“什么时候该激活这个技能”；步骤要足够细，每个步骤之间逻辑连贯，AI 不容易中间卡住；一定要写禁止事项，比如“禁止在未运行迁移验证的情况下标记任务完成”。这几个要点，比你在提示词里苦口婆心说十遍都管用。
5.3 需要绕开的限制与替代方案
使用 Superpowers 到现在，我遇到的最大的限制是“它或多或少会改变你的使用习惯”。你不能再随手一问就指望它给个出色方案，你得接受先建待办、再分步执行这个相对慢的节奏。如果你日常主要用 Codex 做快速问答，刚开始可能会觉得“怎么变笨了”。但只要切换到真实开发任务，就能明显感觉到后半程的省力。
另外一点是技能文件的质量决定了 AI 的表现。如果你仓库里的技能写得很烂，AI 执行起来会一板一眼地错，甚至比没有技能更糟。我的建议是先小范围试点，确认流程跑通后再铺开。
如果你试了之后觉得 Superpowers 不适合自己的项目结构，也可以参考它的思路自己写一套轻量方案：核心就是“项目规范文件 + 命令入口 + 技能目录”，这三件套完全可以手动搭建，不用依赖任何第三方仓库。我在另外一个小型开源项目里就这么干过，效果依然不错。
最后再分享一个小技巧：每次更新 Superpowers 之后，别直接上生产项目测试，先在临时目录里用一个空仓库跑一遍/code，确认命令加载正常、技能目录没被覆盖丢，再回到真实项目里继续用。这个习惯帮我躲过好几次因为版本更新导致的配置丢失问题。
