最近我把主力开发环境切到了 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 到 superpowers2.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. 性能隐患重点识别循环内查询数据库、N1 问题、未分页的列表查询。 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 通过后再合入。因为技能文件是 Markdownreview 起来跟看 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也帮朋友排查过不少问题大部分疑难杂症都可以归到下面几类直接做成速查表症状常见原因解决办法Codex 完全无视技能自由发挥技能目录放错、frontmatter 缺 description、触发词和实际任务不匹配确认文件在正确路径description 写清触发场景先用最小技能测试技能读到了但输出格式还是不统一技能正文太长、表述太委婉、模型能力偏弱精简正文、改用祈使句、在文件里加“输出格式”模板、换更强模型每次会话都额外消耗大量 token技能文件太庞杂或者触发条件写得太宽拆分成多个技能description 缩窄范围长文档不要做成技能而是放进 docsJava 项目里中文注释或技能内容乱码文件编码不统一所有技能文件和项目源码统一为 UTF-8编辑器和 git 终端都别用 GBK改了技能文件但行为没变化Codex 会话还在使用旧索引结束当前会话重新开启一个新会话再测试auto_exec 开启后执行了意外命令技能文件里给了过宽的命令指导或者权限配置太激进先关掉 auto_exec技能里尽量写“给出命令”而不是“直接执行命令”5.2 我自己的排错套路从最小技能开始定位问题碰到 Codex 不听话先别急着怀疑 superpowers 坏了。我的做法是用一个 10 行以内的最小技能做定位只有一句话规则和一个输出模板比如“当用户说你好时必须回复您好”。如果连这么简单的技能都不生效那问题八成出在目录、frontmatter 格式或会话缓存上跟规则复杂度无关。如果最小技能生效了再逐步把真实技能的内容加回去每加一部分测一次。这个方法帮我省了很多时间因为很多时候你以为“规则写清楚了”实际在模型眼里那句话是模糊的拆到最简单才能看清是哪一步出了问题。另外一个提高成功率的小技巧是把“触发条件”写在 description 的第一句而不是埋在后面。我实测下来Codex 在判断要不要加载技能时对 description 开头的敏感度明显更高如果你的触发条件藏在第三句话里它很有可能扫一眼就略过了。这个细节很少有人写但影响挺大。5.3 关于“技能不遵守”的心理学跟模型谈判要用模板最后聊一个比较玄但很实用的经验当模型“读了但不遵守”的时候往往是因为输出格式对它来说太自由了。你可以想象模型面对开放式任务时默认偏好是自由发挥而技能如果只写“你要注意代码质量和异常处理”它仍然有巨大的自由度。一旦你在技能里给出明确的“输出格式”模板比如规定“第一段写结论第二段列严重级别每条附代码片段”它马上就变成了填空题执行力大增。所以我在所有关键技能里几乎都内置了输出模板这一招对各类模型都适用也是我玩 superpowers 以来收益最大的一个习惯。写在最后我个人实际用下来的体会是superpowers 真正厉害的地方不是多了一个功能而是改变了我和 AI 的协作方式。以前我面对的是“记性差、需要反复叮嘱的新人”现在面对的是一个“具备岗位操作手册的熟练工”。那些原本躺在 wiki 里吃灰的规范第一次变成了 AI 真的会执行的步骤这种转变对开发效率的拉动是实打实的。最后再分享一个小技巧把你自己踩过的坑也写成技能。比如你排查某类报错花了三个小时那就用 20 分钟把这套排查步骤整理成技能文件下次遇到同类问题直接让 AI 先读这个技能再动手。技能库积累得越久你的 AI 搭档就越懂你的项目脾气这比任何一次性的调参都来得划算。