如果你最近在用 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 覆盖的开发技能很广我整理成一张清单方便你对照技能类型解决的问题典型场景测试类技能定位测试目录、运行测试、整理失败报告跑通一次完整测试并修复失败用例提交类技能分组暂存、规范提交信息、过滤无关文件完成一轮逻辑清晰的 Git 提交构建类技能识别构建工具、处理多模块编译、分类错误Maven/Gradle 项目编译失败排查重构类技能分步变更、验证编译、回滚方案安全拆分一个大方法依赖类技能依赖树分析、版本冲突处理、统一版本管理修复依赖冲突并保证构建通过审查类技能按清单检查代码质量、输出结构化意见提交前的自测代码审查适合的用户画像其实很宽刚接触 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 以上和 npmCodex 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 行为有技能的 AI 行为定位测试猜测测试命令可能在根目录直接跑mvn test检查 pom.xml、定位模块、确认测试目录执行测试一次性运行全部测试耗时且难定位失败按技能分批运行失败时定位到具体用例报告结果只说“测试失败”输出失败列表、堆栈摘要、原因分类修复建议凭经验猜测按技能要求读取日志先定位再修实测下来最大的变化是遇到多模块项目时 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 Commitsfeat/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 文件导致你看到的结果和实际行为不一致。实际使用中我会把两个技能组合起来形成一条固定的操作链让 AI 运行java-build完成编译再运行java-test执行测试并整理失败用例修复后重新跑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 安装失败类问题安装阶段的问题其实都很机械我把最常见的情况汇总成一张表现象可能原因排查方式克隆仓库失败网络问题或仓库地址错误检查地址、更换镜像源、确认网络环境技能目录链接失败目标目录不存在先创建~/.codex/skills/目录再建软链接AI 助手启动报错技能文件格式不规范检查 frontmatter 和文件名确保无中文或特殊字符技能未加载目录权限不足给技能文件添加读权限chmod r *.md我最常遇到的是第三种技能文件里用了不规范的 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 干活方式的变化。