superpowers：为Codex CLI打造可复用AI技能的工作流

最近我把主力开发环境切到了 Codex CLI 之后，有很长一段时间都觉得不太顺手。倒不是它写不出代码，而是每次开新会话，它都像刚入职的实习生：态度很好，但总记不住团队约定，代码风格、commit 规范、测试要求，每次都要重新嘱咐一遍。直到我把 superpowers 这套技能框架接进来，这个问题才算真正解决。今天这篇文章，我把从安装、配置到写第一个技能、再接入团队工作流的整个过程都整理出来，希望能帮同样在用 Codex 的朋友少走点弯路。

superpowers 本质上是一个“给 AI 编程代理注入可复用能力”的框架，核心思路是把各种任务规范写成 Markdown 技能文件，让 Codex 在遇到对应场景时按需加载。它解决的问题很具体：以前我们会把项目规范一股脑塞进 AGENTS.md 或 system prompt，结果要么上下文被无关内容挤爆，要么规则多了之后互相打架。superpowers 换了个思路——不预加载，按需读。这套玩法尤其适合那些在 Codex 环境下维护多个项目、或者想统一团队 AI 编码规范的人。

1. 先理解 superpowers 的核心思路再动手

1.1 它解决的真正痛点：上下文资源被白白浪费

先别急着装，我们把机制聊透。用过 Codex 这类工具的人应该都有感触：每次对话开始，模型能看到的内容是有限的，窗口就那么大。以前为了让 AI 遵守项目规范，最常见的做法是写一个很长的 AGENTS.md，写在仓库里让它每次自动读取。但问题随之而来，规范文件越来越长，从代码风格写到部署流程，再到接口命名规范、commit 写法，几百行都是常态。你让 AI 写个工具函数，它却要把整个规范从头到尾扫一遍，大量上下文窗口被无关内容占据，真正重要的任务信息反而被稀释了。

我用一个生活类比解释一下：这就像公司给新员工发了一本 500 页的员工手册，要求他每天上班先从头读到尾，结果他确实记住了第七章里的前台电话，但忘记了第一章里最重要的安全红线。superpowers 的思路其实就是把员工手册拆成一本本“岗位操作卡”，新员工在写周报的时候，给他“写周报操作卡”；在处理客户投诉的时候，给他“投诉处理操作卡”，其他无关内容一概不占用脑子。

superpowers 的做法是让技能文件保持在 Markdown 格式，每个文件描述一个特定任务的操作步骤、注意事项和输出格式。当你在 Codex 里下达一个任务，它会先判断“这个任务有没有对应的技能文件”，有就加载，没有就按默认方式处理。这不是我随口说的，是目前社区里对这个项目的主流解读，也是它和普通 prompt 管理工具最大的区别。

1.2 技能文件是怎么被加载的：一个按需读取的机制

要理解它的工作流程，你可以想象 Codex 每次开始任务时会有一个“查找技能”的过程。技能文件通常放在特定的 skills 目录下，每个文件开头有一段 frontmatter 元信息，里面写了这个技能的名称、描述、适用场景和触发条件。比如你写了一个“java-code-review”技能，description 里面明确写了“当用户要求审查 Java 代码时使用”，那么当你在对话里对 Codex 说“帮我看一下这行代码有什么问题”，它就有机会检索到这个技能，读取里面的规则，然后按照规则来执行。

这个过程里最关键的设计，就是“按需读取”而不是“全部读取”。技能文件只在匹配到触发条件时才会占用上下文，其他时间它就是一个安静的躺在硬盘里的 markdown 文件。这样一个小小的机制改动，带来的体验提升非常明显。我在自己的项目里实测，接入之前和接入之后，Codex 对项目规范遵守的稳定度提升了一个档次，而且没有明显感觉到上下文被额外消耗。

1.3 为什么用 Markdown 而不是插件系统

可能有人会问，要扩展 AI 能力，写个 Python 脚本或者插件不是更强大吗？这里面的取舍很有意思。插件系统确实上限更高，但它带来了三个麻烦：一是开发和维护成本高，要有 API 知识、要处理依赖、要适配版本；二是安全问题，一个能执行代码的插件出了问题，影响的可能是整个开发环境；三是团队协作门槛，让每个成员都学会写插件不现实。

Markdown 技能文件把门槛降到了几乎为零。任何能写 wiki 的人都能写技能文件，diff 起来清晰明了，review 也方便，而且本质上它只是让模型多读一段文本，没有任何代码执行能力，风险面小得多。这跟“给模型讲规则”是同一个安全层级，不会出现插件那种“运行了第三方代码”的顾虑。我个人的判断是，对大多数开发团队来说，把技能写成 Markdown 是性价比极高的方案，因为它解决的是“AI 按规则办事”这个 90% 的问题，剩下 10% 的高度定制化场景才需要考虑插件。

2. 安装与初始配置：从 Codex CLI 到 superpowers

2.1 先把 Codex CLI 跑起来

superpowers 目前主要服务的是 Codex CLI 环境，所以第一步是确保你本机已经装好并能正常使用 Codex。Codex CLI 是 OpenAI 推出的命令行 AI 编程代理，安装方式对前端开发者来说很熟悉，走 npm 就行：

npm install -g @openai/codex

装完之后先用codex命令初始化一下，按提示登录账号，跑通一个最简单的对话，确保基础链路没有问题。这里有一个我踩过的坑：如果 Node.js 版本太老，经常会装到一半报各种依赖错误，建议先把 Node 升级到 18 以上再装，会少很多麻烦。另外如果你的 npm 镜像配置得比较慢，安装超时的概率很高，直接换成国内常用的 npm 镜像源就能解决，这个跟项目本身无关，纯粹是网络环境的常规操作。

2.2 拉取 superpowers 并把技能目录挂好

Codex 跑通之后，下一步就是把 superpowers 项目拉下来。常规操作是找一个工作目录，把仓库 clone 下来，然后把里面的 skills 目录以合适的方式放到 Codex 能读取的位置。这里要说明一下，不同版本的 superpowers 支持的技能目录位置可能略有差异，有一些放在用户级目录~/.codex/skills/，有一些支持项目级目录.codex/skills/，具体以你 clone 下来的 README 为准，但大致的流程都是这样：

git clone <superpowers仓库地址> cd superpowers # 把 skills 目录复制到 Codex 用户配置目录 cp -r skills ~/.codex/

复制好之后你可以先打开~/.codex/skills/看一下，如果里面能看到一个叫作 bootstrap 之类的技能文件，说明路径基本没放错。bootstrap 这个技能在 superpowers 里扮演一个“索引”的作用，它会在会话开始时对 Codex 说明存在技能体系这件事，并指导它有需要的时候去查其他技能。如果你发现技能文件存在，但 Codex 始终不认，90% 是路径问题。

每次修改完技能文件，我建议都把当前 Codex 会话结束掉，重新开一个新会话再测试。因为技能的索引信息往往是在会话初始化阶段加载的，你改了文件但旧会话还在跑，它可能还是按照旧规则来，误以为“技能没生效”，其实是会话缓存的问题。

2.3 配置 config.toml：模型、温度和执行权限

Codex 的配置集中在一个 TOML 文件里，常见路径是~/.codex/config.toml，项目级也可以放一个.codex/config.toml覆盖全局配置。我接 superpowers 的时候，会重点调整三个参数，你可以直接参考这个骨架：

model = "gpt-5-codex" temperature = 0.2 auto_exec = true

先解释为什么这么设。第一个是模型选择，想让技能里的规则被严格遵守，最好用当前账号可用的最强推理模型，能力弱的模型在“读了规则还要照着执行”这件事上会打折扣。第二个是温度，我习惯把 temperature 调低到 0.2 左右，它控制的是输出随机性，数值越低，回答越稳定，写规范类代码的时候低温度是王道。默认的 0.7 出活太飘，尤其在技能要求“严格按照模板输出”的时候，温度高一点就开始花样百出。第三个是auto_exec，它控制 Codex 是否可以直接执行自己生成的命令。这里我强烈建议，第一次配置时把它设成false或者用默认的询问模式，等确认它不会乱跑命令之后再放开。

这里补充一个判断：如果你刚开始用，不确定配置怎么写，先只改模型和温度，auto_exec保持 false，跑一个技能任务看看效果，再逐步放开。直接从“全自动执行”起步，万一它根据技能里的规则执行了一个你没预期的清理命令，心态容易崩。

3. 实战：写一个 Java 代码评审技能

3.1 场景设定：为什么拿 Java 开刀

superpowers 本身和语言无关，但很多人搜“superpowers java”，说明 Java 项目里规范问题最让人头疼。我拿一个比较典型的场景来拆解：假设团队用 Java 8 + Spring Boot + Maven，代码评审靠人工，每个人心里都有一套“好坏判断”，但是新人写出来的代码经常踩同样的坑，比如事务注解乱用、循环里查数据库、异常吞掉不记日志。把评审标准写成一个技能文件，让 Codex 在“帮忙看代码”的时候自动加载这套标准，等于每次评审都有一位熟读团队规范的老员工在场。

3.2 技能文件怎么组织：元信息 + 规则 + 输出模板

先看一个我常用的技能文件骨架，还是在~/.codex/skills/下建一个java-code-review.md：

--- name: java-code-review description: 当用户要求审查 Java 代码、检查 Spring 项目改动、或要求"评审""看看代码""查一下这段代码的问题"时使用。适用于 Maven/Gradle 构建的 Java 8+ 项目。 when_to_use: code review, java, spring, bug check --- # Java 代码评审规范 ## 评审要点 1. 事务与并发：检查 @Transactional 是否合理，注意事务内不要做远程调用。 2. 性能隐患：重点识别循环内查询数据库、N+1 问题、未分页的列表查询。 3. 异常处理：禁止吞异常，catch 之后必须记录日志或者上抛。 4. 空指针风险：所有从外部传入的对象参数，使用前必须判空。 5. 接口与实现：Controller 层只做参数校验和响应组装，业务逻辑下沉到 Service。 ## 输出格式 先输出总体结论，再按严重级别列出问题： - 【严重】影响功能正确性或线上稳定性 - 【建议】可读性、性能优化、规范一致性 - 每个问题必须给出修改后的代码片段

注意几个细节：description 是技能被检索到的“钩子”，我故意把“评审”“看看代码”“查一下”这些日常说法都写进去了，因为很多时候你并不会精确地打下“code review”这两个词。正文里的规则全部用祈使句，不带商量语气，比如“禁止吞异常”“必须记日志”，这种表述模型执行起来更干脆，你要是写“建议考虑异常处理”，它就真的只是“考虑一下”。输出格式模板放最后，是为了明确告诉模型“返回什么东西”，实测下来，带模板的技能和不带模板的技能，输出规范程度完全两回事。

3.3 测试技能并调整触发逻辑

写好技能文件之后，重启 Codex 会话，然后在项目目录下给它一个任务：“看一下 UserServiceImpl.java 最近这段改动有没有问题”。如果一切正常，它应该会先读技能文件，然后按照“总体结论 + 严重级别 + 修复代码”的结构给你输出。我第一次跑的时候就没成功，它完全没按技能里的格式来，排查了一圈发现是技能文件没放进 Codex 实际读取的目录，而是放到了仓库目录里。当时我项目里也有一个.codex/skills/，Codex 优先读了项目级的，而我的技能写在用户级目录里，两边目录打架了。

这个坑其实很有代表性：用户级技能和项目级技能同时存在时，Codex 是有优先级顺序的，你写的技能放错了层级，另一个层级里的同名技能就可能覆盖掉你的配置。我给个建议，初期只用一个目录，要么只用用户级，要么只用项目级，别混着放。等你完全搞清楚优先级了，再考虑两级配合。

3.4 技能文件的进阶玩法：复用和组合

当你手上有了几个基础技能，就可以叠加使用了。比如我项目中除了 java-code-review，还有一个“test-generator”技能，专门负责生成单元测试。有次我对 Codex 说“给 UserServiceImpl 的这几个方法补一下测试”，它先调用了 test-generator 技能，又在生成测试时自动参考了 java-code-review 里的事务规则，直接避免了我常见的 mock 滥用问题。这种组合效果是单个大 prompt 很难实现的，因为你不需要把所有规范都写在一条指令里，技能体系会自动在合适的场景激发对应的规则。实际上这就是 superpowers 最吸引人的一个特性：技能的颗粒度可以很小，但组合起来能覆盖复杂任务。

4. 把 superpowers 变成你的 AI 工作搭子

4.1 技能不止是给 AI 看，更是团队共识的载体

我在实践里有另外一个体会：技能文件最大的受益者不只是 AI，还有团队协作。之前我们的代码规范散落在 wiki、群聊记录、老员工脑子里，新人来了全靠口口相传。现在我把关键规范写成一个一个的技能文件，放到仓库里跟代码一起走，Codex 会自动遵守，新人打开项目也能看到这套规则，等于把“隐性知识”变成了“显性资产”。

具体操作上，我推荐在仓库里建一个skills/team/子目录，统一存放团队级技能，比如“git-commit-规范”“接口设计约定”“API 文档生成要求”，让每个技能文件从第一个版本开始就走 git 管理。每次有人提出新规范，先提 Merge Request，说明场景与触发条件，大家 review 通过后再合入。因为技能文件是 Markdown，review 起来跟看 wiki 改动差不多，没有任何技术负担。这比把规范一次次口头强调有效得多。

4.2 正确使用 superpowers 的三种姿势

很多人把 superpowers 当成一个“安装完就能自动变强”的魔法包，实际用下来不是这样，它的价值取决于你怎么组织技能。我整理了三种实际场景里的使用姿势，你可以直接抄作业。

第一种是“写在代码之前”。开始新功能前，先问 Codex 一句“我们项目里有没有对应这个功能的技能”，让它先加载相关技能再开始写逻辑。这就像开工之前先确认操作手册，能避免很多写到一半发现方向不对的问题。

第二种是“分享给同事”。技能文件就是个文本，你完全可以把自己的高效技能分享出去。我经常干的一件事是，调好一个技能后，直接在群里发一段代码块，同事复制到他们的 skills 目录里就能用。这种知识流通效率，比让人家读一篇长博客高太多了。

第三种是“接进自动化流程”。目前社区里比较常见的玩法是把 Codex 和 CI 结合，在提交代码时自动跑一轮基于技能审查的检查。当然这需要脚本配合，但原理就是让 Codex 在非交互模式下按技能执行任务。这块我没有在生产环境大规模跑过，只在小范围实验过，效果不错，建议想试的朋友先在 pre-commit 钩子里做实验。热搜里那个“worbuddy 怎么用 superpowers”我琢磨了一下，其实就是想弄明白怎么把 superpowers 接到自己日常的 AI 编程搭档流程里，本质就是我上面说的这几种姿势的组合：装好技能、设定触发场景、把它当团队成员一样配合。

4.3 多人协作时怎么维护技能库

技能文件一旦多起来，也会遇到“规则膨胀”的问题，这一点跟当初 AGENTS.md 膨胀是同源的。我踩过一轮坑后总结了几个原则：第一，自律地控制单个技能的篇幅，一个技能只解决一个任务，超过两百行说明你塞了太多东西进去，拆开。第二，description 里的触发条件要写窄一点，别写“所有开发场景都用”，否则它什么事都去读这个技能，又变成全量加载了。第三，定一个“先试跑再合入”的约定，新技能先在个人分支用几天，确认输出稳定了再提到公共目录。毕竟你不希望一个没调过的技能在同事代码里突然发疯。

5. 常见问题排查实录

5.1 一张表先解决绝大多数报障

我在多个环境里用过 superpowers，也帮朋友排查过不少问题，大部分疑难杂症都可以归到下面几类，直接做成速查表：

5.2 我自己的排错套路：从最小技能开始定位问题

碰到 Codex 不听话，先别急着怀疑 superpowers 坏了。我的做法是用一个 10 行以内的最小技能做定位：只有一句话规则和一个输出模板，比如“当用户说你好时，必须回复您好”。如果连这么简单的技能都不生效，那问题八成出在目录、frontmatter 格式或会话缓存上，跟规则复杂度无关。如果最小技能生效了，再逐步把真实技能的内容加回去，每加一部分测一次。这个方法帮我省了很多时间，因为很多时候你以为“规则写清楚了”，实际在模型眼里那句话是模糊的，拆到最简单才能看清是哪一步出了问题。

另外一个提高成功率的小技巧是把“触发条件”写在 description 的第一句，而不是埋在后面。我实测下来，Codex 在判断要不要加载技能时，对 description 开头的敏感度明显更高，如果你的触发条件藏在第三句话里，它很有可能扫一眼就略过了。这个细节很少有人写，但影响挺大。

5.3 关于“技能不遵守”的心理学：跟模型谈判要用模板

最后聊一个比较玄但很实用的经验：当模型“读了但不遵守”的时候，往往是因为输出格式对它来说太自由了。你可以想象，模型面对开放式任务时，默认偏好是自由发挥；而技能如果只写“你要注意代码质量和异常处理”，它仍然有巨大的自由度。一旦你在技能里给出明确的“输出格式”模板，比如规定“第一段写结论，第二段列严重级别，每条附代码片段”，它马上就变成了填空题，执行力大增。所以我在所有关键技能里几乎都内置了输出模板，这一招对各类模型都适用，也是我玩 superpowers 以来收益最大的一个习惯。

写在最后，我个人实际用下来的体会是：superpowers 真正厉害的地方不是多了一个功能，而是改变了我和 AI 的协作方式。以前我面对的是“记性差、需要反复叮嘱的新人”，现在面对的是一个“具备岗位操作手册的熟练工”。那些原本躺在 wiki 里吃灰的规范，第一次变成了 AI 真的会执行的步骤，这种转变对开发效率的拉动是实打实的。

最后再分享一个小技巧：把你自己踩过的坑也写成技能。比如你排查某类报错花了三个小时，那就用 20 分钟把这套排查步骤整理成技能文件，下次遇到同类问题，直接让 AI 先读这个技能再动手。技能库积累得越久，你的 AI 搭档就越懂你的项目脾气，这比任何一次性的调参都来得划算。