superpowers实战指南：把Codex CLI升级成会规划、会验证的AI编程搭档

这几周在X上刷到好几个熟悉的开发者都在推同一个关键词superpowers。一开始我以为又是什么营销噱头直到自己也把那个仓库clone下来、跑起来以后才明白这个词真的没有白叫。简单来说superpowers是一套基于AI编码助手目前我主要配合Codex CLI使用的能力增强包它把原本光会“回答问题”“生成代码片段”的终端AI升级成一个会规划、会动手改代码、会跑测试、会按工序推进任务的“虚拟结对程序员”。这篇文章我不打算讲概念PPT全部内容都是我这段时间用来用去、拆来拆去的真实经验包括它怎么安装、怎么激活、内部的工作流到底怎么跑以及那些文档里不会写、但撞上了真的会卡你一下午的问题。如果你正在用Codex这类工具又总觉得它“差了点干活的样子”这篇东西应该能帮你少走不少弯路。1. superpowers到底是给AI编码助手“开了什么挂”1.1 裸Codex能干为什么还需要superpowers先说一个很直观的痛感。原生Codex CLI本身是个很厉害的会话式编程助手你跟它说“帮我写一个二分查找”它能在几十毫秒内给你一段近乎可用的代码。但一旦到真实项目里需求往往是这样的“帮我新增一个用户批量导入接口包含CSV解析、字段校验、重复项去重然后写单元测试最后跑一遍mvn test确认没有破坏其他模块。”这种多步骤、需要先看项目结构、再定位代码、然后动手改、还要循环验证的任务裸Codex很容易陷入“局部正确、整体失控”的状态——它会盯着你给它看的那几个文件猛写根本不管旁边还有没有关联的服务、接口、配置文件、数据库脚本。superpowers要解决的正是这个“局部正确、整体失控”的问题。它的核心思路不是再给模型堆一大堆提示词而是建立一套工程化的工作流让AI先读项目文档、理解任务目标再按“分析—计划—实施—验证—总结”的固定工序来推进每一次代码修改。听起来好像很简单但实际跑下来你会发现这一套“工序约束”比任何单句华丽的system prompt都管用。因为模型再聪明在没有明确流程引导时也倾向于走捷径而superpowers用结构和规则把它按在了“正经干活”的轨道上。我个人的理解是裸Codex像是一个很聪明但没经过入职培训的新同事你问什么它能答什么superpowers则是给这位新同事发了一本《团队开发手册》和一套《工序检查单》让它知道上一个项目里的人都是怎么协作的、代码规范是什么、合并之前必须过哪些验证。你别说差别就是这么大。1.2 能力包里的四个核心设计把一个在我本地跑了很久的superpowers仓库拆开看我能明确看到它至少包含四个层面的设计第一是技能包skills。每个技能就是一份指令集加若干验证条件告诉AI“在什么场景下启用什么流程”。比如有一个技能叫做“plan”它会让AI先不要写代码而是先去项目里调研、列出改动点清单、给出风险项再比如“implement”技能它要求AI在修改代码时必须同步更新测试并且每完成一个步骤就在工作区里做一次状态记录。很多初看superpowers的人以为它是个“代码生成器”其实它更像一个“流程生成器”。第二是项目记忆机制。superpowers会引导AI去读取项目根目录下的AGENTS.md这类约定文件将团队的开发规范、命令偏好、目录结构映射到自己的上下文里。这样AI在不同仓库间切换时不会把上一家项目的习惯带过来而是老老实实按当前仓库的规则来。第三是验证闭环。它内置了大量shell级别的工具调用策略比如“改完代码后必须执行mvn test”“如果测试失败不许直接修改测试去迁就实现而是要回头修实现”。这种验证不是靠AI自觉而是靠技能定义里的强制步骤来约束的。说白了就是把“人工Review”的一部分前置到了AI的执行循环里。第四是任务状态管理。长任务执行到一半AI会输出一份任务状态文档记录“哪些文件动了”“哪些还没做”“下一步该干嘛”。就算上下文被截断、或者你中途关了终端下次接着跑时它还能根据状态文件续上进度。这个设计对很多真实场景特别友好。2. 安装与初始化一次配置长期生效2.1 环境检查先确认这三项在动手clone之前我强烈建议你做一轮环境检查。很多安装问题根本不是superpowers自身的bug而是前置环境不匹配。我自己的经验是优先确认三件事第一Node.js版本。superpowers的主体是一个命令行工具链依赖比较新的Node特性我本地用的版本是20以上的LTS跑得很稳。如果你还在用Node 16甚至更老的版本建议先升级。第二Codex CLI要能正常使用。既然叫superpowers它的存在意义就是给Codex这些AI编码助手做能力外挂如果Codex本身没登录、没配好API权限后面所有工作流都跑不起来。你至少得在终端里单独跟Codex对话一次确认它能正常调用模型。第三git和项目的构建工具链要就绪。这听起来像废话但真有人卡在git拉取权限、Maven没配镜像源、Docker没启动这些基础问题上回头还以为是superpowers装坏了。检查完这三项之后再考虑安装。我建议你找一台常用的开发机器把superpowers装进用户级目录而不是某个单项目目录因为它的技能包和工作流在很多项目里都能复用装成全局工具一次配置、到处生效体验好很多。2.2 Linux或macOS下的安装全过程记录下面是我在Linux环境下的完整安装过程你直接照着敲就行。需要说明的是仓库地址请以你实际获取到的为准不要直接用我这里的示意路径因为不同来源分发方式可能有差异。# 1. 将项目clone到本地我习惯放在 ~/.superpowers 而不是当前项目目录 git clone 仓库地址 ~/.superpowers cd ~/.superpowers # 2. 安装依赖superpowers官方用的包管理器我见过pnpm和npm两种我这边用npm没问题 npm install # 3. 执行初始化脚本这一步会把skills工作流注册到你的开发环境中 npm run setup执行npm run setup之后脚本会问你要不要自动往shell配置里写入一些别名和激活逻辑我建议直接选yes。这么做的原因是superpowers在工作时需要频繁调用Codex CLI而且它需要知道你的终端配置、PATH环境变量以及项目入口写成全局激活脚本可以省去每次手动source的麻烦。setup完成以后可以进到一个测试目录里新建一个最小项目然后在终端里启动Codex把superpowers带的那份“新手引导技能”调出来试试。如果你用的CLI能正确返回技能列表那就说明安装这步已经完成了。整个过程我在干净环境里实测大概五分钟内能搞定。2.3 Java工程激活时需要注意的特殊处理如果你是Java开发尤其是常年工作在Maven多模块工程里的人安装完之后先别急着开干有几个特殊处理必须做。第一确保AGENTS.md能被AI读到。superpowers非常依赖项目根的AGENTS.md来获知项目规则但很多Java仓库恰恰没有这个文件。我的做法是在每个Java仓库根部补一个最小AGENTS.md里面写明“本仓库使用Java 17、Maven 3.9构建命令为mvn clean package测试命令为mvn test单元测试使用JUnit 5禁止使用System.out.println做调试输出。”这短短几句话能让AI后续的行为直接提升一个档次。第二把构建命令的“推荐路径”写进技能偏好里。比如你的项目可能有Web模块、Service模块、Batch模块你以为AI会自己发现吗它大概率会一头扎进根目录直接执行mvn test然后在某个模块编译失败后就陷入混乱。superpowers的优势是允许你通过自定义技能来固化这些命令我后面会细讲但这里你要先有这个意识Java项目的构建路径不是天然自明的必须在配置里告诉它。第三注意JDK版本和多JDK共存的问题。AI执行shell命令时走的是当前shell的PATH解析如果机器上装了JDK 8和JDK 17而你的项目需要17就必须在技能定义或AGENTS.md中明确写死JAVA_HOME指向哪。别问为什么会这样问就是我已经在这个坑里摔过一次了AI可不管你机器上挂了多少个JDK它只会忠实地执行PATH里排最前面的那一个。3. 核心工作流实战让AI按“开发工序”干活3.1 从一句话需求到完成代码验证全程怎么跑理论说一大堆不如直接看一次实际运行。我在一个Spring Boot工程里给superpowers安排了一个“需求”给现有用户模块的UserService增加一个按邮箱模糊查询的方法并补上对应单元测试跑通Maven构建。启动Codex后我输入的需求很简单“用superpowers的工作流帮我完成在UserService里新增email模糊查询功能按项目规范补测试并跑通构建。”注意这里我并没有给任何多余的技术细节。接下来发生的事情很有意思。AI先是激活了“plan”技能。它没有直接动手写代码而是先输出了一份快速计划列出了“读取UserService.java”“检查实体类是否已有email字段”“查看现有Mapper写法”“确认Repository层查询方式”“评估是否涉及SQL变更”这几个步骤。这个过程其实是superpowers在引导模型做上下文探查避免那种“连项目结构都没看清就开写”的冲动行为。随后它读取了AGENTS.md发现自己被要求遵循“Maven多模块规范”于是没有在根目录瞎跑构建而是定位到了正确的模块路径。紧接着是“implement”阶段AI老老实实修改了Service接口、Service实现类、Mapper接口和Mapper XML文件每个文件改完后都在终端里给自己写一条进度备注。最后它自动调用了mvn -pl user-module -am test跑出一次绿BUILD。在一个基本命令不写清楚就会翻车的Java工程里这一整套流程走下来几乎没有人工干预。我的体感是它已经不是“帮我写代码”的助手更像一个“帮我把整个开发任务跟进完”的执行者。3.2 关键配置与直接影响行为的参数superpowers的工作流并非一个黑盒而是由一批配置文件和技能定义驱动的。我挑几个影响比较大的配置项说说。首先是config.json或者你对应版本里的配置文件它控制AI的默认行为边界。我比较关注的是“验证超时时间”和“最大连续执行步骤”。验证超时时间默认可能只有几十秒但对于Java这类冷启动重的构建工具来说明显不够。如果你的项目经常在编译上就要两三分钟务必把这个值调大否则AI跑到一半会因为等不到验证结果而误判失败。其次是技能文件的“激活条件”。所有技能头部都有一块元信息描述告诉AI该技能适合什么场景。你可以在里面明确写“当需求涉及修改数据库访问层时必须先检查MyBatis映射文件”这样的规则。因为这本质上是提示词工程AI是否愿意遵守很大程度取决于你写的是“建议”还是“强制要求”。我在实际写技能时会刻意使用“必须”“禁止”这类强约束词效果比“建议”“尽量”好太多了。另外在customInstructions配置里我建议把团队的Code Review偏好注入进去。比如我们团队要求“所有新增依赖必须经过架构师审批”“禁止在Controller里写业务逻辑”这些约定直接写进配置后AI在实施阶段就会主动规避掉这些雷区相当于把团队的隐性知识外挂到了模型上面。下面是一个简化版配置文件示例方便你理解结构{ model: default, defaultTimeoutSeconds: 180, maxIterations: 24, customInstructions: [ 所有新增代码必须包含对应的单元测试, Controller层禁止出现业务逻辑, 数据库变更脚本必须单独放置于db/changelog目录 ], skillDir: ~/.superpowers/skills }3.3 与IDE和CI联动时的一些实用建议虽然superpowers的主体工作在终端里但在实际开发中你不可能完全脱离IDE和CI。我有几个亲测顺手的联动方式。在IDE侧我目前是VS Code和JetBrains家混着用。体验下来最重要的一条是终端窗口别关让AI工作流所在的终端尽量复用项目根目录。因为superpowers执行验证命令时依赖当前文件系统上下文不像IDE里面按个按钮就能本地跑测试。很多朋友让AI跑着跑着报出一堆“文件不存在”十有八九是它根本不在项目根目录下执行的。 技巧是把Codex终端固定在项目工作区内再用IDE自带的“集成终端”功能来启动Codex路径问题就能大幅缓解。在CI侧superpowers更适合做的是“本地预验证”而不是替代CI。我的做法是AI在自己机器上跑完mvn test后再由我人工推送代码到远程触发CI流水线。虽然看起来多了一步但实际上非常稳。因为CI里面还会有代码审查、覆盖率门禁、镜像构建等流程AI目前还处理不了那种“被机器人驳回再改再推”的循环人工在中间做一个“质量闸门”反而效率最高。另外我强烈建议频繁使用“阶段快照”功能。每完成一个大步骤让AI用简短文本输出一个状态说明描述“改了什么、验证了什么、还有哪些风险”。这个状态说明可以直接粘到合并请求描述里解决很多团队反馈的“AI改了一堆代码但完全说不清楚”的尴尬。4. 自定义技能沉淀团队自己真正的“超能力”4.1 技能包目录理解了这个你才算入门对我而言superpowers最精髓的部分不在它自带的那些通用技能而在它的“技能包目录机制”——你可以按项目或团队需要自由组合、扩展、覆盖一套专属技能集。这套机制理解透了你才算真正入了门。技能包在仓库里对应一个固定目录结构通常是skills/目录底下每个子目录就是一个技能。每个技能目录里会有一个描述文件常见的命名是SKILL.md里面包含了该技能的元信息、适用场景、执行步骤和验证命令。如果你之前接触过AI Agent的function calling可以把技能类比成一组“有约束的函数”但这里的函数体不是代码而是一份完整的操作指令文档。我自己的技能包目录大概是这样的~/.superpowers/skills/ ├── plan/ │ └── SKILL.md ├── implement-java/ │ └── SKILL.md ├── run-tests/ │ └── SKILL.md └── db-migration-check/ └── SKILL.md在这个结构里每一个SKILL.md就定义了一个工作流。AI在接收到用户请求时会根据请求内容自动匹配合适的技能并优先按照技能描述中的流程去执行。这就像你给AI准备了一本“工作手册”它遇到事情先翻手册再动手而不是每次都凭临场发挥。4.2 技能定义文件怎么写从一个真实示例说起直接上一个我在Java团队里写的简化技能定义你把它当作模板来改就行。这个技能解决的是“修改Mapper层时必须要检查和更新XML映射”的场景。--- name: java-mapper-update description: 当需求涉及新增或修改MyBatis Mapper接口方法时使用该技能确保XML映射文件同步更新并遵守数据库字段规范。 --- ## 步骤 1. 定位对应的 Mapper 接口文件确认方法签名。 2. 查找 resources 目录下同名 XML 映射文件。 3. 若XML中缺少对应方法必须补全 resultMap、SQL语句和参数映射。 4. 检查新增SQL是否包含 where 或 trim 以规避空条件拼接问题。 5. 在提交代码前必须确认已有测试覆盖新的数据库访问路径。 ## 验证 - 执行 mvn -pl 对应模块 -DskipTestsfalse test 确保单元测试通过。 - 检索XML文件中是否存在方法ID与接口方法名不一致的情况。你看这个技能定义其实一点都不玄乎它就是把你平时做Code Review时反复交代给新人的要点写成一条条AI也能遵守的规则。我写这个技能的直接背景是团队里AI生成的SQL经常把delete写成全表删除风险语句还总是不更新XML加入这个技能后这类问题几乎绝迹。写技能定义的时候有两件事务必上心第一一个技能只解决一类问题。别想着写一个“万能技能”把所有约束都塞进一个文件AI在长上下文里拆解复杂指令的能力有限技能越小越聚焦执行成功率越高。第二验证动作必须可执行。不要写“检查代码质量”这种没有语义的验证条件要写“执行某条命令输出是否包含某关键词”这种可以机械判断的验证步骤。AI本身没有“审美”它只能执行明确到你我都不会误解的指令。4.3 给Java团队基于superpowers的三个调优方向如果你的团队打算引入superpowers我建议别盲目复制网上别人的技能包而是针对自己项目的痛点定制。这里给出三个我实践下来特别值得做成技能的方向。第一个方向是“多模块构建路径固化”。Java后端发展到一定规模基本都是Maven多模块或Gradle多模块AI最常犯的错就是找不到正确的模块路径直接在根目录硬跑一个必定失败的命令。你可以为此写一个技能里面把各模块名字、依赖关系、构建顺序全列清楚并告诉AI“任何构建行为都先读取该文件”。这套技能写好后团队里所有依赖该仓库编码的AI都会少走很多弯路。第二个方向是“数据库脚本变更检查”。很多项目里数据库变更由Flyway或Liquibase管理规范的变动流程是“新增脚本-修改版本号-执行迁移验证”。AI很容易漏掉这一步。我写的技能里规定“任何涉及实体字段变更的任务必须检查是否存在对应的迁移脚本若无脚本则拒绝完成任务并明确提示开发者补充”。这个强约束有效避免了许多线上环境“代码和库对不上”的惨案。第三个方向是“API兼容性检查”。如果你维护的是对外接品AI改动一个接口的签名可能直接影响下游调用方。我建议写一个技能要求AI在修改Controller或Feign Client接口前必须全局检索调用方并评估兼容性。这个技能看起来只是一个简单的约束但它在微服务环境里价值极高——AI眼里只有一个仓库但你的系统由十几个服务构成兼容性的视野必须靠人工通过技能注入给它。5. 常见问题速查我实际使用中踩过的那些坑5.1 安装激活场景里的高频故障先说我遇到最离谱的一个问题运行npm run setup成功但死活没有产生任何激活效果Codex里也调不出新技能。排查了半天发现是终端用的shell环境被某个脚本改过而setup脚本写入的是用户级配置。后来我手动source了一下环境文件再重启终端问题就消失了。这类“配置写入成功但未生效”的问题十有八九是shell会话的缓存没刷新先别急着怀疑安装坏了重启一个新的终端窗口往往比改任何配置都有效。还有一个常见问题是Node版本不满足。superpowers的依赖里有一些比较新的语法和API安装时如果看到某种engine相关的警告那就说明你的Node版本不够新。我处理的方式是用版本管理器把Node切到20以上的LTS不推荐直接用系统自带的老版Node去硬顶。最后很多人会忽略一个软性前提网络环境。superpowers在首次使用时需要拉取一部分模型配置和技能索引如果网络受限会出现“安装成功但运行报错找不到资源”的假象。这里就需要你保证开发机能正常访问相关资源站否则后面所有工作流都会时好时坏。5.2 执行与验证过程最烦人的几件事在具体编码任务里我最常遇到的是AI执行验证命令时的“串台”问题。典型场景是项目里同时存在Yarn和npm的锁文件或者既有Maven又有Gradle的构建文件AI在验证阶段选错了工具然后生成了一个完全没必要的报错。解决思路很简单在AGENTS.md里把所有命令偏好写死比如“本项目只使用mvn禁止使用gradle”。强约束比后期不断纠错要省心得多。另外一个很隐蔽的问题是“测试通过但实际引入回归”。AI修改代码时会偷懒用“保留原有行为”来规避测试失败但代价是可能牺牲了你要改的预期行为。我遇到过它调用了一个“兼容性适配层”来把新逻辑藏住然后测试全绿但我一看代码方法体内充满了糟糕的折衷。从那以后我在技能定义里明确加了一条“如果为了通过测试而需要引入复杂适配代码必须暂停执行并询问开发者。”强约束能防住一部分这种“AI小聪明”。关于超时问题也需要特别提一下。有些Java项目的冷启动和热部署速度特别慢如果你的验证步骤里包含mvn test这种重型命令默认的超时时间大概率不够用。AI在等待很久后可能直接判定步骤“失败”然后自作主张去改代码来“修复”一个完全不该存在的失败。处理办法就是早早在配置里把超时时间调到300秒甚至更长宁可多等一会儿也别让AI做错误归因。5.3 自定义技能不生效时的检查清单自定义技能写好后不生效是新手最头疼的问题。其实你只需要按顺序排查这几个位置第一技能目录放得对不对。确认技能目录被纳入了配置文件里的skillDir并且目录命名和name字段一致。第二描述文件格式对不对。我见过很多人把YAML写成了三线表或者忘了在元信息前后加---分界线AI解析失败后就会静默跳过这个技能。第三激活条件写没写清楚。如果技能描述里的场景太窄比如“仅当用户要求新增Mapper方法时”而你的实际需求是“修改现有Mapper方法”这技能就不会被触发。建议把描述里的触发词放宽一些宁可多触发再让AI在流程里自行判断也不要写得太窄导致它从未被激活。第四重启会话没有。技能更新后如果当前对话里AI已经构建了自己的记忆它不会立刻感知到新技能建议新开一个会话去验证技能改动。下面是我整理的一些快速对照症状可能原因处理建议技能完全不触发skillDir配置错误或描述文件格式有误检查目录路径、YAML边界符触发成功但流程不完整技能内步骤指令不明确使用“必须/禁止”强约束词拆小步骤验证阶段频繁误判超时时间过短调整默认超时到300秒以上AI执行了错误构建工具项目规则未写入在AGENTS.md里明确命令偏好新技能改了但不生效会话上下文未刷新新开一个会话再测试5.4 给新人的一份排查口诀最后分享一些排查心得。遇到superpowers行为异常时别一头扎进去改各种高级配置先把自己切换到“人肉Debug模式”第一步复现用最简任务确认问题是否稳定出现第二步看日志把AI的每一步执行输出打出来逐行看它到底做了什么、卡在哪第三步比规范翻出技能定义和AGENTS.md看AI有没有按约定走第四步收范围临时禁用自定义技能只留内置工作流如果恢复正常基本就能锁定是自定义技能配置问题而不是工具本身出了问题。这套排查顺序我反复用帮我省下了大量时间。尤其是“收范围”这一步多数人遇到AI行为怪异时都觉得是工具坏了从来不去怀疑自己写的技能有问题。实际上在superpowers这种开放配置体系里自定义配置出问题的概率远远大于工具本体出问题的概率。我在实际使用中还有一个习惯就是每隔一段时间就把新的团队约束沉淀成一个新技能。因为这个工具的成长性恰恰来自这里一开始你用它的内置工作流时间长了你会发现真正让它值钱的是你围绕自己团队、自己项目写下的那些“定制规则”。这种把经验固化成自动化脚本的过程本身就是一种很上头的事而且长期看比起让每个新人都靠口口相传去理解团队规范把规范写进技能文件里让AI自动遵守要可靠得多。