默认状态下的 Codex 就像一个聪明但没做过入职培训的实习生代码写得出来但不知道你们仓库的构建命令是什么不知道团队要求提交前跑哪些检查也不知道“新接口必须带单元测试”这种约定。每次新对话它都从头开始猜。直到我接触到“superpowers”这套玩法才真正解决了这个问题——它不是某个具体的软件版本也不是一个固定仓库而是一套给 AI 编码助手注入项目认知的“技能包”体系目前社区里讨论最多的场景就是和 Codex 配合使用。这篇内容主要写给实际在用 Codex CLI 或 Codex 相关 IDE 插件做日常开发的工程师。无论你是 Java 后端、前端还是全栈只要手里有一个超过三五个模块的仓库并且希望 AI 生成的东西能直接通过构建、测试和代码评审那这篇文章能给你一套从安装到落地的完整思路。我会先从原理讲清楚再给一份可以直接抄走的目录结构和规则示例最后分享我在真实工程里踩过的三类问题以及如何写一套团队专属的 superpowers。1. 先从“superpowers”是什么说起AI 助手缺的那层项目认知1.1 为什么默认的 Codex 会“水土不服”很多人第一次用 Codex 的感觉是哇代码写挺快但再往下用就会发现不对劲。它给出的代码风格经常和项目现有代码不一致比如项目里统一用 Lombok它却写了一大段 getter/setter项目里用 JUnit 5它生成的是 JUnit 4 的 import让它跑测试它可能自信地说“测试通过了”实际上根本没跑。问题不在于模型能力而在于上下文缺口。Codex 每次对话拿到的信息只有你当前打开的会话内容、代码片段或仓库索引但并没有一个稳定的机制告诉它“我们团队的规则是什么”。默认情况下它依赖的是通用编程知识而不是你的仓库知识。这就好比一个经验丰富的厨师到了新餐厅菜单上的菜他都会做但他不知道这家后厨的调味料放在哪、出餐标准是什么、摆盘有什么要求。你让他直接上手他只能按自己习惯来做出来的东西有基本功但不符合这家店的规矩。1.2 superpowers 不是插件是一套“软能力”注入方案我第一次听到 superpowers 这个词以为是某个新出的 IDE 插件。深入了解后才发现它更像一套“软能力”注入方案把项目规范、技能示例、校验脚本三者打包让 AI 助手在每次对话时都能读取到这些内容从而表现得像一个“熟悉本项目的开发者”。我实际落地时把它拆成三层来理解规则层用 Markdown 写清楚项目的构建方式、测试命令、代码风格、禁用的 API、目录职责。技能层为高频任务准备可复用的提示词模板比如“新增一个标准 REST 接口”“修复并复现一个 Bug”“给模块补充单元测试”。校验层用脚本把 AI 的产出变成可验证的结果比如跑构建、跑测试、做静态检查而不是听它嘴上说“我觉得没问题”。这种结构与传统插件最大的区别是它不需要模型额外加载代码逻辑而是把“项目认知”放在了一个 AI 每次都能看到文本位置。对 Codex 来说规则文件就是它在项目里的“入职手册”。2. 从零到一在当前工程里把 superpowers 跑起来2.1 先准备好运行环境在动手之前先确认你的机器环境满足基本条件。我当前的工作方式是使用 Codex CLI所以以下命令都是以命令行环境为例IDE 插件的读者可以对照理解。node -v git --version codex --version建议 Node.js 版本不低于 18Git 必须可用Codex CLI 需要已经登录并能正常发起会话。为什么强调这些因为 superpowers 技能包里通常包含自动化脚本而脚本要调用的就是这些基础工具。如果 Codex 连 git 都找不到那后面所有和提交、分支相关的技能都会失灵。如果你还没有安装 Codex CLI可以先通过对应包管理器完成安装然后在项目目录里跑一句最基础的提问确认网络和鉴权都没问题再进行下一步。这一步不是浪费时间而是先把“运输工具”准备好再谈“装载货物”。2.2 初始化一个最小可用的技能包我见过很多人把 superpowers 理解得很玄乎上来就搞一堆文件最后 Codex 根本读不过来。我的建议是先做一个最小可用版本跑通以后再逐步加料。以下是我在 Java 后端项目里最常用的一套目录结构repo/ ├── AGENTS.md ├── .codex/ │ ├── rules.md │ └── skills/ │ ├── java-build.md │ └── api-endpoint.md └── scripts/ └── verify.shAGENTS.md是入口它告诉 Codex“先读我”。这个文件名和位置是有讲究的很多 AI 编码工具默认会在仓库根目录查找这类说明文件相当于一个约定俗成的入口。.codex/rules.md放的是强制规则所有任务都适用比如“禁止提交 target 目录”“统一使用 ./mvnw 命令”。.codex/skills/下面按任务类型拆分技能文件每个文件聚焦一类高频场景。scripts/verify.sh是最后的守卫它会执行真实的构建和测试命令。我不建议把校验逻辑塞在规则文件里让 AI 自行判断那样不够可靠脚本更硬。初始化时先创建一个极简的AGENTS.md里面只写三样东西项目是干什么的、构建用什么命令、测试用什么命令。不要一上来就写几百行规则AI 和你都一样信息太多反而记不住重点。2.3 用“探针任务”验证安装是否生效文件建好以后怎么判断 Codex 真的读到了我习惯用一个“探针任务”来测试。选择一个简单但必须依赖项目上下文的问题比如请查看项目里的构建配置告诉我新增一个带单元测试的 Service 类后应该用什么命令运行全部测试。如果 superpowers 生效Codex 会回答出你规则里写的那条命令比如./mvnw test并且会主动提到测试文件的位置约定。如果没有生效它大概率会给出一个通用答案比如“你可以用 mvn test”或者直接说“我没找到构建配置”。我列了一个简单的判定表方便你快速判断状态现象可能原因处理方式回答正确且引用了规则文件superpowers 生效继续增加技能文件回答通用但没有引用项目规则入口文件没被读取调整 AGENTS.md 位置和命名回答正确但执行命令时跑错技能文件里的命令与项目实际不符用项目真实命令覆盖规则完全答非所问会话上下文被裁剪简化规则文件把关键命令靠前探针任务跑通以后再进入日常任务流你会明显感觉到 Codex 的输出从“通用程序员”变成了“这个项目里的程序员”。3. 核心玩法把“技能包”塞进 Codex 的日常任务流3.1 技能包的本质规则、示例、脚本三位一体之前我提到三层结构这里展开讲一讲为什么必须三个都要而不是只写规则。只有规则AI 容易“知道但做不到”。例如你写“新代码必须通过 spotless 检查”它可能真的运行 Spotless 插件也可能只在代码里加了注释说“你可能需要跑一下 spotless”。这是大模型生成式交互的特点它在模仿一个懂规则的人而不是真的在执行规则。所以技能文件里要放示例。示例的作用不是给 AI 抄而是让它知道“符合要求”长什么样。比如写一个“新增 REST 接口”的技能里面放一段标准的 Controller 代码和对应的测试代码AI 在生成类似任务时风格就会向示例靠拢。最后是脚本。脚本才是硬校验。verify.sh里可能就三行#!/usr/bin/env bash set -e ./mvnw spotless:check ./mvnw testAI 可以撒谎说“测试通过了”但脚本不会。所以我常把脚本称为“不会说谎的队友”。技能文件里可以明确写一条规则完成 Java 任务后必须运行scripts/verify.sh并把结果贴出来。3.2 针对 Java 工程配置我的 superpowers因为热词里“superpowers java”出现频率很高我就以 Java 工程为例给一份可以直接参考的技能文件。假设你手里的项目是一个 Spring Boot Maven 的多模块工程测试框架是 JUnit 5代码格式化用 Spotless。那么.codex/skills/java-build.md可以这样写# Java 构建与代码规约 - 构建命令统一使用 ./mvnw clean verify - 不要使用系统全局的 mvn优先项目内的 Maven Wrapper - 测试文件放在 src/test/java 目录命名以 Test 结尾 - 新代码必须通过 mvn spotless:check提交前建议执行 mvn spotless:apply - 禁止将 target/ 目录提交到 Git - 多模块之间如果修改了公共模块必须同步运行整个项目的测试这段文本的最大价值是消除了 Codex 的“猜测空间”。Java 项目最常见的混乱就是 Maven 和 Gradle 混用或者明明项目里有 WrapperAI 却去调系统全局命令。规则写清楚之后Codex 在会话里会选择最明确的路径。我还会在 API 接口类任务的文件里放一个短示例包含正确的返回结构、异常处理方式、日志记录方式。示例不需要很长重点是让 AI 看到你的项目风格。3.3 实战让 Codex 带着 superpowers 完成一次后端改动下面用一个具体场景串一遍整个流程。假设需求是新增一个GET /users/{id}接口返回用户基本信息找不到时返回 404。我会这样给 Codex 下达任务使用 java-build 技能和 api-endpoint 技能新增一个查询用户接口。要求Controller 层返回 ResponseEntityService 层抛出业务异常全局异常处理器负责转换成 404。完成后运行 scripts/verify.sh贴出测试结果。这个指令包含几个关键动作明确引用了技能包、指定了代码分层、绑定了校验脚本。Codex 会先在.codex/skills/下面找对应文件然后按里面的规则和示例生成代码。这和没有技能包时“直接拍脑袋写一个 Controller”的结果完全不同。生成代码后它应该主动调用脚本。如果脚本失败它需要读取失败信息并修改代码而不是直接把失败信息丢给你。这正是技能包把对话从“被动写代码”变成“主动完成任务”的关键区别。我自己实测下来的感受是有了 superpowers 后Codex 更像是“在配合我工作”而不是“在替我写作业”。它会记得项目的测试习惯也会在提交前主动检查代码风格这些体验在默认状态下很难出现。4. 踩坑记录装了 superpowers 之后我遇到的三类问题4.1 多份技能文件互相“打架”根规则和子项目规则冲突第一次完整铺开 superpowers 时我遇到的最头疼的问题就是规则文件多了以后互相冲突。比如根目录的AGENTS.md写着“所有模块统一使用 Maven”但某个子模块其实是 Gradle 工程或者某个历史遗留模块有独立的构建脚本。Codex 读取多个规则文件时如果发现冲突它的表现很分裂有时以最后一个文件为准有时以根目录文件为准有时干脆两个都不遵守自己选一个折中方案。你问它“为什么用 gradle 命令”它会回答“因为子模块配置里有 build.gradle所以我认为这里应该用 gradle”。这个问题的解法是“就近原则”把具体模块的规则放在模块目录下而不是堆在根目录。比如repo/ ├── AGENTS.md ├── service-order/ │ └── .codex/ │ └── rules.md └── service-user/ └── .codex/ └── rules.md根目录只写全局通用规则子模块覆盖特殊规则。CCodex 在某个模块下工作时应该优先读取该模块目录下的说明。同时规则文件之间不要互相重复描述同一件事重复会造成信息权重失真。4.2 Gradle 项目被当成 Maven 项目处理构建命令识别失败Java 后端项目里还有一个非常经典的坑明明项目使用 Gradle Wrapper但仓库根目录可能残留了历史遗留的pom.xml或者某个文档里提到过 Maven。Codex 在扫描项目结构时只要发现pom.xml就很容易倾向使用mvn命令。有一次我让它实现一个新功能它生成的代码没问题但最后运行的是mvn test结果当然跑不起来。它还不自知反复尝试不同的 Maven 参数浪费了很长时间。教训就是规则文件里必须把“唯一构建入口”写死而且要放在技能文件的第一行。比如- 本项目只使用 Gradle Wrapper命令是 ./gradlew test禁止使用 mvn如果仓库里存在多个构建文件的痕迹还要再加上一句说明“不要被 pom.xml 干扰它是历史遗留文件”。这种对“干扰项”的明确排除能让 Codex 少走很多冤枉路。类似的干扰还有目录里同时存在多个测试框架的依赖规则里就要点名“本项目只用 JUnit 5不要生成 TestNG 代码”。4.3 技能文件越修越臃肿上下文窗口被无效信息塞满第三个坑是我自己造成的。superpowers 带来的效果太好我便不停往里加规则今天加一条“日志必须用 slf4j”明天加一条“DTO 不要直接暴露”后天又加一条“事务注解只能写在 Service 层”。一段时间后rules.md膨胀到两千多行。结果 Codex 的行为反而变差了它开始忽略部分规则或者只记得文件前面的内容后面的规则完全失效。原因是上下文窗口有限当规则文件太长时真正重要的信息被淹没了。我后来做了一次大清理把 files 拆成“硬规则”和“参考文档”两部分。硬规则压缩到一页纸以内只放绝不能违反的内容比如构建命令、测试命令、禁止提交的目录。其他的最佳实践、代码风格解释、案例说明全部挪到docs/目录下并在规则文件里写一句“如果需要了解异常处理风格参考 docs/code-style.md”。这样 Codex 不会一次性把所有文档读进去而是按需查找效果反而更好。我还养成了一个习惯每次给规则文件做修改都像改代码一样走 review。新增一条规则前先问自己如果 AI 不知道这条规则会产生多严重的后果如果后果不严重就不写如果后果严重一定要写而且要写在靠前的位置。5. 进阶自己写一套团队专属“superpowers”5.1 先给“坏例子”再给“好例子”让 AI 学会对比当团队准备把自己的开发规范沉淀成 superpowers 时最容易犯的错误是只写好例子。比如技能文件里放了一段标准的 Controller 代码AI 看了以后确实会模仿但它不一定知道自己“为什么不那么写”。我在调优过程中发现同时给出“坏例子”和“好例子”比只给好例子有效得多。因为在 Codex 这类模型的交互逻辑里对比能建立更强的约束。它看到坏例子长什么样就知道哪里是雷区。举个例子在 API 接口技能文件里我会写错误示例 - 直接在 Controller 里写业务逻辑 - 返回裸的 Map 结构 - 用 RuntimeException 表示业务错误 正确示例 - Controller 只做参数接收和响应包装 - Service 层抛自定义业务异常 - 全局异常处理器统一转换错误码这里不用长篇大论解释只要把两种形态放出来AI 就能更快地领会团队意图。这种写法还有一个好处团队里的新人也看得懂等于把代码评审意见沉淀成了文档。5.2 让脚本做裁判别让 AI 嘴上说“已经通过”有一类规则永远不要只写在 Markdown 里那就是“可被脚本验证的规则”。例如“所有新代码必须通过静态检查”“所有测试必须通过”这类规则如果只靠提示词AI 很有可能会生成一个看起来正确但实际没跑过的结论。我发现一个特别典型的现象当 Codex 被要求“运行测试”时如果测试数量很多它有时会只运行某一个测试类然后汇报为“全部通过”。它并不是故意欺骗而是上下文窗口里只保留了一部分结果或者它在模仿人类“抽样验证”的行为。可问题是工程上我们需要的是确定性。所以我的原则是凡是能脚本化的规则一律脚本化。团队技能包里应该有一个verify命令把所有必须通过的检查串联起来并且技能文件里明确写- 任务完成后必须运行 ./scripts/verify.sh - 如果脚本失败必须修改代码直到脚本通过 - 禁止在没有运行脚本的情况下声称完成任务脚本的输出是唯一可信的完成标志。一个好的 superpowers 设计就是要让 AI 的“我认为”让位于脚本的“它确定”。5.3 把技能包当产品迭代版本、回归和灰度很多团队把技能包建好后就丢在仓库里不管了这是不对的。技能包本质上是一份“活的文档”它需要持续迭代而且迭代方式应该接近产品节奏。我现在的做法是对技能包做版本管理。每次修改规则或新增技能都会在提交信息里写清楚变更原因比如“新增规则禁止使用 System.out.println”。如果团队用 Git技能包文件和其他代码走同样的评审流程。灰度也很重要。不要让一份全新的技能包一次性影响所有模块。我通常先在一个试点模块跑一两周观察 Codex 的输出质量有没有变化有没有出现之前没有的怪异行为。确认稳定之后再复制到其他模块。有一次我在一个模块里加了一条“所有 Controller 必须显式声明 produces 类型”的规则导致很多旧接口的测试都开始失败才发现规则不能只看新代码还要考虑存量代码的兼容性。还有一种做法是把技能包本身做成可回滚的独立分支。出现问题时直接切回上一个稳定版本避免阻塞开发流。别小看这个备份动作关键时刻能省不少事。最后分享一个小技巧我在实际使用中会把 superpowers 的变更记录和每周复盘放在一起过一遍。哪类任务让 Codex 做得更顺了哪类任务它还是频繁出错这些信息反过来决定我下一版规则文件改什么。它不是一劳永逸的配置而是需要持续维护的工程资产。