第一次听说 superpowers 这个词是在 Codex CLI 的讨论串里。那时候我用的 Codex 还很简单能读仓库、能改代码、能跑测试但整体感觉就像一个很有潜力的实习生——你说一步它做一步遇到编译错误就开始原地打转甚至会在同一个死胡同里撞三次。后来有人提到 olaulau 做了一套叫 codex-superpowers 的 skill 库装上之后第一反应是这个 Codex 好像换了一个人。它不再急着动手改代码而是先拆任务、写测试、看失败、再实现整个过程像极了一条标准的 TDD 流水线。这篇文章就是围绕 superpowers 的实际使用体验来写的。我会先讲清楚它到底是什么、解决什么问题然后给出完整的安装步骤和验证方法再深入拆解它的核心工作流TDD、任务拆解、失败恢复接着单独拉出 Java 项目场景说一说适配细节最后分享我在实际使用中踩过的坑和排查思路。无论你是刚接触 Codex CLI 的新手还是已经在用但觉得它不够稳的老手这篇都值得往下看。1. 什么是 superpowers给 Codex CLI 装上职业素养的操作手册先说结论superpowers 不是一个新模型也不是什么代码补全插件。它本质上是一套高度结构化的 Markdown 指令集也就是 GitHub 上那个 codex-superpowers 仓库里的内容。这套指令通过 Codex CLI 的 AGENTS.md 机制注入对话上下文告诉模型在什么场景下应该触发什么流程、按什么顺序执行、每一步有什么验收标准。1.1 我的真实使用感受从实习生到熟手我最初是在一个 Rust 项目里跑通 superpowers 的。装之前Codex 面对一个失败测试时最常见的反应是直接打开源文件开始改逻辑改完跑一次测试如果还挂就换个方向再改直到某一次碰对为止。整个过程没有章法像是靠概率在做题。装完 superpowers 之后同样的场景下它会先停下来新建一个 tracking 文件把失败原因、当前分支、测试命令全部记录下来然后按技能列表里定义的TDD 工作流逐步执行先复现测试红再写最小实现最后重构。这种变化不是模型变聪明了而是流程约束生效了。模型还是那个模型但它手里多了一本遇到什么情况该怎么做的操作手册。这就像同样是新来的工程师有人给他一份清晰的团队规范他就知道什么时候该写单测、什么时候该重构、什么时候该问人没人给规范他就只能凭感觉乱来。superpowers 做的就是这个事情。1.2 它的本质技能目录 AGENTS.md 注入机制superpowers 的核心机制并不神秘。Codex CLI 本身支持在项目里放一个 AGENTS.md 文件里面写的是给 AI 的项目规则或操作指引。superpowers 把大量通用开发场景的指引拆成了一个个独立的技能skill每个技能就是一个目录里面放着 SKILL.md 文件以及可能的示例、模板、脚本。然后它通过一个总控的 AGENTS.md 把这些技能目录的组织方式、触发条件、调用方式告诉 Codex。实际表现是什么你在 Codex 对话里输入/skills它会列出一串可用的技能名比如TDD workflow测试驱动开发流程Task breakdown任务拆解与计划跟踪Red-green-refactor红绿重构循环Dependency debugging依赖排查IDE workflow编辑器集成场景每个技能都有自己的 description 字段Codex 会根据当前任务语义决定要不要调用或者你自己手动指定。这里我想强调一个关键认知superpowers 不改变 Codex 的生成能力它改变的是 Codex 的决策路径。生成代码的能力是模型固有的但什么时候写测试、先做哪一步、失败了怎么办这些决策是规则决定的。这就是为什么很多人装了之后觉得 Codex 变靠谱了——不是它变聪明了而是它不再瞎试了。1.3 它到底解决了哪些具体问题我用了一段时间后把它的收益归纳成三类第一类是路径问题。默认 Codex 遇到任务时路径是高度不确定的经常绕过测试直接改功能代码。superpowers 通过 TDD 流程硬性规定路径先写测试、先看失败再写实现。这条路径一旦固定行为的可预测性就大幅提升。第二类是记忆问题。Codex 上下文有限我做一次多文件重构时它经常做着做着就忘了前面的约定。superpowers 的 tracking 文件机制让它在每次改动前把当前目标、已完成项、未完成项、已知风险写进一个文件每次继续工作时先读这个文件。这就等于给 AI 装了一个外部记忆。第三类是恢复问题。失败是常态但模型面对失败时的默认策略是猜下一个答案。superpowers 会要求模型先复现失败、记录失败、分析根因再决定修复方案。这个过程听起来朴素但在长任务里的价值极高能省下大量来回试探的时间。2. 安装与首次启动从 clone 到技能生效的完整过程安装 superpowers 本身不复杂但里面有几个细节如果没注意很容易出现装了半天/skills还是空的的情况。我按自己当时的操作过程一步步拆解你照着走一遍就能跑通。2.1 前置环境Node.js、Codex CLI、Gitsuperpowers 本身不依赖 Node.js但你本机要能跑 Codex CLI而 Codex CLI 一般安装在 Node 环境里。所以前置条件就三条Node.js 18 或更高版本Codex CLI 已经安装并且登录了 OpenAI 账号codex --version能正常输出版本号Git 能正常 clone 仓库这三条看似基础但我当时在第二台机器上装的时候因为 Codex CLI 版本太老/skills这个命令一直没反应后来升级了 Codex 才正常。所以如果你后续遇到技能不加载先检查版本是不是太旧。2.2 三分钟安装路径我的安装路径分成三步每一步都可以验证是否成功。第一步克隆仓库。官方仓库地址是https://github.com/olaulau/codex-superpowers为了节省体积可以加--depth 1只拉最新版git clone --depth 1 https://github.com/olaulau/codex-superpowers.git我习惯把它放到~/codex-superpowers这样固定的位置因为后面配置文件里要写绝对路径。位置换来换去容易导致路径失效。第二步找到你项目里的 AGENTS.md 配置。Codex CLI 会按层级加载指令全局配置在~/.codex/AGENTS.md项目配置在当前工作目录的AGENTS.md。superpowers 的官方 README 里建议的方式是在你的项目目录下新建或编辑一个 AGENTS.md往里面写入对 superpowers 目录的引用。我当时是在自己的项目根的 AGENTS.md 里加了这样的引用片段具体写法以你 clone 下来的 README 为准## Available Skills This project supports the superpowers skill system. Run /skills to list available skills. Skills are defined in ~/codex-superpowers/skills.这里的关键是给出技能目录的绝对路径让 Codex 能顺着路径找到 SKILL.md 文件。第三步配置 Codex 的全局指令文件。如果你希望 superpowers 对所有项目都生效而不是只在某个项目里生效可以直接编辑~/.codex/AGENTS.md把同样的引用写进去。我实测下来全局生效更适合我因为我的开发环境里经常同时开好几个仓库不想每个仓库都单独配一遍。不过要注意全局 AGENTS.md 的内容会被所有会话加载如果里面写了太多技能描述会白白消耗上下文窗口。我的做法是全局只放一个入口说明具体的技能描述让它按需读取。2.3 验证安装是否生效装完之后进入你的项目目录启动 Codexcd /path/to/your/project codex进入对话界面后输入/skills。如果一切正常你会看到一份技能清单里面列出了所有可用的技能名、描述和触发方式。如果这个命令没有反应或者提示找不到技能大概率是 AGENTS.md 里的路径写错了或者文件名不对后面排查章节我会细说。2.4 不同系统的注意事项我在 macOS 上用得很顺利但在帮朋友排查时发现Windows 上如果用的是 WSL 2 环境跨文件系统访问会有性能问题建议把 superpowers 仓库 clone 到 WSL 的 home 目录下而不是/mnt/c下面的 Windows 目录否则每次读取技能文件都有肉眼可见的延迟。另外Linux 服务器上使用时要留意文件权限。如果遇到Permission denied执行一次chmod -R ur ~/codex-superpowers这些问题都不难解决但它们是装了但没生效的高频原因。3. 核心工作流TDD、任务拆解和失败恢复这三板斧superpowers 最值钱的部分不是安装本身而是它内置的那套工作流。这套工作流不是凭空造出来的它几乎就是把一支成熟开发团队的操作规范翻译成了 AI 能执行的指令。我用下来最重要的就是三板斧TDD 流程、任务拆解、失败恢复。3.1 为什么 TDD 是 superpowers 的第一技能如果你让 Codex 直接写一个功能函数它通常会先给你一坨代码然后让你自己测试。但让它按 TDD 流程走顺序就完全反过来了先写测试、跑测试确认失败、再写实现、再跑测试确认通过。这个顺序的意义在于测试先行实际上是把需求硬编码成了可验证的契约。superpowers 的 TDD 技能会指示模型做这些事先阅读现有测试文件的风格理解断言库和测试框架在动手写实现前先写一个新测试这个测试描述期望行为运行测试确认它是红的failed并且失败原因正是该功能不存在或行为不符合预期再写最小实现只为了让这个测试变绿运行整个测试套件确认没有回归最后重构清理重复代码这个流程看起来死板但就是这种死板治住了模型跳步的毛病。我见过最典型的场景是没有 TDD 约束时模型会在写实现之前先顺手改了一堆无关代码最后测试红的时候根本不知道是哪里出了问题。按 TDD 流程走每一步都有明确的验证点定位问题的成本大幅降低。3.2 红-绿-重构循环在 Codex 里怎么实际操作我举一个具体例子。假设我要给一个订单模块加一个超过 30 分钟未支付就自动取消的逻辑。没有 superpowers 的时候我可能会直接让 Codex在 OrderService 里加一个 cancelExpiredOrders 方法。它会生成代码然后等我反馈。有 superpowers 的情况下它会先问我要不要启动 TDD 工作流然后自动进入以下步骤codex /tdd它先创建一个测试文件。假设项目是 TypeScript Vitest它会生成类似这样的测试骨架import { describe, expect, it } from vitest; import { OrderService } from ./order-service; describe(OrderService, () { it(should mark orders unpaid for over 30 minutes as canceled, () { const service new OrderService(); const order service.createOrder({ createdAt: new Date(Date.now() - 31 * 60 * 1000) }); service.cancelExpiredOrders(); expect(order.status).toBe(canceled); }); });然后它立刻跑一次测试。注意这时候cancelExpiredOrders方法根本不存在测试必然失败。它会记录这个失败把这作为红的证据。接下来它写最小实现再跑一次测试直到变绿。最后它检查有没有重复代码或者可以提炼的公共逻辑。整个过程你会看到 Codex 对话里出现清晰的RED → GREEN → REFACTOR标注。这种可追踪的执行方式是我认为 superpowers 带来的最大体验提升。3.3 任务拆解用 plan 文件给 AI 装外部记忆TDD 解决的是每一步怎么走任务拆解解决的是整个任务怎么不跑偏。superpowers 内置了一个任务拆解技能它会引导模型把大任务拆成多个小步骤并把每一步写进一个 plan 文件。这个文件通常放在项目的一个约定位置比如docs/plan.md或者.superpowers/plan.md里面记录的字段包括字段含义示例目标这个任务最终要完成什么为订单模块增加过期取消逻辑当前步骤正在做哪一步编写过期订单查询已完成步骤已经完成的子任务创建测试文件、确认红待办步骤接下来要做什么实现 cancelExpiredOrders风险当前已知的坑时区问题、数据库索引缺失这个文件的作用是让 Codex 在长任务中随时复盘。我试过一个比较大的重构任务涉及 6 个文件、4 个测试。如果没有 plan 文件Codex 干到一半就会忘记自己最初设计的接口约束甚至把已经确认过的 API 结构改掉。有了 plan 文件之后每次继续它都会先读一遍 plan再决定下一步。这就像是给 AI 配了一个记事本治的是模型的短期记忆焦虑。我自己在后面做自定义技能的时候也会默认给每个复杂任务配套一个 plan 文件模板这个习惯就是被 superpowers 带出来的。3.4 失败恢复不猜、不蒙、先复现模型面对失败测试最大的问题是它倾向于猜一个更可能对的答案而不是找到失败的真实原因。superpowers 的依赖调试和失败恢复技能做的就是把后者强行变成默认行为。它的实际流程是完整记录失败输出粘贴测试日志尝试本地复现这个失败确认不是环境问题定位失败发生的函数或模块分析根因可能的原因列出来对每个可能原因写一个最小验证找到根因后再按 TDD 流程修复我在一个 Python 项目里遇到过循环依赖导致 import 时崩溃的问题。普通操作下Codex 会直接改 import 结构然后反复试错。但按 superpowers 的调试技能走它会先让我提供完整的调用栈然后写一个最小脚本复现失败确认根因是两个模块互相依赖再把其中一个依赖关系通过延迟导入解除。整个过程只改一处代码测试一次通过。这个先复现再定位的思维其实是任何资深工程师都知道的基本方法。superpowers 的价值在于它把这种思维写成了模型必须遵守的指令让 AI 没机会走捷径。4. Java 项目实战superpowers 在 Maven/Gradle 场景下的适配我在 Java 项目里用 superpowers 的经历格外有代表性因为 Java 项目对 Codex 来说几乎是重灾区构建慢、测试慢、语言冗余、项目结构复杂。直接裸用 Codex体验往往很糟。但配上 superpowers 之后Java 项目也能跑得相对顺。4.1 Java 项目为什么是 Codex 的重灾区Java 项目有三个特点每一个都天然克制 AI 的发挥。第一个特点是构建系统重。Maven 或 Gradle 的构建时间动辄几十秒甚至几分钟。如果模型每次改完代码都全量构建一次任务可能搭进去一个小时。它又不会主动判断这次改动只需要增量编译所以经常把时间浪费在无意义的等待上。第二个特点是项目结构复杂。Java 项目的目录层次深、类名长、包名多模型很容易找不到该改的文件。我遇到过它打开一个 Controller 文件夹里三个相似命名的类改错了一个然后整个任务链全部崩溃。第三个特点是测试反馈慢。JUnit 测试和断言风格相对正式模型写出来的测试经常因为生命周期注解不对、mock 方法不匹配而失败调试成本高。4.2 我定义的 Java 技能集构建、测试、断言风格superpowers 默认技能更偏向 Node/Python 等轻量生态。我针对 Java 项目做了一套自己的技能集放在~/codex-superpowers/skills/java/下面。这里把我的设置分享给你第一个技能是Java 增量构建。它的指令核心是优先使用 Maven 的增量编译避免无意义的全量清理。具体规则是如果只修改了单个模块执行mvn -pl module -am test而不是mvn clean test如果项目的目标文件存在优先mvn compile而不是mvn clean compile确认构建工具是 Maven 还是 Gradle主命令分别用mvn和./gradlew第二个技能是JUnit 5 测试规范。它会要求模型遵循以下约定使用DisplayName说明测试意图断言使用 AssertJ 的assertThat风格而不是裸 JUnit 的assertEqualsmock 使用 Mockito遵守given/when/then三段式结构测试类命名用XxxTest测试方法用should_xxx格式第三个技能是上下文精简。Java 源码长得离谱模型很容易把整个文件塞进上下文。这个技能要求模型在读取 Java 文件时优先提取类签名、方法签名、注解跳过 getter/setter 大段样板代码。4.3 一个具体的 JUnit 用例生成过程我在一个 Spring Boot 项目里让 Codex 配合 superpowers 给 UserService 生成找不到用户时抛异常的测试。它的操作路径非常清晰先检测项目的测试基础设施ls src/test/java cat pom.xml | grep -A 2 junit然后生成 JUnit 5 测试文件DisplayName(UserService) class UserServiceTest { Test DisplayName(should throw UserNotFoundException when user not found) void should_throw_exception_when_user_not_found() { UserRepository repository mock(UserRepository.class); when(repository.findById(99L)).thenReturn(Optional.empty()); UserService service new UserService(repository); assertThatThrownBy(() - service.getUser(99L)) .isInstanceOf(UserNotFoundException.class) .hasMessage(User not found with id: 99); } }这个测试生成过程最大的亮点是它没有直接去改 UserService 的实现而是先运行测试看到UserNotFoundException类是 missing 的失败结果再去创建异常类、修改 UserService最后重新跑测试。整个过程里Codex 没有出现改完实现却忘了补异常类的低级错误因为 TDD 的红-绿循环天然保证了每一步都有验证。4.4 上下文管理Java 项目如何省 tokenJava 项目的上下文消耗比脚本语言大得多我总结了几条实测有效的方法第一精简技能目录。superpowers 默认包含大量技能但一个 Java 项目可能用不到那些前端、移动端相关技能。我会在项目的 AGENTS.md 里只引用 Java 相关的技能目录减少模型每次加载的指令数量。第二开启按需读取。在自定义技能里写清楚不要一次性把整个项目的 AGENTS.md 和所有源码读进上下文而是先读取目录树按需打开具体文件。第三对大文件做分段提示。如果一个 Java 类超过 400 行让模型优先读取方法签名列表只再打开它认为需要修改的方法所在的区域而不是从第一行读到第 400 行。这套组合拳下来同样的 Java 重构任务我的 token 消耗大概降了三分之一而且正确率还更高了。因为上下文越干净模型越不会因为无关代码而分心。5. 排查实录技能未生效、配置失效与上下文爆炸任何工具用久了都会踩坑superpowers 也不例外。我不打算只给结论而是把这几次典型的排查过程完整写出来这样你遇到类似问题时可以按同样的思路排查。5.1 问题一装了但/skills列表是空的这是我见过最多的问题也是最容易犯的错。我当时在一台新的 Linux 机器上 clone 了 superpowers配置也写了但进入 Codex 后输入/skills它回了一句unknown command。我的排查路径是分层的第一步检查技能目录本身是否存在ls ~/codex-superpowers/skills如果目录不存在说明 clone 没成功或者路径错了。第二步检查 AGENTS.md 文件的名字。Codex 只认AGENTS.md这个精确的文件名不认agents.md或Agent.md。在 Linux 和 macOS 上文件名大小写是敏感的。我排查了一圈发现问题就是我把文件写成了agents.mdCodex 直接忽略了它。第三步检查配置文件里是不是有语法错误。Codex 的 config.toml 里如果某个字段写错了它可能不报错但行为完全不对。比如引用了不存在的路径它也不会提示只是静默忽略。这个排查顺序很重要先确认文件和目录存在再确认文件内容可读再确认配置语法正确。很多人一上来就改配置文件结果问题只是少了个s。5.2 问题二Codex 版本升级后配置字段变了superpowers 是紧跟 Codex CLI 的变化走的。我第一次遇到昨天还好好的今天突然不认技能的情况就是 Codex 升级之后配置文件里的某个旧字段被废弃了。我当时的处理方式是先看 Codex 的更新日志确认配置项变化然后对比 superpowers 仓库里的 AGENTS.md 模板看它是否已经更新了推荐写法。这类问题没有一劳永逸的解法只能保持两个习惯一是 clone 了 superpowers 之后不要放着不管经常git pull拉最新版二是升级 Codex CLI 之后第一时间跑一个简单的/skills验证早发现问题早处理。另外不要直接修改原仓库里的文件。如果你改了~/codex-superpowers里的内容下次git pull很容易产生冲突。我的做法是原仓库保持只读所有个性化配置都通过项目里的 AGENTS.md 覆盖。5.3 问题三上下文窗口被打满了superpowers 技能一多AGENTS.md 里引用的指令长度就会膨胀。Codex 的上下文窗口是有限资源如果技能说明占掉太多留给实际代码和测试的上下文就少了模型会表现得明显变笨。我遇到的典型场景是在一个大型 TypeScript 项目里Codex 突然开始频繁忘记前面已经确认过的接口定义。排查之后发现根因是全局 AGENTS.md 加载了 20 多个技能的完整说明每次对话光技能说明就吃掉了一大块上下文。解决办法有三个全局只放精简入口不放完整技能说明让模型按需读取将不常用的技能移到独立目录通过对话中手动指定技能名触发对常用技能用更短的语言重写 description把不必要的示例代码移出主文件我最后是把技能目录分成了core和extended两层核心技能常驻扩展技能按需加载。这样既保留了能力又控制了上下文开销。5.4 问题四Java 项目 Maven 测试一直失败这个坑放在 Java 场景下特别典型。superpowers 默认的测试技能总是假设项目用 npm test 或者 pytest碰到 Maven 项目就抓瞎。我在一个 Maven 项目中遇到过它反复执行mvn test因为某个模块需要先 install 依赖导致一直失败。排查后发现是技能里没有定义如果项目是多模块 Maven 项目先mvn -pl module -am install -DskipTests这个规则。这类问题的通用排查思路是把构建失败视为环境适配问题而不是模型能力问题。默认技能覆盖的是通用场景你要在自己的 AGENTS.md 里补充针对当前项目的局地知识比如该项目用什么构建工具、测试框架是什么、有没有特殊的环境变量要求。补充完之后同样的问题一般就不会再犯。6. 自己写一个技能把团队规范变成 AI 肌肉记忆用熟 superpowers 内置技能之后你大概率会走到这一步想把自己团队的一些规范也变成 AI 的肌肉记忆。这一步其实比想象中简单核心就是会写 SKILL.md。6.1 技能目录结构和 SKILL.md 写法一个技能就是一个目录目录名是技能名目录里至少要有一个 SKILL.md 文件。SKILL.md 的开头是一个 YAML frontmatter里面包含两个字段--- name: conventional-commit-zh description: 当用户要求生成 Git 提交信息时使用中文撰写符合 Conventional Commits 规范的提交信息 ---name是技能名description是触发条件描述。Codex 会根据 description 的语义匹配来决定是否调用这个技能。所以 description 要写得具体最好包含触发场景。frontmatter 下面是技能的具体指令正文可以写任何你想让模型遵守的规则。格式上建议用明确的步骤列表而不是大段文字。模型对结构化指令的遵循度明显更高。6.2 一个示例强制输出中文提交信息我在国内团队做项目时最头疼的就是模型默认生成英文提交信息。我写了一个技能效果非常直接。在~/codex-superpowers/skills/cn-commit/SKILL.md里--- name: cn-commit description: 生成 Git 提交信息时使用中文遵循 Conventional Commits 规范 --- 当需要生成提交信息时遵守以下规则 1. 用中文写 subject 部分不要用英文 2. subject 第一个词是提交类型feat、fix、docs、style、refactor、test、chore 3. 格式为 类型(模块): 简短描述例如 feat(订单): 增加超时自动取消逻辑 4. 如果有对应 issue在正文中引用 5. 描述保持一句话不超过 50 个字符写完之后下次让 Codex 帮你 commit它就会自动使用中文提交信息而且格式还会带上类型和模块前缀。这个技能我用了大半年非常稳定。6.3 让技能支持参数和条件分支SKILL.md 里也可以定义更复杂的逻辑。我当时为了处理不同模块的测试命令写过一个带条件分支的技能片段当用户要求运行测试时按照以下逻辑执行 - 如果是 Maven 项目 - 单模块执行 mvn test - 多模块执行 mvn -pl module -am test - 如果是 Gradle 项目 - 执行 ./gradlew test --tests 特定测试类 - 如果是前端项目 - 执行 npm test 或 yarn test模型读到这里会当作决策树来执行效果比让它随机应变好得多。这个思路可以进一步扩展像写代码一样写技能把团队所有重复性操作都固化成规则。6.4 你的可复用清单最后给你一份我总结的技能编写要点description 写得越具体触发越准确指令用有序列表比散文段落更有效每个步骤都给出执行命令或验收标准能写路径就不写描述能写命令就不写概念技能越短越好把长细节放在独立示例文件中按需读取写完后一定要用一个真实场景验证触发是否正常我自己现在维护着七八个自定义技能覆盖提交信息、构建优化、测试规范、日志规范等场景。每一段配置都是踩过坑换来的但它带来的收益是持续的——AI 开始用我们的方式干活而不是我们每次去纠正 AI 的方式。这套技能库的思路其实不只适用于 Codex任何支持自定义指令的 AI 编程工具都可以借鉴。把团队规范固化下来AI 才能真正成为团队里那个可靠的新人。