如果你跟我一样最近半年每天都在跟 Codex 这类 AI 编程代理打交道你大概率也遇到过这个画面任务一复杂它就开始东一榔头西一棒子改完一个文件忘了另一个最后只能你出手兜底。Superpowers 就是冲着这个问题来的——它不是又一个聊天插件而是一整套安装在 Codex 里的技能包把 AI 从“会聊天的助手”变成“按工程流程干活的同事”。这篇文章我会把 Superpowers 是什么、怎么安装、怎么配置、实际用起来什么感受以及踩过的坑全部摊开讲。适合已经用过 Codex、想把它压榨得更狠的人也适合刚听说“技能包”这个概念、准备入门的兄弟。1. Superpowers 到底是什么把散装指令变成一套工作系统先说结论Superpowers 不是一个独立运行的软件而是一堆 Markdown 格式的技能文件挂在 Codex CLI 的 skills 目录下。它解决的问题很具体——AI 编码代理在简单任务上很猛可一旦任务超过三五个文件就会暴露出“缺流程”的毛病。你给它一句“加个用户注册接口”它可能直接生成一堆代码但依赖写错、测试没补、现有代码风格也没顾上。Superpowers 的思路是给 AI 一套固定工作习惯先探索、再计划、然后小步实施、最后验证。1.1 为什么单靠提示词不够我一开始也觉得提示词写得长一点不就行了后来发现根本不是这回事。提示词是一次性输入AI 读完就开干过程中有没有拆解任务、有没有回头看现有代码完全看模型当时的心情。复杂项目里这种“一锤子买卖”特别容易翻车改到一半跑不通测试它就开始猜问题越猜越偏。Superpowers 换了个思路把资深工程师的干活流程拆成一个个可复用的技能文件。每个技能描述一种能力比如“探索代码库”“制定任务清单”“运行测试并解读失败原因”。Codex 在真实任务中会按照触发条件自动加载这些技能相当于给 AI 灌入了一套工作 SOP。类比一下直接给提示词像口头交代新人“把这事办一下”挂上 Superpowers则是甩给新人一套项目交接文档加操作手册上手节奏完全不同。1.2 技能包结构是怎么设计的打开 Superpowers 的仓库你会发现它内部按场景分了几个模块比如代码、任务管理、研究探索、写作、复盘反思等。每个模块下都是独立的 Markdown 文件文件名就是技能名文件里除了正文还带一小段元信息技能是干什么的、什么时候该触发、不适合在什么场景下用。Codex 依赖这些元信息决定何时调用哪个技能。这种设计有两个好处。第一是轻量技能文件都是纯文本不依赖任何运行时环境模型直接在上下文窗口里读取就行。第二是可组合同一个代码任务可以先用“探索代码库”技能摸清底细再用“制定计划”技能排出步骤最后用“写测试”技能收尾——各技能之间不捆绑像搭积木一样按需取用。这比把整个工作流塞进一个巨型提示词里容易维护得多也方便你自己添加团队专属技能。2. 安装前准备Codex 环境与模型配置Superpowers 依赖 Codex CLI所以第一步是把 Codex 装好、登录好、模型选好。这步看起来基础但不少人在模型配置上翻车导致后面技能加载了也跑不出效果。2.1 Codex CLI 安装与登录目前最省事的安装方式是用 npm 全局安装。先确认本机有 Node.js 18 以上的版本然后执行npm install -g openai/codex装完先验证版本号codex --version能正常输出版本号说明安装成功。接着登录codex login这个命令会打开浏览器完成 OpenAI 账号授权。登录成功后Codex 会创建配置文件目录也就是~/.codex/后面装 Superpowers 和改配置都用这个目录。如果你的机器上已经有旧版 Codex建议先卸载再装新版避免 skills 相关配置字段不兼容。Homebrew 用户也可以直接用brew install codex路径和 npm 装出来的没有本质区别。2.2 模型选择与运行模式Codex 的配置文件在~/.codex/config.toml。核心要改的就是模型选择。以我自己的实际体验跑 Superpowers 这类多步任务别用太小的模型因为技能文件本身就占不少上下文小模型容易“看了后面忘前面”。我目前用的是gpt-5跑复杂一点的 Java 重构也能稳住。如果任务比较轻比如改个脚本、写段文案可以临时切到偏快的模型省点时间和成本。配置里最简单的模型指定长这样model gpt-5改完保存重启codex生效。关于运行模式Superpowers 设计出来就是给全自动模式用的因为它的技能体系已经把“先做什么、后做什么”理顺了你完全可以让它一口气跑完再检查。建议至少在熟悉阶段用自动模式观察它调用技能的节奏这对理解它怎么工作非常有帮助。3. 安装 Superpowers 的完整步骤与验证聊完了前置环境下面进入正题怎么把 Superpowers 装进去并且确认它真的被 Codex 读到了。这里我踩过两次坑一次是目录放错一次是放对了但项目里没有引用入口导致 Codex 全程没看一眼技能文件白装了。3.1 克隆与目录布局Superpowers 官方推荐的位置是用户级技能目录也就是所有项目都能共享。先执行mkdir -p ~/.codex/skills git clone https://github.com/obra/superpowers.git ~/.codex/skills/superpowers把仓库放在~/.codex/skills/superpowers里而不是某个项目目录下这样你在任何项目里打开 Codex它都能发现这套技能。克隆完成后可以进目录快速看一眼结构ls ~/.codex/skills/superpowers你会看到一堆.md文件和子目录每个文件对应一个特定技能。注意千万别把 Clone 路径搞错比如手滑放到了~/.codex根目录下Codex 扫描不到后面排查起来很头痛。这套技能更新很频繁作者会持续补新的工作流。升级方式很简单git -C ~/.codex/skills/superpowers pull如果你自己做了本地改动pull 可能会冲突。我的建议是自定义技能别直接改原仓库文件单独放一个新目录避免升级时被覆盖。3.2 在 config.toml 中挂载技能新的 Codex 版本只要检测到~/.codex/skills下的技能目录就会自动纳入技能体系不用额外配置。但如果你用的版本没有自动扫描或者扫描到但项目里没引用Codex 在会话里也不会主动去读。最稳妥的办法是在项目根目录的 AGENTS.md 里写明技能入口。在项目根目录创建一个AGENTS.md内容可以这样写# 项目约定 - 执行任何编码任务前先阅读并遵循 ~/.codex/skills/superpowers/AGENTS.md - 任务开始前需要完成代码库探索任务结束后需要验证测试结果为什么这么写因为 Codex 在每个项目会话启动时会优先读取项目根目录的 AGENTS.md把它当作长期项目记忆。你在里面点名 Superpowers就相当于告诉 Codex这套技能是这个项目的“默认工作流”。这比依赖全局配置自动扫描更可控也不会因为多个项目需求不同而互相干扰。3.3 验证技能是否被加载装完别急着干大活先验证它有没有真正加载。启动交互模式codex然后在对话里直接问“请根据我的技能文件列出你现在面对一个编码任务时通常会执行哪些步骤。”我碰到的正常回复是先梳理代码库结构和现有依赖再建立任务清单随后按照小步策略实现功能最后运行测试并复盘失败原因。如果你得到的回答里完全没有这些工程步骤只有一句泛泛的“我会尽力帮你写代码”那基本可以断定技能没被读到。这种状态下先检查三件事第一~/.codex/skills/superpowers目录存不存在第二ls一下确认里面的 Markdown 文件完整第三项目根目录有没有 AGENTS.md。逐个排查下来多半能定位到问题。4. 用起来是什么感受一次典型任务拆解配置好之后真正体验的重点来了。我拿一个真实场景演示假设你手头是个 Spring Boot 的 Java 项目现在要新增一个GET /api/tasks的接口要求补上测试。我直接描述一下挂载 Superpowers 后的完整执行过程。4.1 任务初始化与探索代码库我打开 Codex输入需求“给项目新增一个 tasks 接口返回任务列表用现有的工程规范并补上测试。”如果是没有技能的 Codex它很可能下一秒就开始写代码了。但挂载了 Superpowers 的 Codex会先进入“探索代码库”环节。它会读取项目的构建文件确定用的是 Maven 还是 GradleJava 版本是多少Spring Boot 版本是多少然后把现有 Controller、Service、Repository 的代码风格看一遍连测试目录下用的是 JUnit 4 还是 JUnit 5 都会确认。这个阶段它的输出会明显体现“研究感”而不是直接甩代码。例如它会说“项目使用 Java 17 和 Spring Boot 3.x现有 Controller 返回统一响应体测试目录下已有 3 个集成测试用例风格是 RestAssured 加 JUnit 5。”看到这种回复你就知道它真的在按工程思维干活。4.2 分步执行与测试驱动探索完代码库后它不会一股脑把所有文件改完而是先列一个任务清单并且每一步都检查。我观察到它的典型节奏是这样的先写测试再写实现然后跑测试根据测试结果回头修正。有一回测试失败了原因是我的项目里测试环境需要 mock 外部服务而它写的单元测试没有注入 mock导致启动上下文失败。这时候没有技能包的 AI 通常会立刻疯狂改代码试图“把测试改绿”。但 Superpowers 体系里会触发“复盘失败原因”的技能它会先看异常栈对比上下文配置最后定位到是测试缺少 mock 定义而不是业务代码写错。它甚至会在回复里反思说“这个失败不是接口逻辑问题是测试上下文不完整我需要补一个 MockBean。”这个“先归因再动手”的习惯是我觉得整套体系最有价值的地方。它也提醒使用者不要等它一次性改完而是接受它分步执行的节奏中途可以用 CtrlC 打断调整策略再让它继续。整个过程中任务清单不是摆设。你可以让它把大任务切分成多个可勾选的小项每完成一项就汇报一次。这样做的好处是你随时知道它进行到哪一步出问题也能精准定位到具体环节而不用在几十个文件里瞎猜。4.3 Java 等语言场景下的实际表现很多人问“Superpowers 是不是只适合特定语言”其实它是语言无关的。技能包关注的是“先探索、再计划、后测试”这样的通用流程具体到 Java反而会有一些额外优势。Java 项目里的“环境噪音”特别多Maven/Gradle 依赖、模块划分、注解处理器、代码生成框架如果 AI 不先搞清楚这些就直接生成代码很容易在你的项目里堆出没法编译的东西。挂载技能后Codex 会习惯性地去读pom.xml或build.gradle确认 Lombok 开了没有、MapStruct 是否引入、编译器版本是多少。这种“先看构建文件再动手”的习惯在 Java 项目里能把返工率降低一大截。我至少见过三次没有技能时它生成了一堆 Lombok 注解而项目里根本没装 Lombok导致编译直接挂掉有了探索技能后再也没犯过这种低级错误。如果是 Python 项目技能包会引导它关注pyproject.toml、虚拟环境、测试框架选择如果是前端项目它会先看package.json里用的是 Vue 还是 React、构建工具是 Vite 还是 Webpack。本质上都是在写代码前先建立“项目上下文”避免凭空猜测。5. 常见问题速查加载失败、会话切换、第三方工具集成用了一段时间遇到的坑不少但绝大多数都集中在三个方向技能没被加载、多个技能相互干扰、以及第三方工具怎么复用这套技能。下面我把这些问题和处理思路整理完整。5.1 常见问题排查表下面这张表是我自己排查时经常对照的速查表基本覆盖了新手的九成问题症状可能原因解决办法Codex 回答里完全没体现工程步骤项目根目录缺少 AGENTS.md 引用入口在项目根目录创建 AGENTS.md写明加载技能目录技能文件在工作但行为时好时坏技能目录里混入了自定义且描述冲突的文件检查技能元数据里的触发条件避免两个技能覆盖同一场景升级后出现行为异常旧版技能文件残留执行git -C ~/.codex/skills/superpowers pull同步到最新版Java 项目编译失败次数多项目没有 Maven/Gradle 本地仓库缓存导致依赖解析慢使用项目的./mvnw或./gradlew包装器并确保构建环境有依赖缓存技能包加载导致上下文太满技能文件数量过多、响应变慢裁剪自定义技能保留高频使用的核心技能会话中临时改需求后它还在按旧计划执行任务清单没有更新明确告诉 Codex“更新任务清单”再继续后续步骤还有一个容易被忽略的点技能文件的元信息写得越清晰Codex 越容易在正确时机调用它。如果你自己写技能一定要写清when_to_use和when_not_to_use这两个字段否则会出现“该用的时候不用不该用的时候乱用”的情况。5.2 在 WorBuddy 这类容器里怎么用不少同学问 WorBuddy 或者其他封装了 Codex 的工具能不能用 Superpowers。说实话只要底层还是 Codex CLI思路就是一套的。Superpowers 并不是独立软件它只是依赖 Codex 的 skills 扫描机制所以问题的核心变成了“目标工具有没有开放 Codex 的 skills 目录访问权限”。有的容器工具会直接复用你本机的~/.codex配置和技能目录这种情况下什么都不用额外做装好就能用。另一些工具会用自己打包的配置目录不读你本机的~/.codex。遇到这种最省事的办法是把技能目录软链到它实际读取的位置ln -s ~/.codex/skills/superpowers /path/to/tool/.codex/skills/superpowers软链的好处是以后升级时只需要在原始目录执行git pull所有关联位置都会同步更新不用每个工具维护一份副本。如果目标工具内部干脆不支持 skills 机制那就只能回到 AGENTS.md 方案在项目级说明文件里写明要读取的技能目录路径让模型以普通文本的方式加载技能内容。虽然不如原生机制顺滑但总比没有强。话说回来别被工具名框住。判断标准永远是三件事它是否使用 Codex 作为执行内核、它是否能读自定义技能目录、它的项目上下文文件里能不能引入外部路径。三个条件满足两个以上Superpowers 基本都能跑起来。我自己从直接写提示词切换到 Superpowers最明显的变化不是 Codex 突然变万能了而是它终于学会先看再动手、边做边验。刚开始两天你会觉得它有点啰嗦每次都要先列计划、跑测试但真遇到几十个文件的大改动时这套流程能帮你省掉大量“改完再修”的时间。最后分享一个小技巧别把技能包当圣旨在你的 AGENTS.md 里补充团队自己的硬性规范把“必须遵守的规则”和“可以借鉴的方法”分开写。规则部分放在项目说明文件里方法部分让 Superpowers 去管。这么一拆AI 既不会放飞自我也不会被技能包绑住手脚长期用下来项目边界会清晰很多。