superpowers：为Codex CLI打造可复用的工程技能系统

1. 先说结论superpowers 到底给我的 Codex CLI 加了什么最近 Codex CLI 更新之后开发圈里聊得最多的其实不是模型本身而是社区里一个叫 superpowers 的项目。它不是新模型也不是 IDE 插件而是一套专门给 Codex CLI 用的“技能系统”通过 SKILLS.md、config.toml、MCP servers 和自定义指令的组合把原本需要反复口头叮嘱的工作流变成了可以复用、可以分发、可以版本化的能力包。如果你已经装过 Codex CLI但总觉得它在真实项目里输出不够稳多步骤任务经常跑偏那这套东西值得花半小时研究。我最初以为它只是某个人的 dotfiles 集合实际用下来发现它解决的不是“少一个功能”的问题而是“模型不知道怎么按资深工程师的节奏干活”的问题。这篇文章不打算念文档就从安装、实测、踩坑三个角度把我在本地环境里折腾 superpowers 的全过程讲清楚。1.1 它解决的三个真实痛点第一个痛点是上下文利用率太低。Codex CLI 基础能力很强能读文件、能跑命令、能改代码但面对一个大仓库时模型经常挑着看几眼就开始动手改完了发现和周边代码风格不一致或者把一个核心接口的调用方忽略了。第二个痛点是多步骤任务没有节奏感。让模型直接实现一个新功能它大概率一次写一大堆代码然后等你跑完测试再回来修中间缺了“先列计划、小步验证、随时回滚”的工程节奏。第三个痛点是方法论无法沉淀。每个人、每个团队都有自己的开发习惯但这些习惯只存在于文档里或者老同事的脑子里模型每次对话都等于重新教一遍。superpowers 的核心思路很朴素把“资深工程师接到任务后的处理顺序”写成结构化的技能文件每次对话里只要输入技能名模型就会先读这套操作流程再按流程执行。它不依赖魔法依赖的是工程方法的结构化表达。1.2 为什么叫 superpowers 而不是“配置包”我一开始也以为这是增强模型能力的某种黑科技实际上它给的是“工作流的超能力”。模型不会因为你装了这个就变成更强的模型但它会变得更像一个懂规矩的协作者动手之前先给方案改完代码先补测试遇到问题先分析日志而不是瞎猜。这个项目由几层内容组成我用自己的理解拆解一下第一层是技能目录里面每个技能对应一个 SKILLS.md 文件描述在什么场景下触发、按什么步骤执行、有哪些注意点第二层是自定义指令用来给 Codex 设定通用行为准则第三层是 MCP 服务器配置让模型能通过工具访问文件系统、数据库、网页等外部资源第四层是项目级记忆文件比如 AGENTS.md帮助模型理解当前仓库的约定。简单说如果你把 Codex CLI 比作一个聪明但有自己想法的实习生superpowers 就是一套写满公司规章、代码规范、排查手册的入职培训资料。实习生还是那个实习生但有了这套资料他做事的靠谱程度会高很多。2. 安装之前需要先搞清楚的 Codex CLI 扩展点直接 clone 仓库、跑安装脚本当然可以但如果你连 Codex CLI 的扩展点都没搞明白后面出了问题会完全不知道从哪里排查。我建议安装 superpowers 之前先花十分钟确认一下自己对下面几个概念的理解。2.1 config.toml全局配置的入口Codex CLI 的全局配置默认放在~/.codex/config.toml。这个文件管理着模型参数、输出风格、MCP 服务器列表、是否启用某些实验特性等。superpowers 安装时一般会备份原配置然后往里面追加自己的配置块。我对所有折腾配置文件的行为都有一个铁律先备份。不管安装脚本做没做自己手动复制一份config.toml.bak永远是值得的。这个文件也是排查问题的第一站。技能没加载、MCP 没生效、模型行为不正常第一步永远是看 config.toml 的内容和语法。TOML 语法对缩进不敏感但对 key 的层级和引号有要求输错一个引号可能导致整段配置失效而且 Codex CLI 未必会给出清晰的报错信息。2.2 AGENTS.md项目级的行为规范Codex 系列工具普遍支持在项目根目录放一个 AGENTS.md 文件作用是告诉模型这个项目的结构、命令、约定和禁区。例如后端项目里写“所有数据库迁移必须先生成 down 语句”前端项目里写“组件样式统一使用 Tailwind 工具类”这些都可以写进 AGENTS.md。它和 superpowers 的技能文件是互补关系技能描述“怎么做一件事”AGENTS.md 描述“在这个项目里有什么规矩”。两者都会占用上下文所以要点到为止别写一万字。2.3 skills 目录技能系统的载体Codex 支持从指定目录加载技能形式上是子文件夹加 SKILLS.md 文件。superpowers 的仓库里大量内容是这类技能文件例如 plan、tdd、debugging、code-review、refactoring 等。触发方式也很简单在对话里提到技能名或者用专门的斜杠命令。模型会去读取技能文件然后按照文件里描述的工作流程来执行任务。每个 SKILLS.md 通常包含 frontmatter技能名、描述、适用场景和正文执行步骤、检查清单、注意事项。模型是否真的读到了这个文件决定了整个环节能不能跑通。我见过不少人说“技能没反应”最后查下来基本都是 frontmatter 格式不规范导致解析失败后面踩坑部分我会细讲。2.4 MCP servers让模型摸得到外部世界MCP 是一个工具调用协议简单理解就是给模型接上“外置设备”。Codex CLI 支持把 MCP 服务器配置进 config.toml。常见的用途包括文件系统操作、REST API 调用、浏览器自动化、数据库只读查询等。superpowers 的某些高级技能需要 MCP 提供的外部数据支撑比如让 Codex 去查线上接口文档、读取某个网页内容、或者使用检索服务搜索仓库里相关代码。这里我要提个醒MCP 是这套体系里收益最大、同时也是风险最大的部分。因为它让模型拥有了执行外部动作的能力配置不当可能导致不可预期的副作用。我的建议是刚开始只接 1 到 2 个必要的 MCP 服务器验证稳定之后再逐步增加。3. 实操从 clone 到第一次跑通技能3.1 完整安装步骤我是在 macOS 环境下装的整个过程大概花了十五分钟。如果你用的是 Windows路径会略有差异但原理一样。第一步确保 Codex CLI 是最新版。我建议全局安装方便命令行直接调用。npm install -g openai/codexlatest第二步把 superpowers 仓库拉下来。仓库地址以你搜索到的为准我这里用最常见的路径示意git clone https://github.com/obra/superpowers.git cd superpowers第三步执行仓库里的安装脚本。这个脚本一般会做三件事备份旧配置、把技能目录复制到 Codex 的配置目录、往 config.toml 里追加必要的配置。运行之前先看一下脚本内容确认它究竟会改哪些文件这是开源工具的基本使用习惯。./install.sh第四步验证技能目录是否正确生成ls ~/.codex/skills正常情况下你会看到多个技能文件夹每个文件夹里都有一个 SKILLS.md 文件。如果这个目录是空的后续所有技能都不会生效。第五步检查 config.toml 是否正常备份和合并。我习惯打开文件看一眼确认没有语法错误也确认原来的 models 配置没有被覆盖掉。3.2 影响我最大的三个技能技能很多但我日常高频使用的基本上就三个。第一个是 plan。它要求 Codex 在动手之前先分析需求、梳理相关代码、给出实现计划。以前我让 Codex 改一个功能它经常闷头直接改改完才告诉你它做了什么。用了 plan 之后它会先列出改动点问我确认与否。这一个小小的变化让整个协作体验从“和一个冒失的同事共事”变成了“和一个靠谱的同事开会对齐方案”。第二个是 tdd也就是测试驱动开发。这个技能会强制 Codex 先写失败测试再写实现代码然后跑测试确认。我不是对每个任务都启用它但对于核心模块的修改启用 tdd 后代码质量和可回归性确实提升了一个档次。第三个是 debugging。它定义了一套排查问题的流程先重现再缩小范围然后输出假设再验证假设最后修复并补回归测试。这套流程对模型来说尤其重要因为语言模型在没有约束时最常见的表现是看到报错就猜测原因而 debugging 技能让它强制按证据链推进。3.3 一次真实的小任务演示我拿一个实际的经历来说明当时的任务是在一个 Python 项目里给现有 API 增加分页参数。如果没有 superpowers我直接问 Codex“给列表接口加分页”它会怎么写大概率是找到列表接口加上 page 和 page_size 参数返回结构里嵌套一个 pagination 对象。看起来很合理但它不会去看前端是怎么调这个接口的也不会意识到这个接口还有别的调用方。有了 superpowers 之后我会这样发起对话我先输入plan然后描述任务。Codex 会先读取 plan 技能接着分析路由、查询参数、客户端调用方式整理出一份改动清单。我看到清单后指出来漏了一个老版本客户端的分页逻辑兼容问题。它补充计划后我再切到 tdd 模式让测试先驱动改动。整个过程节奏清晰每一阶段都有可验证的产物。这个例子想说明一件事技能的价值不在于让模型“一步到位”而在于让模型的思考过程变得可见、可控、可纠偏。4. Java/后端项目里的实测为什么这里收益最大热搜词里有“superpowers java”我猜很多人和我一样拿到这套东西第一反应是拿到后端项目里试一试。这其实是合理的。Java 项目依赖多、构建慢、启动慢模型如果上来就乱改试错成本比写脚本要高得多所以更需要技能约束。4.1 给自己项目写一个构建技能superpowers 自带了不少通用技能但 Java 项目的一些操作细节仍然值得固化。我给自己维护的 Maven 项目写了一个非常简单的技能内容大致如下--- name: build-java-project description: 在 Maven 项目中执行构建、测试、编译检查等操作时使用 --- ## 构建流程 1. 执行 mvn -q compile 检查主代码是否编译通过。 2. 执行 mvn -q test 运行完整测试套件。 3. 如果测试失败先读 failsafe/surefire 报告定位失败原因。 4. 不允许跳过测试除非用户在对话中明确要求。 5. 修改 pom.xml 之前先说明修改后的依赖影响范围。这个技能解决的具体问题是默认情况下Codex 在 Java 项目里遇到编译错误时会尝试各种猜测性修改而有了构建技能它会把编译和测试当成前置步骤永远先拿到反馈再动手。你也可以把mvn -DskipTests这类命令写成禁区防止它为了省时间跳过测试。4.2 用 Codex 加 superpowers 做一次保守重构我最近在重构一个老系统里的 Mapper 层。说实话一开始我是不敢让模型碰这种代码的因为老项目里常常有大量隐式约定比如某个查询方法是给历史报表用的、某个字段在特定场景下才有值。这个项目的 AGENTS.md 里写了相关约定但模型还是容易“自作聪明”地合并方法。后来我的做法是先把重构范围切成小块每一块都用 plan 技能生成方案然后用 code-review 技能审查它自己写的 diff最后再交给测试验证。其中 code-review 技能很关键它会按检查清单审视代码是否有未处理异常、是否破坏了原接口签名、是否引入了与项目风格不一致的写法。这种“模型自己审自己”的流程听起来有点奇怪但实际效果比我想象的好因为它强迫模型在输出之后重新读一遍自己的代码。4.3 团队里用 Java 场景的几点建议如果你打算在团队里推广这套玩法我有几个具体的建议。第一把 AGENTS.md 当作团队规范的一部分来维护而不是个人随手写的小纸条。项目里来了新人模型就是最好的“规范执行者”。第二Java 项目里尽量让模型先跑命令验证再给方案。Java 的类加载、依赖冲突、Spirng 上下文初始化这些错误光看代码很难看出来必须靠构建反馈。第三不要让模型直接改pom.xml版本号。依赖升级通常涉及兼容性评估这属于人应该做的决策。可以在技能文件里明确写出“未经用户同意不得修改依赖版本”。这样的硬性边界越早写越好。5. 踩过的坑三条完整的排查链路折腾这类工具踩坑是必然的。这里分享三个我实际遇到、并且花了不少时间排查的问题每条都按“现象、排查过程、最终原因”的顺序来写希望能帮你节省一点时间。5.1 技能加载不出来先查 frontmatter现象我在对话里输入了技能名Codex 也正常回应了但它完全没有按照技能文件里的步骤执行表现就像没加载过技能一样。我一开始怀疑是安装脚本没把文件放对位置于是重新检查了~/.codex/skills目录结构完全正常。然后又怀疑是 config.toml 里缺少加载项翻了几遍也没找到问题。最后我干脆把其中一个 SKILLS.md 从头到尾看了一遍才发现 frontmatter 里的description字段换行了。YAML 里多行写法的缩进不对导致解析器读不到描述信息技能虽然存在但无法被正常触发。这类问题如果想快速定位可以尝试用 YAML 解析器单独检查所有 SKILLS.md 的 frontmatter看哪几个文件解析失败。技能文件一旦多了手写 frontmatter 很容易出错我后来统一使用了继承自仓库模板的规范格式才彻底解决。5.2 MCP 服务器连不上先分清楚 transport 方式现象我给 Codex 配置了一个文件系统 MCP 服务器启动 Codex 后没有任何报错但模型一旦调用相关工具就超时或者提示无法连接。排查时首先想到的是服务有没有起来于是单独在终端里手工启动 MCP 服务器结果服务本身完全正常。然后再看 config.toml 里的配置我最初以为 MCP 服务器的默认方式是 HTTP于是写了transport http并指向了一个不存在的端口。实际上这个 MCP 服务是标准输入输出方式也就是 stdio配置时只需要指定command和args不需要填 URL。正确配置大致是这样[mcp_servers.filesystem] command npx args [-y, modelcontextprotocol/server-filesystem, /path/to/allowed]如果你需要连接远程的 MCP 服务确实要用transport http并配置 URL但本地服务多数是 stdio。踩过一次坑之后我的习惯是先看 MCP 服务 README 里写明支持哪种 transport再写进配置。5.3 长任务做着做着就“失忆”主动拆分上下文现象任务开始时 Codex 表现很好技能也执行得很规范但做到后面它开始忘记前面确认过的方案甚至开始重复修改已经改好的文件。一开始我以为这是上下文窗口不足于是换用更大窗口的模型但还是没有根治。后来我发现问题不只是窗口大小而是对话历史被大量文件内容、命令输出充塞模型真正能利用的有效注意力越来越少。尤其是 Java 项目里mvn test的输出非常长几轮测试跑下来前面 plan 的内容就被冲散了。我的解决办法是把任务拆成更小的批次每个批次开始前重新让 Codex 读取一次相关技能和计划文件。同时我在项目里维护一个PLAN.md把已经确认的计划和已完成事项写进去每次开始新批次前让 Codex 先读这个文件。这样做之后“失忆”的频率明显降低。6. 更进一步把团队方法论沉淀成技能6.1 一个可复用的技能模板到了这一步你应该能感觉到 superpowers 的真正价值它不是一套固定能力而是一个容器。你完全可以把团队的代码评审清单、发布检查表、安全自查清单都写成技能。我常用一个模板分享出来供你参考--- name: skill-名称 description: 主要用于什么场景在什么条件下触发 --- ## 前置检查 - [ ] 是否已经确认项目当前的基线版本 - [ ] 是否已经了解相关模块的现有实现 ## 执行步骤 1. 读取相关文件梳理现状。 2. 制定改动计划等待用户确认。 3. 按计划执行保持小步提交。 ## 完成标准 - 所有相关测试通过。 - 没有修改不需要改动的地方。 - 输出简明变更摘要说明影响范围。 ## 禁区 - 禁止未经确认就删除代码。 - 禁止对锁定依赖进行版本升级。技能创建的格式并不复杂难的是把你脑子里的隐性经验一步步拆成可执行的步骤。这个拆解过程本身就是有价值的事哪怕最后不用到 Codex 上写一遍也能帮团队把流程理清楚。6.2 需要克制的地方superpowers 好用但不意味着技能越多越好。我见过有人一口气装了五十多个技能结果模型反而不知道该遵循哪个。技能是给模型的行为增加约束但约束过多会显著增加决策成本。模型每次行动前都要读技能文件、对照多条规则输出会变慢而且可能变得过度谨慎。我在实际使用中保留了一组“最小核心技能”大概五个左右剩下的按项目临时启用。这样既保证了行为框架又给模型留了足够的灵活度。6.3 安全边界最后说说安全。superpowers 赋予了模型更强的行动能力但这在带权限的终端环境中是一把双刃剑。我给自己定了几条规则建议你也参考。第一不要把 Codex 的自动执行模式当作默认模式。特别是涉及删除、覆盖、依赖升级这类操作时必须设置人工确认。第二MCP 服务器暴露的路径要限制在项目目录内不要给它整个磁盘的访问权。第三技能文件里应该明确什么操作需要用户确认比如“禁止直接推送代码到共享分支”“禁止修改 GitHub Actions 配置”等。这些边界不是为了防止模型“变坏”而是为了在协作过程中保留人的决策权。工具越强越需要清晰的边界。我现在的习惯是每个新项目开始前花十分钟写一个与当前项目相关的 AGENTS.md外加两三个定制技能。这个初始化成本不高但后续每一次和 Codex 的协作都会顺畅很多。这也算是我折腾 superpowers 到现在最值得推荐的一种使用方式。