先说结论如果你最近在搜“superpowers”那你大概率不是在看超级英雄电影而是在搜一个能让 AI 编程助手直接从良品率一半提升到稳定能交付的配置增强方案。我花了一周时间把它装进日常的工作流里实测下来的感受是这个超能力不是玄学它就是一套把提示词、项目规范、技能模板结构化了的工程化打法。这篇文章我会把 superpowers 是什么、为什么要用它、怎么安装、怎么和 Codex CLI 这类工具配合使用、以及我在 Java 项目里的落地配置全部写清楚最后附上我踩过的坑和排查清单。没有废话全是可抄的配置和命令。1. superpowers 到底是什么一个被热搜推出来的 AI 编程增强方案1.1 从超能力到开发者的效率外挂superpowers这个词在开发者社区里出现频率最高的时候并不是在聊游戏或者励志学而是指向一套针对 AI 编程助手的增强配置方案。它的核心思路很简单现在的 AI 编程助手虽然底子很强但默认状态下就像一个什么都懂一点、却没有任何项目经验的实习生——你不知道它的工作习惯它也不知道你的代码规范、测试标准、重构边界所以每次给它的指令都要从头解释一遍输出的质量自然不稳定。superpowers 要解决的就是这个问题。它把给 AI 赋能这件事做成了可复用的工程资产你不再像以前那样临时写一段几百字的提示词塞给 AI而是直接丢给它一套结构化的技能包——包括项目环境说明、代码规范、测试策略、Review 清单、常见坑位提醒甚至是一整套按场景拆好的操作指令。AI 每次进入项目时先读这套规则再按规则执行相当于给那个实习生发了一本员工手册。我在实践中体会最深的一点是superpowers 的价值不在装了之后 AI 突然变聪明而在于它让 AI 的输出下限变得很高。以前 AI 写出来一个 70 分的代码我要花时间改到 90 分现在它默认就按 90 分的规格写我只需要做检查和微调。这种体验上的差异比单个功能点提升更值钱。1.2 它的定位不是工具是配置资产这里必须先说清楚一个容易混淆的地方superpowers 不是一个独立运行的软件它更像是一套配置资产 技能模板的组合。你可以把它理解成游戏里的外挂插件——它必须挂载在某个人工智能编程底座上才有意义比如 OpenAI 开源的 Codex CLI或者其他支持项目级规则文件的 AI 编程终端。它解决的核心痛点有三个上下文断层每次新会话AI 都要重新理解你的项目结构、技术栈、代码风格。superpowers 通过统一的配置文件比如 AGENTS.md、CLAUDE.md 或者自定义规则文件把这些信息固定下来让每次会话都能秒接上。指令不稳定同一个需求你用口头描述和用结构化指令让 AI 执行效果天差地别。superpowers 把每种任务写测试、做代码审查、修复 Bug都固化成独立的技能档位AI 只需加载对应档位。团队经验不可沉淀老员工积累的坑位、规范、最佳实践以前都存在脑子里没法传递给 AI。superpowers 把经验写成了明文的 Markdown 文档和模板等于把团队智慧下放给每一个 AI 工作会话。它的定位决定了它的适用人群很明确如果你日常工作里重度依赖 Codex、Claude Code、Cursor 这类 AI 编程工具而且被不错的代码但总是少了点什么反复折磨——这方案适合你。如果你只是偶尔让 AI 写个一次性脚本那暂时没必要上这套配置成本大于收益。2. 设计思路拆解为什么技能包比临时提示词更可靠2.1 AI 编程助手的默认工作流短板在讲 superpowers 的设计思路之前我想先聊聊一个很多人都有的体感——AI 编程助手刚用的时候很惊艳用久了却总觉得不够稳。这个不稳其实不是模型能力问题而是工作流设计问题。默认状态下Codex 这类工具的运行逻辑大致是读入你的指令 → 结合模型自带的通用知识 → 生成代码/修改文件。这个过程里有一个致命的空缺模型不了解你的项目里什么是对的。举个例子我维护过一个 Java 服务端项目里面用到了项目自己封装的 BaseResult 类作为所有接口的统一返回结构。我让 Codex 新增一个接口时它默认自己造了一个 Map 返回代码逻辑完全正确但和团队规范完全脱节。这种问题靠临时在指令里解释一遍能解决一次但下次新会话它又忘了相当于每次都在重复付学费。superpowers 的设计者们显然看到了这个短板于是他们换了一个思路与其每次重复解释不如把所有项目背景、规范、边界、禁忌提前写好让 AI 在开始干活之前先读手册。这个思路和人类员工入职培训的逻辑是同构的——新人再聪明也得先看公司规章制度再动手。2.2 分层配置与技能调用的核心逻辑superpowers 在实现上最值得称道的一点是它采用了分层配置把信息按照通用性从高到低拆成不同的层级每一层负责一类信息。这样既能避免把所有东西堆在一个文件里导致 AI 抓不住重点又能让配置在不同项目之间复用。典型的分层逻辑是这样的全局层用户目录级别存放跨项目通用的技能模板比如如何写 Git 提交信息如何进行代码审查如何写单元测试。这些技能不分技术栈任何项目都能用。项目层项目根目录级别存放当前项目特有的信息比如技术栈、目录结构、环境变量、测试命令、代码风格约定。Codex 启动时会自动优先读取这一层。会话层临时指令级别每次启动会话时的具体任务描述。这一层的信息动态变化使用频率最高但也是最不稳定的——所以 superpowers 的目标就是尽量把这一层的信息量压缩到最少。技能调用的逻辑也很像函数调用。每个技能是一份独立文档里面有明确的触发条件和执行步骤。比如code-review.md这个技能触发条件是当用户要求审查代码时执行步骤包含先看变更范围、再逐文件检查、最后输出按严重程度排序的问题清单。AI 在会话中读到用户指令后先在技能目录里匹配触发条件命中后按文档执行而不是依赖模型临场发挥。我测试过这个逻辑的稳定性同样一个帮我 review 这段代码的请求在默认状态下 Codex 给出的反馈经常是这段代码看起来不错但可以优化一下空洞得让人抓狂挂载了 code-review 技能之后它会老老实实按清单走——先检查异常分支再查资源释放最后给出一条条具体的修改建议。这就是结构化的力量。2.3 目录结构与配置文件的理想形态既然要当成工程资产来管理一个清晰的目录结构就必不可少。我参考社区常见的方案结合自己的实践最终收敛出来的目录形态大致是这样的~/.superpowers/ # 全局技能包根目录 ├── AGENTS.md # 全局规则入口Codex/Claude 都能读 ├── skills/ # 技能模板目录 │ ├── generate-tests.md # 生成单元测试的技能 │ ├── code-review.md # 代码审查的技能 │ ├── fix-bug.md # Bug 定位与修复的技能 │ ├── refactor.md # 重构技能 │ └── git-commit.md # 提交信息规范技能 └── scripts/ # 辅助脚本非必需这个结构的核心是AGENTS.md这个入口文件。无论是 OpenAI Codex 还是其他支持 AGENTS.md 协议的工具启动时都会自动扫描并加载它。可以把它理解为 AI 助手的开机自启配置里面写清楚你是谁、你在哪个项目、你手头有哪些技能、遇到什么情况该调用哪个技能。我觉得这个目录结构最优雅的地方在于技能的增删改查完全变成了文件操作。我想让 AI 在写 Java 时强制使用 Lombok 的记录语法就新建一个java-lombok.md我想让 AI 在提交代码时严格遵循 Conventional Commits就改一份git-commit.md。整个过程不需要写一行代码也不需要重新训练任何模型。3. 安装与配置实操从零开始跑通 superpowers3.1 安装前的环境准备superpowers 的安装成本很低但对基础环境有一定要求。如果你要把它挂载到 Codex CLI 上首先要保证本机满足这几个条件操作系统macOS 或 Linux 都行Windows 建议走 WSL2我在 WSL2 上跑过兼容性没问题。运行时安装好 Git并且确保git --version能正常输出。另外 Codex CLI 本身要求 Node.js 环境但装 superpowers 本身不需要额外依赖。Codex CLI需要提前装好并配置好 API 访问凭证。安装方式官方文档写得很清楚一般是npm install -g openai/codex我建议装完之后先跑一次codex init完成初始配置确认默认会话能正常对话再继续下面的步骤。关于 Codex CLI 的模型选择我多说一句superpowers 这类大量依赖结构化指令的方案建议在配置文件的模型选择上优先考虑支持长上下文和工具调用的模型比如 Codex 默认推荐的那几个型号。模型本身的指令遵循能力越强技能文档的效果就越明显。如果模型太小再好的技能模板也会打折扣。提醒一下安装前确认你的终端代理设置是否正确因为 Codex 和 GitHub 仓库都需要走网络。如果在企业内部网络环境下安装记得先配好代理环境变量不然克隆仓库和调用 API 都会卡住。3.2 拉取技能包并建立项目级配置环境就绪后就可以开始安装 superpowers 本体了。这里的安装本质上是把技能模板和全局规则克隆到本地然后配置工具去读取它们。具体步骤如下。第一步克隆技能包仓库到本地。社区里有多个维护版本我优先推荐从你常用的 AI 工具生态里找配套仓库。以我用的版本为例mkdir -p ~/.superpowers cd ~/.superpowers git clone https://github.com/你选定的仓库地址/superpowers.git .这里要注意不同仓库的目录结构略有差异有的把技能放在skills/有的放在commands/。克隆完成后先执行ls -la看一遍结构不要急着配路径。第二步如果是带安装脚本的仓库可以直接运行./install.sh脚本一般会做两件事一是将技能目录拷贝到默认位置二是在你的全局配置文件如~/.codex/config.toml里插入读取路径。如果你的仓库没有脚本那就手动把技能目录复制过去mkdir -p ~/.codex/skills cp -r ~/.superpowers/skills/* ~/.codex/skills/第三步在项目根目录创建或修改AGENTS.md。这个文件是项目级配置的入口我来给大家看一个典型模板# AGENTS.md ## 项目信息 这是一个基于 Java 17 Maven 的微服务项目包名根路径为 com.example.demo。 ## 可用技能 本仓库已经加载以下超能力技能请在合适场景下自动调用 - generate-tests: 当需要编写或补充单元测试时使用。 - code-review: 当需要审查代码变更时使用。 - fix-bug: 当用户描述 Bug 并请求修复时使用。 ## 代码规范 1. 所有接口返回值统一使用 BaseResult 包装。 2. 禁止在 Controller 层直接写业务逻辑。 3. 使用 Lombok 的 Slf4j 完成日志输出禁止使用 System.out.println。 4. 单元测试使用 JUnit 5 Mockito。 ## 常用命令 - 构建mvn clean package - 测试mvn test - 启动mvn spring-boot:run写完这个文件后Codex 每次在项目目录里启动都会自动读取它并在每次会话开始时把里面的信息纳入考量。实测下来这比在配置里设置一堆全局参数更有效——因为项目的差异天然存在全局配置无法覆盖所有情况。3.3 与 Codex CLI 的集成配置Codex CLI 的集成重点在~/.codex/config.toml这个文件。如果你之前用过 Codex这个文件大概率已经存在还没用过的话先跑一遍codex init让它自动生成。我在这个文件里主要配置三块内容模型选择、MCP 服务器、自动加载规则。一个可参考的配置片段如下model o4-mini temperature 0 [experimental] mcp_servers [ { name filesystem, command npx, args [-y, modelcontextprotocol/server-filesystem, .] }, { name github, command npx, args [-y, modelcontextprotocol/server-github] } ]这里有两个关键点值得展开。第一temperature 0。对于代码任务我不建议把温度调高。温度越高模型的输出越发散虽然偶尔有惊喜但更多时候会产出不符合语法的代码。superpowers 这套方案的本质是减少随机性所以温度设为 0 是和它匹配的。第二MCP 服务器的作用。Codex 和 MCP 结合后可以访问文件系统、GitHub 仓库等信息这让技能不再局限于文字指令而是能直接调用工具。比如 code-review 技能需要读取 Git diff这个操作靠 MCP 的 tool 能力完成会高效得多。在配置里挂好 MCP 后技能文档里可以直接写调用 Git 工具获取变更列表执行效果比让模型猜 diff可靠得多。配置完成后可以在任意项目目录里启动 codex 做一个快速验证。先输入请列出你拥有的技能以及它们的触发条件正常情况下它会基于技能文档给出结构化的回答。如果回答含糊大概率是规则文件没被加载需要检查路径配置。3.4 Java 场景下的适配示例热搜词里出现了superpowers java说明不少 Java 开发者也在关注这套方案。Java 项目相比 Node 或 Python 项目有几个特别值得在技能配置里固化的点。第一是构建工具的差异。Maven 和 Gradle 项目在本地命令、依赖管理方式、目录结构上差别很大AI 默认经常混用。我在全局技能里放了一份maven-project.md专门说明如果检测到 pom.xml则使用 Maven 相关命令。第二是测试框架的差异。Java 生态里 JUnit 4、JUnit 5、TestNG 并存Mockito 和 MockBean 的使用方式也不同。这些信息如果不在技能文档里写清楚AI 生成测试时简直是开盲盒。我在项目 AGENTS.md 里明确写了单元测试使用 JUnit 5 Mockito一次性解决了两类问题导入错误、断言风格不统一。第三是 Java 特有的类型检查问题。AI 在生成代码时经常忽略泛型检查、异常处理、类加载机制等细节。以泛型为例我用一个简单技能文档来约束# java-type-safety.md ## 触发条件 当生成或修改 Java 方法、类、接口时。 ## 执行步骤 1. 所有集合类型必须声明泛型。 2. 禁止使用原始类型Raw Type如 List、Map。 3. 使用 Optional 处理可能为 null 的返回值。 4. 非受检异常必须使用 throws 标注或在方法签名中声明。这套配置跑下来我代码里的改了一小段结果引入一堆编译警告的情况明显减少。要知道Java 编译器是最严格的编译器之一AI 少写一个泛型参数就会直接编译失败把规则前置到技能文档里等于在生成阶段就拦截了问题比事后检查修复效率高一个量级。4. 日常使用流程与典型场景演练4.1 启动一次带技能的编码会话配置好之后日常会话的启动体验和以前完全不同。以前我打开 Codex 时要花半分钟输入项目背景、技术栈、代码规范现在只需要进入项目目录敲下codex然后直接说需求。启动会话后我的习惯是先花几秒钟做一个技能确认。输入根据当前项目的 AGENTS.md我有哪些技能可以用Codex 会列出当前可用的技能列表。这一步看起来多余其实很有用——它能帮你确认本次会话的规则加载是否正常。如果技能列表为空或答非所问就及时退出会话检查配置而不是带着残废状态继续干活。确认技能后就可以直接提需求了。比如我会说使用 generate-tests 技能为我新增 Service 层的单元测试覆盖用户注册接口的异常分支。注意这里我显式提到了技能名字。虽然某些配置在实际测试中也能让 AI 自动匹配技能但显式指定技能响应质量和命中率更高。我推荐在团队协作初期养成技能名先行的习惯等 AI 的自动匹配足够成熟再偷懒。4.2 测试生成、代码审查、Bug 修复三个高频场景我挑三个用得最勤的场景说说实际操作测试生成。模型默认状态写测试有两个通病只写 happy path、mock 范围过大。挂载 generate-tests 技能后AI 会遵循文档里的测试金字塔原则优先写关键业务逻辑的单元测试再补集成测试。我在技能文档里额外加了每个被测试的方法至少包含一个异常场景断言这一条实测下来测试代码的 bug 捕获率明显提升。代码审查。我的 code-review 技能文档里写了固定的审查顺序先看是否引入新的依赖再看资源释放是否正确然后检查并发安全最后才是代码风格。这个顺序是我踩过很多次坑后总结出来的AI 按这个顺序执行输出的 Review 报告比默认状态下的普遍夸奖 可有可无的建议靠谱太多。Bug 修复。这也很有意思。默认状态下Codex 拿到一个 Bug 描述后经常直接定位到代码开始改速度很快但容易改错地方。挂载 fix-bug 技能后我的文档要求它先复现问题再定位根因然后给出修复方案最后补充回归测试用例。整个流程走下来单次修复的耗时会变长但返工率大幅度降低。算总账还是划算的。4.3 团队共享与版本管理建议superpowers 的目录结构本身就是文本文件天然适合放在 Git 仓库里管理。我和团队现在是把~/.superpowers和项目里的AGENTS.md都纳入了版本控制配合起来效果很好。团队共享时我会建议三件事全局技能包放独立仓库成员克隆后安装路径保持一致统一约定为~/.superpowers。项目级 AGENTS.md 必须和代码一起提交并且每次项目结构大调整时同步更新。新成员入职后第一件事不是读项目 PPT而是花一刻钟过一遍技能文档——因为技能文档里已经浓缩了团队所有的工程规范。另外技能文档的更新可以采用提议-评审-合并的轻量流程。谁踩到坑了直接往文档里补一条案例开个 PR 让同事 review合并后所有人都能受益。时间长了技能包就成了团队知识沉淀最活跃的地方。5. 常见问题与排查技巧实录5.1 技能不生效时先查这三处如果你配置完成后发现 AI 没有按技能文档执行90% 的情况出在下面三个位置第一入口文件没被读取。检查项目根目录是否有AGENTS.md文件名一定要精确。有些工具只认AGENTS.md不认agents.md大小写敏感。另外确认当前工作目录是不是项目根目录——如果你在子目录里启动 Codex它不一定向上递归查找规则文件。第二技能目录路径不对。如果技能文档都在但 AI 说我没有这个技能多半是配置里的路径写成相对路径了。建议统一使用绝对路径比如skills [~/.superpowers/skills]并且不要用~缩写直接用/home/用户名/.superpowers/skills。第三任务指令没有命中触发条件。技能文档里的触发条件写的是当需要编写或补充单元测试时使用而用户指令是帮我看看这代码有没有问题那 AI 自然不认为需要调用测试技能。要么把触发条件写得更宽泛要么在指令里显式点名技能名。5.2 安装脚本与依赖冲突的处理安装过程中最常见的报错是脚本找不到命令或者路径不存在。我遇到过两次第一次是脚本里用了$HOME但我的 shell 环境变量没生效第二次是克隆仓库后目录名带了版本号比如superpowers-2.1.0脚本里的默认路径对不上。处理办法很简单分两步先确认目录结构再手动调整路径。不建议硬跑安装脚本最好把脚本内容打开看一眼确认它要操作的路径和你的实际环境一致。如果脚本里涉及写入config.toml建议备份原始配置cp ~/.codex/config.toml ~/.codex/config.toml.bak万一配坏了还能随时恢复。另外如果你之前手动改过config.toml安装脚本可能会把它的默认配置覆盖掉这一点要重点注意——我习惯在安装后立刻diff检查新旧配置的差异。5.3 和其他 AI 工具搭配时的边界问题热搜词里还有worbuddy 怎么用 superpowers我猜这里的 Worbuddy 是指一些偏工作流编排的 AI 工具。我的建议是superpowers 的配置文本不绑定特定工具因为它本质上是 Markdown 结构化指令。只要是支持读取项目级说明文件AGENTS.md、CLAUDE.md 或等效文件的 AI 工具都能复用同一套技能包。但要注意边界不同工具对规则文件的支持程度不一样。有的工具只读AGENTS.md有的工具认CLAUDE.md有的工具两者都认但优先级不同。我在配置时会把同样的内容适当复制到不同文件名下并尽量保持内容同步避免改了一处忘了另一处导致不同工具行为不一致。另外一个很容易被忽略的点是工具自身的指令裁剪。某些 AI 工作台会内置系统提示词它们可能会覆盖或稀释你的技能文档内容。遇到这种情况需要到工具的设置里关闭自动注入项目总结之类的高层抽象否则技能文档会被视为低优先级内容。5.4 效果不如预期的排查方向如果你按上面全部配置完但发现效果依然不如预期我建议从这几个方向排查模型版本过旧。技能文档的指令遵循要求比较高更新到最新模型往往立竿见影。技能文档过于冗长。一份几千字的技能文档AI 可能只吸收前半部分。我建议每个技能文档控制在 100 到 300 行触达条件放在最前面核心规则控制在 20 条以内。温度参数设置偏高。检查一下配置里 temperature 是否被改到 0.5 以上。温度高了AI 可能灵机一动绕过规则。缺少真实案例。纯讲抽象的规则模型很难精准执行在技能文档里附一个正确示例和错误示例模型的理解速度会快非常多。这套方案的最终效果和工程化程度正相关输入给 AI 的规则质量越高反馈越稳定。我见过有人把技能文档写成百来行的注释式著作结果模型完全记不住也见过有人用 3 句话把关键规范说清楚效果反而好得很。少即是多精炼胜于堆砌。最后再分享一个小技巧给每个技能文档加一个自检清单区块要求 AI 完成技能流程后逐条自检。比如 generate-tests 技能的自检清单就写是否覆盖了异常分支是否 mock 了所有外部依赖是否清除了调试输出。这招本质上是对 AI 输出做一层后置校验能硬生生把交付质量再往上拉一个台阶。我这一年用下来的真实体会是AI 编程的上限取决于模型下限却完全由你喂给它的规则决定。superpowers 的价值就是帮你把这个底线抬到足够高。
