如果你在终端里用过 Codex CLI大概率经历过这种场面你说帮我修一下这个bug它一顿操作猛如虎三分钟后你发现它把整个模块的结构都改了你说给这个接口补个单元测试它写完测试顺手改了一堆生产代码build 还挂了。问题出在哪不是它不聪明而是它没有职业习惯——它不知道资深工程师在动手之前会先确认需求、先写失败测试、先复现问题。superpowers 这套开源技能框架就是来解决这个问题的它给 Codex 装上了一套可加载、可扩展的工作流程让 AI 从一个聪明的愣头青变成一个有章法的老工程师。这篇文章我会从它的核心机制讲起一步步带你完成安装、配置、上手实操最后分享我自己写自定义技能时踩过的坑。适合所有用 Codex CLI以及关心 AI 编程 Agent 生产方式的开发者。1. superpowers到底是什么一套给Codex装上职业习惯的技能框架1.1 它的核心机制可加载的SKILL.mdsuperpowers 本质上是位于 GitHub 上的一份开源技能库作者是 Jesse Vincent社区里都叫他 obra它利用了 Codex CLI 的 skills 机制。Codex 会读取~/.codex/skills/目录下按文件夹组织的技能每个技能文件夹里有一个核心的SKILL.md文件。这个文件不是给人看的说明书而是给 Codex 看的操作手册开头有一段 YAML 格式的元信息声明这个技能叫什么、什么时候该用正文则是 Markdown 格式的步骤化指令告诉 Codex 遇到这类任务时应该按什么顺序思考、执行什么动作、何时停下来确认。你可以把它理解成给 AI 准备的标准作业程序。人的工作习惯是靠长期训练形成的但 Codex 每次对话都是一张白纸除非你把方法写下来让它加载。superpowers 把先写测试再实现系统化排查 bug动手前先出方案这类方法论固化成了一个个可以被按需加载的文件。关键是按需这两个字——Codex 不会把所有技能都塞进上下文而是在面对任务时根据技能描述里的匹配条件选择性地加载最合适的那一份。这比把几十条规则全部写进 system prompt 要经济得多也不容易互相冲突。1.2 为什么需要一套技能框架而不是一段万能提示词很多人第一反应是我不装 superpowers我在 prompt 里写清楚请你先写测试再实现不就行了吗我用过一段时间之后可以明确说提示词和技能框架是两种量级的东西。提示词是一次性的、即兴的、不可维护的。你今天想起来写了先写测试明天忘了Codex 又变回老样子而且提示词越长Codex 越容易在长对话里跑偏前面强调的约束到后面就被遗忘了。技能框架的思维正好反过来把方法论从对话里剥离出来放进一个固定的、可共享、可版本化的文件里。这个 SKILL.md 可以被多个项目共用可以被团队所有人共用甚至可以被其他工具读取。superpowers 里的每个技能都经过作者对真实工作流的提炼步骤之间还有明确的退出条件不是一句请认真测试能比的。我自己的体会是装上之后 Codex 的行为模式肉眼可见地变了它会在改代码之前先问我几个澄清问题会在写实现之前先让我看到失败测试的输出会在收尾时主动跑完整测试套件。这不是玄学是结构带来的改变。2. 安装与激活让Codex真正记住这些技能2.1 前置条件与版本检查开始之前先确认你的环境里已经装好了 Codex CLI 并且完成了登录认证。在终端执行codex --version能看到版本号就说明命令行工具本身没问题。如果还没有装先去 OpenAI 官方的 Codex CLI 文档走一遍安装流程这里不展开。另外你需要一个能正常工作的 Git因为 superpowers 目前主要就是通过 Git 仓库分发的。这里提醒一句Codex CLI 的 skills 机制在早期版本里并不完善不同版本对技能目录的扫描方式和加载策略有过调整。我建议先把 Codex 更新到比较新的版本再装 superpowers否则可能会出现技能文件都在但 Agent 就是不加载的诡异情况。以我实测的经验新版本对SKILL.md的 frontmatter 解析更稳定匹配描述也更智能。2.2 两条安装路径脚本安装与手动安装第一种方式是用仓库自带的安装脚本。把仓库克隆到本地然后执行脚本git clone https://github.com/obra/superpowers.git cd superpowers ./install.sh脚本会帮你把技能文件复制到 Codex 的技能目录通常就是~/.codex/skills/并且如果它检测到你还没有配置过技能相关设置会顺便在配置文件里补充必要项。这种方式适合绝大多数人尤其是不想关心目录结构的用户。第二种方式是手动安装我更推荐有一定定制需求的人。你只需要把仓库里的技能目录链接或复制到 Codex 的技能目录git clone https://github.com/obra/superpowers.git ~/.codex/skills/superpowers我手动装的时候习惯先看一眼~/.codex/目录的现有结构确认 skills 文件夹是已经存在还是需要自己创建。如果 Codex 在首次运行时已经生成过这个目录那就直接放进去如果不存在创建一个同名目录再放技能文件。这一条对新手很容易踩有的人把技能克隆到了别的位置Codex 根本扫不到然后跑来问为什么没效果——先检查路径再说。2.3 安装后验证确认Codex能感知到技能装完之后不要急着开干先做验证。确认~/.codex/skills/superpowers/下能看到带SKILL.md的文件夹比如test-driven-development、debugging、planning这一类。然后在你的项目根目录或者用户目录下检查AGENTS.md这个文件是 Codex 读取项目上下文时的关键入口superpowers 通常会在里面写入技能路径提示相当于给 Codex 指路。最直接的验证方式是在终端启动codex然后问它你现在可以使用哪些技能如果它能把 superpowers 里的几个技能名说出来说明加载成功。如果它一脸茫然多半是技能目录路径不对或者AGENTS.md里的技能说明没有生效。按下 CtrlC 退出重新检查一遍路径和配置文件再开一个新的会话重试。注意一定要开新会话因为旧会话里的上下文可能已经错过了技能扫描。3. 核心技能拆解TDD、深度调试、规划各自解决什么问题3.1 TDD技能让测试先行的纪律落地superpowers 里最有名、也是我日常用得最多的技能之一就是 TDD 技能。它把测试驱动开发拆成了一串明确的动作先写一个会失败的测试运行它并观察失败信息然后写最简实现让测试通过最后回头重构。听起来很简单但 Codex 没有这个技能的时候它的默认行为是直接写一堆实现代码顺带补个测试这完全违背 TDD 的顺序感。有了 TDD 技能之后Codex 在接到一个功能开发任务时会明确告诉你我先写一个失败的测试然后真的先写测试再运行把失败输出贴给你确认。这一步非常关键因为失败信息本身就是需求的验证——如果测试连失败都不符合预期说明你对需求的理解有问题。我在实测 Java 项目时发现这个技能对 JUnit、Maven 这类工具链识别得很好能自动选择合适的测试命令来运行减少了很多来回沟通的成本。3.2 深度调试技能不再瞎试的排查流程调试是另一个我强烈推荐单独拿出来讲的技能。没有调试技能时Codex 遇到 bug 的典型反应是读一遍相关代码凭直觉猜测原因然后直接改。运气好了改对运气不好越改越乱把问题的现场都破坏了。superpowers 的调试技能强制它走一条严谨的排查链路先稳定复现问题再缩小范围到最小复现用例然后提出若干个可能的原因假设逐一验证最后才是动手修复。这条链路其实就是我们人类排查问题时的标准做法只是 Codex 默认不会这么干。最让我觉得值的地方是它会在修复之前先想办法复现而不是看到报错就猜。有一次我在一个老项目里遇到一个偶发的空指针问题Codex 加载调试技能后没有直接改代码而是先停下来问我能不能提供一个稳定的触发方式然后构造出了一个最小复现路径最终定位到一个并发初始化导致的竞态条件。如果它上来就修大概率会把问题掩盖过去。3.3 规划与任务拆分动手之前先想清楚规划技能解决的是大任务如何下手的问题。AI 编程 Agent 最怕的就是抽象的大指令比如给这个系统加一个支付能力这种任务连人类都要想半天Codex 硬冲的结果必然是遗漏需求。规划技能会让它先输出一份结构化的实施计划包括涉及的模块、数据流变化、风险点、验证方式并且会反过来向你提问把模糊的需求变成清晰的条目。它的价值在于把思考和行动分开了。没有规划技能时Codex 的思考和行动是混在一起的一边想一边写写错了再改有了规划技能它会先交付一份计划等你确认或者修正之后才开始动手。这个环节虽然看起来多了一步实际上节省了大量的返工。我在带 superpowers 做 Java 模块开发时最直观的体验就是规划阶段把字段、边界条件都理清楚了后面 TDD 阶段几乎是一路绿灯这种慢即是快的体验很上头。技能名 什么时候用 它强制 Codex 做什么技能核心作用典型触发场景test-driven-development先写失败测试再写实现最后重构新增功能、修复 bug 且有明确预期行为debugging复现→隔离→假设→验证→修复线上问题、偶发异常、逻辑错误planning输出结构化实施计划确认后再行动大模块开发、跨文件重构、新项目起步code-review按清单审查代码质量与隐患合并代码前、审查 AI 生成的改动4. 带superpowers实战从零实现一个Java模块的完整流程4.1 场景设定与项目背景为了让你更直观地看到这套技能是怎么协同的我拿一个最近实际做过的例子来说。项目是一个基于 Spring Boot 的电商服务Java 17 Maven JUnit 5需求是在订单模块里新增一个价格计算器原价超过一定阈值时自动打九折并且要支持后续扩展不同的折扣策略。这个任务不算复杂但正好覆盖了规划、TDD、重构三个关键动作非常适合用来演示。我把项目根目录下的AGENTS.md配置好让 Codex 知道技能库的位置。然后在终端启动codex输入我们要在订单模块新增一个价格计算器需求是超过阈值打九折你先用规划技能把这个任务拆一下。4.2 第一阶段让规划技能先把任务拆明白Codex 加载规划技能之后没有直接去建文件而是先输出了一份计划草稿内容包括需要新建PriceCalculator类和对应的PriceCalculatorTest测试类、折扣阈值和折扣率应该作为可配置参数还是写死、接口设计要预留策略扩展点。然后它问了我三个问题阈值具体是多少折扣率是固定的 0.9 吗需要支持按用户等级区分折扣吗这三个问题问完我已经能感觉到规划技能的价值了——它在逼我把需求边界说清楚。我回答了阈值 80折扣率固定 0.9暂时不区分用户等级但要留扩展接口。Codex 确认后在对话里输出了最终的开发计划并且把任务拆成了三个小步骤先写失败测试再实现最简逻辑最后重构抽出策略接口。这份计划我确认没问题才进入下一步。4.3 第二阶段TDD技能驱动红灯-绿灯-重构确认计划后我对 Codex 说按刚刚的计划用 TDD 技能开始实现。它随即加载 TDD 技能第一步是创建测试类内容大致是这样的package com.example.order.pricing; import org.junit.jupiter.api.Test; import static org.junit.jupiter.api.Assertions.*; class PriceCalculatorTest { Test void shouldApplyDiscountWhenAmountExceedsThreshold() { PriceCalculator calculator new PriceCalculator(); double result calculator.calculate(100.0); assertEquals(90.0, result, 0.001); } }当时PriceCalculator类还不存在编译都不会通过。Codex 做的第一件事不是补实现而是运行mvn test把编译失败的输出贴出来然后跟我说测试目前失败失败信息是找不到 PriceCalculator 类符合红灯预期。这一步我看得很舒服——它没有跳过红灯直接冲到绿灯这是 TDD 纪律的核心。接下来它才创建了最简实现package com.example.order.pricing; public class PriceCalculator { public double calculate(double amount) { if (amount 80) { return amount * 0.9; } return amount; } }再次运行mvn test测试通过。Codex 贴出了绿色输出然后主动进入了第三个阶段——重构。它问我当前折扣逻辑直接写死在类里要不要我抽一个 DiscountStrategy 接口默认实现是 ThresholdDiscountStrategy我同意后它重构了代码并跑了一遍完整测试确认行为没变。整个过程里它遵循着红灯绿灯重构的节奏一步都没有乱。4.4 第三阶段验证与代码审查收尾实现完成后Codex 没有直接说搞定了。它主动加载了 code-review 技能把自己刚才的代码过了一遍重点检查了几个方面是否有魔法数字需要提取为常量、测试是否覆盖了边界值刚好等于阈值的情况、策略接口是否真的有必要现在抽出来。最终它建议把阈值和折扣率提取成常量并补充一个边界值测试。我接受了建议它修改后又跑了一次完整测试全部通过。这个完整的流程走下来我最大的感受是superpowers 不是在替我做决定而是把每个阶段的检查点摆到桌面上让我和 Codex 始终知道当前在干什么、下一步要干什么。对于 Java 项目尤其舒服因为它对 Maven /JUnit 的认知很强测试命令、测试结果解读都不需要我反复教。5. 自己写技能SKILL.md的格式、编写要诀与踩坑提醒5.1 SKILL.md的标准结构与YAML头信息用了一段时间内置技能之后我自然开始琢磨自己写技能。superpowers 的技能格式其实非常开放骨架上就是一个带 YAML frontmatter 的 Markdown 文件。最基本的模板长这样--- name: commit-message description: Use this skill when writing a commit message to ensure the message is concise, accurate, and follows conventional commit format. --- # Commit Message ## When to use - 在完成一次代码变更后需要提交 Git commit 时 ## Workflow 1. 查看 git diff 和 git status梳理实际变更内容 2. 判断变更类型feat、fix、refactor、docs、test、chore 3. 按 conventional commits 规范生成标题控制在 50 个字符以内 4. 如果变更复杂补充正文说明原因和影响范围 5. 将最终信息直接输出等待用户确认后执行 git commitYAML 里的name是技能标识description是最关键的部分——Codex 就是靠它来判断什么时候应该加载这个技能。正文部分不需要写多么华丽的语言Codex 不是人类读者它需要的是清晰、有序、可执行的动作列表。我写熟练之后发现一个技能的核心竞争力不在于步骤多而在于边界清晰什么时候开始、什么时候停止、遇到异常怎么办都要写明白。5.2 描述信息怎么写Codex才愿意调用这是我自己摸索了很久才想明白的一点技能的描述信息必须站在任务的视角写而不是站在技能的视角写。什么意思如果你写This skill helps you write better code这种描述太泛Codex 面对一个具体任务时根本判断不出该不该用它。正确的写法是直接点出触发条件比如Use this skill when the user asks you to fix a failing test or implement a feature that requires writing new tests。我常用的描述公式是Use this skill when [具体场景] to [达成目标]。把场景写得越具体Codex 匹配得越准。另外可以用when后面接多个候选场景来增加召回率但别把不相关的场景也塞进去否则会出现任务类型不搭Codex 却强行加载了这个技能的尴尬情况。比如我一开始给调试技能写的描述太宽导致它连给我讲讲这段代码逻辑的任务都去加载调试流程明显就不合适。5.3 我踩过的四个坑与改进经验第一个坑是技能文件命名不规范。CLI 工具对技能目录的命名是敏感的目录名最好就是技能名不要带空格、特殊字符也别用中文命名否则在有些版本下会出现扫描不到的情况。第二个坑是正文里写如果你觉得……这种模棱两可的话。AI 会把它当成一个可以自由发挥的空间结果技能步骤被跳过行为又开始漂移。我的改进方式是每个步骤都写成祈使句并且给出明确判断条件比如如果测试输出包含 BUILD SUCCESS则进入下一步否则返回第一步重新检查。第三个坑是贪大求全。我最早写过一个全流程开发技能把规划、写码、测试、审查全塞进一个文件里结果 Codex 加载之后一顿操作猛如虎中间没有任何确认点改得面目全非。后来我拆成了多个单一职责的小技能让 Codex 根据阶段按需加载效果立刻好多了。这跟写代码的单一职责原则是一模一样的道理。第四个坑是忽略 AGENTS.md 的指路作用。技能装好了但如果AGENTS.md里没有写明技能库的位置Codex 在新项目里可能根本感知不到这些技能。我现在的做法是在每个项目根目录的AGENTS.md里加一行说明技能目录的路径并在开头提示本项目可使用以下技能这能显著提高技能的加载率。最后再分享一个小习惯我每隔一段时间会翻一遍 superpowers 仓库的更新记录因为技能这种文件的迭代非常快作者经常会根据真实使用反馈调整步骤顺序和描述措辞。本地克隆的版本如果太久不更新行为会跟不上上游的设计意图。我现在用的是一个简单的更新流程进到技能目录下拉最新代码然后重新跑一次安装脚本顺手核对一下AGENTS.md里的技能清单有没有变化。这套安装验证更新的闭环是我用 superpowers 大半年下来觉得最稳妥的维护方式了。