说实话我第一次把 Codex 这类 AI 编码助手接进项目的时候心态挺膨胀的多了一个随时待命的结对程序员写代码的效率不得起飞结果第二个星期我就发现问题了——它确实是会写代码但它更擅长交给你一堆“看起来能用但没人敢合”的代码。没有测试、没有文档、不考虑项目里的历史约定甚至改了接口都懒得告诉你。后来我慢慢摸索出一套东西专门解决这个问题。我习惯管它叫 superpowers你可以把它理解成一套给 AI 编码助手“立规矩”的工作流规则文件 辅助脚本 项目记忆。这篇文章我就把这套东西的完整玩法写出来照着做你也能让 Codex 从“会写代码”进化到“会交差”。很多人搜到 codex superpowers 这个关键词时其实想找的不是什么新模型而是怎么让 Codex 这种工具真正拥有“超能力”。答案不在模型层而在上下文层你给它的项目背景、指令约束和行为边界越清晰它输出的东西就越像团队老手而不是一个随手写 demo 的新人。下面我从配置思路、安装步骤、Java 项目实操到排查技巧一次性讲透。1. 围绕superpowers的核心思路1.1 先搞清楚它解决的是什么问题AI 编码助手的底层模型确实很强但它在处理具体项目时有一个天然弱点它不会主动了解你项目的规矩。你们的代码分层是怎么定的接口文档是写在 README 里还是单独一个 docs 目录改动业务逻辑需不需要先跑一遍全量测试这些问题它统统不知道于是默认就按“最通用”的方式来写写出来的东西自然跟团队风格格格不入。我常跟人打比方Codex 原厂状态像一个技术很强但不认识你团队的新同事你让它改代码它能改但不会主动按你们的 Code Style 调整也不会在提交前跑编译甚至可能直接改了接口定义而不更新调用方。superpowers 这套思路解决的就是信息差问题把你希望 AI 遵循的规则写成它能稳定读取并执行的配置。它不是某个特定软件的专有名词而是一种工作流设计方式核心落点在规则文件、辅助脚本和项目记忆库这三个东西上。这套方式最适合的人有两类一类是正在重度使用 Codex / 同类 CLI 工具、但对交付质量不满意的人另一类是在 Java、Spring Boot 这类工程化程度很高的技术栈里做长期维护项目的团队。前者需要的是工具层面的约束后者需要的是团队规范的“AI 可执行版本”。1.2 核心三件套规则文件、辅助脚本、项目记忆库先说规则文件。最常见的形式是项目根目录下的 AGENTS.md也有一些工具会读取其他自定义名称的 markdown 文件。无论文件名是什么作用都一样告诉 AI 这个项目用什么语言、什么构建工具、测试怎么写、文档放哪里、完成一个任务需要走哪些步骤。它相当于把团队约定翻译成模型能稳定遵循的指令。再说辅助脚本。很多操作不是“想清楚就行”的比如运行测试、编译项目、更新日志文件这些动作靠 AI 自由发挥很容易出错因为模型对命令的记忆不一定匹配你们项目的实际环境。更好的做法是提供一个固定脚本路径比如 tools/verify.sh然后在规则里写明“每次完成代码改动后运行这个脚本”。AI 不需要猜测命令只需要沿着你给的入口执行出错信息也更可控。最后是项目记忆库。我的习惯是在项目里维护 CHANGELOG.md 和 docs/ 目录让 AI 在动手前先读取这些历史记录。这样它写新功能时能看到之前接口是怎么设计的、变更记录遵循什么格式而不是每次都凭空创造一套新风格。模型本身没有记忆但你可以用文件系统给它造出一个“记忆库”这也是 superpowers 最容易被忽略但长期收益最高的部分。1.3 为什么自建比照抄一份通用配置更靠谱网上其实已经有不少现成的“AI 编码助手规则模板”有些还包装成了开源项目。但我个人强烈建议你花一两个小时自建而不是直接抄一份回来。原因很简单规则的本质是你们团队对“什么叫做完一件事”的定义这个定义不可能通用。别的团队可能要求高测试覆盖率你们可能更看重接口兼容性别人用 Gradle你们用 Maven别人文档写 Wiki你们写 MD 文件。这些差异决定了每一份配置都必须是贴合自身土壤的东西。我第一版规则是从一个开源模板抄的看起来挺全面实际用下来极其别扭。它要求 AI 修改后必须运行某个 linter但那个 linter 在我们项目里根本不存在它还规定“所有文件必须有作者注释”跟团队风格完全冲突。结果 Codex 每轮都在执行无意义的指令反而拖慢了交付。把模板当作参考没问题但每一行规则都要过一遍你自己的场景这真的能提升质量吗还是在制造噪音这种自建的过程也是团队复盘开发流程的机会你会被迫去想清楚很多平时没意识到的隐性约定。2. 环境准备与安装从零搭出一套可用配置2.1 先检查前置依赖在动手配置之前先把基础环境理一遍。无论你用什么 AI 编码助手首先要确保 CLI 本身可用然后确认你日常开发需要的工具链都已经就绪。以 Java 项目为例至少要有 JDK 和构建工具。下面三条命令能快速确认状态codex --version java -version mvn -v如果是在 Windows 环境建议装上 Git Bash 或者 WSL因为很多辅助脚本是用 bash 写的后面会发现这比在 CMD 和 PowerShell 之间来回折腾省心得多。我的习惯是同时保留一个 PowerShell 终端用于常规操作但所有和 AI 协作的自动化脚本统一用 bash降低跨工具的心智负担。检查环境还有一个容易忽略的点JAVA_HOME 是否指向了项目实际使用的 JDK 版本。很多电脑装了多个 JDK默认版本和项目要求不一致Codex 调用构建命令时就会踩坑。规则文件写得再漂亮也挡不住环境本身不一致带来的幺蛾子先把地基打平再谈配置。2.2 编写项目级规则文件前置环境没问题之后接下来就是整个 superpowers 的核心操作在项目根目录创建规则文件。这里我以团队最常见的 Java 单体仓库为例新建一个 AGENTS.md 文件# order-service 项目协作规则 ## 技术栈 - JDK 17 - Spring Boot 3.x - Maven使用 mvnw wrapper - JUnit 5 AssertJ ## 完成任务的前置动作 1. 修改任何 .java 文件前先查看 src/main/java 下的包结构 2. 修改业务逻辑必须同步补充 JUnit 测试 3. 代码完成后运行 ./mvnw -q compile 确认编译通过 4. 运行 ./mvnw test 执行全量测试并修复失败用例 ## 文档约定 - 对外接口变更后更新 README.md 中的 API 表格 - 每次提交前把变更记录追加到 CHANGELOG.md ## 上下文位置 - 历史接口变更记录见 docs/api-evolution.md - 测试用例风格参考 src/test/java/examples/UserServiceTest.java写这个文件时有个关键点规则必须具体到“命令级别”。很多失败案例都是因为写着“运行项目测试”这种模糊描述模型可能理解为直接敲 mvn test也可能想运行某个特定测试类结果偏差挺大。我把可执行命令直接写进规则里AI 就没有自由发挥的空间。另外规则文件不是越全越好。我见过有人写了五十几条规则结果模型上下文被大量占满反而丢失了对用户输入的有效关注。我的经验是一条规则解决一个具体问题先抓最影响交付的三个点编译要通过、测试要补全、文档要同步。2.3 添加自动化辅助脚本规则文件告诉 AI “要做什么”辅助脚本负责解决“怎么做才稳定”。我通常在项目里放一个 tools/ 目录最简单也最常用的是验证脚本#!/usr/bin/env bash # tools/verify.sh set -euo pipefail echo Compile check ./mvnw -q compile echo Run tests ./mvnw test echo Check docs if [ -f README.md ]; then grep -q API README.md || echo WARNING: README missing API section fi然后在 AGENTS.md 里加一行“每次代码修改完成后运行 bash tools/verify.sh根据输出修复问题。”AI 在这个流程里扮演的是“执行者 修错者”的角色而不是“命令发明者”出错概率立刻下降。脚本设计的思路可以参考 CI 流程把你想让 CI 检查的东西先在脚本里检查一遍。CI 是事后防线脚本是前置防线AI 每次交付前先过这一道等到合代码时就不会被 CI 的红灯砸一脸。我自己的项目里verify.sh 还会顺带检查代码格式、接口文档关键词具体字段完全由团队成员共同约定。2.4 全局配置与路径陷阱项目级配置相当于“每个仓库自带规矩”但如果你的习惯是很多小项目共享一套基础规则还可以设置全局层级的配置文件通常放在用户目录下例如 ~/.codex/AGENTS.md。用全局配置的好处是让 AI 始终知道你的通用偏好比如“默认使用 2 空格缩进”“提交信息用中文描述”。项目配置和全局配置同时存在时项目配置的优先级一般更高但具体行为取决于 CLI 版本建议用最小测试验证。这里有个我踩过不止一次的坑规则文件放错了层级导致完全不生效。有一次我在项目根目录建了一个 codex/AGENTS.md结果 Codex 根本没读它因为工具约定的入口是项目根目录下的 AGENTS.md。后来我把文件挪到根目录一切才正常。遇到规则不生效的问题时第一件事就是核对路径而不是怀疑规则写得不清楚。这类路径问题和配置文件的分层机制在不同的 Codex 版本里略有差异所以我把“建完文件后先确认入口”写进自己的配置检查清单避免反复踩坑。2.5 安装后的最小闭环验证配置到这一步还没法确认整个链路是通的。我建议你做一个最小闭环验证随意挑一个现有 Java 类让 Codex 改一行日志输出然后明确要求“按项目规则执行完整验证”。你用 2.2 节那份规则测试时观察它是否真的先跑了 verify.sh是否在编译报错时主动修复是否记得改接口后更新 README。通过这个验证你能快速识别三种状态第一种是规则根本没生效Codex 理都没理第二种是规则生效了但模型理解不到位只执行了部分步骤第三种是完整生效编译、测试、文档全部到位。第一种大多指向路径或者配置版本问题第二种需要你把规则描述改得更窄更具体第三种说明你已经具备继续深入的基础。这个闭环花不了五分钟却能帮你省下后面大量排查时间。3. Java项目实操把 superpowers 落实到日常开发3.1 用任务矩阵规划不同类型的工作到了真正干活的环节如果所有任务都用同一套规则很容易让 AI 在一些不需要文档的小改动上浪费时间。我习惯把 Java 项目里的任务分成五类每一类定义不同的规则强度功能开发需要完整闭环重构需要格外关注测试修 Bug 需要先写复现用例文档更新不需要跑测试而依赖升级则要重点观察兼容性。分类之后规则文件里不用堆砌几十条只需要说明“任务类型 X 的完成标准是 Y”。这五类任务的差异可以通过一张表看得很清楚任务类型superpowers重点规则辅助命令人工介入点功能开发补测试、更新文档、编译通过bash tools/verify.sh接口设计评审重构原有测试全量通过、行为不变bash tools/verify.sh关键逻辑走查修Bug先写失败用例再定位问题bash tools/test.sh BugTest根因分析确认文档更新只改文档、不碰业务代码无格式与准确性核对依赖升级全量测试跑通、关注废弃API./mvnw dependency:tree兼容性评估你可能注意到我反复强调“人工介入点”这是很多 AI 协作方案里容易被忽略的东西。 superpowers 不是让人完全撒手而是把 AI 的自主空间锁定在“不需要人拍板”的环节真正有风险的决策必须保留人工确认。比如重构任务里AI 可以自主改代码跑测试但最终的行为差异对比应该由人来看一眼。3.2 Maven 与 Gradle 场景下的规则差异Java 生态里构建工具主要就是 Maven 和 Gradle两者在 superpowers 配置上差别不小。 Maven 的生命周期相对固定compile、test、package 这些阶段名称稳定规则里直接写命令就好。但 Gradle 是任务驱动的一个项目里的 test 任务可能被重写甚至有自定义的 integrationTest、fastCheck 这类任务。如果你把 Maven 那套规则原样套到 Gradle 项目上AI 执行 ./gradlew test 未必是你想要的完整验证。所以我的经验是不同构建工具的项目建议维护不同的规则模板甚至不同团队分支可以各自维护一套指令集。 Gradle 项目我一般会在规则文件里专门加一段“可用任务清单”比如列出 test、check、compileJava 分别做什么让 AI 不靠猜直接选。因为 Gradle 任务的依赖关系通常藏在构建脚本里单纯执行任务名未必能反映项目真实的检查要求。同理如果你的项目里同时存在多模块 Maven 结构规则里最好写明“在哪个模块下执行命令”否则 AI 可能跑错模块的测试。3.3 实战让 Codex 自动补齐 JUnit 测试测试是 Java 项目交付质量最直观的防线也是 superpowers 能发挥最大价值的地方。先看一个常见的业务方法public BigDecimal calculateRefundAmount(Order order, boolean isForceRefund) { if (order null) { throw new IllegalArgumentException(order cannot be null); } if (order.getStatus() OrderStatus.COMPLETED !isForceRefund) { return BigDecimal.ZERO; } return order.getPayAmount().multiply(BigDecimal.valueOf(0.9)); }如果规则文件里只抽象地写一句“补充测试”Codex 可能会生成一个非常肤浅的测试覆盖正常路径就不管了。所以我通常会在规则里写得更细比如“测试类放在 src/test/java/com/example/order/service/OrderServiceTest.java用 AssertJ 做断言至少要覆盖正常路径、入参为 null、状态为已完成且非强制退款这三种情况。”这一步看着写的是规则其实是在“教”模型如何思考测试的设计。AI 测试生成能力的强项是模仿弱项是理解业务边界所以你要把业务边界的关键分支点告诉它或者让它先阅读代码中的 if 判断。我在实践中更倾向于在规则里加一句“assert 条件必须覆盖当方法中的所有 if 分支”这句话能触发模型主动去做分支覆盖效果比让人工罗列场景更高效。吃过几次亏之后我会在测试文件里点出一个约定“测试方法命名用 should_xxx_given_yyy 格式”让测试的第一行文字就能读懂意图而不是看到 test1 这种命名。3.4 实战自动生成接口文档和变更记录Java 服务端项目里接口文档的维护一直很烦人因为代码变动后文档总是滞后。 superpowers 可以把这件事自动化一大半在规则文件里写明“新增或修改 REST API 时更新 README.md 的 API 表格”然后让 Codex 根据代码里的注解自动生成对应条目。 Controller 里的注解信息足够完整时模型可以直接提炼出请求路径、请求方式和参数说明这份“代码到文档”的转换能力是 AI 做得很好的部分。除了 API 文档变更记录也值得交给 AI。我一般会准备一个小脚本来自动追加格式化的记录#!/usr/bin/env bash # tools/update_changelog.sh TODAY$(date %Y-%m-%d) echo - $TODAY: $1 CHANGELOG.md然后在规则里让 Codex 每次完成代码改动后运行bash tools/update_changelog.sh feat: add user query API。这样变更记录统一用“日期 描述 影响范围”的格式历史版本看过去非常整齐。文档自动化不是为了省那几分钟而是让 AI 的每一轮交付都留痕方便团队复盘哪些改动是它独立完成的哪些又被人修正过。3.5 一条指令跑完整个工作流配置做到位之后日常使用的体验会非常接近“给一个任务描述它把整个流程走完”。我最常用的命令长这样codex 为 UserController 增加一个 GET /users/{id} 接口要求按项目规则补齐测试和文档Codex 会先读取 AGENTS.md确认规则然后定位到 UserController看现有代码风格接着写接口实现生成测试类运行 bash tools/verify.sh根据报错反复修复最后更新 README 和 CHANGELOG。这一串动作在交互模式下会多次停下来问你是否继续跑测试、是否接受某个改动所以我会优先打开自动接受低风险操作的选项让它在编译和测试环节自驱。风险较高的改动仍然会停下来等我确认。这种分工带来的体验是我可以去处理别的事务回来之后直接 review 代码和测试结果而不是坐在终端前给它当操作员。真正跑顺之后你会发现规则文件不是一份静态文档它在持续迭代你的角色也从“代码书写者”变成了“规则维护者”。4. 更进一步自定义能力与团队共享4.1 把常用流程固化成自定义指令AGENTS.md 里如果写了一大段流程每次让 Codex 处理任务时它都要完整解析一遍既占用上下文又容易因为关键词理解偏差漏掉某一步。更好的做法是把完整流程整理成一个模板然后在规则里给这个模板起个名字。比如我在规则文件里定义过“标准功能开发流程”## 标准功能开发流程 当用户要求“按标准流程开发”时 1. 拆解需求列出受影响的文件 2. 先写测试用例运行失败确认是红 3. 实现代码运行测试直到全绿 4. 运行 bash tools/verify.sh 5. 更新 README 涉及到的 API 描述 6. 追加 CHANGELOG.md 变更记录这样我每次只需要说“按标准流程开发新增一个删除用户的接口”Codex 就知道完整意图。这个做法本质上是给 AI 创造了一套“宏”机制让常见业务逻辑不需要反复描述。对于团队来说这种自定义指令还能沉淀出很多高频场景修 Bug 流程、依赖升级流程、代码评审准备流程。每一条都是一笔知识资产因为指令本身来自团队的反复打磨。4.2 上下文窗口的分配策略上下文窗口再大也是有限的规则文件如果写成长篇小说AI 处理任务时真正留给代码的注意力就会变少。我采用的分配策略是“强制项短详情项外置”强制项必须在一段话内说清楚比如编译、测试、文档同步而像编码风格示例、测试命名规范、API 文档格式这类细节则放到 examples/ 目录下规则文件里只写一句“具体示例请查看 examples/java-style.md”。模型在大多数情况下不会主动去读外部文件除非规则里在关键步骤处点明“需要参考它”。这个方法用起来很像给模型做索引把最核心的指令放在一眼能看到的位置把背景资料放到可查的地方。实测下来规则文件的上下文占用能少一半以上而且因为关键指令更集中模型遵守规则的稳定性反而提高了。如果项目中确实有非读不可的文档我建议用“在满足某条件时读取 docs/xxx.md”这种条件式表达而不是让它无脑全量加载。4.3 团队共享与分层配置一个人用 superpowers 和全团队用 superpowers面临的复杂度完全不同。单人的规则文件可以追求个人偏好但团队协作时规则文件也会像代码一样发生“合并冲突”。我的建议是把配置分成两层项目级规则进 Git精炼稳定代表团队共同约定个人级规则留在本地存放个人编码习惯。这种分层能避免频繁改规则引发团队争论也方便新人通过阅读 AGENTS.md 快速理解团队协作风格。把规则放进 Git 管理还有一个好处可以通过 Pull Request 审查规则改动。规则文件的每一次变更都意味着团队协作方式的调整值得用和代码变更同等的流程来对待。我见到不少团队连 README 都没人看更别说规则文件但恰恰是它直接决定了工具化协作效率的天花板。规则分层的逻辑用在小团队是规划用在大团队是秩序别等到模型每次交付行为都漂移时再补救。4.4 与 CI 流程的衔接最后一层玩法是把 superpowers 的规则和 CI 流程对齐。我经常看到团队里 AI 改完代码跑本地测试是绿的推到远端 CI 却挂掉原因往往是本地环境与 CI 环境不一致。规则文件里会出现“用 mvn test 验证”这样的字眼但 CI 流水线里可能跑的是 mvn verify而 verify 里挂了额外插件。解决方案很朴素在规则文件里写明“本地执行的验证命令和 CI 保持一致具体为 ./mvnw verify”。更进一步你可以把 CI 中执行的命令拆出来做成一个共享脚本让版本不是把规则当成指导性建议而是作为可执行标准。团队里如果有多条流水线比如 PR 校验和主分支发布各有不同阶段我建议在规则文件里用一个清晰的表格注明场景对应的命令。这样 AI 在本地生成的代码质量与 CI 的门禁完全一致人不需要在推送后处理那些本来可挽回的格式与测试问题。5. 常见问题与排查技巧实录5.1 规则文件写好了但 Codex 完全不理会这是出现频率最高的问题。遇到这个情况先别怀疑规则内容写得不够好大概率是路径和工具配置问题。我先检查规则文件是不是放在项目根目录并确认文件名完全正确然后查看当前使用的 Codex 版本是否支持读取 AGENTS.md或者它需要的是其他入口文件最后确认你启动 Codex 时的工作目录是否在规则文件所在目录下。很多人习惯在子目录里启动工具规则文件明明存在却根本不被识别。如果路径确认没问题再考虑规则与用户请求的冲突。模型会倾向于认为用户的新指令优先级更高比如你让它“直接改不用跑测试”它就真的会跳过验证步骤。解决思路是在规则文件顶部明确写着“所有代码修改都必须执行验证脚本除非用户明确指出跳过”这样模型的默认倾向会被规则文件重新校准。5.2 Java 版本与构建工具版本冲突我在一个 Spring Boot 项目里遇到过本地默认 JDK 是 21项目却要求 Java 17编译时 AI 生成了一堆 Java 21 的新语法本地编译过了但推到 CI 就挂。问题的根子不是 AI 能力不够而是它读取到的环境信息和项目要求不一致。处理办法是在 AGENTS.md 的“技术栈”一节明确写清楚 JDK 版本和构建工具版本例如## 技术栈 - 使用 JDK 17禁止使用 Java 21 引入的新特性 - 使用 Maven 3.9.x通过 mvnw wrapper 构建同时在辅助脚本里固定 Java 路径比如在 verify.sh 开头设置export JAVA_HOME/path/to/jdk17。模型是按上下文信息执行动作的环境约束写清楚了它就不会随意使用版本敏感特性。要是你机器上装了多个 JDK可以把切换脚本也在规则文件里点名让 AI 在需要时自己调。5.3 多项目规则文件互相串场如果你同时维护多个项目而且是单终端切换目录的方式启动 Codex很可能出现项目 A 的规则被用在项目 B 的情况。典型现场是在 order-service 里修改接口Codex 却按照另一个项目的构建脚本路径去执行命令然后报出一堆找不到文件的错误。原因是模型的工作目录上下文没有正确重置或者你启动时路径不对。这种串场问题主要通过两个手段根治第一每一步请求里都明确当前项目根目录的绝对路径让模型不会跑偏第二在项目级规则文件顶部写一句“本规则仅适用于当前仓库根目录不要在子目录或其他仓库中执行其中命令”。如果 CLI 支持独立的项目工作目录参数也在启动命令里固定好。一开始觉得这些设置多余真正维护多个仓库时你就会知道这是保命条款。5.4 Windows 环境下脚本权限和路径问题很多人第一次把项目的 tools/verify.sh 放进 Windows 环境执行时爆出一个“permission denied”。如果你的辅助脚本是在 Linux 下写好推到 Git 仓库里的在 Windows 上直接用 bash 运行前需要先确认可执行权限。使用 Git Bash 时可以用chmod x tools/*.sh补权限如果是在 PowerShell 环境调用脚本尾部可能有\r的换行符问题运行前用 dos2unix 处理一下。另外规则文件里如果写了 bash tools/verify.sh在 Windows 的 CMD 终端中是跑不起来的我在规则文件里明确约定“所有辅助脚本统一在 Git Bash 中运行”模型看到后就不会尝试用 CMD 去执行。5.5 其他同类配置工具的横向对比最后快速对比一下市面上常见的几种 AI 编码助手配置思路方便你理解 superpowers 所处的位置。除了 Codex 的 AGENTS.md 机制还有不少图形化 AI 编程工具支持 .cursorrules 这类规则文件也有一些开源仓库直接把整套工作流打包成模板供人克隆甚至有人纯粹靠把团队规范写进系统提示词里来约束模型。它们和 superpowers 的区别主要在两点一是配置文件是否和项目仓库的标准化能力绑定二是规则是否配合可执行脚本和项目记忆库一起工作。我个人的结论是预制模板能帮你起步但稳定落地的关键还是那份属于你自己团队的规则文件。真正跑生产的团队不会每改一个工具就迁移一套模板而是会把规范沉淀成自己的“能力集”也就是前面反复提到的规则 脚本 记忆的组合。不同工具之间的横向对比本质上比的不是谁的文件名更好看而是谁的“上下文工程”更贴合实际开发流。最后分享一点我自己的体会。 superpowers 这套东西真正难的不是写那些 markdown 规则而是想清楚你的团队到底怎么才算把一个任务做完。很多人以为目标是 “让 AI 少犯点错”我觉得更准确的目标是 “把 AI 的错误控制在可修复的范围内”。我每次给项目加一条规则都会先问一句如果没有 AI这个要求我自己能做到吗如果连人都做不到那让模型执行它就是在造空中楼阁。有个小技巧值得一试每次规则文件更新后让 Codex 自己读一遍并总结规则内容如果它总结得和你想的不一样说明规则描述还不够清晰改到它能准确复述为止。这条方法帮我避开了不少表面完善、实际含糊的配置也算是对整个工作流最实用的一次校准。