如果你最近在用 Codex CLI 这类终端里的 AI 编程助手大概率遇到过这个场景让它修一个接口它三下五除二把代码改了但既不跑测试也不更新依赖文档甚至心情好时还会把不相关的文件一起格式化。输出完全像开盲盒。我后来把一套名为 superpowers 的技能包接进工作流这种“抽卡式”编程体验才算稳定下来。superpowers 不是什么黑魔法它是一套以 Markdown 文件为核心的“技能库”。每个技能对应一个明确任务比如代码审查、测试生成、重构计划AI 在执行前先读取这些文件相当于拿到一份前辈整理好的操作手册。它解决的核心问题是默认状态下的 Codex 更像一个“很聪明但没有职业习惯的实习程序员”而 superpowers 把这些职业习惯——先分析再动手、改完必须补测试、提交前检查边界条件——一件件固化下来。这篇文章写给谁如果你在用 Codex CLI、或者任何支持 AGENTS.md 的终端编程助手又恰好被 AI 的输出波动折磨过应该能直接用上。尤其是 Java 后端开发者我在文章里会专门讲怎么把 superpowers 和 Maven/Gradle 项目对齐。下面所有内容都基于我自己的安装与使用经验细节以项目官方 README 为准。1. 先搞清楚 superpowers 解决的是哪个痛点1.1 Codex 不是能力不够是缺少“职业习惯”Codex 这类工具本身很强。给一段代码它理解上下文、生成补丁的速度比大多数人类还快。但问题在于它默认的工作方式太“自由”你说“帮我看看这段代码”它可能只给两行意见你说“优化一下”它可能把整个文件重写了。没有统一的标准就没有稳定的产出。我试用过一段时间裸奔状态下的 Codex最难受的一点是它不会主动做“完整闭环”。让它改一个 Java 方法它会改但不会自己去跑mvn test让它查一个 bug它可能给一个局部修复却没有检查是不是还有相同模式的其他调用点。这些不是模型能力缺陷而是缺少流程约束。superpowers 的切入点就在这里它不试图提升模型的知识水平而是把成熟开发者的做事流程写成 AI 能读懂的执行手册。与其每次手动在 prompt 里把流程敲一遍不如让 AI 自己加载一个技能文件按里面的步骤走。1.2 一个技能文件到底是什么以最常用的代码审查技能为例。它的核心文件通常是一个SKILL.md开头是 YAML 格式的元信息技能名称、用途描述、触发关键词。正文是具体执行的检查步骤比如先理解改动范围和调用链路不要只盯着 diff 的几行检查错误处理分支是否完整检查是否有并发或状态一致性问题检查单元测试是否覆盖新增逻辑最终输出按“严重问题 / 建议改进 / 风格问题”分类这段内容看起来平平无奇但对 AI 的效果非常明显。因为模型在生成回应时会尽量遵循上下文里给出的指令结构。一份写清楚的技能文件比你在 prompt 里即兴说“你仔细点”有效得多。1.3 谁最适合引入 superpowers从我自己的经验看有三类人收益最大。第一类是长期使用 Codex 处理真实项目代码的人尤其是 Java、TypeScript 这类工程化程度高的语言因为光靠模型自由发挥测试和构建环节最容易丢。第二类是想要“团队 AI 行为一致性”的场景比如几个人共用一套 Codex 配置希望 AI 的输出风格统一而不是每台电脑一个性格。第三类是写 prompt 写烦了的人与其每次重复描述流程不如集中写一次技能文件长期复用。如果你是那种只用 AI 聊天问答、不跑工程命令的人superpowers 暂时帮不上太多忙。它更适合放在“AI 替我写代码”的环节里。2. 核心设计拆解为什么技能库比“一条大提示词”靠谱2.1 技能文件的结构化设计一个完整的 superpowers 技能包通常包含三部分元信息、执行步骤、验收标准。元信息解决“什么时候该用这个技能”。AI 收到任务后会先根据技能描述判断是否匹配。比如你在 prompt 里说“帮我做个设计评审”如果技能描述里写了“用于设计评审、方案评估”它就更容易被触发。执行步骤是核心它把任务拆成有序的小步骤每一步尽量可检查、可输出。最后是验收标准告诉 AI 做到什么程度才算完成。例如“所有新增代码必须包含对应测试”“构建命令必须执行成功”。这套结构和人写的 SOP 很接近。我经常跟朋友说superpowers 的底层思想不是技术而是管理把不确定的工作拆成确定的小环节。就像餐厅后厨不会让厨师“凭感觉炒菜”每一道菜都有固定的备料、火候、装盘流程AI 写代码也一样没有流程就会忽好忽坏。2.2 工作流和单技能的分工superpowers 里还有一类比技能更大的单位叫工作流。单一技能解决一个任务比如“写单元测试”工作流解决一串任务比如“完成一个新功能”内部可能包含需求拆解、设计、编码、测试、构建、提交等多个环节。我实际用下来的感受是单技能适合“点状操作”工作流适合“端到端任务”。如果只是让 AI 重构一个类直接加载重构技能就够了如果是一个完整功能从零到上线我会选择工作流让模型先产出计划再分布执行。两者不是替代关系工作流底层也会调用多个单技能。2.3 为什么不把所有规则塞进一条提示词这是我刚开始最疑惑的地方既然 AI 能读上下文那把所有规则写进项目里的一个长文档不就行了试过之后发现有三个问题。第一是上下文浪费。一条包含几十条规则的提示词每次对话都要占用大量 token真正需要它关注的任务反而被稀释。第二是优先级混乱。规则一多模型分不清哪些是必须的哪些是偶尔参考的经常出现“捡了芝麻丢西瓜”。第三是维护困难。规则写在长文档里更新一处要翻半天最后往往没人维护。技能库按需加载的逻辑就像工具箱里分类放好的工具。需要用扳手的时候拿扳手而不是把整个工具箱焊死在手臂上。这也是我觉得 superpowers 设计上最聪明的地方。2.4 技能为什么能稳定提升输出质量因为大语言模型的输出高度依赖上下文中的“示范结构”。技能文件本质上是一种给模型的 few-shot 示范只不过不再是一两个例子而是一整套可以遵循的判断标准。当模型按步骤走时它不会过早跳到代码细节而是先完成前置分析它不会忘记测试因为验收标准里明确写了。我在同一个 Java 项目上做过对比不使用 superpowers 时AI 生成代码后测试失败率大约有三四成使用技能后大部分任务第一次就能通过测试至少也会主动把测试跑起来再交付。这背后的原因不是魔法而是流程兜底。3. 从零装好 superpowers环境、克隆与第一个技能跑通3.1 环境准备别跳过在安装 superpowers 之前先确认两件事。第一Codex CLI 已经安装并能正常运行建议用最新版本因为技能加载依赖读取文件的能力。第二本机有 git 和基础的 shell 环境macOS、Linux 都行Windows 建议用 WSL。如果你主要写 Java还要确认java -version、mvn -version能正常输出。这一步经常被跳过但后面很多技能会调用构建命令环境变量不对会直接报错。我见过太多人卡在“AI 生成的代码没问题但构建失败”最后发现是 JDK 路径不对。3.2 克隆 superpowers 到本地我习惯把技能包放在~/superpowers下git clone https://github.com/obra/superpowers.git ~/superpowers cd ~/superpowers ls skills看到skills目录下按名称排列的文件夹说明克隆成功。每个文件夹里一般都有一个SKILL.md那就是 AI 执行任务时要读的核心文件。这里提醒一句superpowers 的社区版本迭代挺快如果你 clone 时发现目录结构和我在文章里写的不完全一样不用慌核心思路不变认准SKILL.md就行。如果你在 GitHub 上找到的是某个二次开发的版本也没有问题重点看技能目录的组织方式是否类似。3.3 让 Codex 知道去哪找技能技能文件 clone 下来之后还要让 Codex 知道去哪里找。我的做法是在项目根目录维护一个AGENTS.md里面加一段“技能加载说明”## 技能加载 当任务涉及代码审查、测试补充、重构、Bug 排查时先读取 ~/superpowers/skills/ 下对应 SKILL.md 文件并严格按照其中的步骤执行。这行字的作用是给 Codex 一个“路径提示”。实际会话里我一般还会补一句请先加载代码审查技能再开始处理。点名具体技能触发会更快。如果你的团队有统一的 Codex 配置也可以把这段写进团队级的指令文件里这样所有成员的 AI 行为一致。很多团队抱怨“每个人用 AI 写出来的代码风格不一样”问题往往就出在缺少这一层统一约束。3.4 Java 项目里的环境对齐Java 技能比较特殊因为大部分步骤都依赖构建工具。我遇到过的典型问题是AI 知道要跑测试但不知道项目用 Maven 还是 Gradle也不知道 JDK 路径。所以我会在AGENTS.md里把环境信息写清楚export JAVA_HOME/path/to/jdk17 export PATH$JAVA_HOME/bin:$PATH然后在AGENTS.md里写明项目构建使用 Maven统一执行 mvn test 验证JDK 版本为 17请勿使用 gradle。这些信息看起来和 superpowers 无关但实际是它能不能跑起来的关键。技能文件告诉 AI“要做什么”环境配置告诉它“怎么在你这台机器上做”。两者缺一不可。3.5 用一个真实任务验证链路配置完成后我建议先用一个小任务验证技能是否生效。找一段改动过的代码对 Codex 说请按照 superpowers 的代码审查技能检查我最近这次改动。接下来观察三点。第一它有没有主动读取技能文件比如回复中提到了检查清单。第二它有没有按技能里的输出格式分类而不是随口给意见。第三它有没有指出具体的测试建议。如果三点都满足了说明链路已经跑通。如果它完全无视技能先回去检查AGENTS.md加载说明是否写对再检查技能名称拼写是否和目录一致。我最早一次失败就是技能目录叫code-review我在 prompt 里写成了code_reviewAI 自然找不到。4. 用了一个月后我总结的避坑清单4.1 技能文件不是越详细越好技能文件本质上会消耗模型的注意力。如果一份技能写了上千行AI 读到后面很容易忽略前面的关键要求。我自己测试下来单个技能控制在 100 到 200 行之间效果最好。太短说明颗粒度可能不够太长则会稀释重点。如果你是初学者不用一上来就把所有流程写进去可以从两三段开始跑通了再逐步加细。我见过一些人把整个团队规范、编码风格、部署流程全部塞进一个技能文件结果 AI 每次执行任务都很“犹豫”因为约束太密集反而不知道怎么下手。4.2 别在 AGENTS.md 里塞全部技能索引我最初犯过一个错把所有技能的名称、路径全部写进AGENTS.md希望 AI“全自动”选择。结果它经常选错或者同时加载过多技能任务还没开始先把自己绕晕了。后来我改成“只写常见触发场景具体技能在会话里点名”。例如只写“涉及测试生成时参考 superpowers 的 test-writing 技能”其余按需临时告诉它。这个改动让输出稳定了很多。AI 不是数据库它不会像查表一样精确匹配给它越多的可能性它就越容易选出奇怪组合。4.3 项目级规范优先于通用技能superpowers 里的技能是通用最佳实践不一定适配你们团队的特殊约定。比如技能要求“所有函数都写 Javadoc”但团队代码风格明确不要冗余注释这时候以项目级AGENTS.md为准。我的做法是在AGENTS.md顶部写一句“本项目规范优先于任何通用技能文件”避免 AI 拿着通用技能和团队规范打架。这种冲突一旦发生AI 的输出就会变得不可预测因为它会在两个矛盾指令之间做“自由裁量”。4.4 本地自定义技能怎么不被更新覆盖如果你把 superpowers 仓库直接 clone 到本地改动了技能文件下次git pull可能被覆盖。我的习惯是不改上游技能自定义技能放到单独目录比如~/superpowers-custom/然后在AGENTS.md里把两个目录都写进去。这样上游更新不影响自定义部分。这个习惯尤其重要。我刚开始为了图省事直接改了上游技能文件结果项目更新后所有自定义全部丢失又重新整理了一遍浪费了不少时间。5. 常见问题速查与排查实录5.1 技能没有被加载的排查顺序最常见的表现是你让它用代码审查技能但它还是像普通对话一样直接输出意见。我会先检查三件事第一AGENTS.md里的路径是否存在文件夹名大小写是否一致第二技能文件是不是叫SKILL.md而不是skill.md或说明.md第三是否在会话里明确点名了技能。大多数情况下补一句“请先读取~/superpowers/skills/code-review/SKILL.md”就能解决。5.2 Java 环境导致构建失败现象是 AI 生成的代码没问题但一跑mvn test就报错。排查顺序先手动执行mvn -version确认 Maven 可用再确认JAVA_HOME指向 JDK而不是 JRE然后看项目根目录是不是有pom.xml如果项目其实是 Gradle技能里的 Maven 命令肯定不行。这些信息越早写进AGENTS.mdAI 越少踩坑。5.3 多个技能文件规则冲突当一个任务同时触发多个技能时可能出现互相矛盾的要求。比如“测试生成技能”要求 mock 外部服务但“集成测试技能”要求连真实环境。遇到这种情况我在AGENTS.md里做了优先级排序以当前任务目标为主线冲突时选择更贴近验收标准的技能。更重要的是尽量别在一个任务里同时加载两个强规则技能。5.4 模型上下文不足导致中途丢步骤如果任务很复杂模型可能在执行到后半段时忘了技能后半部分的要求。我的办法是分阶段调用技能而不是指望一个大任务从头到尾只靠一个技能。比如先让它出方案再让它编码最后单独跑验证技能。每一步都重新点名技能链路反而更稳。下面这个表格是我的排查速查表遇到问题可以直接对照现象可能原因解决办法技能未被加载AGENTS.md 路径错误修正路径会话里点名技能文件AI 忽略技能步骤技能描述与任务不匹配调整 SKILL.md 元信息或换触发词Java 构建失败JAVA_HOME 不对手动执行 java -version 和 mvn -version使用了错误构建工具项目信息未写明在 AGENTS.md 里写清 Maven/Gradle 与 JDK 版本技能规则冲突同时加载多个强规则技能拆分成多次会话或设置优先级中途丢步骤上下文过长分阶段调用技能重新点名技能文件6. 我的实际体验什么场景收益最大文章写到这我想分享一下自己的真实体会。superpowers 不是那种装上就万事大吉的工具它更像一个“习惯养成器”。你用它的时间越长就越清楚自己的 AI 工作流里哪些环节容易失控然后把对应流程固化进技能文件。到今天我项目里用得最多的技能是代码审查和测试生成Java 环境下这两个技能帮我省掉了大量返工时间。如果你刚开始接触我的建议是先挑一个最近反复发生的痛点写一个最小技能跑一周再决定要不要扩展。没有必要一次性上全套。我见过太多人一上来就克隆整个技能库结果面对几十个技能根本不知道从哪个开始用最后又回到裸奔状态。还有一个小技巧我习惯把技能加载说明放在AGENTS.md的前几行而不是埋在文件末尾。模型读取项目指令时前面的内容往往权重更高。这个细节对触发准确率的影响比想象中大。最后说一句superpowers 的生态还在快速变化市面上也出现了不少二开版本。工具未来怎么变不重要重要的是你已经理解了它的核心思路用流程约束不确定性把 AI 的随机发挥变成稳定交付。这一招放到任何编程助手上都适用。