最近两个月我把 OpenAI 的 Codex CLI 当主力编码工具在用日常提交、跑测试、改 bug 基本都交给它。但用久了你会发现一个很尴尬的事模型本身能力挺强可它总是“没有章法”——让它做一件事它要么一口气全部干完不给你留任何检查余地要么做到一半停下来问下一步你还得反复解释同一句话要么闷头按它自己的“审美”改代码最后出来的东西跟你的项目风格完全不搭。后来我把 superpowers 这套技能框架接到 Codex 上这个问题解决了大半。它不是给 AI 再叠一层魔法而是把“遇到什么场景、按什么顺序、做什么事”固化成一整套可复用的技能文件让模型不再是随机发挥而是像老员工一样照章办事。简单说superpowers 是一套给 AI 编码代理用的“技能包 工作流”管理框架可以配合 Codex CLI、Claude Code 这类工具使用。它把工程方法论测试先行、小步提交、bug 修复流程、代码审查规范等写成 markdown 格式的技能文件再由 Codex 在每次会话中按需读取和执行。这篇文章我会从设计思路、安装配置、技能文件编写到常见坑位完整拆一遍这个项目适合那些已经受够了 AI 胡写一通、想把它真正“调教”成团队成员的人参考。1. 项目定位与设计思路1.1 superpowers 的本质技能包不是魔法外挂很多第一次看到 superpowers 的人会误以为它是个“一键增强 Codex 智商”的工具装上之后 AI 就变神了。真不是这样。它的本质是一套分层清晰的方法论文件集合技能Skills、工作流Workflows和元技能Meta-Skills。技能是最小执行单元。一个技能就是一个.skill.md文件里面用 YAML 头部声明“我是谁、什么时候用”正文则是一段给 AI 看的操作步骤。AI 在执行任务时会根据语义匹配决定要不要加载这个技能。工作流则把多个技能串成一条流水线比如“缺陷修复”可以拆成“复现问题 → 定位根因 → 写失败测试 → 修复代码 → 回归验证 → 提交”每一步都对应一个或多个技能。元技能更像“程序入口”比如常用的 begin、continue、debug它们解决的是 AI 编码中三个最头疼的问题怎么开始、怎么继续、怎么排错。所以 superpowers 真正改变的不是模型的推理能力而是把“过程控制权”从模型手里收回到你手里。以前你给 Codex 一句“修复登录接口的 bug”它可能直接甩你一段改动现在你让它走 fix-bug 流程它会先读技能文件按步骤复现、定位、写测试、再修复。行为稳定性提升非常明显。1.2 为什么要给 Codex 加一层“技能”我过去用 Codex 最大的痛点是“上下文遗忘”和“风格漂移”。上下文遗忘很好理解一个复杂任务从开始到结束可能要十几轮对话模型经常做到后面忘了前面定的规范。风格漂移则是说同一个项目里它今天给你输出 2 空格缩进明天就变 4 空格今天记得要写单测明天直接跳过测试。这不是模型“笨”而是提示词里的约束在长对话中被稀释了。解决方案其实很简单把规范和流程外置成文件每次会话强制加载。superpowers 的思路就是如此——它不依赖你在对话里反复重申规则而是把规则沉淀成技能文件。Codex 每次开工前读取 AGENTS.md 或技能索引相当于把团队规范写进了 AI 的“肌肉记忆”。这跟在团队里写 README、写 CONTRIBUTING 是一个道理只不过读者从人变成了模型。用生活类比的话普通 Prompt 是给 AI 一张白纸它想到哪画到哪superpowers 是给了它一份施工图纸加一箱标准件虽然看起来不如自由发挥“有创意”但对工程产出来说可预期、可复用才是第一位的。1.3 核心概念拆解Skill、Workflow、Meta-Skill这三个概念必须分清否则后面写配置容易乱。Skill技能单一场景下的操作步骤颗粒度最小。比如“写一个失败测试”“检查 Git 提交信息是否符合 Conventional Commits”“给 Python 代码补类型注解”。一个技能文件通常只做一件事。Workflow工作流按业务场景组合多个技能。比如“实现一个新功能”可能是“需求澄清技能 → 架构梳理技能 → 测试先行技能 → 小步实现技能 → 提交规范技能”。Meta-Skill元技能不针对具体业务而是管理 AI 行为本身的技能。begin 负责在接手任务时先列 TODO 和计划continue 负责从断点恢复上下文debug 负责在遇到失败时引导 AI 先复现、再定位而不是瞎猜。实操中我建议先别急着自定义把内置的元技能跑通再去写自己的业务技能。因为元技能定义了“AI 怎么开始干活”的默认姿势这个姿势不对后面再多的业务技能都会在执行中跑偏。2. 环境准备与安装2.1 前置条件Node.js 与 Codex CLIsuperpowers 最早是为 Claude Code 设计的后来社区把它扩展到了 Codex CLI。所以安装前你至少需要准备好两样东西Node.js 18 以上建议直接用 20 LTS实测更稳以及已经登录好的 Codex CLI。Codex CLI 本身是 OpenAI 出的开源命令行工具装好之后会在终端里提供一个交互式编码代理会话。如果你之前没用过 Codex强烈建议先单独把 Codex CLI 的基础流程跑一遍比如让它改一个小文件、跑一次测试。因为叠加 superpowers 之后Codex 的行为会变得“多步骤化”如果你连基础会话都没见过大概率会分不清哪一步是 Codex 原生行为、哪一步是技能在起作用出了问题也不好排查。检查环境时可以跑一下node -v npm -v codex --version三个命令都有输出再往下走。2.2 安装 superpowers安装方式很简单全局装 npm 包就行npm install -g superpowers装完验证一下superpowers --version如果你用的 Codex 版本较新官方也支持通过插件机制安装codex install superpowers两种方式本质没有区别都是把 superpowers 的可执行命令和技能包放到你的用户目录下。装完之后最关键的一步是初始化superpowers init这个命令会在~/.superpowersmacOS/Linux或你指定的目录下生成技能库骨架。不同版本生成的目录结构可能略有差异但通常包含skills/和workflows/两个子目录以及一个index.md索引文件。这里我想强调一个被很多人忽略的点init 之后先不要急着自己写技能先看看生成的默认技能里有哪些。因为这些内置技能本身质量很高而且它们的文件格式就是你自定义技能的最佳模板。先读别人的格式再动笔写自己的踩坑率会低很多。2.3 让 Codex 认识 superpowersAGENTS.md 配置光装好 npm 包不够你得告诉 Codex CLI“每次进入项目会话时去哪个位置加载技能”。这是通过 AGENTS.md 文件实现的。Codex CLI 在启动时会在项目根目录寻找这个文件并把内容注入系统上下文相当于每轮对话都带上这个“工作手册”。你需要在项目根目录创建或编辑AGENTS.md在里面显式声明 superpowers 的位置# AGENTS.md 本项目的编码任务遵循 superpowers 技能框架。 请先读取 ~/.superpowers/index.md 了解可用技能并根据任务场景选择合适的工作流执行。 不得跳过测试技能直接实现功能。 不得在未运行测试的情况下提交代码。配置好之后随便打开一个 Codex 会话输入一条简单指令比如“列出当前目录结构”你会发现 Codex 的输出里多了一部分“我读取了哪些技能文件”的过程信息。如果出现了说明链接成功如果没出现大概率是 index.md 路径写错了或者 Codex 版本不支持自动读取 AGENTS.md。2.4 Java 项目能用吗语言无关的关键配置热词里有一项是“superpowers java”这里单独说明。superpowers 的技能文件本身是语言无关的它只是给 AI 的通用步骤指令。真正决定“这个技能适不适合你的 Java 项目”的是你写在技能里的命令和上下文。比如说你在一个 Maven 管理的 Java 项目里用 superpowers测试先行技能里的步骤写成“运行测试并确认失败”这本身没有问题但如果你不告诉 AI 项目的测试命令是mvn test它可能会默认去执行npm test或者pytest。所以我的建议是在 Java 项目的 AGENTS.md 里把构建命令、测试命令、目录结构约定先写清楚再加载 superpowers。这一点适配好之后Java 项目用起来和 Node/Go 项目没有本质区别。3. 核心文件格式与技能编写3.1 一个技能文件的完整骨架直接看一个最简技能文件我以“测试先行”为例--- name: write-tests-first description: 在编写任何功能实现之前先创建一个失败测试来驱动开发TDD。 when_to_use: 当用户要求实现新功能、修复缺陷或需要新增一段业务逻辑时。 version: 1.0.0 --- # Write Tests First 1. 先阅读项目现有测试文件确认测试框架与命名约定。 2. 为要实现的函数或模块编写一个最简测试预期失败。 3. 运行测试命令确认失败原因与预期一致说明测试覆盖了正确行为。 4. 实现最小代码来让测试通过。 5. 再次运行完整测试套件确认无回归。 6. 将测试代码与实现代码分两个 commit 提交。关键点有三处。一是 YAML 头部的name和description必须认真写。AI 寻找技能时靠的就是语义匹配如果 description 太泛比如“写代码”它会在任何任务里都加载这个技能导致上下文被无关步骤塞满如果 description 太窄它又永远不知道该什么时候用它。我自己的经验是把触发条件讲得越具体越好甚至可以写明“当用户说 X 或 Y 关键词时使用”。二是正文的步骤要拆到“AI 可以直接执行”的粒度。你不能写“进行充分测试”而要写“运行mvn test确认失败输出失败原因”。模型对模糊指令的理解会发散但对明确命令的服从度很高。三是可以在正文里加“禁止事项”。比如“禁止在测试通过前提交代码”“禁止修改与当前任务无关的文件”。这些负面约束对防止 AI 越权改动非常有效。3.2 Workflow 文件把技能串成流水线单个技能的威力有限工作流才是 superpowers 的重头戏。一个工作流文件的格式类似--- name: fix-bug description: 从缺陷报告到修复完成的完整流程适合用于可复现的 bug。 --- # Fix Bug Workflow 1. 调用技能 reproduce-bug尝试复现用户描述的问题。 2. 如果无法复现向用户请求更详细的步骤与期望行为停止执行。 3. 调用技能 locate-root-cause定位可能导致问题的代码位置。 4. 调用技能 write-tests-first为缺陷行为编写失败测试。 5. 修复代码让测试通过。 6. 运行全量测试调用技能 review-changes 检查改动范围。 7. 按约定格式提交代码。工作流文件本身也是 markdown它不需要写具体怎么操作只需描述“先调用哪个技能再调用哪个技能”。这就像 RPA 流程里编排节点一样AI 在执行时会依次加载对应技能文件作为上下文。这里有个设计要点工作流里最好设置“停止条件”。比如第二步“无法复现就向用户请求信息并停止”这能避免 AI 在信息不足时硬猜。很多翻车场景都是 AI 在没复现问题的情况下就开始改代码最后改了一个不存在的问题。加上停止条件等于给 AI 装了一道刹车。3.3 技能之间的引用与上下文控制技能可以嵌套引用比如fix-bug工作流里引用了locate-root-cause技能而这个技能本身又可以引用read-logs技能。但这里必须强调一个教训引用链一旦过长上下文就会爆炸。Codex 每次加载技能文件都会把文件内容塞进上下文窗口。如果一次任务要加载五六个长技能每轮对话都带着好几千 token 的指令模型的注意力会被严重稀释反而更可能忽略关键约束。我个人的取舍标准是单次任务最多加载 3~4 个技能文件技能正文不超过 60 行超过 60 行就必须拆分子技能。另外不要让技能之间形成循环引用。技能 A 引用技能 B技能 B 又引用技能 AAI 会陷入无限套娃表现为输出内容反复重复同一个步骤。这在 YAML 层面没法静态检查只能靠你在编写时留意依赖方向从抽象到具体单向引用。3.4 内置技能包的取舍superpowers 初始化后自带了不少技能涵盖代码审查、Git 规范、调试、重构等。但我不建议全量保留。原因很简单技能越多AI 在做语义匹配时越容易选错。它可能把一个“优化性能”的任务误匹配给“重构代码结构”的技能虽然都是优化但操作路径完全不同。我实际操作时会把内置技能分成两批第一批是元技能begin、continue、debug、improve全部保留第二批是业务技能只挑当前项目真正会用到的比如write-tests-first、write-good-commit-message、refactor-with-caution其余暂时移出技能目录。记住一个原则技能库是“少而精”才有价值。装了一百个技能却总是选错不如只放十个但每个都精准命中场景。4. 实操从创建技能到驱动 Codex 干活4.1 第一步初始化并导入内置技能包假设你已经完成了第二章的安装现在终端里输入superpowers init superpowers installinstall子命令会从内置仓库或 GitHub 拉取官方推荐技能包。执行完看一眼~/.superpowers/skills目录ls ~/.superpowers/skills你应该能看到每个技能都是一个.skill.md文件并且这些文件都带完整的 YAML 头部。随手打开一个重点看它是怎么描述“何时使用”的——因为接下来你写自定义技能时要模仿的就是这个语气和粒度。4.2 第二步写一个你自己的技能文件假设你维护一个 Java 项目团队要求新增接口时必须先补充 OpenAPI 文档再写实现。这个流程很适合做成技能。--- name: api-contract-first description: 在实现新的 REST 接口之前先更新 OpenAPI 描述文件确保契约先行。 when_to_use: 当添加新接口、修改请求/响应字段或调整现有 API 路径时。 --- # API Contract First 1. 定位项目中 OpenAPI 描述文件通常是 src/main/resources/openapi.yml。 2. 在文件中添加或修改接口定义包括路径、请求体、响应码与响应体。 3. 运行 mvn validate 确认 OpenAPI 描述文件语法正确。 4. 根据契约生成 DTO 类如果项目使用了 openapi-generator。 5. 最后才实现 Controller 与 Service 逻辑。 6. 检查最终改动是否只涉及该接口相关文件。写完后保存为~/.superpowers/skills/api-contract-first.skill.md。注意文件后缀只要是.skill.md即可superpowers 会自动识别。然后重启 Codex 会话让它加载最新的技能清单。这一步很多人会忘记导致新技能不生效结果花了半天排查才发现是缓存问题。4.3 第三步在 Codex 里触发技能启动 Codex CLIcodex输入任务描述为新用户注册功能添加一个 REST 接口按团队契约先行流程执行。接下来观察 Codex 的行为。如果配置正确你会看到它先说出“我将按 api-contract-first 技能执行”然后先打开 OpenAPI 文件而不是直接创建 Controller。那种“先改文档、再跑校验、最后写实现”的顺序感就是技能在起作用。这里分享一个实测的小技巧如果你希望某个技能“必定被触发”可以在 AGENTS.md 里加一句“所有涉及新接口的任务都必须先加载 api-contract-first 技能”。把上下文级的强约束写进 AGENTS.md比依赖模型的语义匹配要可靠得多。我遇到签了合同式的需求时就用这种“硬指定”来保证技能执行率。4.4 第四步用 begin / debug 元技能控制过程两三个技能跑通之后强烈建议把元技能用起来。尤其是 begin 和 debug。begin 的用法是启动 Codex 后输入/begin 实现用户登录功能它不会立刻进入编码而是先输出一份 TODO 计划并把计划拆分成几个阶段。你确认计划没问题再让它逐条执行。这一步相当于给 AI 加了“先计划后执行”的硬约束有效避免了它闷头乱写。debug 则是我个人救命级别的技能。遇到测试失败时输入/debug 测试 testLoginShouldSucceed 失败了它会按“复现 → 定位 → 假设 → 验证 → 修复”的顺序走而不是直接改代码。过去我手动干预 AI 修 bug 时最烦的就是它在没有复现的情况下就给出“可能原因”然后盲目改。debug 技能把这条路径彻底堵死了——它会在复现失败时停下来向你索要更详细的信息。4.5 第五步提交代码时的技能组合git 提交规范是最容易见效的技能场景。你可以创建或保留内置的write-good-commit-message技能让 AI 在提交前先运行测试再查看 diff再按 Conventional Commits 规范生成提交信息。实测下来这能让提交记录从“修了点东西”直接升级到“fix(auth): 修复刷新 token 时的竞态条件”代码审查效率提升一大截。整个串起来的流程长这样begin建立 TODO 计划。实现阶段自动匹配write-tests-first和api-contract-first。测试阶段会运行全量测试。提交阶段自动调用 commit 技能先审查 diff 再提交。四条技能织成一张网AI 的行为立刻变得有纪律。5. 常见问题与排查技巧实录5.1 安装后命令找不到装完superpowers却提示“command not found”这基本是 npm 全局 bin 目录不在 PATH 里。先用npm bin -g查看全局 bin 路径然后把它加到 shell 配置中。macOS 上经常是/opt/homebrew/bin或/usr/local/bin。这个坑很烦但一次配置就永久解决。5.2 Codex 不加载技能路径都配置好了Codex 却像没读过 AGENTS.md 一样我行我素。这时先确认三件事AGENTS.md 是否在项目根目录文件编码是否为 UTF-8Codex 版本是否支持自动读取 AGENTS.md。前两项好排查第三项在旧版本上确实不支持升级 CLI 即可。还有一个隐蔽的问题如果你开了多个 Codex 会话新技能必须在新建会话中才会被加载旧会话里的上下文不会刷新。5.3 技能匹配不准确明明写了api-contract-first让 Codex 加个按钮它却跑去更新 OpenAPI 文件这说明 description 写得太宽泛。我在 3.1 里说过的“触发条件要具体”就在这里起作用。改法是把when_to_use收敛到“添加新接口、修改请求/响应字段”这类精确场景甚至可以直接写明“不包括前端页面改动”。5.4 项目语言与技能命令不匹配这是 Java 用户最容易踩的坑。内置技能沟通常使用通用的“运行测试”描述但你的项目是mvn test而不是npm test。superpowers 本身不会替你判断语言它只会把技能指令原样交给模型。解决办法有两个在 AGENTS.md 里写清构建命令映射或者把内置技能复制一份把命令替换成 Maven/Gradle 版本。我实际采用后者因为技能文件变成了“项目专属”后续维护时不会污染其他项目的技能库。5.5 上下文过长导致 AI “失忆”加载了大量技能文件后Codex 的回复质量和技能遵循度会同步下降。这不是 superpowers 的问题而是上下文窗口的物理限制。排查时可以用一条测试指令判断“请告诉我当前会话加载了哪些技能。”如果模型只能准确报出一两个那就说明上下文已经超载。对策是精简技能目录或把你的业务技能拆成一页以内。症状可能原因解决方案命令找不到npm global bin 不在 PATHnpm bin -g找到路径并加入 shell 配置技能完全不生效旧会话缓存 / AGENTS.md 路径错误新建会话检查路径与 UTF-8 编码技能频繁选错description 触发条件太宽收敛 when_to_use写明精确触发场景Java 项目跑了 npm 命令技能文件命令过时复制技能并替换为 Maven/Gradle 命令AI 渐渐不听指令上下文被技能文件塞满精简技能数量单次保留 3~4 个Codex 升级后行为变化新版本改动会话逻辑锁版本或关注官方更新说明5.6 排查技巧让 Codex 自己报告用了哪些技能这是我最近才学会的排查方法。在 AGENTS.md 里加一条规则“会话开始时请说明你将优先使用哪些技能并在每次切换技能时用一句话告知用户。”这会让 Codex 在执行任务时持续输出“正在加载技能 X因为任务需要 Y”。一旦我发现它加载了一个无关技能立即就能判断是 description 匹配出了问题不用再云里雾里地猜。这个习惯对长期调教技能库非常有价值。在个人实践中我最满意的并不是某个具体技能而是 superpowers 带来的“过程可观测性”。以前我调教 Codex 靠反复改提示词改完也不知道哪句话起了作用现在技能文件本身是文本我可以 diff、可以回滚、可以分享给团队。每次 Codex 行为不对劲打开技能文件改几行描述、加一条禁止项效果立竿见影。它把一个本来只能靠“玄学调参”的环节变成了像维护普通配置文件一样可控的事。如果你也想试我建议起步别贪多先挑三个最痛的点下手提交信息规范、测试先行、bug 修复流程。用两周时间把这三个技能打磨到自己满意再推下一个。把 Codex 从“能写代码”调教到“懂规矩、按流程、可预期”这才是 superpowers 真正值回票价的地方。