先说个有意思的事。我从今年年初开始重度使用 Codex CLI 做日常开发，最初的感觉是：这玩意儿真聪明，但聪明和好用是两回事。你让它写一个函数、补一个单元测试，它干得比大多数人都利索；可一旦你让它“完整地做一个功能”，它就开始自由发挥了——想到哪写到哪，边界不做，异常不处理，测试更是有一搭没一搭。像是一个基础扎实但完全没经历过正规团队协作的实习生，需要你不断在边上拽着它，它才能走上正道。后来我找到了一个叫 Superpowers 的开源项目，简单说就是一套专门给 Codex CLI 这类终端编程代理用的“技能包框架”，通过一组设计好的 Markdown 技能文档，强制 AI 在动工前先理需求、再定方案、先写测试、小步实现、最后重构。用了几个星期之后，我最大的感受是：它没有让 Codex 变得更聪明，但让 Codex 变得更靠谱了。这篇文章就写写我实际把它跑起来、用起来的过程，以及那些文档里没写清楚的坑。

如果你也在用 Codex CLI、Claude Code 这类命令行 AI 编程工具，正觉得“能力是有的，但流程总是一团乱麻”，那这篇文章应该能帮你省下不少折腾时间。

1. AI 编程助手的处境：能力很强，流程很乱

1.1 Codex CLI 到底缺了什么

先把话说清楚：Codex CLI 本身的能力，放在终端类编程代理里是第一梯队。它对仓库上下文的感知、工具的调用、改动的执行都很成熟，很多时候你真能从终端里得到让人一愣的回答。但问题恰好出在这里——它采用的是“问题-回答”的单轮决策模式，每一轮都是独立的，没有“全局施工计划”。

我打个比方你就明白了。普通对话式 AI 像是问一个经验丰富的师傅：“这个墙怎么刷？”师傅能给你讲得头头是道。但 Codex 这些工具被要求直接上手干活时，它更像一个有着极强执行力但没有项目经验的工人，你让它刷墙，它拿起刷子就刷，不会先检查墙体基层，不会问你要什么颜色的漆，也不会在刷完后帮你清理现场。

代码任务天然是分阶段的：先拆解需求，再设计数据结构，然后写测试确定行为，再写最小实现让测试通过，最后重构整理。这套流程在真实团队里靠的是开发流程规范、代码评审、结对编程来保证，但在 Codex CLI 里，缺的就是这一层“软约束”。它的能力不需要再变强，它需要的是有人告诉它“接下来该用哪套流程”。

1.2 社区给出的解法：流程即技能

Superpowers 这个项目的思路很直接：把工程流程写成 AI 能读懂、能主动调用的“技能文档”。这不是什么高深的技术，就是一组有结构的 Markdown 文件，每个文件定义一个技能，比如“用 TDD 开发一个功能”“写一次重构计划”“做代码评审”“调研一个技术方案”。文件里写清楚这个技能适用于什么场景、前置条件是什么、执行步骤是什么、每一步的输出标准是什么。

真正有意思的是它的读取机制。你会在项目根目录放一个AGENTS.md，里面写清楚“这个项目使用了什么样的技能体系”，并告诉 Codex：在你开始做任何事情之前，先到指定目录去查阅相关技能，如果发现当前任务匹配某个技能，就必须按技能里写的步骤走。

结果就是，你不再需要每次都在 prompt 里反复叮嘱 AI“先写测试、先想方案”，而是让它在动手前自己去翻“施工手册”。一旦它养成了这个习惯，产出的代码质量会稳定得多。

1.3 它和 Prompts/规则文件的本质区别

可能你会想：这不就是写几个规则、放进 CLAUDE.md 或者AGENTS.md吗？我自己也写过不少这类规则，但效果都不太理想。原因很简单：规则文件写的是“禁止什么”“应该什么”，都是静态约束，而工程流程是动态的、分步骤的，天然不适合用一条条禁令来表达。

举个例子。你在规则里写“所有重要功能都必须先写测试”，AI 看到这句话，知道有这个要求，但具体到“这个功能该怎么写测试”“写到什么程度算完成”“写完测试之后下一步干什么”，它仍然没有一个清晰的行动路径。于是最常见的结果就是：AI 象征性地写了一个测试，然后自顾自地实现完了所有功能，步骤上看似遵守了，实质上流程完全走样。

Superpowers 的不同在于它把规则变成了“调用指引”：一个技能文件本身就是一个独立的任务执行流程，AI 一旦判定当前任务匹配某个技能，就把自己的后续行动切换成“执行技能步骤”的模式。这比一百句“你要怎么做”有效得多。

2. 把 Superpowers 跑起来：从安装到项目内配置

2.1 环境准备：Node 版本和 Codex CLI 登录

动手之前先把环境捋一遍。Superpowers 本身依赖 Node.js 运行环境，我当时踩过一个小坑，就是本机 Node 版本停留在 18，装完之后有部分脚本跑不起来。建议你提前装 Node 20 以上，最好顺手用一个 Node 版本管理工具，避免跟系统里其他项目打架。

然后是 Codex CLI 本身的准备。这一步不复杂，但要确认你已经在终端里完成登录认证。怎么确认？直接运行codex随便问一句话，能正常回复就说明认证没问题。如果 codex 还没装，按官方文档先装好，这里我不展开。

2.2 克隆仓库和运行安装脚本

接下来把项目拉下来。Superpowers 的仓库我建议 clone 到一个独立目录，而不是直接丢进项目仓库里。原因有两个：一是安装脚本会创建一些全局软链接和辅助文件，放在项目里容易污染 Git 状态；二是这样你在多个项目之间用，只需要配置一次。

git clone https://github.com/obra/superpowers.git ~/superpowers cd ~/superpowers ./install.sh

这个安装脚本做了几件事：把技能文件复制到你的全局配置目录，还会根据你当前使用的 AI 工具做相应配置文件的写入。我当时用的就是 Codex CLI，所以它直接把AGENTS.md这类入口文件放到了对应的配置位置。

装完之后，脚本会在终端打印一行说明，告诉你入口文件在哪里、接下来该做什么。如果你没看到任何提示，多半是环境变量没配对或是分支切换问题，先检查 Node 版本，再重跑一次。

2.3 在具体项目里挂载技能入口

真正的关键一步在项目里：你需要在自己项目的根目录创建或修改AGENTS.md，让 Codex 在进入这个项目时能感知到技能体系。

我实际的配置大概是这样的：

# 项目级 AI 工作约定 本仓库遵循基于技能的任务执行模式。任何任务开始前，请先阅读全局技能目录： - `~/superpowers/skills/*.md` 下的技能文档 - 若任务匹配某技能的描述，则必须严格按照该技能定义的步骤执行

这里有个细节要注意：Codex 在读指令时，是按“特定性覆盖一般性”的规则来处理的。项目根目录的AGENTS.md会覆盖全局配置里的同名内容，子目录里的AGENTS.md又会覆盖根目录的。所以不要在主目录写一套、子目录又写一套，除非你确实是有意为之。

2.4 检查安装是否成功

一个很实用的验证方法是：让 Codex 自己解释这个项目的工作方式。运行时问它“这个项目的开发流程是什么样的？”，如果它能在回答里提到“先查阅技能、再按技能步骤执行、支持 TDD 流程”，说明技能体系已经成功加载。如果它一脸茫然地回答“这是一个普通的代码仓库”，那说明入口文件大概率没被读到，回到上一步检查路径。

3. 技能文件是怎么“驱动”AI 的：原理拆解

3.1 一份技能文档的内部结构

既然技能文档是核心，那它的内部长什么样？我自己打开看过，标准化程度很高，基本由四部分组成：

第一部分是 frontmatter，用 YAML 格式写元信息，包括技能名称、描述、适用场景。这部分非常重要，因为 Codex 是靠它来做技能匹配的。描述写得好不好，直接决定 AI 能不能把当前任务跟技能对应上。

第二部分是触发条件，明确列出“什么时候该用这个技能”。比如 TDD 技能会写“当需要开发一个具有明确行为的业务功能时”“当用户要求先写测试再写实现时”。

第三部分就是核心执行步骤。每一步步都写得很具体，不只是“写出测试”这种口号，而是“列出你理解的验收条件，与用户确认后再开始”“为每个验收条件写一个测试，运行并确认失败”。这种颗粒度才是关键。

最后是完成标准，告诉 AI 什么时候才算真正做完，避免它在写完代码后直接宣布胜利。

3.2 自动匹配的机制和它的边界

我一开始以为这套东西有什么智能调度系统，后来发现其实没有。它就是靠 Codex 自身的上下文理解能力：入口文件告诉它“有技能目录这回事”，它自己在接任务时会到目录里翻一翻，找到描述最匹配的技能文件，然后照着做。

这个机制有一个天然的好处——零插件、零 API、零后台服务，纯粹考的是“文档写得清晰，AI 自然会读”。但也有一个明显的边界：AI 不是每次都会主动去翻技能文件。尤其是你给的任务非常具体、又没在项目入口里强调技能体系时，它很可能直接跳过查技能这步，凭“印象”就开始干活。

所以我在自己的实际配置里，会在入口文件开头写一句类似“每次任务开始时，第一步永远是查看技能目录”的话。因为从实际经验来看，Codex 对这种流程性指令的遵循度非常高，只要你把“查技能”设定为诊断流程的第一步，它就不会跳过。

3.3 多个技能如何串成一条工作流

单个技能解决单个阶段的问题，但真实开发任务是需要多个技能接力完成的。Superpowers 处理这个问题的思路也很朴素：一个技能文档可以在它的步骤里指向另一个技能。

比如“实现功能”这个技能，它会写：先调用“需求分析”技能澄清需求；需求确认后，调用“TDD 开发”技能进行测试先行开发；实现完成后，调用“代码评审”技能进行自我检查。你看到这里就明白了，技能之间不是孤立的，而是通过这种引用关系，自然形成了一条完整的工作流。

对一个没有接触过这种模式的开发者来说，初看会觉得有点绕，但用一段时间后你会发现这其实非常贴近真实工程实践——一个专业的开发者，本来就是这样组织自己的工作节奏的。

4. 实战记录：用 Superpowers 推进一个 Java 功能的完整流程

说再多原理不如来一次实打实的演示。我这边正好有一个实际项目，用 Spring Boot 写的一个内部工具服务，功能是提供一个接口，按条件查找用户设备信息并做分页返回。这个需求在我在没有加载 Superpowers 之前试过一次，Codex 的表现是典型的“快速跑通”：直接生成 Controller、Service、Mapper，一把梭写完整套，但边界情况几乎没有处理，设备状态过滤条件也漏了。这次我全程启用 Superpowers 技能体，想看看流程会有什么不同。

4.1 第一步：它没有直接写代码，而是先做需求澄清

我在终端里说了一句：“新增一个设备查询接口，按照设备类型和在线状态筛选，支持分页，返回设备编号、名称、最后在线时间。”

如果不是技能模式的 Codex，这句话已经足够它开写了。但加载了技能之后，它先做了一件事——主动返回了几个澄清问题：筛选条件之间是 AND 还是 OR、分页参数用什么风格、最后在线时间的空值怎么处理、是否需要对设备类型做枚举校验。你看，这些问题没有一个是瞎问的，全是后边写代码时会真实遇到的歧义。

它跟我在终端里来回确认了几轮，把行为边界彻底定了下来，最后输出了一版明确的“验收条件清单”，然后才宣布“进入下一阶段”。这一步在传统开发流程中对应的是需求评审，以前我跟 AI 协作时从未有过这种体验。

4.2 测试先行：这次是真的先写测试

接下来我注意到它在终端里没有直接打开 Service 实现类去写代码，而是先建立了一个测试文件。它会为上面确认过的每个验收条件写一个对应的测试用例，最开始所有测试都会跑，确认失败，然后再开始写实现。

这里要说明一下，在 Java/Spring Boot 项目里，写测试比在动态语言项目里要“重”一些——需要准备 Mock 数据、初始化测试上下文。我原以为它会在这里偷懒，但实际它做得很认真：先搭了一个内存数据库的测试环境，构造了设备数据，再逐个验证查询条件。所有测试先跑一遍，确认有失败项，才进入实现阶段。

4.3 最小实现与测试通过

进入实现阶段后的行为也跟以前明显不同。它没有一次性把查询逻辑、分页、异常处理全塞进去，而是一个接一个地让测试变绿。写一个方法，跑一次测试，发现某个条件没通过，再补上，再跑。整个过程我就是在终端里看着它自己循环“读失败信息—修代码—重跑测试”。能感受到它是有意识地在“小步前进”，而不是一步到位。

在某个测试用例里，它一开始漏掉了“设备类型为空时返回全部设备”这个分支，测试红了。放在以前它可能会直接修掉断言，或者干脆把这个用例删掉，但技能模式下的它认认真真地在实现里加了一个空值判断，重新跑通全部测试。这种“尊重失败用例”的意识，正是真实开发流程中最基础最重要的素养。

4.4 重构与自我评审收尾

全部测试变绿之后，它没有立刻说“任务完成”。下一步是重构：把测试代码里重复的设备构造逻辑抽了个方法，把 Controller 层跟 Service 层的参数校验职责理顺。重构完成后，它重新跑了一轮完整测试，确认没有破坏行为，最后给我输出了一份简短的改动摘要。

在整个过程里我能感受到，它执行的其实不是一个“写代码”的任务，而是一个“用 TDD 流程交付软件”的任务——后者才是一个软件工程师真实的日常。这就是 Superpowers 这套技能框架对我的项目最有价值的改变。

5. 使用中的关键坑位与减负技巧

5.1 模型选择会直接影响流程遵循度

一个很现实的问题：技能流程能否被严格执行，跟底层模型本身的能力边界有关系。我实测下来，更强的推理模型对技能步骤的遵循度明显更高，而一些小模型很容易在步骤中段“走神”——可能读完了技能文档，但写着写着又回到了自由发挥状态。

所以如果你发现技能模式不稳定，先别急着怀疑配置，大概率是当前模型的任务跟随能力达不到要求。我的建议是：使用 Codex CLI 时优先选择支持度最好的旗舰推理模型，如果因为成本想换轻量模型，那就得接受流程执行会打折扣的现实。这不是 Superpowers 能解决的问题，任何靠文档驱动 AI 的框架都会有这个前提。

5.2 技能文件的路径别乱动

技能文件安装好之后会在全局目录里稳定驻留。安装脚本还会创建一些辅助符号链接，如果你手贱改动了目录结构、重命名了目录、或者把它挪到了有空格和特殊字符的路径下，就可能出现技能文件加载失败的情况。症状是：Codex 在开始任务时完全不提技能目录，直接干活。

排查思路也不难：先确认项目入口文件里写的路径，跟技能文件实际所在路径是否完全一致，注意结尾斜杠、符号链接是否有效。我自己遇到过几次，都是因为重装系统后技能文件路径变了，入口文件里还是旧路径，一路排查就能发现。

5.3 多会话协作时记得用好工作日志

Superpowers 里还有一个值得单独拎出来的技巧：让 AI 在工作时维护一个简单的进度日志。说白了就是在实现较大功能时，要求 AI 把“已完成的步骤、当前所处阶段、下一步行动”记录下来。

这个习惯在单次对话里看不出什么价值，但在两种情况下特别有用：一是 Codex 的会话上下文一旦超限需要继续开新会话时，这些日志就是下一段上下文最重要的锚点；二是在多文件、多阶段任务中，它能防止 AI 自己“转头忘记”前面的约定。现在我已经习惯了在每个项目里用这个模式，明显发现代码交付的稳定性提高了很多。

5.4 token 消耗的节省与消耗两端

最后聊一个大家都会关心的点：token 消耗。加载技能框架之后，Codex 每次任务开始都可能多读几个技能文件，这在有明显匹配的情况下可以接受；但如果每次都很模糊，它会反复地在技能目录里“翻找”，这就会拉高消耗。我优化后的做法是：在入口文件里列出最常用的三四个技能及适用场景，相当于预先给 AI 打了一个目录索引，让它精确查找，而不是漫无目的地遍历所有技能文档。

至于节省出来的价值，那远比多消耗的 token 划算——因为流程化的 AI 几乎不会写出“跑不通的大版本代码”，你省下的是大把的 review 和返工时间。对于我这种重度使用者来说，这笔账怎么算都是值的。