如果你最近在用 Codex CLI 这类 AI 编程助手写代码，大概率遇到过这样的场面：它看起来无所不能，能改文件、能跑命令、能解释报错，可一旦让你连续干几个小时的活，它就露馅了。任务稍微复杂一点就开始“失忆”，忘了你半小时前定的目录约定，跳过测试直接改代码，甚至把原本正常的逻辑顺手改崩。这种体验会让人琢磨：AI 编程助手到底是增强器还是捣蛋鬼？

其实问题往往不在 AI 本身，而在于我们交给它的“操作手册”太薄了。默认状态下，Codex CLI 只知道通用编程常识，不知道你的项目结构、代码规范、构建流程，更不知道你最在意的验收标准。要解决这个问题，就得给它补一层可复用的技能库。superpowers 就是干这个的，一个专门为 AI 编程助手设计的能力扩展集合，核心思路是把开发者的经验固化成结构化指令，让 AI 在遇到具体任务时按流程执行，而不是自由发挥。本文会完整写清楚 superpowers 是什么、怎么安装、怎么用，以及我在 Java 项目里实操时踩过的坑和排查思路，刚上手的人可以直接照做。

1. 项目到底是什么：superpowers 的定位与价值

1.1 它解决的痛点

先说一个所有 AI 辅助编程用户都会遇到的问题：上下文丢失。Codex CLI 这类工具有很长的对话记忆，但它不会像人类同事一样，在第二次合作时自然记得你的偏好。你昨天告诉它“测试用 Maven 跑，不要用 Gradle”，今天一开新会话，它又开始凭直觉行动，或者更糟，从一个陈旧的文件里猜出一套并不正确的命令。你重复解释的时间，往往比自己手写代码还要多。

superpowers 解决的就是这个“重复解释”的问题。它把项目中反复出现的操作场景，比如运行测试、提交代码、重构模块、处理依赖冲突，固化成一个个独立的技能文件。每个技能文件包含触发条件、执行步骤、完成标准，AI 在行动前会先判断当前任务是否匹配某个技能，匹配后按步骤执行。这样你就无需重新教它，只要确保技能文件写得够清楚，它就能表现出“接手过项目”的样子。

我打一个生活化的比方：你在公司带过一个新实习生，第一次让他发邮件，你花十分钟教了格式、称呼、附件规范。第二次他又忘了，你得再花十分钟。superpowers 相当于把这份“教导”写成了一份实习生手册，手册放桌上，他每次动手前翻一翻，就能保持稳定输出。AI 编程助手本质上就是那个记忆力不太稳定的实习生，手册越详细，它越靠谱。

1.2 它能做什么、适合谁

从功能范围看，superpowers 覆盖的开发技能很广，我整理成一张清单方便你对照：

适合的用户画像其实很宽：刚接触 AI 编程助手的新手，可以用它少踩坑；团队里已经有 AI 协作流程的，可以用它统一团队规范；个人开发者，可以用它把自己的工作习惯教给 AI。需要提前说明的是，superpowers 本身不包含“智能”，它的效果完全取决于你如何定义技能。它更像是一份员工手册，手册写得越细，AI 的表现越接近老手；手册是空的，AI 就还是那个自由散漫的实习生。

还有一个容易忽略的点：superpowers 的价值会随项目复杂度上升而变大。在只有一个文件的 demo 项目里，AI 自由发挥也无所谓；但当你面对一个 5 个模块、几十个依赖、测试要跑十分钟的中型项目时，没有技能约束的 AI 就是一台“随机破坏机”。所以我会建议每个有长期维护项目的人都认真看看这套东西。

2. 安装与初始配置：从零开始把 superpowers 跑起来

2.1 安装前的环境准备

在动手安装之前，先确认环境，这一步能避免一半的安装问题。我以最常见的“Codex CLI + superpowers 技能目录”组合为例，你需要准备四样东西。

首先是一台能正常联网的开发机，macOS、Linux、Windows WSL 都可以，Windows 原生命令行下跑软链接会比较折腾，如果你用的是原生 Windows，建议优先开 WSL。其次是 Node.js 18 以上和 npm，Codex CLI 的典型运行环境依赖它们，装完后先跑一下node -v和npm -v，顺手记录版本号，后续排查问题能省很多时间。然后是 Git 客户端，这个通常系统自带，但 Windows 上要注意是否勾选了 PATH 环境变量。最后是已经登录的 Codex CLI 或对应 AI 助手 CLI，如果还没登录，先执行codex login完成认证，再继续后面的操作。

这里有一个很容易踩的坑：很多人直接在旧版本 Node 环境下安装，结果装到一半才意识到版本太老，命令报错信息又晦涩，白白浪费时间。我建议用nvm管理 Node 版本，装到最新 LTS，环境干净了，后续所有工具的兼容性问题都会少很多。

2.2 安装步骤详解

第一步，把 superpowers 仓库克隆到本地。不同作者维护的仓库路径可能不同，最稳妥的方式是先到 GitHub 搜索superpowers codex，找到你认可的版本，然后执行：

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

我这里用~/superpowers作为安装目录，是因为用户目录下权限最不容易出问题。实际地址以你选择的仓库 README 为准。

第二步，把技能目录链接到 AI 助手的配置目录。以 Codex CLI 为例，技能文件通常放在~/.codex/skills/下，如果目录不存在就手动创建：

mkdir -p ~/.codex/skills ln -s ~/superpowers/skills/* ~/.codex/skills/

这里用软链接而不是直接复制，目的很明确：方便升级。下次 superpowers 仓库更新了，你只需要git pull，技能文件就会自动同步，不用再手动拷贝覆盖。如果你用的是 Claude Code 或其他工具，配置目录名会不同，常见的有~/.claude/skills/，原理完全一致。

第三步，验证安装是否成功。重新启动 Codex CLI，打开任意一个项目，直接问它：“列出你已经加载的技能。”如果安装正确，它会列出技能清单，你能看到类似run-tests、commit-changes、refactor-module这样的名字。如果它回答“没有加载任何技能”，不要急着重装，先检查软链接目录下的文件是不是空的，再检查文件权限。

提示：技能文件需要具备读权限，否则 AI 助手会在扫描阶段直接忽略。执行chmod +r ~/.codex/skills/*.md能解决大部分权限导致的不加载问题。

2.3 安装后的第一件事：写一个属于你自己的技能

装好之后别急着让 AI 帮你干活，第一件事应该是写一个最简单的自定义技能，把安装链路彻底跑通，顺便验证你对技能机制的理解。以一个build-demo技能为例，创建~/.codex/skills/build-demo.md：

# 技能名称：build-demo ## 适用场景 当用户要求构建本项目并验证产物时 ## 执行步骤 1. 运行 `mvn -q compile` 检查代码是否可编译 2. 编译通过后运行 `mvn -q package -DskipTests` 3. 检查 `target/` 目录下是否生成了 jar 包 4. 如果失败，列出完整错误日志，不要自行猜测原因 ## 完成标准 构建成功且产物存在，或提供可定位问题的失败日志

把这个文件保存后重启 Codex CLI，然后说“用 build-demo 技能跑一次构建”。如果它按你写的步骤逐条执行，说明整条链路已经通了。这一步的价值在于建立信任：你亲眼看到了技能文件如何变成 AI 的行为准则。很多人第一次装完 superpowers 就想让 AI 全自动写代码，结果不满意又卸载，其实只是因为他们连技能文件都没写对。

写技能文件还有一个隐藏收益：你被迫梳理自己的开发流程。比如“先编译再打包”“失败时不要猜原因”，这些平时靠直觉做的事，一旦要写成文字，你会发现很多流程自己都没想清楚。这个过程对任何开发者都是有好处的。

3. 核心技能拆解：superpowers 最值得用的几个能力

3.1 技能体系的运作逻辑

superpowers 的核心机制可以概括为“场景触发”。每个技能文件里包含三要素：触发条件、执行步骤、完成标准。AI 在对话中先判断当前任务是否匹配某个技能的触发条件，匹配后按步骤执行，而不是自由发挥。这个设计背后有一个很朴素的经验：给聪明人定标准流程，效率反而更高。AI 生成能力强，但上下文理解不稳定，有了明确的步骤约束，它跑偏的概率会大幅下降。

从技术实现路径来看，技能文件一般采用 Markdown 或 YAML 格式，放在约定目录，AI 助手会在启动时扫描目录，并把技能内容作为上下文注入。所以技能的编写质量直接决定 AI 的执行质量。一个含糊其辞的技能，比如“当需要测试时执行”，AI 会把它当成一个无关紧要的建议；而一个精确到命令级别、步骤之间逻辑闭环的技能，AI 会把它当成必须遵守的流程。

我强烈建议你在写技能时遵守三个原则：

• 触发条件要可判断。不要写“当有帮助时”，要写“当用户明确提到运行测试、检查测试失败或修改测试代码时”。
• 步骤要可验证。每一步都对应一个明确的动作：运行什么命令、读取什么文件、输出什么结果。
• 完成标准要可衡量。至少要能回答“这是一次成功执行，还是一次需要干预的失败”。

3.2 实操演示：用 run-tests 技能跑通一个完整测试周期

我拿最常用的run-tests技能来演示。假设你接手了一个 Java Maven 项目，想用 Codex CLI 做一轮完整的测试，技能文件可以这样写：

# 技能名称：run-tests ## 前置检查 - 检查根目录是否存在 `pom.xml` 或 `build.gradle` - 如果存在多模块，先运行 `mvn -q test -pl <模块名>` 定位到具体模块 ## 执行流程 1. 运行 `mvn -q test` 2. 如果存在失败用例，收集失败用例的类名和方法名 3. 运行 `mvn -q surefire-report:report-only` 生成测试报告 4. 读取 `target/surefire-reports/*.txt` 中的失败详情 ## 完成标准 - 输出测试通过率 - 列出失败用例清单 - 对每个失败给出初步原因分类（断言失败/环境问题/编译失败）

把这个技能放进技能目录后，让 AI 跑一次测试，它的输出质量会有肉眼可见的变化。对比一下没有技能和有技能时的表现：

实测下来最大的变化是：遇到多模块项目时 AI 不再迷路，失败定位从“猜”变成了“按日志找”。尤其是surefire-reports目录里的原始输出，没有技能时 AI 很少主动去读，有了技能它会把失败详情逐条贴出来，排错效率高了一大截。

3.3 commit-changes 技能：让 Git 提交也有章法

另一个强烈推荐的是commit-changes。AI 改完代码后，经常一股脑把所有文件都git add进去，然后生成一个含混的提交信息，对代码审查很不友好。这个技能会强制 AI 先查看变更，再分组提交，最后按规范生成提交信息。

我实际使用的一个简化版本：

# 技能名称：commit-changes ## 触发场景 用户要求提交代码变更 ## 执行步骤 1. 运行 `git status` 查看变更文件列表 2. 运行 `git diff` 区分功能性变更与格式化变更 3. 将功能性变更按逻辑分组，分别提交 4. 提交信息遵循 Conventional Commits：`feat/refactor/fix/docs` 开头 5. 若存在无关的调试文件或临时文件，明确询问用户后再决定是否提交 ## 完成标准 - 提交记录按逻辑分组 - 提交信息格式规范 - 不包含无关变更

这个技能最直接的价值，是省去了每次提交后手动整理 commit 历史的痛苦。更重要的是，它把“格式化改动”和“功能性改动”分开提交，审查者能一眼看出哪些行是格式变化，哪些行是真逻辑变化。对团队协作来说，所有人通过同一套规范生成提交记录，历史信息的可读性会明显提升。

如果你用 AGENTS.md 或类似的项目说明文件，可以在里面补充一句“所有提交必须走 commit-changes 技能”，这样 AI 每次触发提交行为时都会自动匹配技能，不需要你反复提醒。

4. Java 场景下的 superpowers 实战：从编译到依赖管理的完整闭环

4.1 为什么单独把 Java 拎出来说

如果你搜过 “superpowers java”，大概率是遇到了两种情况：一是想在 Java 项目里用 Codex CLI 辅助开发，二是踩了某个 Java 生态特有的坑。Java 项目跟 Node、Python 项目不太一样，启动慢、测试重、依赖管理复杂，AI 更容易在没有技能的情况下乱来，所以单独讲一下 Java 场景下的配置和实战经验特别有意义。

Java 项目最典型的痛点是多模块。一个稍大的工程往往有 parent POM、多个子模块，模块之间还有依赖顺序。AI 如果不了解结构，直接在根目录跑mvn test，要么触发一堆无关模块的测试，要么因为模块依赖没构建而报错。更麻烦的是 Maven 的依赖仲裁机制，一个传递依赖版本冲突可以藏得很深，AI 靠猜根本定位不到。所以在 Java 项目里，我建议至少配置三个技能：java-build、java-test、dependency-fix。

4.2 java-build 与 java-test 的组合用法

java-build的核心是处理多模块编译顺序和编译错误分类。建议的写法如下：

# 技能名称：java-build ## 前置检查 - 判断构建工具：`mvn -v` 或 `gradle -v` - 识别根模块：查找 `pom.xml` 或 `settings.gradle` ## 执行流程 1. 如果是多模块，从依赖底层模块开始编译：`mvn -q clean install -DskipTests` 2. 编译失败时，读取完整错误输出 3. 对编译错误按类型分类：语法错误、依赖缺失、版本冲突、资源文件缺失 4. 分类后按顺序解决，每次只修一类问题 ## 完成标准 编译通过且模块产物（jar/class）生成成功

配合java-test，就能形成一个完整的开发闭环。java-test的要点是，AI 需要先确认是否已有编译产物，再决定是只跑测试还是先全量构建。缺少这一步，AI 经常会在改动代码后直接跑测试，结果测试跑的是旧 class 文件，导致你看到的结果和实际行为不一致。

实际使用中我会把两个技能组合起来，形成一条固定的操作链：

1. 让 AI 运行java-build完成编译
2. 再运行java-test执行测试并整理失败用例
3. 修复后重新跑java-build和java-test，确认无回归

这套组合拳的好处，是 AI 不再抱着“一条命令走天下”的思路，而是按模块逐层推进。我在一个真实 Spring Boot 项目里，就用这套流程让 Codex CLI 完成了一次涉及 5 个模块的依赖冲突修复，整个过程没有把项目改坏。

4.3 dependency-fix：处理版本冲突的经验

Java 的依赖版本冲突是 AI 最容易翻车的地方。没有技能时，AI 会盲目改 pom.xml 里的版本号，改崩了再改回来，陷入死循环。更糟的是，它可能只改了当前模块的版本，忽略了其他模块仍引用旧版本，最后运行时报出莫名其妙的 NoSuchMethodError。

我的dependency-fix技能是这样写的：

# 技能名称：dependency-fix ## 执行流程 1. 运行 `mvn dependency:tree -Dverbose` 查看完整依赖树 2. 定位冲突项，找到同时依赖该库的多个模块 3. 优先使用 dependencyManagement 统一版本，而不是直接改子模块版本 4. 改完运行 `mvn -q compile`，确认编译通过 5. 再运行上下游模块测试，确认行为无变化 ## 完成标准 冲突消除，构建通过，关键测试通过

这个技能最大的价值，是把“改版本”这个危险动作变成了“先看依赖树再统一管理”的规范流程。依赖冲突这种事，AI 靠猜不可能解决，必须给它一条正确的侦查路径。你还会发现，技能里的第五步“运行上下游模块测试”非常关键，它避免了 AI 修好编译后立刻宣布成功，却忽略运行时行为异常的隐患。

如果你用的是 Gradle 项目，把mvn dependency:tree -Dverbose换成gradle dependencies --configuration compileClasspath即可，其他思路完全一致。依赖冲突的处理原则在任何构建工具里都一样：先看全貌，再定版本，最后统一入口管理。

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

5.1 安装失败类问题

安装阶段的问题其实都很机械，我把最常见的情况汇总成一张表：

我最常遇到的是第三种：技能文件里用了不规范的 YAML frontmatter，或者文件名带了空格，AI 助手在解析技能列表时中断了整体扫描，导致后面所有技能都加载失败。解决办法很简单：只用字母、数字、连字符命名文件，并严格按模板写 frontmatter。任何特殊字符都可能让解析器罢工。

还有一种隐蔽情况是软链接创建后，链接指向的源文件路径变化了。比如你把 superpowers 仓库移动到了别的位置，旧软链接就失效了，AI 扫描到的目录是空的。排查时运行ls -l ~/.codex/skills/，看链接是否还指向有效路径，这个动作能省下不少冤枉时间。

5.2 运行异常类问题

技能被加载了，但 AI 不按技能执行。这个问题在刚上手时几乎必现。原因通常是触发条件写得太模糊。比如技能文件里只写了“当需要测试时执行”，但 AI 判断不了什么时候算“需要测试”，它可能觉得聊两句测试方案就算需要，于是跳过了整个技能。

解决方法是把触发条件写得非常具体，最好直接列出用户可能说的指令变体：“当用户明确提到运行测试、检查测试失败、修复测试用例或查看测试报告时”。你会看到 AI 对技能的遵守率明显上升。另一个常见问题是技能步骤之间的衔接。AI 在执行完第一步后，如果第二步的条件不明确，它会跳回自由发挥模式。所以每一个步骤都应该是“可验证的动作”：运行什么命令、读取什么文件、输出什么结果。宁可把步骤写细，也不要指望 AI 替你脑补。

还有一个值得注意的点：技能的优先级问题。当项目里同时存在多个技能，且任务可以匹配多个触发条件时，AI 可能选了错误的那一个。解决办法是在触发条件里加入排除描述，比如java-test技能的触发条件里写明“排除单纯的编译请求”，这样它就不会和java-build抢任务。

5.3 使用体验优化

最后分享三条提升使用体验的经验，这是我在项目里用了几周后摸索出来的：

• 技能的粒度要小。单个技能只解决一个问题。不要写一个“开发代理”技能把编译、测试、提交全包进去，那样 AI 会选择性地执行一部分，结果就是不可控。一个技能对应一个可定义的验收动作，效果最稳定。
• 技能要配合项目文档使用。把项目结构、模块边界、构建工具写在 AGENTS.md 或 README 里，技能负责流程，文档负责背景。只靠技能文件去描述完整项目背景，会很累且容易过时。
• 定期更新技能库。工具链升级、目录结构变化后，技能里的命令可能失效。我习惯在每次较大重构后，让 AI 重新执行一遍关键技能，确认命令仍然可用，再顺手更新技能文件。

这三条看着简单，实际执行起来能避免绝大多数“AI 今天又抽风”的情况。尤其是第一条，很多人的技能文件写得像一篇散文，AI 根本不知道该在哪个环节停下来检查，流程自然就失控了。

5.4 一个典型的排查过程实录

说一个我真实踩过的坑。某次我把 superpowers 装好，然后让 Codex CLI 执行一次完整测试流程，结果它完全无视技能，直接给出一个mvn test就算完事。第一次排查，我以为是技能没加载，检查了目录、权限、frontmatter，全部正常。第二次排查，我发现技能文件里的触发条件写的是“当用户需要执行测试时”，这个描述表面能匹配，但它没有任何强制性说辞，AI 判断“聊聊测试也算需要执行测试”，于是选择了忽略。

我把触发条件改成“当用户明确说出‘运行测试’‘跑一下测试’‘检查测试失败’等指令时”，并加了更明确的完成标准，再试一次，它就按流程执行了。这个案例让我意识到一个核心问题：你在跟 AI 协作时，给的指令越结构化，它的表现就越稳定。模糊的自然是模糊地执行，精确的指令才能换来精确的产出。

这个排查过程也说明了一个很实用的原则：当 AI 不按技能执行时，先别急着怪工具，翻一下技能文件，看触发条件是否具体到“可判定”。绝大多数情况下，问题出在触发条件太抽象，而不是技能体系本身坏了。

最后再分享一个小技巧：技能文件本身就是项目文档的一部分。当你把它们写清楚，实际上也相当于给团队留下了一份“AI 可读的操作手册”。新同事或者新的 AI 实例加入项目时，都能快速对齐工作方式，这个价值往往比 AI 本身代写的代码还要大。我从第一次接触 superpowers 到现在，最大的体会是：这类工具的价值不在于“装上了”本身，而在于你愿不愿意花时间把经验写下来。给 AI 写技能，本质上是在梳理自己的开发流程，你写得越仔细，AI 就越像你。所以我的建议是，从一个小技能开始，先把你日常重复最多的一个动作固化下来。比如你就是反复跑测试、反复提交代码，那就先写run-tests和commit-changes这两张卡，用上一周，你会明显感受到 AI 干活方式的变化。