配过 Codex CLI 的人应该都有同感默认的 Codex 很聪明但不够“懂规矩”。你问它一句它答一句写代码还算利索可一旦涉及多文件改动、跨模块排查、按流程推进任务它就容易跑偏——要么上来就闷头写、要么把测试抛在脑后、要么做完不复查。这套叫 Superpowers 的技能包配置解决的就是这个问题它通过一整套结构化的技能文件系统把 Codex CLI 从“随问随答的助手”改造成“按专家工作法推进任务的协作搭档”。我现在日常开发基本离不开这套配置这篇文章就把我踩过的坑、试出来的方案、以及每个技能的实际价值完整讲清楚适合正在用 Codex 但觉得差点意思的人也适合刚入坑命令行 AI 编程想一步到位的人。1. 先搞懂 Superpowers 到底改了什么不是 prompt是“技能文件系统”很多人第一次看到 Superpowers 会下意识觉得“不就是一段人设 prompt 吗”。我第一次也这么想直到把仓库拉下来才发现完全不是一回事。1.1 裸 Codex CLI 的四个典型毛病先说默认 Codex 的表现这样你对 Superpowers 的价值才有体感。我连着用了几个星期总结出四个最困扰我的问题第一行为不稳定。同一个问题换一天、换一次会话Codex 的处理方式可能完全不同。今天它知道先写测试明天它可能直接改实现今天它会做全量回归明天它只改了局部就跑。第二缺少流程感。让它“实现一个用户故事”它通常不会主动拆解成“阅读上下文 → 设计 → 写测试 → 实现 → 重构 → 复查”这样的节奏而是直接给出一坨代码。第三上下文利用低效。面对一个陌生代码库它每轮都在重新扫描文件既费 token 又容易遗漏关键模块接到任务就开始猜。第四边界感模糊。该不该动某个文件、该不该改数据库脚本、该不该顺手重构无关代码这些“该不该”的判断裸 Codex 几乎没有全靠你人在后面盯。Superpowers 就是冲着这四点去的。它的做法不是往系统提示词里塞更多“你要当一个好工程师”这种空话而是把“好工程师”的工作方法拆成一个一个具体的技能包每个技能包都是一个独立目录里面装着行为规范、参考文档、脚本工具。1.2 技能包的标准结构SKILL.md references scripts打开 Superpowers 的 skills 目录你会发现每个技能的结构基本是统一的skills/ tdd-with-superpowers/ SKILL.md references/ tdd-workflow.md scripts/ run-tests.sh codebase-mapping/ SKILL.md references/ mapping-examples.md scripts/ generate-map.sh核心是那个 SKILL.md 文件它用 YAML 头部声明技能的名称和适用场景正文则是一套完整的“行为契约”。Model 每次加载这个文件就等于拿到了一份针对特定任务的执行手册什么时候该用这个技能、先做什么、再做什么、中间必须遵守哪些规则、结尾必须输出什么。加粗强调一下这个设计和普通 prompt 的本质区别prompt 是给模型看的“建议”技能文件是给模型读的“规程”——前者显得越短越好后者显得越结构化越好。发生冲突时技能文件里明确写着的步骤往往能覆盖模型惯有的自由发挥。1.3 为什么叫 Superpowers给 AI 装“超能力”的真相是约束Superpowers 的核心理念挺反直觉的AI 的超能力不是来自“放开”而是来自“约束”。就像你不会让一个资深工程师“随便写”而是给他一套团队约定、一份代码规范、一个流程模板AI 更需要这种外部约束来对冲它的“讨好倾向”——你让它干什么它就容易干什么哪怕那个做法在工程上是错的。技能文件里的约束分成几类流程类约束规定了任务从启动到结束的必经阶段比如 TDD 必须红灯-绿灯-重构。边界类约束明确告诉模型“这一步不要做什么”比如重构阶段不许新增功能。输出类约束规定了每个阶段结束时要交付什么比如先输出影响分析再动手。验证类约束要求每一步有可检查的证据比如测试结果、命令输出。这些约束组合在一起相当于给模型的工作过程装了轨道。它确实牺牲了一点“自由发挥度”但换来的是可预测、可管控、可复用——这才是工程场景真正需要的“超能力”。2. 安装与启动从拉仓库到让 Codex 认技能一条龙讲透安装这块我踩了不少坑。网上很多教程只说“clone 下来放进去”但具体放哪个目录、配置怎么写在哪个文件、怎么验证生效语焉不详。这节我把完整流程和每个操作背后的原因一次性说清楚。2.1 前置条件版本与依赖先确认你的环境。我目前的配置是这样的Codex CLI 版本0.44 及以上我实测 0.46 和 0.48 都正常。版本不同启动参数略有差异旧版本没有 skills 参数的话建议先升级。Node.js 版本18Codex CLI 本身是 npm 包太老的 Node 会装不上。项目要求需要 Git 仓库因为技能里有不少脚本依赖 Git 状态来生成映射和执行检查。安装命令没什么新鲜的npm install -g openai/codex codex --version装完先跑一次正常对话确认 API 配置没问题再继续下一步。有个小经验如果你用的是企业代理或者自定义 API 端点先确认codex能连上再说别急着集成技能不然后面排查时你会分不清是网络问题还是技能配置问题。2.2 拉取技能包并放到正确目录Superpowers 仓库在 GitHub 上直接把整个仓库 clone 下来git clone https://github.com/obra/superpowers.git ~/superpowers关键点来了不要把整个仓库原封不动扔进项目里你只需要它的 skills 目录。Codex CLI 默认会从两个位置加载技能一个是全局的~/.codex/skills一个是项目根目录下的.codex/skills或者skills目录。我的做法是mkdir -p ~/.codex/skills cp -r ~/superpowers/skills/* ~/.codex/skills/放在全局的好处是你名下所有项目都能用同一套技能不用每个仓库翻录一遍。不过要注意如果你在多个项目间切换并且不同项目对技能的需求差异很大全局加载会带来上下文浪费——Codex 每次会话都要扫描一遍技能索引技能太多会吃掉不少上下文窗口。我的建议是全局只留五六个高频技能项目专属技能放到项目目录里。2.3 写 AGENTS.md让 Codex 学会“先读技能索引再干活”光把技能文件放对位置Codex 不一定知道怎么用。你需要通过 AGENTS.md 告诉它两件事项目或环境存在技能目录每次会话开始先读技能索引skills/skills.md根据任务选择合适的技能然后严格按技能文件的指令执行。这可能是整个配置流程里最容易被忽略的一步。很多人以为技能文件放进去就自动生效结果跟 Codex 聊了半天它压根没读技能最后得出“Superpowers 没用”的结论。实际上Codex 加载技能更像“按需取用”而不是“全量灌注”。你需要在 AGENTS.md 里写清楚触发机制。我项目里的 AGENTS.md 精简后是这样的# AGENTS.md 你拥有 Superpowers 技能系统。启动后必须执行以下步骤 1. 读取 skills/skills.md查看全部可用技能。 2. 根据用户任务选择最匹配的一个或多个技能。 3. 输出你选中的技能 ID 和理由一行即可。 4. 严格遵循所选技能文件中的步骤执行不得跳过阶段。这段指令的核心目的是建立“元认知”让模型先意识到自己有工具再决定用什么工具。我第一次实测时发现加不加这段话Codex 读取技能索引的概率差异极大——不加它只有不到三成概率主动看技能文件加了基本每次都看。2.4 验证安装用“技能自检”确认一切生效配置完成后别急着干正经活先做一次快速验证。我习惯在项目根目录跑一个简单对话请读取技能索引列出你这个环境可用的技能并告诉我当前这个项目最应该启用哪些技能。如果配置成功Codex 会输出一个技能清单并且给你推荐 2 到 3 个适合当前项目的技能。如果它说“我没有找到技能目录”或者直接忽略清单那就按下面的顺序排查先看codex --help里技能相关参数的实际名字不同版本可能有--skills、-s等差异检查技能目录路径是否在 Codex 的默认搜索范围里比如全局的~/.codex/skills确认 AGENTS.md 被读取了没有——可以在 AGENTS.md 里加一句“读取后回复 READY”如果它没回复就说明文件路径不对。我在升级 Codex 后遇到过几次 AGENTS.md 失效的情况原因是新版改了配置文件优先级。我的排查方法是在项目里跑codex --info之类的诊断命令不同版本命令不同看它实际加载的配置文件路径然后把 AGENTS.md 放到被加载的那一份里。2.5 Java 项目的特殊配置热词里出现了 “superpowers java”这里多说几句。Java 项目使用这套技能包有个天然优势结构规整、构建工具统一Maven/Gradle、测试框架成熟JUnit/TestNG非常契合 TDD 技能和 codebase-mapping 技能的用武之地。但有三个 Java 特有的配置点需要注意构建命令的注入。技能包里的脚本默认调用的可能是npm test这类命令对 Java 项目不适用。我的做法是在项目 AGENTS.md 里显式声明## 构建与测试命令 - 构建: mvn clean compile - 测试: mvn test - 单个测试文件: mvn test -DtestClassName没有这句技能里的验证阶段会跑错命令然后 Codex 可能一顿乱猜。测试超时问题。Java 项目首次跑测试经常因为下载依赖超时技能里 TDD 工作流的“验证红灯”阶段会卡住。我会在 AGENTS.md 里加上“如果 Maven 依赖下载失败先执行 mvn dependency:resolve 再重试”。多模块工程的映射。如果项目是 Maven 多模块codebase-mapping 技能生成目录树时可能只看到顶层结构。建议在映射前先让 Codex 读取根的pom.xml把模块依赖关系补充进映射文档。这个能极大提升后续任务的质量。3. 核心技能逐个拆解每个技能背后的设计逻辑Superpowers 仓库里的技能不少但真正高频使用的就那几个。这节我按实战频率排序把每个技能的设计逻辑、适用场景、以及我用下来的真实感受都讲一遍方便你决定先装哪些。3.1 Codebase Mapping让 AI 先认路再干活这个技能是我所有项目里的必装项也是“superpowers 使用指南”类文章里被反复提到的一个原因很简单它解决了 AI 在陌生代码库里“盲人摸象”的问题。它的工作流程大致如下扫描项目根目录生成目录树和模块职责清单识别关键入口点、配置文件、数据库脚本、构建文件标注模块之间的依赖关系把结果写成一个codebase-map.md存到项目里后续所有任务基于这张地图展开。为啥这个设计重要因为 Codex 的上下文窗口有限你不可能让它每次对话都把整个项目读完。地图相当于一个“低成本索引”让 AI 进入项目时只读一两个文件就能建立起全局认知然后按图索骥去查具体代码。我举个实际例子。有次我让 Codex 给一个旧 Spring Boot 项目加一个分页查询接口。没配技能时它直接开始改 Controller甚至连 Service 层有哪些现成方法都没看配了 codebase-mapping 之后它先花两分钟生成地图然后告诉我“这个项目的查询逻辑集中在 ProductQueryService建议在 Controller 层新增端点并复用现有查询方法”。后者明显靠谱得多。使用建议每当你换一个新项目第一件事就是跑一次这个技能。生成的codebase-map.md建议提交到 Git以后其他协作者或 AI 工具都能受益。3.2 TDD With Superpowers红灯-绿灯-重构的硬约束TDD 技能是整个 Superpowers 体系里约束最强的一个也是我“真香”感受最明显的一个。它把测试驱动开发拆成了严格的三阶段红灯阶段先写一个失败的测试说明需求的“预期行为”绿灯阶段写最少的实现代码让测试通过重构阶段在测试保护下清理代码结构不新增功能。单独看这段流程你可能觉得“这也没什么”但关键是技能文件里对每个阶段都有极细的行为约束。比如红灯阶段技能明确要求“不要写任何实现代码确保测试因功能缺失而失败”绿灯阶段要求“不要做重构只求最快通过”重构阶段要求“跑全量测试确认没有回归”。为什么这很重要因为默认的 Codex 根本没有这种耐心。你让它 TDD它往往会“跳步”——先写实现再补个测试糊弄你。技能文件的价值就是强制它按节奏走并且允许你在对话里随时打断纠正它“你现在在哪个阶段如果还在红灯阶段请不要开始写实现。”我在 Java 项目里实测这个技能配合 JUnit 5 效果很好。Codex 能自动生成测试类、执行mvn test、根据失败信息定位代码、再迭代修改。整套下来像一个谨慎的结对程序员而不是一个赶稿子的实习生。一个小坑技能里的脚本默认可能没有针对 Maven 的命令需要配合我在 2.5 节提到的构建命令注入来使用。另外建议在 AGENTS.md 里补充“测试通过后输出测试结果摘要”不然 Codex 每次都是一句含糊的“测试通过了”你根本不知道它跑的是哪个测试。3.3 Code Review Security Review把关用的不是感觉是清单Code Review 这个技能被很多人低估但我认为它反而是最能体现 Superpowers“工程化思路”的设计。它把代码审查从“AI 看你代码顺不顺眼”变成了“按清单逐项核查”。技能文件里内置了一套审查清单大致覆盖正确性逻辑是否覆盖边界条件异常路径是否处理并发安全共享状态、锁、线程安全性能无意义的重复计算、N1 查询等错误处理错误码、日志、用户提示是否得当可测试性代码是否方便写单测安全注入、越权、敏感信息泄露等。每个检查项都配有标准的问法和报告格式。审查结束时它会按严重程度输出问题清单并给出修改建议。我用这个技能定期审查自己的 PR抓出过好几个“看着没问题但边界条件会炸”的 bug。Security Review 则更聚焦安全问题。它不只查 SQL 注入和 XSS 这类经典漏洞还会看依赖版本、配置文件暴露的密钥、权限校验缺失等实际工程问题。Java 项目里尤其好用因为 Spring 生态的权限配置经常出错靠人眼审查容易遗漏。3.4 Sprint Planning把“一句话需求”变“可执行任务”这个技能适合稍微偏管理一点的场景。它的输入通常是一个比较模糊的诉求——比如“用户希望能在订单列表里看到预估送达时间”——然后技能会引导 Codex 生成用户故事和验收标准涉及的功能点与技术模块实施顺序和依赖关系每个任务的完成定义DoD。为什么这个有价值因为 AI 编程最大的瓶颈之一就是“需求不清”。你让 Codex 直接写代码它只能基于猜测写你让它先规划再动手它的产出质量会有质的提升。Sprint Planning 技能本质上是在 AI 和需求之间加了一层“翻译”。不过要提醒的是这个技能的产出质量比较依赖你对需求的描述质量。描述越具体、约束越多生成的计划越靠谱。我建议使用的时候先手动把关键业务规则写清楚比如“库存为 0 时不能下单”“优惠券和满减不能叠加”再去让技能展开效果会好很多。3.5 Debugging 与 Troubleshooting从“瞎猜”到“定位”调试类技能可能是最容易被忽略但实际最省心的。它的核心逻辑是规范排查流程复现要求先稳定复现 bug而不是对着报错信息猜信息收集收集日志、堆栈、输入输出、环境信息范围缩小通过二分排除法定位到具体模块假设验证对可能的根因逐一验证修复与回归修改后跑相关测试确认没引入新问题。我印象最深的一次是排查一个偶发性的空指针异常。之前我直接让 Codex 看堆栈它给了一堆“可能原因”的猜测。配了 Debugging 技能后它先要复现步骤然后主动提出在关键方法里加日志、用条件断点缩小范围最后定位到一个第三方库在空集合时返回 null 的兼容性问题。这种“按证据链推进”的体验和默认的“疯狂猜答案”完全是两个级别。3.6 写作与文档技能不写代码时也能用Superpowers 里还有一组写作类技能比如把对话记录整理成博客、生成周报、撰写 PRD 等。这类技能的设计思路是把“写作套路”编码成文件先定读者、再定结构、后补细节、最后润色。我用得比较多的是梳理技术方案文档。给 Codex 一段零散的讨论记录它能按技能要求输出“背景-方案对比-选型理由-风险-实施步骤”结构化的文档。虽然这个功能算不上核心卖点但配合 Codex CLI 在终端里使用确实省了不少写文档的时间。4. 实操场景实录用一个 Java 需求把整套流程串起来说再多原理不如看一次完整实操。我挑一个比较有代表性的 Java 任务——给一个订单服务加一个“按用户查历史订单”的分页接口——走一遍配置了 Superpowers 之后 Codex 的实际表现。4.1 场景设定与触发项目是一个标准的 Spring Boot Maven 多模块工程已有用户模块和订单模块订单表数据量不小。我的需求描述在终端里发给 Codex给订单服务新增一个接口GET /api/users/{userId}/orders分页返回该用户的历史订单 排序规则为下单时间倒序。参数含 page、size默认值分别是 0 和 20。 要求接口校验 userId 必须存在订单数据不得泄露他人订单。配了 Superpowers 之后Codex 的回复明显不一样了。它先读取技能索引输出选定的技能将使用以下技能 - codebase-mapping: 定位订单模块相关代码 - sprint-implement-step-by-step: 按计划逐步实现 - tdd-with-superpowers: 以测试驱动方式完成开发这个“报技能 ID”的行为就是 AGENTS.md 里要求的效果。它强制 AI 在动手前先想清楚“我要用什么方法来干这个活”而不是条件反射式地开始写第一行代码。4.2 Codebase Mapping 阶段花两分钟认门Codex 先扫描项目结构生成了订单模块的地图。这个阶段我没看到它写任何业务代码而是在梳理以下信息Controller 层的 RequestMapping 前缀和现有的订单接口风格Service 层是否已有分页查询的通用方法Repository 层用的什么框架JPA 还是 MyBatis现有的异常处理机制比如用户不存在抛什么异常。输出是一份结构化的地图文档关键信息包括订单模块映射结果 - 入口: OrderController (/api/orders) - 服务: OrderQueryService (包含 findByUserId) - 持久层: OrderRepository (Spring Data JPA) - 异常约定: UserNotFoundException → 404 - 已有分页工具: Pageable, PageRequest说实话这个地图帮我理清了项目结构即使没有后续的 AI 开发光看这份映射也值回票价。项目落到新同事手里一份地图能省掉大量提问时间。4.3 TDD 阶段红灯、绿灯、重构它真的按章执行了进入 TDD 技能后Codex 没有直接写实现而是先创建了一个测试类。我特意盯着看它是不是“做个样子”。结果它的测试写得有模有样Test void findOrdersByUser_shouldReturnPageableResult() { User user userRepository.save(new User(Alice)); orderRepository.save(new Order(user, ORD-001)); orderRepository.save(new Order(user, ORD-002)); PageOrder result orderQueryService.findOrdersByUserId(user.getId(), PageRequest.of(0, 20)); assertThat(result.getTotalElements()).isEqualTo(2); }写完测试后它主动执行了mvn test -DtestOrderQueryServiceTest屏幕打印 BUILD FAILURE。这个阶段它没有继续写代码而是输出了一段“红灯确认”红灯阶段完成测试因 findOrdersByUserId 方法缺失而失败与预期一致。然后进入绿灯阶段它才补上 Service 方法和 Repository 查询。再次跑测试BUILD SUCCESS。整个过程的节奏非常清楚不像默认 Codex 那样“写实现和写测试混在一起”。最后是重构阶段它检查了代码是否有重复结构顺手把新接口的分页参数校验抽到了统一的PageRequestUtils工具类。这些都是“安全重构”没有新增功能。4.4 代码审查阶段自查时抓到一个真实 Bug实现完成后我让它走一遍 Code Review 技能。这个阶段它对照清单审查新增代码结果抓到一个我自己都忽略的问题发现潜在问题 - OrderRepository 的 findByUserId 未加排序参数接口要求按时间倒序 当前测试覆盖的是分页但未验证排序。 - 建议补充排序字段的测试用例或在 Repository 方法中显式指定排序。这确实是疏漏。测试里只验证了返回数量和分页结构没有断言排序顺序。Codex 主动指出这一点让我对这套技能组合的信任度一下子拉高了。4.5 对全过程的行为观察走完整个流程我的一个强烈感受是Codex 的“工作人格”确实被技能系统重塑了。它不再是一个“问一句答一句”的工具而是一个“先看全局、再按计划推进、自己有质量关卡”的协作者。特别是以下行为变化我认为是配置成功的信号动手前先上报技能 ID 和理由每个阶段结束后明确输出阶段结论测试失败和测试成功都有明确的可见证据不自作主张跳过或颠倒流程阶段。这些行为不是靠模型“自己想出来的”而是靠技能文件约束出来的。一旦你看到这些信号说明 Superpowers 配置真的生效了。5. 常见问题与排查技巧我踩过的坑全记录配置和使用 Superpowers 的过程中几乎每个环节都有坑。这节我把常见问题、症状、排查思路和解决方案整理成一张速查表都是我实际遇到过并在别人机器上复现过的。症状可能原因排查与解决Codex 完全无视技能索引AGENTS.md 没被读取或路径不对确认配置文件实际路径必要时用codex --info诊断技能索引读了但 Codex 不执行技能步骤技能描述与实际任务匹配度低检查技能 SKILL.md 的 YAML 描述是否覆盖了你的任务类型上下文很快用爆全局技能包太多每次扫描全量索引精简技能目录只保留高频技能技能里的命令跑的是 npm 而不是 mvnJava 项目未注入构建命令在 AGENTS.md 中显式声明构建测试命令TDD 流程被跳过AGENTS.md 要求不够硬确认是否明确写“不得跳过阶段”一类强约束表达多技能同时触发导致行为混乱技能间职责重叠在 AGENTS.md 中指定优先级冲突时以哪份技能为准项目技能与全局技能不兼容两份 AGENTS.md 指令冲突合并规则全局写通用行为项目写专属约束下面挑几个重点问题展开讲。5.1 技能文件加载不出来先查路径再查版本这是新手遇到最多的一个问题。症状是你跟 Codex 说“读取技能索引”它回复“我这边没看到技能目录”。大概率不是技能文件有问题而是 Codex 根本没去那个目录找。我的排查顺序是第一看 Codex 当前工作目录在哪技能目录是不是被放到了别的项目里第二确认技能目录的放法是否符合你所用版本的预期路径新旧版本差异很大第三检查文件夹里有没有 SKILL.md以及 YAML 头部的 name 和 description 字段。Codex 是靠描述来判断技能何时被启用的如果 description 写得过于模糊它可能“看不到”这个技能第四用最简单的方式验证在项目根目录跑一次 codex直接问“你自动加载了几个技能文件路径分别是什么”。之所以强调版本差异是因为 Codex CLI 更新很勤快不同版本对技能目录的扫描机制不完全一样。我升过一次大版本后相同的配置就出现了一次“读了索引但技能不生效”的诡异现象后来发现是新版要求 SKILL.md 的 YAML 头部必须带 version 字段。这类问题基本靠codex --help和--info就能定位。5.2 技能被 AI“无视”大概率是描述匹配问题有时候 Codex 明确读了技能索引但实际执行时还是我行我素。我观察下来最核心的原因是技能文件里的 description 和用户的任务描述没有触发匹配。Codex 加载技能是“按需的”如果它的语义匹配机制没认定当前任务需要这个技能它就不会主动调用技能里面的行为约束。解法有两个第一个解法是在 AGENTS.md 里把“匹配逻辑”写到指令层面明确写着“对于实现新功能类任务必须使用 tdd-with-superpowers对于已有代码改动必须使用 code-review”这类条件规则。这样就不依赖模型自由判断了。第二个解法是会话中人工干预。一旦发现 Codex 没有按技能走直接指出“你应该使用技能 X请读取 SKILL.md 并严格遵循”。实测下来这种“纠偏”通常一次就能生效前提是技能文件本身存在。5.3 上下文和成本失控精简技能集是唯一的解药Superpowers 的技能全量加载是很占上下文的。我刚开始把整个仓库的技能目录全部拷到了全局结果 Codex 每次会话光扫描技能索引就消耗不少 token后面干正经活的时候上下文窗口经常告急。被教育过几次后我的做法是全局技能目录只保留 5 个左右的高频技能——codebase-mapping、tdd-with-superpowers、code-review、debugging、sprint-planning。项目专属技能放项目目录比如某个项目用的 Spring 状态机就把状态机调试技能放项目里。这样既保证功能覆盖又把上下文开销压到最低。另外一个技巧技能索引文件skills.md尽量保持精简每个技能一行包含名称和一句话描述。不要让索引本身变成一份冗长文档。5.4 与团队已有 AGENTS.md 冲突的合并策略如果你所在的项目已经有团队维护的 AGENTS.md直接往里面追加 Superpowers 相关指令可能导致冲突。最典型的冲突是团队 AGENTS.md 说“所有 Java 代码必须通过 SpotBugs 检查”而你技能文件里的重构阶段可能要求做一些不经静态检查的中间改动。我的合并策略是分层团队 AGENTS.md 放在项目根目录作为“最高行为准则”Superpowers 的启动指令作为“工作流引擎”挂在下面。具体写法是在团队 AGENTS.md 后面追加一个章节## AI 工作流配置 本环境配置了技能系统。请读取 skills/skills.md遵循技能流程完成编码任务。 如果技能步骤与上文项目规范冲突以上文项目规范为准同时报告冲突点。这个策略既保留了团队规范又让技能流程能跑起来并且把冲突显式化让人来判断。用下来很稳推荐照抄。5.5 Java 项目里最容易踩的三个隐藏坑前面提过的构建命令注入和测试超时之外Java 生态还有三个隐藏坑我把它们单独列出来Lombok 的问题。技能包里的 codebase-mapping 扫描依赖关系时如果项目大量使用 Lombok会看到很多“幽灵字段”生成的映射里 getter/setter 会被误判为不存在的属性。我建议在 codebase-mapping 的脚本里加上对Data、Getter等注解的识别规则或者在 AGENTS.md 里提示 Codex“字段可能来自 Lombok 生成以注解为准”。Maven 多模块间的依赖顺序。Codex 的 TDD 阶段跑测试时如果涉及模块间依赖而未先在父模块 install会报找不到依赖。我的 AGENTS.md 里总是加这一句多模块测试前先执行 mvn install -DskipTests -pl 模块名 -am。测试基类里的 Spring Boot 上下文启动耗时。Java 项目的单元测试和集成测试经常混在一起Codex 全量跑mvn test时可能因为某个集成测试拉起完整 Spring 上下文导致 TDD 回路极慢。我在配置里加了规则“日常开发优先跑单个测试类避免全量集成测试”。6. 一些实在话Superpowers 的边界、维护成本与个人建议到这里该讲的实操都讲完了最后说一点没那么“技术”但同样重要的话。Superpowers 确实强大但它不是魔法搞清楚它的边界你才不会对它抱有不切实际的期待。6.1 它改变的是行为不是智商Superpowers 改变的是 Codex 的工作方式不改变模型的推理能力。如果模型本身对一个业务领域理解不足技能包无法替你补足那个领域知识。换句话说技能包解决“怎么干”不解决“懂不懂”。所以该补的业务知识、该看的文档、该维护的项目上下文一样都不能省。我在 Java 项目里对技能包寄予厚望但真正让 Codex 发挥价值的还是我把项目的核心业务规则写进了 AGENTS.md。另外要留意的是技能文件不是越严越好。约束过强会导致模型在某些场景下“僵化”比如遇到明显的紧急修复仍要按 TDD 走完整流程效率反而低。我的做法是给紧急修复单独写一个“hotfix”技能步骤更短、验证门槛更低。6.2 技能包本身需要维护很多人配置完 Superpowers 就当甩手掌柜这是不对的。技能包和代码一样需要演进项目结构变化了codebase-map.md 会过期团队规范更新了AGENTS.md 要同步Codex 版本升级了某些技能文件的写法可能失效。我大概每两个月会专门抽出一个小时过一遍技能目录清理不用的、更新过时的、补写新场景的。维护技能文件的门槛其实比想象中低——它本质就是 markdown。你完全可以把自己“折腾出来的经验”沉淀成新的技能文件比如针对你们公司特有框架的开发流程写一个company-framework-skill。用久了之后整个技能目录就是你个人工作方法论的资产库换项目、换工具都能带走。这才是 Superpowers 最有价值的地方它不是别人给你的一堆现成配置而是一套让你持续积累和沉淀的工作流框架。6.3 给不同人群的配置建议如果你是新手我的建议是先配置四个技能就够codebase-mapping、tdd-with-superpowers、code-review、debugging。别一口气全上技能多了反而是负担。先跑通一轮“映射-开发-审查”的最小循环感受行为变化再逐步扩展。如果你已经是深度用户可以把精力放在自定义技能上。最值得写的技能往往是那些频繁发生的、有固定步骤的、但又没有现成模板的任务——比如你们团队的发布检查流程、数据库迁移签字流程、跨模块联调排查流程。把这些写成技能等于把你的团队经验复制给了每一个 AI 会话。我在实际使用中最满意的一点是这套配置让我对 Codex 的输出越来越放心。以前每段代码都要肉眼全量 review现在我会更关注它标记出来的风险点把精力放在决策上而非低水平重复校对。这种“人和工具各司其职”的感觉大概就是工具价值最好的体现。最后再分享一个小技巧花时间读一下你自己常用技能的 SKILL.md 原文它不仅是给 AI 读的也是给你读的——里面包含了很多你平时没注意过、但确实有效的工作方法。用好一套技能系统首先是从理解它开始的。
