Superpowers实战：为Codex CLI注入规划与思考技能-北京尧图网络

1. Superpowers 到底是什么给 Codex CLI 装上大脑说实话第一次把 OpenAI 的 Codex CLI 拉进日常开发流程时我的第一感觉是这家伙确实能写代码但很多时候它太听话了——你说帮我写个登录模块它二话不说直接甩出几十行代码压根不问你业务背景也不考虑现有代码风格更不会先做需求拆解。代码能用但离好用还差着十万八千里。这不是模型能力的问题而是缺少了一层关键的东西思考流程。后来我在 GitHub 上翻到一个叫 superpowers 的开源项目名字起得很夸大但实际用下来确实有点那个意思。它本质上是一套给 Codex CLI 定制的技能包和工作流集合通过 Codex CLI 原生支持的 AGENTS.md 配置体系把规划先行、深度研究、代码审查、测试驱动这些实践固化成了 AI 可以直接遵循的提示协议。不换模型、不动底层推理只是让 Codex 在做任何操作之前先从本能反应式写码切换成深思熟虑式执行。这篇文章写给所有正在用、或者正准备入坑 Codex CLI 的开发者。我会从零开始完整拆解这套配置的安装方法、目录结构、底层原理再用一个 Java 项目的真实落地场景演示它到底能改变什么最后把我踩过的坑和排查思路一并列出来。不管你是前端、后端还是做数据工程这套东西对你的终端 AI 编程助手都会有质的提升。2. 安装与目录结构把技能库装进本地环境2.1 从 clone 到运行的完整步骤superpowers 的安装方式足够简单基本就是克隆下来复制过去跑一次脚本。我实测过两条路径都稳定可用。第一种直接使用项目自带的安装脚本git clone https://github.com/obra/superpowers.git cd superpowers ./install.sh脚本做的事情很简单把仓库里的配置文件和技能目录整体复制到~/.codex/这个 Codex CLI 的全局配置目录下。如果你的 Codex CLI 已经装好了安装完就能直接生效如果顺序反了也没关系先装 superpowers 再装 Codex CLI 同样没问题AGENTS.md 会在 Codex CLI 首次启动时被读到。第二种方式手动复制适合想自己调整目录结构的人mkdir -p ~/.codex cp -r superpowers/* ~/.codex/手动复制的好处是你可以精准控制哪些技能要、哪些不要。比如你日常主要做 Java 后端完全可以把跟前端构建相关的技能文件从目录里摘出去减少上下文噪音。需要注意的是~/.codex/AGENTS.md这个全局入口文件必须保留它是整套系统的开关。装完以后我在终端里直接跑了一个验证命令codex 读一遍你的全局 AGENTS.md告诉我你接下来会遵循哪些工作约定如果 Codex 的回答里提到了先规划再编码使用技能库中的工作流之类的内容说明 superpowers 已经正确加载了。2.2 装完之后目录里到底有什么装完后~/.codex/看起来大致是这样的~/.codex/ ├── AGENTS.md ├── skills/ │ ├── deep-research.md │ ├── plan-v1.md │ ├── review.md │ ├── debugging-session.md │ └── ... └── sessions/ # Codex 会话记录默认生成其中最重要的就两个角色AGENTS.md是所有行为规则的入口Codex CLI 启动时先读它从里面得知我有哪些技能可用、我该按什么顺序执行任务skills/目录里每一份 Markdown 文件都是一个独立的、结构化的提示协议定义了特定场景下 Codex 该怎么做。这里要特别强调一点superpowers 里的技能不是插件、不是脚本、不是任何可执行的二进制程序它们就是一本本操作手册。Codex 读完 AGENTS.md 之后会把这些手册的要点记在上下文中在遇到对应场景时按手册指示行事。这听起来很像提示词工程但它的高明之处在于把提示词组织成了可维护、可组合的模块而不是一条塞满几千字要求的巨型指令。你可以往 skills 目录里随手丢一个新 Markdown 文件然后在 AGENTS.md 里加一行索引Codex 就学会了一项新技能——这一点对喜欢折腾的人来说非常友好。2.3 升级与卸载要注意的事superpowers 更新频率不算低作者会持续往 skills 目录里补充新的工作流。升级方式就是重新拉取仓库再把新文件复制进~/.codex/但要小心别用cp -rf直接覆盖整个目录否则你本地自定义过的 AGENTS.md 会被冲掉。我习惯把自定义内容单独放在~/.codex/custom/子目录里然后在 AGENTS.md 中引用这样升级时只覆盖原版技能文件不改动自己的定制部分。卸载更简单把~/.codex/AGENTS.md和~/.codex/skills/删掉Codex CLI 就完全回到默认行为。不过实测下来一旦你习惯了带 superpowers 的 Codex就再也回不去了——默认那种问一句写一段的交互方式会显得格外敷衍。3. 核心机制AGENTS.md、技能与思考协议是如何运作的3.1 AGENTS.md 在一开始就定下了规矩Codex CLI 在启动时会自动搜索并读取 AGENTS.md 文件查找顺序是当前项目目录向上递归最后读全局的~/.codex/AGENTS.md。项目级文件优先生效全局文件作为兜底。superpowers 利用的正是全局级这一层让所有项目都天然具备这套技能。AGENTS.md 的语法并不复杂本质就是 Markdown 文本加上一些约定格式。但内容组织的逻辑非常关键。我在自己的 AGENTS.md 里维护了几个大块全局行为约定例如所有代码改动必须先在计划中列出、技能索引列出可用技能及适用场景、禁止事项例如不允许在未跑测试的情况下声称功能完成。Codex 读完之后相当于在每次对话开始时都被强制复习了一遍工作准则。有个细节值得注意Codex 的上下文窗口有限AGENTS.md 内容如果太长会挤占实际对话和代码分析的空间。superpowers 的做法是把详细的步骤写进 skills 目录的单独文件里AGENTS.md 里只保留索引和触发条件这样既保住了规矩感又不至于淹没上下文。3.2 规划先行为什么这步是整套系统的灵魂默认状态下的 Codex 很像一个急于表现的新人你让它做任务它恨不得一次性把所有代码改完。superpowers 最核心的改动就是强制它先规划、再动手。具体行为是这样的当你提出一个稍大的需求Codex 不会直接改代码而是先创建一份PLAN.md在文件里列出当前状态、目标状态、实施步骤、风险点和验证方式。它只有在你确认计划之后才会进入编码阶段。这个过程看起来多花了十几秒但实际省下的返工时间远不止这些。我用一个真实例子说明。之前我给一个内部工具加批量导入功能直接跟 Codex 说帮我加一个能读 Excel 文件并批量写入数据库的功能没装 superpowers 之前它直接写了个入口函数用了 POI 解析、逐行 insert看着挺完整。但我一问失败行怎么处理、重复数据怎么去重、超大文件会不会撑爆内存它就答不上来了。因为这些问题在初期根本没建模。装上 superpowers 之后同样的需求它在 PLAN.md 里把文件上传限制、解析分批策略、数据校验规则、失败补偿机制列得清清楚楚再开始写代码。我只需要在计划阶段补充业务规则剩下的实现路径清晰得多。3.3 思考协议让模型慢下来的提示结构superpowers 还内置了一种思考协议本质是一套引导模型进行结构化推理的提示词。它要求 Codex 在输出任何结论前先做七步内部推演理解问题、列出已知条件、形成备选方案、推演每种方案的后果、评估优劣、做出决策、进入执行。这套协议不是玄学它对应的是大模型推理的实际短板——模型在生成代码时容易出现自洽但错误的路径。没有强制推演时模型往往会选择一条统计概率最高的输出路径而有了推演步骤它会强迫自己在多个候选方案里做比较显著减少低级错误。实测下来装了 superpowers 之后Codex 写的代码首测通过率明显高了一截尤其是涉及边界条件和异常处理的场景。4. 核心技能拆解与实操从深度研究到诋毁测试4.1 深度研究技能让 Codex 先当调研员再当程序员这个技能解决的是那种需求本身就不清晰的难题。比如你让 Codex 给一个 Spring Boot 项目接入 Redis 缓存它默认会直接写配置类和工具类。但 superpowers 的 deep-research 技能会先进入调研模式搜索你项目里的现有缓存使用方式、确认 Redis 版本兼容性、检查是否有自定义序列化器、梳理哪些接口需要缓存——全部理清之后再输出一份带结论和建议的调研报告然后才进入编码。调研报告不是走过场它会被 Codex 当作后续编码的上下文锚点。项目里其他代码无意中违反了调研报告里的结论时Codex 会主动提醒。这个机制很妙相当于把前期调研变成了长期约束。实操上启动深度研究的触发词很简单。你可以在对话里直接说用深度研究技能分析一下这个需求或者在 AGENTS.md 里规定任务涉及超过三个文件修改时必须先走研究流程。我建议后者因为人往往会忘记触发。4.2 诋毁测试技能从找茬视角重读代码这是我个人最喜欢的一个技能。它要求 Codex 暂时放下实现者身份切换到恶意审查者视角专门挑自己刚写过的代码的毛病。听起来有点自虐但效果极佳。具体的执行方式是这样的编码完成后Codex 会阅读一遍刚才生成的 diff然后按几个固定维度进行诋毁测试并发安全、异常路径、边界值、资源释放、性能退化、安全注入、与现有代码风格一致性。每个维度都会输出潜在问题证据修复建议而不是简单说代码写得不错。我用一个实际案例说明一次让 Codex 写一个文件导出功能正常实现完全没问题但它用自己的诋毁测试技能发现导出大文件时没有设置响应超时网关层会直接掐断连接。这个问题常规代码审查根本看不出来因为本地测试数据量太小。它主动加了分段写入和超时配置上线之后客户那边的大文件导出一次通过没出幺蛾子。这里给个小贴士诋毁测试输出的问题清单别急着全改让 Codex 对每个问题按严重程度和发生概率排序先修高严重度高概率的。否则所有小毛病都要处理反而拖慢进度。4.3 代码审查技能让 AI 当你的 Pull Request 搭档superpowers 的代码审查技能可以理解成 Reviewer 模式的强化版。我通常在两种场景下用它一是刚写完一个功能模块想让 Codex 过一遍二是代码合并进主分支之前做一次最终检查。它和普通 code review 提示词最大的区别是分级输出。Codex 会把发现的问题分成三个等级阻断性问题、建议改进、风格偏好。阻断性问题会给出具体的修复 diff建议改进会结合项目上下文说明为什么值得改风格偏好则直接列出来让开发者自己决定。这里有个使用技巧如果你的项目有 CI 流水线让 Codex 在流水线跑完之后再执行审查它会结合测试结果一起分析定位问题的准确率更高。审查过程中 Codex 会频繁引用具体文件和行号你在终端里可以直接跳转过去体验很顺。4.4 调试会话技能把瞎猜变成实验调试是 AI 编程助手最翻车的场景之一。默认的 Codex 遇到 bug 时会基于报错信息直接猜一个原因然后改代码很多时候越改越乱。superpowers 的调试技能要求 Codex 按实验方法论来先复现问题、再列出所有可能原因、设计最小实验去验证每个原因、最后定位到根因才动手修复。举个例子我在一个 Java 服务里遇到偶发性的连接池超时问题报错信息时有时无。Codex 默认模式下会直接调整连接池参数治标不治本。调试技能模式下它先列出了 DNS 解析延迟、TCP 连接队列积压、数据库端最大连接数、连接池回收策略、线程池阻塞共五个候选原因然后按影响概率逐个给出验证方法。我按它的指引抓了 JVM 线程 dump发现是线程池核心线程数配置和连接池大小不匹配导致的任务堆积。这个根因说实话让我自己排查没有小半天根本搞不定。注意调试技能生效期间会消耗较多上下文配额建议在长会话开始前手动清理一次 Codex 的会话记录给调试过程留足空间。5. Java 场景实战从项目初始化到测试闭环5.1 用 superpowers 初始化一个 Maven 项目Java 生态有自己的一套行规Maven/Gradle 构建、JUnit 测试、Lombok 简化样板代码、SLF4J 做日志、Spring 框架或轻量级的 Javalin/Quarkus。直接让默认 Codex 初始化项目它大概率会给你一个极简的pom.xml然后丢一个Hello World就完事了。这在真实开发里毫无用处。装了 superpowers 之后初始化项目的流程完全不同。Codex 会先进入规划阶段询问几个关键决策构建工具选 Maven 还是 Gradle项目是单体还是微服务测试框架用 JUnit 5 还是 TestNG是否引入 Lombok然后再生成项目骨架。它在 PLAN.md 里甚至会标注当前 JDK 版本是否匹配 Spring Boot 3.x 的基线要求这种细节。我实际操作时的完整指令是这样codex 用深度研究规划技能初始化一个 Java 17 的 Maven 项目要求包含 JUnit 5、Logback、Lombok 依赖并生成一个带用户服务的模块骨架它在动手之前先生成了PLAN.md里面列了 6 个实施步骤验证本机 Maven 版本、生成标准目录结构、编写 pom.xml 并校验依赖冲突、创建基础包结构、实现一个简单的 UserService 接口与 InMemory 实现、编写对应单元测试。每条都有验收标准。我确认之后它一次性全部完成mvn test直接绿。5.2 测试优先从写测试到写实现的无缝衔接superpowers 另一个让我觉得值回票价的地方是把测试优先实践贯彻到了 Codex 的编码流程里。常规情况下Codex 会先写实现再补测试这导致测试质量往往不高——测试只是走了主路径边界情况基本没覆盖。而 superpowers 要求先写测试再写实现用测试驱动实现。具体操作是这样的你让 Codex 实现一个金额格式化工具类它会先创建MoneyFormatterTest.java里面列出常规格式、负数、小数点后超过两位、超大金额共 8 个测试用例然后运行测试确认它们按预期失败红最后才写MoneyFormatter.java让测试变绿。这个流程走下来覆盖质量比传统后补测试高一个量级。在 Java 项目里我还要强调一个点千万让 Codex 先跑测试再宣布完成。默认模式它经常在写完代码后补一句测试应该能过但根本不会实际执行。superpowers 的流程会调用 Maven 的mvn test把真实输出展示出来测试没过就继续修绝不会拿应该能过来糊弄人。5.3 Java 特有的编译与依赖坑位Java 项目的依赖管理远比表面看起来复杂。pom.xml里一个依赖的传递依赖可能直接把整个构建带崩。Codex 在处理这类问题时的思路差异也很明显。默认模式下Codex 遇到依赖冲突会直接改pom.xml加个exclusion了事。superpowers 模式则先跑mvn dependency:tree把冲突的来源摸清楚再判断该不该排除、在哪个层级排除。因为很多依赖冲突是版本语义不一致导致的粗暴排除会引发运行时 NoSuchMethodError。这里分享一个我踩过的坑当时让 Codex 添加一个 AWS SDK 依赖它解决了编译期的版本冲突但运行时报了NoSuchMethodError。后来我用调试技能重新梳理发现问题出在一个传递依赖在两个组件中被分别引入了不同版本而且两个版本 API 都不完全兼容。Codex 给出的方案是把两个组件统一升级到一个兼容版本而不是简单排掉其中一个依赖。这种分析深度在默认模式下基本不太可能得到。再有就是 LombokCodex 默认生成的实体类经常缺少Builder或Accessors(chain true)这些注解不是它不会写而是它默认的输出习惯没有贴合项目实际。让 Codex 先读一遍项目里现有的实体类写法再照葫芦画瓢一致性会好很多。5.4 一个完整的 Java 任务流程示例我把一个真实任务的完整链路展示一下方便你理解整个流程是怎么串起来的。假设需求是给现有 Spring Boot 项目加一个按日期范围查询订单的接口。启动超能力模式后Codex 的行为大致是先进入规划会话创建PLAN.md列出现在的问题、目标行为、涉及文件清单、风险点比如日期格式标准化、空范围处理、索引命中情况。进入调研模式扫描现有 Controller、Service、Mapper 层命名风格确认用 Lombok 还是手写 getter确认分页工具是 PageHelper 还是手写。编写测试先准备一个带内存 H2 数据库的测试环境写日期边界、空参数、跨月查询三个用例跑一遍确认红。编写实现从 Mapper XML 到 Service 再到 Controller 逐层补齐。跑一次全部测试确认绿再做一轮诋毁测试检查 SQL 注入风险和日期间隔边界。最后输出一份变更说明包含改了哪些文件、每个文件的改动目的、以及提测前需要人工关注的三个点。这个流程跑下来大概三四分钟但产出的代码质量和可维护性远高于直接甩给我一段可以跑的代码。6. 经验沉淀常见问题与避坑清单6.1 高频问题速查表问题现象可能原因排查思路Codex 不遵守 AGENTS.md 里的规则项目级 AGENTS.md 覆盖了全局规则检查项目根目录是否存在 AGENTS.md必要时将全局规则合并进去技能没有触发Codex 直接开工触发条件没写清楚或对话已经偏离上下文在对话里显式声明使用 xx 技能或者把触发条件写得再明确一点上下文很快被耗尽skills 目录文件过多AGENTS.md 太长精简技能索引只保留核心技能删除不常用技能的索引行PLAN.md 生成了但 Codex 不执行Codex 在长对话中会遗忘早期计划经常把 PLAN.md 路径重新指给 Codex或在新会话中让它先读 PLAN.md测试说全绿但实际代码有问题测试用例过于简单没有覆盖边界用诋毁测试技能对测试本身做审查别让 Codex 自娱自乐6.2 我的个人使用习惯与建议这几个月高强度用下来我形成了几个固定的习惯。第一个建议是别把 superpowers 的技能全量加载。技能越多Codex 每次启动时被占用的上下文就越大响应速度和准确率都会受影响。我现在全局只留规划、调试、诋毁测试、代码审查四个核心技能其他按项目额外加载。第二个习惯是把 AGENTS.md 当成代码维护。每次新增技能或调整规则我都会在文件头部写清楚改动日期和原因然后用 Codex 自己确认是否能正确理解。这种配置即代码的思路让整个系统保持可演进的状态而不是一次配好就再也不碰。第三个建议是关于使用心态的superpowers 不会让 Codex 变成万能的 AI 工程师它只是把 AI 的开发过程规范化了。我自己最大的收获不是代码写得快了多少而是 Codex 的输出变得可预期了。可预期意味着我可以放心委派任务、放心让它在 CI 流程里干活、放心把它接入代码评审环节。对于一个 AI 编码工具来说这种确定性比一时的代码生成速度值钱得多。最后分享一个小技巧当你感觉 Codex 的行为又飘了——比如开始不写计划就动手、测试不过就说完成了最快的纠正方式不是改配置文件而是直接说一句请重新阅读你的 AGENTS.md并按照其中的工作流程执行。它每次都会乖乖回归正轨。这个简单的重读法在我日常使用中救了无数次场。

Superpowers实战：为Codex CLI注入规划与思考技能

相关推荐

盾构穿越地下管线的Abaqus数值模拟实践

计算机图形学数媒期末复习：从变换管线到光栅化的核心考点

嵌入式系统资源开发实战：Flash/RAM预算与低功耗优化全解析

更多资讯

超扭滑模与快速终端滑模的永磁同步电机无感控制：理论、离散化实现与仿真研究（Simulink仿真实现）

Java Set接口详解：特性、实现与性能优化

Superpowers开源协作游戏引擎：安装教程、常见问题与上手体验

AUTOSAR XCP配置实战：从Transport Layer绑定到DAQ同步落地

AUTOSAR XCP配置核心要点：从初始化失败到稳定DAQ的工程实践

TRO、PI、缺席判决有什么区别？—— 美国知识产权诉讼中，卖家必须看懂的三个关键节点

今日更新

防关联浏览器哪个好？三款产品实测差异解析

2026钢铁行业AI转型系统选型对比：多基地排产、大宗原燃料采购与质量追溯，六家厂商能力差异在哪里

影刀RPA深度实战：大模型Fine-tuning定制RPA专用Prompt与指令生成

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？