Codex 的默认能力其实一直被严重低估很多人用了一两天就放弃说“它就是个高级补全工具”。我一开始也这么觉得直到花了整个周末把超级能力superpowers配置方案完整地跑了一遍才发现问题根本不在 Codex 本身而在于默认配置里缺少了一整套工程化工作流。这个项目说白了就是一套基于 AGENTS.md 规则的增强方案它把规划、深度思考、验证驱动开发、子代理协作这些能力直接注入 Codex CLI。配置完之后Codex 不再是有问必答的对话助手而是一个会先分解任务、再逐步验证、最后自我复盘的全流程协作者。文章会从安装配置讲到规则机制再讲核心模块的实战用法最后重点演示 Java 后端工程的完整落地帮你彻底摆脱“AI 写代码像开盲盒”的体验。1. 项目整体设计思路与核心价值1.1 它到底解决什么问题原生 Codex CLI 的问题不是能力不行而是缺少“工作方法”。你让它改一个 Bug它会直接给出修改建议你让它写一个模块它会直接生成一堆代码。这在简单任务上没问题但一旦涉及多文件、多步骤、需要验证的工程任务这种“直接给答案”的模式就会频繁翻车然后你认为 AI 编程不靠谱其实只是没有给它一套靠谱的工作流程。superpowers 的设计思路很有意思它没有改 Codex 任何一个底层功能而是纯靠 AGENTS.md 规则文件来约束和引导模型行为。这个方案本质上是在做“行为塑造”告诉模型在什么阶段该做什么事、输出什么格式、调用哪些工具、如何验证结果。相当于给一个反应很快但没什么耐心的实习生配了一本非常详细的工作手册。这个项目最初的形态是作者在长时间使用 Codex CLI 后把自己验证过有效的所有工作流、提示词、规则模板固化成了文档。后来发现这套方法论可以复用就整理成了可安装的配置包。所以它的核心资产不是代码而是那些打磨过无数遍的规则文本。1.2 设计上的三个关键决策第一选择 AGENTS.md 而不是硬编码改 Codex。这意味着你随时可以打开规则文件自己改不用动 Codex 一行源码而且同一套 Codex 可以按项目配置不同的规则组合。这种可插拔设计非常聪明升级 Codex 也不会覆盖你的自定义配置。第二强调“验证驱动”。超级能力把验证内建到流程中写完代码必须跑测试、改完配置必须重启服务、动完 schema 必须检查迁移脚本。这直接解决了 AI 编码里最尴尬的问题——看起来很对一跑就挂。第三自带幂等性和重复执行机制。真实工程里失败太常见了方案里专门设计了循环检测、任务重试、失败恢复机制。Codex 在任务被打断后能基于上次的进度继续推进而不是从头再来。这对长时间任务特别关键。1.3 适配场景与适用人群最适配的场景是“真实工程项目开发”——就是那种有测试、有构建、有依赖管理、有前后端联调的复杂环境不是刷 LeetCode 那种单文件算法题。Java 后端、Python 数据处理、前端全栈都适用通常只要机器能跑 Node.js 18 就行。这个方案最适合正在认真用 Codex CLI 做项目的人。如果你还没装 Codex建议先跑通基础命令再回来如果你已经在用但总觉得缺一口气那你就是它的目标用户。那种只想点几下就有完整产品的想法还是趁早放下——这不是魔法它是给专业开发者的效率杠杆。2. 环境准备与完整安装过程2.1 前置依赖与检查在装超级能力之前先把基础环境确认清楚。我建议按下面的顺序检查别跳过任何一步后面踩坑时排查范围会小很多Node.js 18建议直接上 20 LTS实测对后续依赖兼容性更好Codex CLI 已经安装并登录能正常执行codex exec有一个可以放配置的工作目录建议单独建一个.codex目录来管理规则文件网络能正常访问 npm registry 和 GitHub这里提前说一下检查命令。node -v确认 Node 版本codex --version确认 CLI 版本。如果 codex 命令找不到十有八九是安装的时候没有把 npm 全局 bin 目录加到 PATH这个坑我后面在常见问题里会展开讲。2.2 下载与部署配置安装超级能力本身不复杂核心就是把规则文件放到 Codex 能找到的位置。以 macOS/Linux 为例操作流程是这样的# 进入你的工作目录 cd ~/workspace # 克隆项目到本地 git clone https://github.com/obra/superpowers.git # 查看目录结构确认规则文件 ls -la superpowers/克隆完成后你会看到类似AGENTS.md、skills/、scripts/这样的目录结构。这里要特别注意不建议直接把这个项目当作普通代码库去改而是要把它当作规则来源来引用。我自己的做法是把规则文件复制到项目的.codex/目录里统一管理这样每个项目都有独立的规则副本互不干扰。# 创建项目专属配置目录 mkdir -p .codex # 复制核心规则文件 cp -r superpowers/AGENTS.md .codex/ cp -r superpowers/skills .codex/ cp -r superpowers/scripts .codex/提示如果你用的是 macOS 或 Linux路径没问题Windows 下推荐直接用 Git Bash 或者 WSL省去一大堆转义和换行符的麻烦。我实测 WSL 下的体验最接近生产环境。2.3 验证配置正确加载配置完之后最关键的一步是验证 Codex 有没有真的读到规则。直接把 AGENTS.md 放到项目根目录往往不够因为 Codex CLI 加载的是你配置的引用。用下面的命令做一个快速冒烟测试codex exec 根据当前项目配置列出你可以使用的超级能力模块如果返回结果里出现了任务规划、验证驱动、子代理协作这些关键词说明规则已经生效。如果只是普通的回应多半是路径配置没生效去检查~/.codex/config.toml里的配置项。# 在 config.toml 中追加项目规则路径示例 [project_rules] enabled true path /绝对路径/.codex/AGENTS.md这里要提醒一句绝对路径一定要写对相对路径在 Codex 的某些工作目录下会失效。我一开始用了相对路径结果换了子目录执行任务的时候规则完全不生效排查了一个多小时才发现是这个问题。3. AGENTS.md 规则机制深度解析3.1 规则文件如何驱动模型行为AGENTS.md 本身不是一个代码文件而是纯文本的 Markdown 指令集它的语法没有任何神秘感就是通过清晰的层次结构告诉模型“你是什么角色、你应该遵循什么流程、你需要注意什么约束”。因为 Codex CLI 在启动时会自动加载这些指令模型在生成每一个 token 之前都会“看到”这些规则所以规则的措辞、顺序、颗粒度都会直接改变模型的输出行为。这就像同一个程序员面对一个“随便写写就行”的需求和一个“必须按这五个流程走完”的明确要求时产出的质量完全不同。超级能力能起作用就在于它把“自我要求”写成了可用的、结构化的工程规范。它的措辞非常关键规则不是“应该尽量做测试”而是“每个任务完成后必须执行测试命令并汇报结果”——这就是强制约束和自由建议的区别。3.2 核心模块逐项拆解打开 AGENTS.md你会发现它把规则分类组织得非常清晰。每个模块都像一个插件你完全可以根据需要启用或屏蔽。我把最核心的几个模块梳理一下Planning 规划模块强制在动手前生成任务分解清单。它要求模型对每个目标至少拆出三步以上的子任务并且在执行完一个子任务之后回到清单打勾。这个模块直接解决了 AI 容易“只见树木不见森林”的问题。Thinking 深度思考模块要求模型面对复杂问题时先给出多种候选方案再逐个分析利弊最后才选一个执行。这个模块在调 Bug 或做架构决策时特别实用能有效避免那种“第一反应直觉写代码”的鲁莽操作。Verification 验证模块内置“先测试后提交”的强制要求。它要求模型在做完任何代码改动后主动给出并执行验证命令而且通常规定了具体的测试命令格式。这个模块是提升代码质量贡献最明显的部分。Subagent 子代理模块定义了不同角色的子代理比如“研究代理”“审查代理”“调试代理”。Codex 的 SDK 支持你自主调用这些子代理来处理更细分的工作比如让一个代理去探索代码库另一个代理去审查改动再把结果整合回主流程。每个模块都配备了独立的 Markdown 模板和配套提示词脚本。就算你完全不懂怎么设计提示词直接组装这些模块也已经能跑得很好。3.3 自定义规则的最佳实践超级能力不是封闭的爸爸系统完全可以按你的习惯来改造。我强烈建议你在搞懂核心规则之后再开始自定义否则很容易改得四不像。自定义的核心原则有四个第一把规则设计成“显式指令”而不是“性格描述”。“你是一个资深的 Java 工程师”这种话基本没用要换成“在生成 Maven 项目代码时必须使用 4.0.0 的 modelVersion并在 pom.xml 中明确定义所有依赖版本”。第二设置明确的“推荐路径”和“禁止路径”。换句话说既要告诉它应该怎么做也要告诉它别怎么做。比如“不要用var推断 null 可能出现的返回类型”就比“注意代码规范”强很多。第三按项目拆分规则。Java 项目需要 Maven 构建规范Node 项目需要 npm 脚本规范数据项目需要数据流规范。一个通用规则文件放不下所有内容建议用子目录分别管理让 AGENTS.md 的主文件不要超过 200 行保持可维护性。第四规则加入量化指标。比如“重构后测试覆盖率不得低于 80%”“微服务启动时间不应超过 15 秒”这类可验证的指标比模糊的建议更能约束模型的生成策略。4. 核心技能模块的工程化实战4.1 任务拆解告别“一问就答”的浅层模式配置前的 Codex 面对“帮我给订单模块加一个导出功能”这类需求通常反应是直接给一段代码片段或者简短说明——这种回应放到真实工程里基本无法直接使用。配置超级能力之后它的第一动作会变成搜索代码结构、理解现有订单实体、查询当前使用的导出库然后输出一个至少包含数据模型变更、接口定义、业务逻辑实现、单元测试、接口测试的五步规划。这就是“任务拆解”带来的质量差异。实际使用中你会发现Codex 在回答“需要哪些步骤”时是带着上下文去理解的而不是凭空猜测。它会主动打开仓储、实体类、控制器然后才给出分解后的清单。有了这个清单后续每一步执行时都有参照物就算中途指令断了回恢复了也能照着清单继续往下推。4.2 深度思考与方案选型工程里最难教给 AI 的是“在做技术选型时如何权衡”。超级能力在 Thinking 模块里专门设计了多个方案对比模板它会要求模型列出三套候选方案分别说明各自的优点、成本、风险然后再给出推荐结论。比如“事务应该放在服务层还是领域层”“缓存应该用本地 Caffeine 还是 Redis”“分页查询应该用 MyBatis-Plus 还是手写 SQL”这些问题在真实项目里都可能出现而规则内置的选型框架恰好能引导模型输出有理有据的答案。我遇到过一个很典型的例子让 Codex 处理一个慢 SQL 优化它没有直接推荐加索引而是先对比了“加复合索引”“改写查询逻辑”“引入数据冗余”三种方案还列举了各自的适用场景和代价。这种输出质量如果放在没有规则的状态下根本出不来。4.3 验证驱动开发如何闭环开发中最烦的事情是“AI 写完代码你说编译一下它告诉你我没有终端权限”。超级能力对验证的约束是强制性的它要求模型在每个代码生成动作之后立刻执行测试命令并且把测试输出贴回对话里作为反馈。以 Java 项目为例正常流程是mvn compile mvn test mvn package在验证模块的约束下Codex 每一步执行前都会自主调用这些命令然后根据报错信息迭代修改直到测试全绿为止。这带来的好处非常直接——它不会再让你手动去跑一遍测试再贴回给它看整个调试闭环完全由它自己完成。这在处理“测试挂了、报错信息看不懂”的场景下特别舒服。4.4 子代理协作的合理分工超级能力最先进的可能是子代理机制。它允许你在主对话中生成一个“研究代理”去做代码库探索生成一个“审查代理”去审查你刚刚的改动生成一个“调试代理”去单独攻关某个测试失败。子代理之间彼此隔离不会污染主对话的上下文这在小仓库里作用不大但在中大型项目中价值就非常明显。举个直观的例子在主对话中你让 Codex 给用户服务添加缓存机制它可以先把“研究代理”派出去看当前用户服务的调用链路和热点方法再让“代码生成代理”基于研究结果写实现最后让“审查代理”检查 Redis 的 key 设计是否合理。整个过程都在一次会话中完成但每个子任务的上下文是干净的、专用的生成的代码逻辑清晰且可审查。5. Java 后端项目的完整实战演示5.1 场景设定与任务规划为了把前面的理论落到实处我专门用一个典型的 Java 后端任务来走一遍全流程在 Spring Boot 项目中给用户模块增加一个“导出用户列表为 Excel”的接口。这个需求看起来简单但涉及控制器、服务层、仓储层、依赖管理、测试、文件下载响应等多个环节很适合演示规则的作用。配置好超级能力之后我给它下达了一个简短指令“请给用户模块新增一个导出 Excel 的功能按规划模块的流程执行。”Codex 的第一反应并不是直接写代码而是开始探索项目结构。它读了 pom.xml 确认现有依赖搜索了 UserController 和 UserService 的代码然后输出了一个任务清单分析现有用户查询接口确认分页参数和返回结构设计 Excel 导出工具类指定 EasyExcel 作为导出库新增导出接口接受查询条件参数返回二进制流编写单元测试覆盖导出核心逻辑更新接口文档列出导出字段和格式说明这段规划的质量比我预期的要高它没有一上来就写代码而是先做了技术调研。EasyExcel 的选择也是基于项目里已经引入过 Alibaba 系列依赖才推荐的这比那些“空降方案”靠谱太多了。5.2 实现过程与验证闭环规划完成后Codex 进入执行阶段。它会先在 pom.xml 中追加依赖dependency groupIdcom.alibaba/groupId artifactIdeasyexcel/artifactId version3.3.4/version /dependency紧接着它会创建 ExcelUtil 工具类在 UserController 中新增导出接口。关键的是每一步代码生成之后它都会自动执行一次mvn compile来确认没有编译错误。有一次我发现它在实体类转换的代码上绕了两圈后来意识到是因为 EasyExcel 的ExcelProperty注解需要显式指定列顺序它在前一次尝试中漏掉了编译通过了但运行时可能出问题。在验证模块的约束下它主动在生成控制器代码之后补跑了单元测试把列顺序验证问题提前暴露并修复了。这里最能体现规则作用的地方是Codex 在写完导出工具类之后主动在测试目录中创建了一个对应的测试类创建了临时用户数据列表调用导出的核心逻辑断言生成的文件存在且可以解析然后运行mvn test看到测试通过之后才向我汇报完成。5.3 自动化重构与代码质量导出功能本身做完之后我用了一个额外指令来检验超级能力的重构能力“请在刚才的实现中抽取导出模板接口让 Excel 导出和未来可能的 CSV 导出共用一套逻辑。”如果由普通模式接手大概率会直接新增一个接口文件然后结束。但在规则驱动下Codex 首先分析了现有的 导出实现找出了工具类与控制器的耦合点然后设计了一个UserExportService接口把用户数据的查询、组装、格式化都封装到服务层里。重构完成后它还主动执行了原有测试确认没有破坏既有行为。整个操作过程像是一个半自动的结对编程搭档——它在你划定的范围里自主推进同时每一步都会通过测试反馈来保证没有跑偏。这跟我以前用 AI 写代码时“写一版、跑一下、错一堆、再修半天”的体验完全不同。6. 参数调优与日常开发流程整合6.1 两种运行模式与适用场景日常使用中我主要切换两种模式轻量模式和深度模式。轻度任务比如改个字段名、加个日志、调整某个方法条件判断用默认配置就够了较重任务像上面演示的整个导出功能、跨模块重构、排查复杂 Bug我才会让 Codex 完全按照规划、思考、验证、子代理的完整工作流来推进。深度模式需要你显式指示“请使用系统化工作流先规划再调研然后分步实现每步都运行测试。”在规则文件的约束下它会自动加载所有对应模块。如果你直接复制了项目的 AGENTS.md 到项目目录那么默认就会走深度模式希望切回轻量模式时在指令里加一句“直接处理不要规划”就行了。这两种模式的切换成本非常低但适应的任务类型差异很大。我用下来最大的感受是轻量模式追求的是响应速度适合那些你知道答案、只是想让它快速完成的任务深度模式追求的是正确率和可维护性适合那些你心里没底、需要它有逻辑地探索的任务。6.2 关键参数与配置参考我提供一个经过实测的配置参考你可以根据自己的项目特点来调整。下面是~/.codex/config.toml的核心配置# 模型选择与运行参数 model gpt-4.1 temperature 0.2 # 上下文管理 max_tokens 32000 # 规则加载 [project_rules] enabled true path /workspace/.codex/AGENTS.md # 沙箱模式 sandbox danger-full-access关于温度参数我想多说两句写代码和文本创作不一样代码需要的是确定性和正确性所以温度别调太高0.2 是我在多语言项目里反复横跳后找到的甜点值太高了模型容易“灵光一闪”写出风格漂移的代码太低了又容易陷入模板化套路。上下文窗口同样很关键深度模式下模型需要同时规划、跑测试、读文件窗口太小会经常打断思路32K 是一个比较平衡的选择。6.3 与 IDE 和 Git 工作流的整合超级能力不仅可以在终端里用也可以整合进 VS Code 的 Codex 插件里。你只要把 AGENTS.md 放到项目根目录VS Code 插件启动对话时也会自动加载规则。这样你在 IDE 里选中一段代码、让 Codex 重构时重构行为也会遵守规划与验证流程。Git 工作流方面我推荐一种保守的用法让 Codex 干活前先手动分一个特性分支给它然后要求它在实现完功能且测试通过后主动生成一份符合 Conventional Commits 的提交信息。在我的实践中这个流程能大大减少“模型改完了但提交信息写得像天书”的问题也让代码审查变得有据可查。7. 常见问题排查与避坑指南7.1 AGENTS.md 没有被加载这大概是配置完以后最常遇到的问题。表现是执行codex exec 列出可用的超级能力模块结果 Codex 的回答完全没提到任何规则模块就像 AGENTS.md 根本不存在。产生这个问题的原因通常有路径用的是相对路径在 Codex 切换工作目录后失效或config.toml中没启用[project_rules]又或者 modification 的时机在进程启动后修改了规则文件但没有重启会话。排查思路很简单先确认 config 里配置的路径是绝对路径再确认文件内容和字符编码是 UTF-8偶尔会被工具写成带 BOM 的格式导致解析失败改了配置一定要重启 codex 进程规则文件在启动时只加载一次。如果你发现这些都没问题那就把 path 换成不带~的完整路径再试一次。7.2 任务陷入无限循环模型在验证闭环里卡住绝对是高频事故常见表现是 Codex 反复跑同一个测试、反复得出相同的失败原因却一直没有进展。这不是规则文件的问题而是模型在预设路径中钻了牛角尖预设的验证命令也可能没有把所有测试环境的必要参数传进去导致它一直用了错误的方式重复验证。这种情况下我最有效的做法是直接打断它然后明确指示“停止当前修复分析为什么会有这个错误改变验证命令的参数组合给出两个替代方案后再继续”。中断操作并不影响已生成的内容Codex 会基于当前上下文重新定向。另外一个长期对策是给验证模块添加循环检测规则如果在日志中看到“相同的失败信息出现超过三次”就自动切换为“调查模式”并汇报问题。这个简单规则能把很多无谓的反复直接摁住。7.3 上下文耗尽与 Token 爆量深度模式在大型项目里确实费 token尤其是启用子代理之后。我经历过一个中型微服务模块的处理四个子代理各读了一堆文件主对话的上下文眨眼间就被榨干了之后 Codex 的行为明显退化经常答非所问甚至开始听不到我最新的指令。我的对策是把任务拆得更细一次主对话只负责一个子模块而不是试图在一个会话里完成一整个服务。研究类的探索任务尽量交给子代理去消化别在主对话里铺开所有文件。项目文件数量多的时候先让 Codexgrep定位关键点再有针对地打开三四个关键文件比一次性把所有相关文件塞进上下文高效得多。7.4 过度工程与需求偏移规则开启以后另一个有意思的问题是模型会“用力过猛”——本来只想加一个简单的导出接口它却非要给你抽一套导出框架出来。模型为了体现自己的严谨往往在“方案对比”环节选择最复杂、最“工程化”的方案而没有考虑当前项目的实际复杂度。我的解决办法是在任务描述里提前限定复杂度明确告诉它“此任务为简单任务不需要引入新的抽象层不要新增额外的设计模式保持现有项目风格”。规则本身也支持添加“最小改动原则”这一条这是我在实际项目里新加的自定义规则有效避免了很多“花式重构”。7.5 实践后的几个核心心得踩完这些坑以后我对 AI 编码协作方式的最大改变是别把 Codex 当搜索引擎要当结对工程师。超级能力发挥了作用是因为它把这种结对工程师的工作素养落成了可执行的规则。你的任务质量直接决定产出质量当你给了足够的上下文、清晰的验收标准、明确的改动边界产出的代码质量高到可以合并进主干当你给的需求含糊不清模型会自己脑补出一个不太好的方案。用超级能力和用其他配置的差别本质上就是“你希望 AI 怎么帮你干活”的差别。同一个人用与不用这套工作流在一周内的产出质量能够相差十倍——这句话毫不夸张。有实际项目的人不要让 Codex 停留在“补全”这个级别给它一套好用的规则框架它能给你更好的回报。