如果你用过 Codex CLI大概率遇到过这种情况它很聪明但总带着一股一次性做题的味道——说改哪就改哪不问你上下文也不在乎代码风格更不会主动补测试。我最初在项目里引入 superpowers 这套方案就是冲着解决这个痛点去的。superpowers 本质上是一套给 Codex CLI 定制的技能包集合把测试驱动开发、错误追踪、记忆管理等 AI 编码时该有的方法论全部写成 Markdown 格式的技能文档让 Codex 从会聊天的代码生成器变成懂工程协作的结对程序员。这篇文章我会从安装、配置、核心技能实操到常见坑位排查完整走一遍我的落地过程适合已经开始用 Codex CLI、但对工程化协作还不满意的开发者参考。1. superpowers到底是什么一套给Codex CLI的技能外挂1.1 为什么需要技能包裸Codex和强化Codex的差距裸装的 Codex CLI 你直接用会发现几个很典型的毛病。第一它缺乏上下文记忆同一个项目里上午刚确认过命名规范下午它可能又按自己的习惯来第二它不爱写测试你让它实现一个函数它往往直接甩出实现代码根本不考虑边界条件和回归验证第三遇到报错时它倾向于再试一次而不是先定位根因同一个坑能踩三次。superpowers 这个开源项目给了另一个思路与其每次对话都临时教育 AI不如把做过的事情、踩过的坑、团队沉淀的规范全部固化成可复用的技能文档。Codex CLI 启动时会通过 AGENTS.md 文件知道这些技能的存在遇到对应场景就自动调用就像游戏里的角色突然学会了技能书——这就是 superpowers 这个名字的由来。这个项目是社区开发者 obra 发起的核心仓库就在 GitHub 上目前已经有相当多人在用。它的设计哲学很朴素AI 编码的最大瓶颈不是模型能力而是缺少一套稳定的工作协议。superpowers 就是那套协议的具体实现。1.2 核心设计markdown驱动的可扩展技能体系superpowers 没有引入任何新的编程语言或框架它的全部逻辑都写在 Markdown 文件里。每个技能文件就是一个操作手册包含名称、描述、适用场景、具体执行步骤AI 读到这份文档后会严格按照里面的步骤去执行。这种设计有几个好处。一是极低的学习成本任何能写 Markdown 的人都能给 AI 定义新技能二是极强的可读性技能文档可以直接走 Code Review团队里所有人都能看到 AI 被要求做什么三是天然支持版本管理技能和代码放在同一个仓库里迭代记录清清楚楚。整个体系里有几个关键角色。首先是 AGENTS.md它相当于技能目录告诉 Codex CLI 有哪些技能可用、分别放在哪里其次是 skills 目录里面存放具体技能比如 test-driven-development.md、root-cause-tracing.md还有 memory 机制让 Codex 能把关键决定写回持久化文件跨会话记住用户的偏好和项目约定。trajectory 机制则专门用来记录错误处理轨迹下次遇到相似问题时可以快速回溯。2. 安装与初始配置二十分钟跑通基础环境2.1 环境准备Codex CLI版本与Node.js安装 superpowers 之前你要确认 Codex CLI 本身是可用的。Codex CLI 是 OpenAI 官方的终端编码代理整体依赖 Node.js 运行时所以第一件事是检查这两个东西的版本。node --version codex --version我自己用的 Node.js 是 20.xCodex CLI 保持在最新版。如果你的 Codex 版本过低尤其是 0.2 之前的版本技能加载机制可能不完整表现就是 AGENTS.md 读了但 slash command 不生效。建议先把 Codex CLI 更新到最新npm install -g openai/codexlatest另外Codex CLI 会读取你的 API 凭证你可以在终端里先跑一次codex随便聊两句确认基本对话、文件读取、命令执行都正常再往下走。这一步不是为了装 superpowers而是为了排查基础链路是否通畅。注意如果你是在公司内网环境使用还要确认终端能正常访问对应 API 服务。这一步不通过后面所有技能加载都无从谈起。2.2 安装superpowers克隆、复制、注册三步走superpowers 的安装方式很传统克隆仓库把技能文件复制到 Codex 能找到的目录然后在 AGENTS.md 里注册。三步走完整命令如下# 1. 克隆 superpowers 仓库 git clone https://github.com/obra/superpowers.git ~/superpowers # 2. 创建 Codex 全局技能目录 mkdir -p ~/.codex/skills # 3. 复制技能文件到全局技能目录 cp -R ~/superpowers/lib/skills/* ~/.codex/skills/ # 4. 把 superpowers 的主文档复制成 AGENTS.md cp ~/superpowers/lib/superpowers.md ~/.codex/AGENTS.md我建议先做全局安装也就是把技能放到~/.codex/skills下这样你所有项目都能用到这些技能。如果你只想在某个特定项目里启用 superpowers也可以把 skills 目录复制到项目的.codex/skills下并在项目根目录放一份 AGENTS.mdCodex CLI 会优先读取项目级配置。复制完之后你可以打开~/.codex/AGENTS.md看一眼里面应该有一份完整的技能清单类似当用户请求实现 xxx 时使用 test-driven-development 技能这样的索引内容。这份文件决定了 Codex 在什么时候调用哪个技能。2.3 权限配置读skill、执行命令、memory写回Codex CLI 在执行操作前会向你请求权限superpowers 依赖三类核心权限。第一类是读取技能目录Codex 需要能访问~/.codex/skills/**才能读到技能文件第二类是执行终端命令因为很多技能比如跑测试、查 git 状态需要调用 shell第三类是写回 memory 文件Codex 在会话中确认了某些用户偏好后需要把结论写入记忆文件。在你第一次使用 superpowers 时Codex 大概率会弹权限确认请求你按需 Allow 即可。如果嫌手动确认太频繁可以在 Codex 配置里添加规则例如允许它读取 skills 目录、允许执行特定命令。我的建议是Read 和 Write 可以给执行命令的权限要克制只想让它跑测试和 git 操作而不是随意装包、改全局配置。配置完权限后建议开一个新会话测试一下。直接告诉 Codex使用 TDD 技能实现一个简单的函数。如果它开始先写测试代码说明技能加载成功如果它根本没有反应那就检查上一步的文件路径和 AGENTS.md 内容。3. 核心技能实操Java项目改造实战3.1 用TDD技能做需求拆解技能包的效果不能光靠看文档得真实跑一个项目才看得出来。我拿一个 Java 后端项目举例需求很简单给订单状态增加已取消这个枚举值并补充对应的状态流转校验。如果不用 superpowersCodex 大概率直接改枚举类、加 if 判断、完事。但用了 TDD 技能之后它遵循的技能文档会要求它走完整循环先写失败测试再写最小实现最后重构。实际对话中我只需要说一句订单状态需要增加 CANCELED走 TDDCodex 就会自己完成下面这些步骤阅读现有订单状态相关的测试文件了解覆盖率在测试类里补充CANCELED的状态流转用例运行测试确认新用例失败修改枚举类和流转校验逻辑让测试通过运行完整测试套件确认没有破坏其他用例。这个过程中最有价值的不是它能写代码而是它把工程流程走了一遍。我给的命令很少但技能文档帮它补齐了方法论层面的指导。这就是技能包和普通 prompt 的本质区别普通 prompt 是一次性指令技能文档是稳定的流程模板。3.2 让Codex自己开分支提交代码写完只是第一步提交规范是另一个工程痛点。很多人让 AI 写代码最后还得自己手动处理分支、提交信息体验很割裂。superpowers 的 git 相关技能解决的就是这个问题。在项目中启用 git 技能后Codex 会主动遵守仓库的提交规范。我实际让它操作时它会先检查当前分支状态然后根据变更内容创建 feature 分支再多次跑测试最后生成符合 Conventional Commits 格式的提交信息例如git checkout -b feature/order-status-canceled git add src/main/java/com/example/order/OrderStatus.java git add src/test/java/com/example/order/OrderStatusTest.java git commit -m feat(order): add CANCELED status and transition validation你需要提前在技能配置里告诉它团队的提交规范是什么比如type 必须包含 feat/fix/refactor/docs/test否则它生成的提交信息可能不符合要求。这一点建议在 AGENTS.md 或项目文档里写得越具体越好。注意让 Codex 自己推远程分支是可以的但我不建议让它直接推 main 分支。团队分支保护规则要提前配好否则 AI 一兴奋直接推到主干Code Review 还没开始代码已经上线了。3.3 错误定位的记忆轨迹双保险实际编码中Codex 经常会遇到测试失败。没有技能引导时它会反复猜测浪费大量 token。superpowers 里的错误追踪技能把这个过程结构化了许多记录错误发生时的完整日志与堆栈分析失败可能的原因并列出候选修复方案按照最小改动原则逐项尝试修复后把结论写入 trajectory 或 memory 文件。我遇到的一次典型场景是Java 项目在加枚举后某个序列化测试一直失败。Codex 起初尝试改 Jackson 注解失败后我让它调用 root-cause-tracing 技能它重新读日志发现失败原因其实是测试数据里有一处硬编码字符串没有同步更新而不是注解问题。修正测试数据后测试全部通过。这个过程中最有用的其实是 memory 和 trajectory 的沉淀。Codex 会把该模块的测试数据里存在硬编码订单状态写入 memory 文档下次再改这个模块时它会主动检查相关测试数据避免重蹈覆辙。4. 深入理解superpowers的文件结构和扩展方法4.1 skills目录到底藏了什么你安装完 superpowers 之后可以打开~/.codex/skills/目录看看里面是一堆 Markdown 文件。每个文件就是一个技能命名规律非常清晰比如test-driven-development.md测试驱动开发流程root-cause-tracing.md根因定位与错误追踪code-review.md代码审查清单memory-management.md如何写记忆文件git-workflow.mdGit 分支管理与提交规范。每个技能文件的头部通常有一段 YAML frontmatter类似--- name: test-driven-development description: Use this skill when implementing new features or fixing bugs when_to_use: New feature, bug fix, refactoring with behavior change ---description和when_to_use是 Codex 决定何时调用这个技能的关键。你还不能用模糊描述比如Improve code quality这种因为 AI 在执行时会花太多时间判断是否匹配不如直接写清触发条件。4.2 如何编写你自己的技能文档了解结构之后你可以写自己的技能文档了。比如团队最近发现数据库迁移经常出问题想沉淀一个数据库迁移审查技能可以这么写--- name: db-migration-review description: Review database migration scripts for safety issues when_to_use: A migration file is created, modified, or mentioned in a PR --- 1. 读取 migration 文件列出所有变更语句。 2. 检查是否存在破坏性操作DROP、TRUNCATE、ALTER COLUMN 类型变更。 3. 确认列类型变更是否兼容旧数据。 4. 如果存在破坏性操作要求提供数据迁移方案。 5. 输出审查结论按照 SAFE / NEEDS_FIX 标注。把这个文件放到~/.codex/skills/后发现下次再让 Codex 处理 migration 时它就会自动套用这套审查逻辑。你不需要懂任何编程就能给 AI 定义行为规范这种扩展性非常关键。4.3 内置变量与上下文注入规则superpowers 的技能文档还可以引用一些模板变量比如当前分支名、项目路径、issue 编号。这个功能让技能能够适配不同项目的实际情况。具体可用变量在 superpowers.md 主文档里有说明常见的有{{repo}}当前仓库名{{branch}}当前分支名{{issue}}用户提到的 issue 编号。我实际用下来比较实用的做法是在 git-workflow 技能里加入分支名规范比如创建分支时如果用户提到了 issue使用 {{issue}}-short-description 的格式。这样 Codex 创建的分支天然带着编号PR 关联起来非常方便。不过要提醒一下不同版本的 Codex CLI 对模板变量的支持程度不一致你本地测试的时候要多试两次变量没注入也不影响技能执行只是少了自动化便利而已。5. 常见问题与排查技巧实录5.1 AGENTS.md索引失效我刚开始用 superpowers 时遇到最挫败的问题是技能明明装好了但 Codex 完全不按技能走。排查之后发现是 AGENTS.md 路径不对。Codex CLI 会优先读取项目根目录的 AGENTS.md再读全局的~/.codex/AGENTS.md如果项目里已经有一个旧的 AGENTS.md全局配置就不会被加载。解决方法是先看项目根目录是否存在 AGENTS.md存在就把 superpowers 的内容合并进去而不是删掉旧的。另外改完 AGENTS.md 之后一定要开新会话Codex 的长上下文不会每轮都重新读一遍文件。5.2 memory不生效memory 不生效的常见原因有两个。一是 Codex 没有被授予写文件的权限它想记录但被权限拦住了表现为对话里它说了我会记住这一点但下次开新会话完全不记得二是 memory 文件路径错了superpowers 默认在~/.codex/skills/memory.md或项目目录下路径不一致时读写都在不同文件里。排查时直接打开 memory 文件看一眼如果里面是空的说明记录还没写进去如果文件存在但乱糟糟说明技能格式配置有问题。我的建议是每周翻一次 memory 文件清理过期信息因为它只是 Markdown内容多了之后 Codex 读取时也会犯选择困难。5.3 slash command串台superpowers 里的 skill 描述如果写不好Codex 很容易调错技能。比如你把 code-review 的 when_to_use 写成代码写完之后它可能会在每次实现完功能后都调用很啰嗦。我遇到的问题就是多个技能描述高度相似导致 AI 分不清是应该用 TDD 还是用 code-review。解决方法是给每个技能写非适用场景在文档里加一段when_not_to_use。比如when_not_to_use: 仅需要修改注释、格式化代码时不要使用本技能。这个技巧非常管用能把 AI 的选择范围缩小很多。5.4 常见问题速查表现象排查方向解决方案技能完全没生效AGENTS.md 是否被项目级文件覆盖合并配置开新会话技能时好时坏Codex CLI 版本过旧更新到最新版重测技能记忆不跨会话Write 权限未授权授权 memory 目录写入权限调用错误技能when_to_use 描述宽泛细化触发条件加 when_not_to_use技能执行到一半中断上下文过长精简技能文档只留核心步骤6. 最佳实践与我的使用心得6.1 给技能文件写使用场景比写功能说明更重要这是我从踩坑里总结出的第一原则。你可以把技能文档理解成一个函数description和when_to_use就是函数签名AI 靠它来决定是否调用。很多人写技能文档喜欢写一大段本技能用于提升代码质量这种废话一点用没有。正确做法是写具体的触发条件。比如每当用户要求实现新功能时、每当测试失败超过两次时、每当涉及数据库表结构变更时。触发条件写清楚AI 对技能的选择准确率会大幅提升。我在实践中把 TDD 技能的 description 从Use this to write tests 改成了 Implement features following a strict test-first approachalways use when implementing new business logic效果好得多。6.2 人机分工边界别让AI直接推main分支用 superpowers 不等于完全放飞 AI。我的工作流是需求拆解、技术方案由人确定具体的编码执行、测试编写、提交信息生成交给 Codex最后的 Code Review 和合并由人完成。这个边界必须提前定好。具体操作上我会在 git-workflow 技能里明确规定禁止直接推送到 main/master 分支并且要求 Codex 在创建 PR 时提供变更摘要、测试结果和影响范围。这是一条强制规则写在技能文档里比每次对话时口头要求可靠得多。还有一点关键路径的测试必须由人亲自跑一遍不能只信 AI 报的All tests passed。因为有些测试是 AI 自己改过的它可能顺势把断言也调整了——这种情况我遇到不止一次。6.3 团队落地建议把skills清单化如果你打算把 superpowers 引入团队我建议先把 skills 目录提交到 Git 仓库让所有人共用一套技能集。这样有几个好处新人克隆仓库后自动拥有团队级的 AI 工程规范技能变更走 PR 评审出问题时可以回退到之前的技能版本。具体操作很简单在项目根目录建一个.codex/skills/目录把团队认可的技能文件放进去同时写一份 README 说明每个技能的用途。新成员加入时只需要确认 Codex CLI 已安装项目里的 AGENTS.md 会自动把它们带入工作流。这样一来每个人的 AI 编码行为都是可预期、可管理的。根据我个人的使用体会superpowers 最值得借鉴的不是某一个技能而是把经验固化成 Markdown 给 AI 用这套思路。我在实际项目中用下来TDD 和相关技能带来的收益最明显——测试补齐了代码质量有了基本保障。最后再分享一个小技巧不要贪多先只启用两三个核心技能跑几周稳定后再逐步增加新技能否则 AI 光选技能就把上下文消耗掉了反而不如轻装上阵。