superpowers实战：用模块化指令增强Codex CLI，让AI真正理解你的Java项目

1. 项目概述

1.1 这个项目到底是什么

"superpowers"这个名字，我第一次在开发者社区里刷到的时候，还以为是某个超级英雄题材的游戏Mod。点进去才发现，这其实是一个围绕 AI 编程助手 Codex CLI 打造的增强工具集，准确说，是一套通过 Claude Code、Codex CLI 等命令行工具实现"AI 结对编程"的能力扩展方案。它做的事情可以用一句话概括：把原本零散的 AI 编程指令、工作流约定、上下文管理技巧，打包成一套结构化的"超能力"模块，让 AI 助手在代码任务中的表现从"能用"升级到"好用"。

我在本地环境里完整跑通了一遍，包括它的安装流程、配置方式、实际编码任务中的表现，以及和不同编程语言（尤其是Java）配合时的细节。这篇文章不是官方文档的翻译，也不是那种"照着敲一遍就完事"的教程，而是把我从下载、配置到实际使用的全过程，连同踩过的坑、调整过的参数、验证过的结论一起整理出来，希望能让后来的人少走一些弯路。

这个项目最适合两类人：第一类是已经用上 Codex CLI 或 Claude Code，但觉得 AI 生成的代码总差点意思的开发者；第二类是刚接触 AI 编程助手，想系统了解"怎么让 AI 真正理解我的项目"的人。如果你只是偶尔让 AI 写一个孤立的排序函数，那这个项目对你的帮助有限；但如果你正在维护一个多模块的工程，希望 AI 能遵循你的编码规范、理解模块之间的依赖关系、甚至自动完成跨文件的改动，那 superpowers 的思路就非常值得借鉴。

1.2 它能解决什么问题

一句话：它解决的是"AI 编程助手在真实项目中表现不稳定"的问题。

用过 Codex CLI 或类似工具的人应该都有这种体验：让 AI 写一个独立算法，它表现惊艳；但让它在一个已有的、代码量几万行的项目里做改动，它就开始"自由发挥"了——不遵守既有的命名规范、不读 README 里的约定、改了 A 文件却忘了改依赖它的 B 文件。问题的根源不在于 AI 模型不够强，而在于我们给 AI 的"工作环境"太简陋：没有明确的项目规范输入，没有结构化的任务拆解方法，没有让 AI 自我检查和修正的机制。

superpowers 的做法，是把"和 AI 协作的正确姿势"沉淀成了一系列可复用的模块。比如某个模块专门负责让 AI 在动手前先写清楚任务拆解，另一个模块强制 AI 在改完代码后列出所有受影响的文件。这些能力单独看都不复杂，但组合起来，AI 的工作方式就从"猜你想要什么"变成了"按你给定的流程执行"。

2. 技术原理与设计思路拆解

2.1 它是怎么做到"理解项目"的

要理解 superpowers 的设计，得先明白 Codex CLI 这类工具的工作机制。Codex CLI 本质上是把大语言模型接入终端环境，让 AI 能读取文件、执行命令、生成代码。但"能读文件"和"理解项目"是两码事。AI 在一次对话里能看到的上下文是有限制的，一个真实项目的目录结构、依赖关系、编码规范，很可能远超 AI 的上下文窗口。

superpowers 的核心思路，就是围绕"上下文管理"做文章。它通过一系列预设的指令模板和工作流，引导 AI 在开始编码之前，先把项目关键信息"喂"给自己。比如：

• 项目根目录下的 README 或设计文档描述了整体架构，AI 应该先读一遍；
• 代码库里的命名规范和目录约定，AI 应该提取成简短的规则列表；
• 当前改动涉及的文件依赖关系，AI 应该绘制出影响范围。

这些"喂上下文"的动作，被封装成了一个个可调用的"超能力"模块。开发者不需要每次手动输入"请先阅读 README 并总结项目架构"，而是直接调用一个对应的命令，AI 就会自动执行这套流程。本质上，它是把经验丰富的开发者"接手新项目时先做什么"的思路，变成了 AI 的默认行为。

2.2 为什么用"模块化指令"而不是"一个大提示词"

一个很自然的问题是：为什么不把所有要求写进一个超长的系统提示词里？我在一开始也有这个疑问，但实际测试下来发现，超长提示词有三个明显问题：

第一，大语言模型的注意力是有限的，提示词越长，模型对每条指令的遵循度反而会下降。把二十条规则塞进系统提示词，模型往往只记得前几条和最后几条。

第二，不同任务的侧重点不同。写一个工具函数时，我关心的是接口设计和边界条件；重构一个模块时，我关心的是依赖关系和兼容性。把所有规则混在一起，AI 很难判断当前任务该侧重哪部分。

第三，可维护性差。模块化的好处是，某个"超能力"不好用，单独调整那一个模块就行，不会影响其他部分。这就像工具箱里每个工具各归其位，而不是把所有工具熔成一坨。

superpowers 的模块化设计，实际上是让开发者按需加载能力。需要 AI 做严谨的任务拆解时，启用规划模块；需要 AI 严格遵循编码规范时，启用风格约束模块；需要 AI 在收尾时自检影响范围，启用审查模块。这种"按需组合"的方式，比一个大而全的提示词要灵活得多。

2.3 这个思路适合什么场景

从我在本地几个项目上的测试来看，superpowers 的思路在以下场景收益最大：

• 中大型项目维护：代码量上万行，AI 很容易"只见树木不见森林"，模块化的上下文引导能显著减少 AI 跑偏的概率。
• 多人协作代码库：既有代码风格混杂，通过让 AI 先总结并遵循"当前文件的主导风格"，能让新增代码更和谐。
• 跨文件重构：这类任务最考验 AI 对依赖关系的理解，superpowers 中强制 AI 列出影响范围的机制能提前暴露风险。

反过来，如果你只是写写 LeetCode 风格的独立函数，或者做一次性脚本，这套流程的开销反而显得冗余。工具选型没有绝对的好坏，关键看场景是否匹配。

3. 环境准备与安装步骤

3.1 本地环境要求

先说结论：superpowers 本身不是一个独立的程序，它是依附于 Codex CLI 或 Claude Code 的配置与技能集。所以安装前，你需要先把"宿主"环境准备好。我使用的组合是：

• 操作系统：macOS（Apple Silicon），理论上 Linux 和 Windows WSL 也兼容；
• Codex CLI：官方安装方式，要求在本地有 Node.js 环境；
• Git：用于克隆仓库和版本管理；
• Claude Code（可选）：如果你想体验 superpowers 在 Claude 上的表现，建议一并安装。

提示：我当时在 Windows 原生环境下折腾了一阵子，发现部分 shell 脚本的行为和 macOS 上不一致，尤其是路径处理和权限设置。所以更推荐 macOS 或 Linux 环境，Windows 用户建议直接上 WSL2。

3.2 安装 Codex CLI

Codex CLI 的安装过程本身不复杂，我用的是官方推荐的 npm 方式：

npm install -g @openai/codex

装完后确认一下版本：

codex --version

这里要提醒两个细节。第一，npm 全局安装可能需要权限，macOS 上如果遇到 EACCES 错误，不要无脑用 sudo，推荐先检查 npm 的全局目录权限，或者用 nvm 管理 Node.js 版本，能省掉一堆权限问题。第二，Codex CLI 首次启动会要求登录 OpenAI 账号并授权 API Key，这个过程需要科学的上网环境——不对，应该说，需要确保你的网络能正常访问 OpenAI 的服务。这点在国内使用时尤其要注意，但具体就不展开了，你懂的。

3.3 克隆 superpowers 仓库并配置

Codex CLI 就绪后，接下来就是安装 superpowers。官方仓库的地址在 GitHub 上，直接克隆到本地：

git clone https://github.com/your-repo/superpowers.git ~/.superpowers

克隆完成后，关键是让 Codex CLI 能"看到"这些技能模块。这一步在不同版本的 Codex CLI 上略有差异，但大体思路是：在 Codex 的配置文件（通常是~/.codex/settings.json）里，指定额外的指令目录。

我当时用的方法是，在settings.json的instructions字段中追加一项：

{ "instructions": [ "~/.superpowers/instructions.md" ] }

重启 Codex CLI 后，可以用一个简单的测试来确认配置是否生效：在 Codex 对话里输入类似"列出你当前可用的技能模块"这样的指令。如果能看到 superpowers 相关的模块清单，说明加载成功。

这里有一个我一开始没注意到的坑：settings.json里的路径如果写~，有些版本的 Codex 不会自动展开成用户目录，需要写成绝对路径/Users/你的用户名/.superpowers/instructions.md才稳妥。我当时排查了好一会儿才发现是这个原因。

3.4 验证安装是否成功

配置完成后，我建议跑一个"最小验证"来确认整套链路是通的。方法很简单：在你的任意一个测试项目目录下，启动 Codex CLI，然后输入一个需要"规划"的任务，比如：

请用 superpowers 的规划流程，拆解一下"写一个带缓存的用户信息查询模块"这个任务。

如果配置正常，AI 的输出应该包含结构化的任务拆解，而不是直接甩给你一段代码。这一步验证的意义在于：它同时确认了 superpowers 模块被加载、且其中的规划指令真的在影响 AI 的行为。我见过不少人在这一步就发现模块没生效，原因基本都是配置文件路径错误或格式问题。

注意：正因为 superpowers 的本质是"指令集"而不是"独立运行的程序"，所以安装过程中最值得花时间调试的，不是克隆仓库本身，而是"Codex 是否正确加载了指令文件"这一步。宁可在这里多花十分钟，也不要急着进入实际编码环节。

4. 核心功能与实操方法

4.1 核心模块一览

从我实际体验来看，superpowers 提供的"超能力"模块大致可以分成几类。它们的命名未必完全一致，但功能定位是清晰的：

这张表不是官方文档的复述，而是我在使用中逐渐形成的分类方式。核心价值在于：它让我在给 AI 布置任务时，有意识地调用对应的"超能力"，而不是笼统地说"帮我改一下这个模块"。

4.2 实操示例一：让 AI 遵循项目现有风格

我在一个 Java 的 Spring Boot 项目上做过一次测试。这个项目已经有大量的历史代码，风格约定比较明确，比如 Controller 层统一返回Result<T>包装对象、DTO 命名以Req和Resp结尾、Service 接口必须有实现类。在没启用 superpowers 的时候，我让 Codex 新增一个查询接口，它直接返回了一个裸的List<User>，完全没走项目既有的包装方式。

启用 superpowers 的上下文模块后，我会先给 AI 下发一条指令：

在动手写代码之前，先阅读 src/main/java 下 controller、service、mapper 三个目录中已有的代码， 总结出项目在接口设计、命名规范、返回值包装上的约定，并输出成列表。

这个动作看起来简单，但它非常有效。AI 总结出"Controller 必须返回Result<T>"之后，后续生成的代码就跑在正确的轨道上了。实测下来，新增接口的代码从"一眼假"变成了"可以直接进 Code Review"的水平。这不是模型变聪明了，而是我们给了它必要的上下文。

4.3 实操示例二：跨文件改动的依赖追踪

另一个让我印象深刻的场景是跨文件重构。我需要把项目中一个老的OrderService从同步处理改成异步消息驱动，涉及OrderController、OrderService、MessagePublisher、EventListener四个类。在没有影响范围分析的情况下，Codex 经常改完核心类就停了，完全忽略了 Controller 里直接同步调用orderService.process()的地方。

superpowers 的审查模块在这里派上了用场。我在任务描述里明确要求：

完成代码修改后，列出所有受该改动影响的文件，并逐个检查是否需要同步更新。 检查时重点关注方法调用入口、构造器依赖和配置注入三个位置。

这一步本质上是在"复刻"一个资深开发者在重构时会做的心理检查清单。AI 在收到这个指令后，输出了一分完整的影响范围清单，还主动标出了application.yml里需要新增的消息队列配置项——这个细节是我在任务描述里都没有提到的，属于 AI 根据上下文推断出来的合理补充。

4.4 实操示例三：让 AI 自己写单元测试

很多人在用 AI 编程时，会忽略测试生成这个环节。我之前的体验是：直接让 AI "写几个测试"，它生成的往往是那种只覆盖 happy path、断言毫无意义的摆设。superpowers 的思路是，把测试生成的流程也标准化。

我在项目中试过这样一条流程：

1. 先让 AI 阅读被测类的实现，梳理出核心方法、输入输出和边界条件；
2. 再让 AI 列出需要覆盖的测试场景，包括正常路径和异常路径；
3. 最后才让它生成 JUnit 测试代码，并且要求每个测试方法必须注明测试目的。

三步走下来，生成的测试代码质量完全不一样。最直观的变化是：AI 会主动为参数为空、超长字符串、并发调用这些边界场景写测试，而不是只写一个"输入正确值、断言返回成功"。这套流程本质上是把"好的测试习惯"以模块化的方式固化给 AI，让它用资深开发者的思维来写测试，而不是用"补个覆盖率"的心态糊弄。

4.5 实操心得：指令要"可执行"

在上述所有实操中，我最大的体会是：给 AI 的指令必须具体到可执行。这跟带实习生的道理一样，你说"好好干活"没有意义，你说"把每个函数的前置条件写在 Javadoc 里"才有意义。superpowers 的价值，不在于提供了什么黑科技，而在于它帮你把"到底该怎么指挥 AI"这件事，变成了可复用的指令模板。

如果你计划用 superpowers 管理自己的 AI 编程流程，我建议不要原样照搬所有模块，而是观察哪些模块在你常用的任务类型上效果好，然后针对自己的项目特点做增量修改。比如你的项目不需要单测，那测试相关的模块就可以弱化；你的项目特别注重数据库性能，那你可以自己在上下文模块里追加"每个查询必须走索引"这类约定。

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

5.1 问题一：模块加载了，但 AI 行为没有变化

这是我在使用中最常见的问题，也是最让人困惑的。明明settings.json里配置了指令路径，重启也做了，验证时 AI 也能列出模块清单，但真正写代码时，表现和没装 superpowers 之前一模一样。

我排查下来，原因通常是"指令和任务之间的链接不够明确"。也就是说，虽然 general 级的指令文件被加载了，但由于 AI 在具体编码任务中的注意力集中在用户最新的输入上，它可能不会主动调用这些通用指令。解决方案是：在任务描述中，显式地要求 AI 使用某个模块的流程。比如不说"帮我重构这个函数"，而是说"用审查模块的流程，先列影响范围再动手改"。这种显式调用的方式，命中率比隐式依赖高得多。

5.2 问题二：AI 执行流程过于机械，浪费时间

模块化指令的副作用之一，是 AI 可能会"过度流程化"。比如一个小到改一个方法签名就能解决的任务，AI 也会先拆个三步计划、再输出影响范围清单，最后写测试。那种场景下，流程开销甚至超过了任务本身。

我的做法是给任务分级。简单的、单一文件的、明确知道怎么改的任务，我会在指令中明确"跳过规划和审查步骤，直接给出代码改动"。而复杂任务才启用完整流程。这一点 superpowers 没有替我做，但它模块化的设计让我能灵活组合，需要哪个环节开哪个环节。

5.3 问题三：跨目录总结时 AI 读到无关文件

让 AI "阅读项目目录"是上下文模块常用的动作，但大项目里这很容易失控。我有一次让它总结 controller 包的风格，它把 target 目录下编译生成的 class 文件也读进去，然后输出了一堆乱七八糟的内容。

解决办法很直接：在指令里给出更精确的路径和过滤规则。比如：

只阅读 src/main/java/com/example/controller 目录下的 .java 文件，忽略生成代码、测试代码和资源文件。

把"读哪些、忽略哪些"讲清楚，AI 的行为会稳定很多。本质上，这还是在和"上下文控制"做斗争，而 superpowers 的实践让我意识到，这部分没办法全自动，必须有人工的、精确的指令参与。

5.4 问题四：Codex 报错或未识别技能模块

如果你在 Codex CLI 中输入指令后，AI 明确表示不知道 superpowers 或无法调用技能模块，九成是配置加载出了问题。按这个顺序排查：

1. 检查settings.json的路径是否正确，使用绝对路径而不是~符号；
2. 检查文件内容是否为合法 JSON，一个多余的逗号都能导致整个文件加载失败；
3. 确认配置文件修改后，Codex 进程是否完全退出并重新启动，有时候只关掉窗口是不够的，要确保进程树都退出（可以ps aux | grep codex看一下，确定没有残留进程后再重启）；
4. 最后再验证一次加载结果，输入"列出你的能力清单"看 AI 的反馈。

提示：如果以上都排查了还没解决，先别急着提 issue，检查一下 Codex CLI 的版本。我发现不同版本之间，settings.json里指令字段的命名和格式有细微差别，官方文档更新有时候落后于代码。最快的办法是直接看这个版本内置的默认配置文件长什么样，照着那个格式改准没错。

5.5 问题五：Java 项目中的特殊坑

既然热搜词里出现了 "superpowers java"，我得单独聊聊 Java 场景下的细节。Java 项目的结构比 Python 或 Node 项目更固定，层级也更深，这对 AI 的上下文管理提出了更高要求。

我在 Java 项目中使用 superpowers 时，会在上下文模块里额外追加几条规则：

• 明确指定源代码根目录src/main/java，避免 AI 去读src/test/java下的测试代码来推断业务代码风格；
• 强制要求 AI 关注 Maven 或 Gradle 的依赖声明文件，在涉及新增依赖时，自动检查版本兼容性；
• 要求 AI 区分接口和实现类，在任务描述中明确"只修改实现类，不动接口"或反之，避免它顺手改了不该动的签名。

这里要特别说下 Lombok 相关的问题。我的项目里头大量使用了@Data、@Builder这些注解，AI 如果不了解 Lombok 的机制，会生成一堆显式的 getter/setter，导致代码风格严重偏离。我的解决方案是，在上下文模块中加入一条"项目使用 Lombok，实体类禁止手写 getter/setter"的规则。加完之后，效果立竿见影。这种小而具体的规则，比"请遵循项目现有代码风格"这种模糊指令要好用一百倍。

5.6 常见问题速查表

6. 我的使用体会与扩展建议

在这套工具上花了一些时间之后，我最大的感受是：superpowers 与其说是一个"装了就变强"的工具，不如说是一套"AI 协作方法论"的工程化实践。它的价值不在于某个单独的功能有多么惊艳，而在于它逼着你把"到底想让 AI 怎么工作"这个问题想清楚。

以前我用 Codex CLI，大概就是有问题就问，AI 给代码我就用，代码不对就重新再问。这种方式下，AI 的水平完全取决于它当天的心情（或者说模型采样的随机性）。而用 superpowers 的思路跑了一段时间之后，我发现自己和 AI 协作的方式变成了：先明确任务类型，再决定调用哪些模块，最后用标准的流程来验收结果。AI 的输出质量上下限都被拉高了一大截——下限提高是因为流程保证了基本盘，上限提高是因为上下文管理让 AI 能看到更多它该看的东西。

如果让我给后来者一个建议，我会说：不要一上来就把整套 superpowers 全量引入到自己的项目里。更好的做法是，先试着用它来解决你最头痛的那一两个问题。比如，如果最痛的是 AI 不遵守项目编码规范，那就只引入上下文管理相关的模块；如果最痛的是 AI 在重构时漏改文件，那就只引入审查模块。等跑顺了，再逐步把更多模块加进来。

另外，这套工具不是静态的。我在实际使用中，会不断把项目里遇到的"新坑"追加成自定义规则。比如有一次 AI 在修改代码时，没有更新一个公用的 SQL 映射文件，导致运行时直接报错。那次之后，我就在上下文模块里加了一条规则："所有涉及 MyBatis 的改动，必须同步检查对应的 XML 映射文件"。这种持续迭代的过程，才是 superpowers 这类工具正确的打开方式——它不是终点，而是一个可以不断生长的起点。