说实话我最近已经被命令行 AI 编码代理搞得又爱又恨。爱的是它写工具脚本、补单元测试确实快恨的是但凡任务稍微涉及一点全局理解——比如让 Codex CLI 去改造一个没人维护的老模块——它就像个刚入职的热血新人上来就动手改完一跑测试红了一片。后来我在 GitHub 上刷到 Superpowers 这个项目花了一个周末把它接入到我的工作流里这才发现问题不全在模型而在我们根本没给代理一套如何做工程的行为框架。这篇文章就把我的完整使用过程拆开讲Superpowers 到底是什么、它的工作机制怎么设计、怎么配合 Codex CLI 落地以及我实际用下来哪些地方真香、哪些地方必须小心。1. 当 AI 代理不再只是代码生成器Superpowers 的定位是什么先说我最直观的感受。以前用 Codex CLI 写一个独立的小函数它表现像天才但把它扔进一个几千文件的仓库里让它帮我找到订单模块的重复逻辑并合并它经常给我交来一份结构漂亮的方案但里面引用的文件路径根本不对或者把另外一处正在被使用的公共方法给顺手删了。这不是模型蠢而是它缺少一个合格的工程师在面对任务时天然具备的几步动作先搞清楚上下文、再确认约束、然后才动手最后还要跑验证。Superpowers 这个项目本质上就是把这些工程动作做成了一组可持续加载的技能文件让代理在接到任务时按流程走。1.1 先说说命令行编码代理的三个典型毛病我见过的翻车现场大致可以归成三类你可以对照一下自己有没有遇到过。第一个是缺乏上下文探索。代理拿到一个 issue 描述经常直接跳到它认为最相关的代码文件里开始改完全不看调用方、不搜历史改动、不查测试覆盖。对小型代码库这可能还好但在稍微大一点的项目里它改的往往是表面症状问题根子在三层调用之下的另一个模块里。第二个是不做验证闭环。它告诉你改好了但你问它跑测试了吗它会说我没找到测试命令。更常见的版本是它自己在脑子里推演了一遍觉得逻辑正确就不再实际执行。对 AI 代理来说想象里的正确和真实的正确之间经常隔着一大堆编译错误和隐藏的边界条件。第三个是不遵守项目约定。每个团队都有自己的代码风格、目录组织和约定俗成的写法比如错误处理统一用某个返回结构、数据库访问必须走 repository 层。代理不知道这些的时候写出来的代码看着能用但和整个项目格格不入。1.2 Superpowers 解决的核心问题后来我才理解这几个毛病的共同根源是我们在用生成答案的思路去驱动一个应该执行过程的代理。你给模型一个大 prompt让它一次输出最终方案它当然倾向于一步到位跳过中间那些不可见的过程。Superpowers 的思路反过来了。它提供的是一个行为框架代理不是只给你结果而是像真实工程师那样先研究再行动行动完再验证。我自己理解它像是给代理装了一个项目操作系统的调度器——不同的技能Skills就是不同的 App接到任务后先判断该启动哪个 App按里面的流程一步步执行并且把每步结果记录下来。1.3 一个很容易踩的误区以为它是某个具体工具我最初以为 Superpowers 是一个独立的 CLI 工具装完就能用后来发现理解错了。它更像是一套结构化的技能包 工作流约定运行载体是 Codex CLI、Claude Code 这类命令行编码代理。代理本身还是那个代理但因为它先读到了 Superpowers 提供的技能说明书行为方式会明显不同——从一个直接给答案的人变成一个先立规矩再干活的人。适合用它的是每天都在命令行里和编码代理打交道、并且手上确实有多个非 toy 项目的开发者。如果你只是偶尔让 AI 写个一次性脚本那确实没必要上这套东西反而会觉得流程太重。2. 工作引擎拆解Superpowers 的先探索、后行动、再复盘循环我刚开始用的时候比较惊讶的是它并不神秘。Superpowers 没有用任何黑魔法它靠一套非常朴素的执行循环让代理变得可靠。我把这套循环拆开看发现核心思想就是工程管理教科书里常写的 PDCA 循环只不过被翻译成了代理能执行的指令。2.1 一个完整的超能力工作流是怎么跑的拿一次典型任务来说我让代理去修复支付回调里的并发问题。没有 Superpowers 之前它大概率会直接打开回调文件开始分析接入了 Superpowers 之后它的执行路径会长这样Research研究先扫描项目结构搜索支付回调相关的所有调用方和数据表列出代码现状与潜在风险点而不是急着下结论。Plan计划基于研究结果生成一份改动计划写明要改哪些文件、影响哪些模块、需要加什么测试。Implement实施按计划逐步修改每完成一个文件就做一次小验证而不是攒到最后统一处理。Verify验证实际运行相关测试、静态检查或编译把输出结果记录下来。Reflect复盘总结这次改动是否符合项目约束有没有遗漏的调用方并把关键结论写回会话文件。这个循环听起来像废话但难就难在让代理愿意执行。Superpowers 做的就是把每一步拆成代理看得懂、也愿意去做的具体指令并且在循环之间嵌入必须输出中间产物的要求。2.2 技能文件给代理看的标准化作业指导书Superpowers 里的每个技能本质上是一份 Markdown 文件或一组文件里面包含这个技能的触发条件、适用场景、操作步骤和验收清单。你可以理解成给代理看的 SOP或者更生活化一点像是给一个厨师的菜谱里面不仅写了菜怎么做还写了什么时候不能做这道菜做完之后怎么自检。我在实际使用中发现技能文件写得越具体代理执行得越稳。比如研究类技能会要求代理先回答几个问题改动的核心目标是什么、当前实现有哪些潜在路径、哪些地方不在本次范围内再允许它进入计划阶段。这个回答完问题才继续的机制有效避免了代理自作主张乱跑。2.3 Session 文件让代理记得自己干过什么这是我喜欢 Superpowers 的一个设计。每次任务开始时代理会创建一个 session 记录文件把任务背景、发现的事实、制定的计划、执行的步骤和验证结果都写进去每个阶段更新一次。这么做的好处太明显了。以前和 Codex CLI 对话聊到第十四轮它基本忘了第三轮确认过的约束现在它会先读 session 文件再根据以前的记录继续。我遇到任务被中断再恢复的场景靠 session 文件能无缝接上不用把上下文重新喂一遍。2.4 为什么过程监督比结果监督更可靠这里我想说一个我自己的判断。模型生成的代码质量稳定性远不如我们想象中高。一次生成的答案可能 90 分下一次同样的问题可能就只有 40 分。问题在于如果你只盯最终输出你根本看不出来 40 分是怎么来的。Superpowers 真正有价值的地方是它把隐性过程变成了显性产物——中间的研究笔记、计划、验证记录都在那。我作为人类审查者不需要完全信任代理的结果我可以打开 session 文件和各个阶段记录看看它的思考路径有没有跑偏。这个过程监督的工作方式我认为比任何再生成一次碰运气的调优都更扎实。3. Codex CLI 集成实战安装、配置与第一次运行理论聊完直接进入实操。我目前的主力组合是 OpenCode 系的 Codex CLI 加 Superpowers。老实说这个项目更新很快你看到的目录结构可能和我当时不完全一样但核心接入思路基本没变——把技能目录暴露给代理并在工作开始时要求它使用这套流程。3.1 安装 Codex CLI 与获取 Superpowers如果你还没有 Codex CLI第一步很简单需要 Node.js 环境npm install -g openai/codex装完以后先跑一次codex确认它能正常工作。这里有个小提示如果你在公司内网或代理受限环境Codex 的登录验证和大模型请求都算在对外网络流量里需要先确认网络策略是否允许。接着获取 Superpowers 仓库。我当时用的是这个地址如果仓库迁移了以项目 README 上的最新地址为准git clone https://github.com/jesse-vincent/superpowers cd superpowers仓库结构不复杂核心部分是 skill 文件按技能类型分了目录里面每个 Markdown 文件就是一个技能。我一般先花十分钟浏览一遍有哪些技能名字后面触发的时候心里有数。3.2 让 Codex 在任务中读取技能文件这一步是核心。Superpowers 不会自动注入到 Codex 里你必须明确告诉代理哪些文件是你的工作规范。我采用的方式是在项目根目录放一个AGENTS.md文件把技能目录引用进去内容大致是这样# 项目工作约定 - 本项目使用 Superpowers 工作流。 - 当任务涉及需要诊断、重构或实现复杂功能时先读取 ~/superpowers/skills 下的对应技能文件然后按技能中的步骤执行。 - 每个任务开始前创建 session 文件记录研究结论与计划每完成一步更新 session 文件。如果你愿意也可以直接在 Codex 的配置上下文里加入全局指令但我更推荐放项目根目录。原因是 AGENTS.md 是跟着仓库走的团队其他人克隆项目后也会自动生效不依赖个人机器上的配置。3.3 不同项目如何规范路径如果你的项目仓库不属于自己的个人账号或者不能随便放额外文件也可以把技能引用放到~/.codex/config.toml的上下文指令里。大概长这样[model_providers] # 你自己的模型提供商配置 ... [instructions] files [~/superpowers/INSTRUCTIONS.md]这里要特别说一句网上很多教程给了精确的配置字段但我发现 Codex CLI 更新频繁字段名偶尔会调整。最稳的做法是运行codex --help或查看文档确认你当前版本的指令注入方式。我当时花了半小时折腾配置最后发现版本升级后语法已经变了。3.4 第一次运行应该测试什么配置完以后别急着接大任务先用一个中等体量的任务验证整条链路。我当时的自测用例是让 Codex 分析一下某个模块的功能与边界指令这样写请使用 Superpowers 工作流来分析 src/utils/price.ts 的职责边界并输出研究报告。第一次跑完我从输出里看到它没有立刻改代码而是先列出文件结构、搜出调用方、写了一段研究笔记然后才给出结论。那一刻我就知道事成了——因为它终于没有碰代码之前就开始改代码了。另一个观察是 token 消耗会上升。流程变长、中间文件变多每次任务的 token 用量大概比直接问要高 20%-40%。如果你用的是按量计费的大模型这个成本要提前算进去。但在可靠性收益面前我个人认为这点额外开销是完全值得的。4. 我实际用下来的应用场景、效果与翻车教训理论和配置都讲完了这一部分我挑了几个真实的实战场景把效果和坑都摊开说。4.1 遗留项目探索最大的惊喜我接手过一个老模块一个服务里有三套几乎一样的订单状态判断逻辑分散在不同文件里。以前这种任务我会自己花一下午读代码或者让代理直接搜关键词然后整理一份相关代码清单。用 Superpowers 的研究技能之后它主动做了这几件事画出模块之间的依赖关系、找出三套逻辑各自的调用入口、对比它们的状态枚举差异、最后产出一份推荐合并顺序的报告。而且因为它全程使用 session 文件记录我发现它某一步对某接口的判断有误时可以直接在 session 里指出来它修正后重跑了后续分析。这种可被纠正的过程价值极大。4.2 用 TDD 流程实现新功能写一个新功能时Superpowers 的 TDD 技能会在代理写任何实现代码之前要求先写一个失败测试。这对不习惯 TDD 的人来说会有点烦但效果立竿见影。我让代理实现一个带过期时间的本地缓存。按流程它先写测试用例覆盖缓存命中、过期、并发读写等场景然后看着测试失败再实现真正代码。这个过程中最让我放心的一点是代理不会在实现到一半时偷偷改测试来迎合代码——技能里有明确要求测试文件必须保持任务开始时的定义。最后跑下来测试全绿而且覆盖了我原本想手动补的边界情况。4.3 重构一个老模块依赖分析与安全网重构是我最担心代理搞砸的场景因为一次改名会连锁影响到所有调用方。Superpowers 给我带来的改变是它把重构分成了两段先做依赖分析再执行迁移。代理会把目标模块的所有直接调用方、间接调用方、测试引用全部列一遍并确认没有遗漏后才开始改名。改完之后它会跑项目的完整测试集而不是只跑相关模块。我遇到过一次它分析遗漏了某个冷门调用方但当时项目里恰好有编译时检查能兜住这也提醒我无论代理流程多完善人类 review 依赖分析结果这一步不能省。4.4 我踩过的坑技能教条化带来的死角Superpowers 不是银弹我也翻过几次车。最典型的一种情况是过度流程化一个只需要改一行配置的任务代理还在先创建 session、写研究笔记、列详细计划输出了一堆和任务无关的过程文档。后来我在使用指令里加了简单任务可跳过完整流程的约定才好一些。第二种情况是多个技能互相冲突。有一次我想做代码优化结果代理同时读取了优化技能和重写技能的执行流程两边都有重写整个模块的倾向差点把一个稳定的模块推倒重来。这个问题后来靠我在 AGENTS.md 里明确任务优先级解决的当技能发生冲突时优先执行研究技能的依赖分析结论。4.5 针对 Java 项目的额外注意点如果你像一些在 Java 技术栈里的朋友一样主要用 Maven 或 Gradle 项目有两点需要额外注意。一是验证成本天然更高。Java 项目的编译和测试比脚本语言慢很多代理每次 Verify 都要等 Maven 跑完一整个模块token 和等待时间都会明显上去。我给 Java 项目配置时有意识地做了裁剪让代理只跑-pl 模块名 -am这类精准构建而不是根目录全量 build。二是类型与框架约束多。比如 Spring 项目里 Bean 的代理模式、MyBatis 的 Mapper 接口代理靠文本理解很容易绕晕。我在 Java 项目的 AGENTS.md 里写明了所有数据库操作必须先查找现有 Mapper 方法不得自行创建 Session这个问题就少多了。5. 给准备入坑的人配置建议和边界认知最后这节是我用了这个小一个月后的沉淀。有些是配置建议有些是我踩过之后才明白的边界。5.1 什么样的代码库获益最大我的经验是单体大仓库、多模块项目、遗留代码这三类场景收益最大。因为这些项目里上下文理解比代码生成重要得多代理缺的不是写代码的能力而是看懂项目的能力。反过来如果你是做十几个独立小脚本的仓库每个脚本几百行业务流程一目了然Superpowers 带来的过程开销反而可能拖慢你。要理性评估自己的场景再决定上不上。5.2 把团队规范改写成自定义技能Superpowers 真正让我喜欢的一点是它允许你扩展自己的技能。我现在已经把团队常用的错误码规范、提交信息格式、模块分层约束都写成了一个自定义技能文件放进去。改写的门槛很低你只需要遵循和其他技能一样的 Markdown 格式写清技能用途再写操作步骤和自检清单。这样代理在动手前会先读这份团队特有规范写出来的代码就不再是看着没错而是符合我们项目风格——这个差距只有在你对比过之后才会意识到有多大。5.3 权限、隐私与代码审查这里必须提醒一句使用这类工具代码内容会发给大模型提供商处理。涉及商业敏感代码的项目一定要确认公司政策允许。我自己的习惯是核心算法模块、未公开的商业逻辑从不丢给这类代理做分析宁可自己花时间看。另外Superpowers 在工作流里会执行 git 相关操作和运行测试命令本质上是有项目写入权限的。我建议你第一次接入时盯紧一点最好先在一个专门的测试分支上跑通几个任务确认它的行为符合预期后再放到主开发分支上。5.4 三条给新手的落地建议如果你打算试我给出最实在的三条建议。第一条先跑通一个小项目再上大仓库别一上来就让它重构核心模块。第二条务必阅读一遍你自己的 session 文件把你的要求写得更明确它是你观察代理思考过程唯一窗口。第三条保持每周翻一次技能仓库的习惯因为这个项目迭代很快社区里会不断有新技能被合入过两周你可能就从里面发现一个刚好能解决你当前痛点的技能。我个人目前的配置方案是项目根目录一份 AGENTS.md技能库目录保持每周同步一次简单的配置修改任务允许代理跳过完整流程。这套方案我用下来最大的改变不是代理生成的代码变聪明了而是它至少不再像一个没头苍蝇一样乱飞了。最后分享一个小技巧如果你给 Codex 的命令以 请按 Superpowers 工作流执行 开头它读到 AGENTS.md 的时候会更明确地进入对应状态。这个前缀几乎相当于把代理的工程师人格先叫醒再让它干活。