先说个有意思的事。我从今年年初开始重度使用 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 和返工时间。对于我这种重度使用者来说这笔账怎么算都是值的。