开发工具圈这两年的风向变得很快命令行工具一个接一个地冒出来。但“superpowers”这个名字第一次出现在我时间线上的时候我确实愣了一下——这名字起得够狂的。等我把它的文档翻完、在本地跑起来、又在几个真实项目里折腾一遍之后我得说这玩意儿配得上这个名字前提是你知道怎么用它。简单说superpowers是一个围绕编码代理coding agent打造的能力增强层目前最核心的落地场景是配合Codex CLI使用。它解决的是那个让人头疼的老问题编码代理很聪明但它不够“懂事”。你让它改代码它改了你让它跑测试它跑了但一旦遇到跨模块重构、需要先查一堆资料再动手、或者项目里有大量历史包袱需要摸清底细的活儿它就露怯了。superpowers的思路不是重新发明一个编码代理而是给现有的代理装上“外挂”——把检索、规划、执行、验证这些环节拆开用一套可复用的技能包把它们串起来让代理不再是“一问一答”的应声虫而是有方法、有套路地推进任务。这篇文章我会从零开始把superpowers是什么、为什么值得用、怎么装、怎么配、怎么在Java项目里真正跑起来以及我在实操中踩过的坑和排查思路完整过一遍。如果你手头正好有Codex CLI又想让它干更复杂的活儿这篇内容可以直接当操作手册参考。1. 项目概述与核心能力拆解1.1 superpowers到底做了什么先说结论superpowers不是一个独立的大模型也不是什么云服务它本质上是一个工程化的工作流增强套件。它的工作方式是在你的本地环境里给编码代理比如Codex CLI预先定义好一批高度结构化的“技能”每个技能都对应一类具体任务场景比如“梳理现有代码结构”“定位某个功能的实现链路”“规划一次跨模块重构”“执行完修改后做回归验证”等等。这里有个关键点值得展开为什么不能直接靠对话让编码代理干这些事因为对话式交互有两个天然短板。第一是上下文窗口有限项目稍微大一点代理记不住你前面说的关键约束容易跑偏。第二是缺少方法论约束你问它“帮我改一下支付模块”它可能上来就直接改代码忘了先看依赖关系、忘了先跑一遍现有测试、忘了改动会影响哪些调用方。superpowers通过把“正确的工作习惯”固化成技能文件让代理在执行任务时先走一遍标准流程再动手改代码这等于把资深工程师的工作套路复制给了机器。举个例子。你让代理“给用户模块加一个导出功能”如果没装superpowers它就是打开相关文件凭印象写一段代码然后停在那里等你验收。而装上superpowers之后它接到的指令可能是“先定位用户模块的领域模型和Repository接口再查一下现有导出相关的工具类然后按项目里既有的代码风格实现最后补一个单元测试”每个环节都有对应技能文件在底层指导它怎么做。这个差别用过的都懂。1.2 核心模块与工作流程从架构角度看superpowers的核心模块可以拆成三层技能定义层这一层是一堆Markdown格式的技能描述文件每个文件都包含技能的触发条件、适用场景、执行步骤、输入输出要求。Codex CLI读取这些文件之后就能在合适的时机主动调用对应的技能。这一层的好处是可扩展你完全可以自己写一份技能文件塞进去让代理学会你们团队的专属开发流程。任务编排层这一层负责把一个大任务拆成多个步骤并引导代理按顺序执行。比如一个重构任务会被拆成“摸底—规划—实施—验证”四个阶段代理不会跳过摸底直接动手。这种结构化编排是superpowers和普通prompt最大的区别——普通prompt是一段话superpowers是一套流程。验证反馈层这一层负责在执行完每个步骤后做检查比如要求代理运行相关测试、对照项目规范检查代码风格、确认没有破坏现有接口。验证反馈的存在让代理的错误能在早期被拦截而不是等到整个任务做完才发现方向错了。1.3 它能替你解决哪些实际问题我在几个不同类型的项目里试过之后归纳出superpowers真正能扛起来的四类任务一是遗留代码梳理。面对一个没文档、没注释的老项目直接问代理“这项目是干嘛的”往往会得到泛泛而谈的回答。有了superpowers代理会按技能要求先扫目录结构、再读入口文件、然后追踪核心业务流程最后给你一份有依据的整理报告每一步它都会说明信息来源你能去核对。二是跨模块改动的影响面分析。改一个公共方法最怕的就是不知道哪些调用方会受影响。superpowers会把“搜索调用方—分析依赖链—列出风险点”作为标准流程代理在动手前先出分析结论你确认了它才继续。三是带约束的代码生成。比如“按现有项目风格新增一个API接口”代理会先去读现有Controller和Service的写法再照着那个路子写而不是自己发挥一套新风格出来。这个我实测下来代码风格一致性提升非常明显。四是自动化验证闭环。改完代码之后代理会主动跑测试、跑编译、检查lint把报错信息带回来自己修修完再验证。这个闭环跑顺之后代理提交结果的可用性高了一大截。2. 环境准备与安装部署指南2.1 基础依赖与版本选择在动手装之前先把环境摸清楚。superpowers本身对系统没有特别离谱的要求但它依赖Codex CLI来执行具体操作所以你的机器上必须先有可用的Codex CLI环境。我目前用的组合是macOSApple Silicon、Node.js 20 LTS、Codex CLI最新稳定版。如果你用的是Linux比如Ubuntu 22.04或更新版本也没问题Windows的话我更建议用WSL2跑省去很多原生环境的老大难问题。Java项目本身不挑这个但后面做Java项目集成时你的机器上得有JDK 17及以上版本——这不是superpowers的要求而是现在主流Java项目的基础环境。版本选择上有一条我个人的建议不要追最新。superpowers这种迭代快的工具偶尔会有小版本引入行为变化影响你已有的工作流。比较稳妥的做法是先在GitHub仓库的Release页面挑一个最近的稳定版装完之后别急着升级等当前项目跑完再考虑更新。2.2 安装步骤与关键配置安装流程本身不复杂核心三步拉取项目仓库、安装依赖、把配置文件放到该放的位置。我按我实际敲过的命令走一遍。git clone https://github.com/worksingh/superpowers.git cd superpowers npm install装依赖这一步如果你的网络环境一般可能会有点慢或者直接卡住。我遇到过npm registry超时的问题解决办法是临时切换镜像源装完再切回来npm install --registryhttps://registry.npmmirror.com装完之后下一步是把配置目录设置好。superpowers的配置不像很多工具那样挤在一个config.json里它用的是目录结构。你需要把仓库里的配置目录链接到你本机的Codex CLI配置位置这样才能被正确加载。在macOS/Linux下通常是这样mkdir -p ~/.codex ln -s $(pwd)/config ~/.codex/superpowers这里有个容易被忽略的细节Codex CLI的配置文件里需要显式引用superpowers的技能目录。也就是说光把目录放过去还不够你还得在Codex的配置文件里声明这个目录让Codex知道去哪里找技能。这一步如果漏了你装完会发现superpowers毫无存在感——因为代理根本读不到那些技能文件。具体在Codex配置里加这样一段路径按你的实际情况调整{ skills: { superpowers: { path: ~/.codex/superpowers } } }配置完成之后跑一下自检命令确认安装结果codex skills list如果输出里能看到superpowers相关的技能清单安装就算成功了。我第一次装的时候这条命令返回空列表排查了好一阵子才发现是配置文件里的路径写成了相对路径导致Codex没找到目录。这个问题后面在排查章节里细说。2.3 安装后的自检清单装完不等于能用建议按这份清单过一遍避免后面真干活的时候才发现问题技能清单是否正常输出codex skills list是否能正常启动Codex CLI交互界面codex命令能进REPL随便让代理读一个你项目里的文件确认基本读写链路通畅在一个测试目录里跑一个简单的“技能触发”指令比如让代理“使用superpowers技能分析当前目录结构”确认它真的调用了技能文件而不是普通对话这个自检过程十分钟之内能跑完但能帮你省掉后面大量排查时间。尤其是第四步它能直观告诉你“技能调用”这个关键链路是否真的通了。如果你发现代理完全没提到技能回答还是那一套通用风格大概率是配置没生效别急着怀疑人生回头检查配置文件和路径。3. Java场景下的典型实践3.1 Java项目里能用它做什么很多Java开发者第一次听说superpowers第一反应是“这跟我用IDE重构有什么区别”。实话实说日常的小重构IDE确实够了但superpowers的价值恰恰在IDE覆盖不到的环节。IDE能帮你安全重命名、提取方法、查找引用这些是确定性操作。但面对“搞清楚这个遗留系统的会员积分计算链路”“分析这几个服务之间有没有隐藏的循环依赖”“给一个多模块Maven工程生成模块依赖报告”这类需要理解和推理的任务IDE给不了答案只能靠人读代码。superpowers的价值就在于它能驱动编码代理按一套系统性的思路去读、去盘、去归纳最后给你一个结构化的结论。我在一个老Spring MVC项目上做过一次试验。项目有六七个Maven模块代码量在几十万行级别没有README、没有架构文档。我让装了superpowers的Codex从入口开始梳理核心业务链路它先扫了web层的Controller找到了几个关键的RequestMapping然后顺着Service层往下追最后定位到MyBatis的Mapper层。整个过程中它不断记录每一步的发现中途还主动问我“是否要继续追踪某个扩展点”。最终产出了一篇包含调用链、关键类清单、潜在问题列表的梳理报告。这个过程我全程没有给它手把手指引一开始我只告诉它“请用superpowers分析这个项目的核心业务流程”后面就是它在自己的技能框架下一步步走完的。这个案例给我的感受是superpowersCodex的组合干活的方式更像一个初级工程师在导师带领下做任务拆解而不是一个搜索引擎。3.2 一个真实的Java功能开发案例理论说再多不如跑一个实际案例。我选了一个比较典型的小任务给用户模块新增一个“导出用户列表为CSV”的API接口。这个任务不复杂但涉及Controller、Service、工具类、测试四个层面足够展示superpowers的工作流。我给的指令是这样的请用superpowers规划并实现“导出用户列表为CSV”的功能。 要求输出UTF-8编码的CSV表头包含用户名、手机号、注册时间 数据源从UserService获取接口路径为GET /api/users/export。 请先分析现有代码风格再按项目惯例实现。后面发生的事情让我对这个工具彻底改观。代理没有直接写代码而是先按技能要求做了四件事第一摸清现有代码风格。它先读了UserController的全文看现有接口是怎么定义REST风格的、用什么方式包装返回值。又读了几个已有的Service实现确认事务注解和日志写法。它甚至注意到项目里用的是Lombok所以在实体类上自动使用了Data而不是手写getter/setter。第二规划文件改动清单。它列出了改动涉及的文件列表标注了哪些是新增、哪些是修改以及每个文件的操作要点。这一步非常关键因为Codex默认的行为是一次性给你整段代码但有了规划环节改动范围和设计意图在动手前就明确了。第三按步骤实现代码。它先写了CSV工具类导出时用OutputStreamWriter指定UTF-8编码避免Excel打开中文乱码。然后写了Controller层的接口方法复用了项目里已有的ApiResponseT包装类。接着改动了Service层加了一个返回ListUser的方法注意保持了现有方法命名习惯。每一步它都会停下来解释这段代码的设计理由而不是闷头写。第四验证和修正。写完之后它主动提议编译并运行项目已有的测试。因为项目里本来就有一套基于Spring Test的集成测试它照猫画虎补了一个导出接口的测试方法。运行测试时发现CSV工具类里的逗号转义没处理——用户昵称里如果包含逗号本来应该用引号包裹首版代码漏了。代理在测试报告中发现了这个失败用例自己回去改了工具类补上转义逻辑再跑测试直到通过。完整流程跑下来给我的体验像在跟一个靠谱的结对程序员工作。我把这个案例写下来是想说清楚一件事superpowers真正改变的不是代码生成能力而是代理的工作方式。它把“写完就交差”变成了“分析清楚—规划到位—按序实施—主动验证”。3.3 Java生态集成注意事项在Java项目里用superpowers有几点我踩过坑之后觉得必须提醒你。第一确保Codex CLI能正确解析项目结构。Codex不会真的去编译你的Maven工程所以它理解项目结构靠的是读取pom.xml、目录结构、已有代码之间的引用关系。如果你项目里用了大量Lombok的链式构造或者自定义的依赖注入框架它可能读到一半卡住。我的习惯是让代理先“分析项目整体结构”确认它的理解和实际一致再让它动手。第二告诉代理JDK版本和构建工具版本。我遇到过代理生成代码时使用了JDK 17才有的语法但项目实际跑在JDK 11上编译直接失败。后来我在项目根目录放了一个.superpowers.md的说明文件里面写清楚JDK版本、构建命令、测试命令代理每次进场都会先读这个文件。这个做法非常管用基本杜绝了“版本不匹配”这类低级错误。第三Maven多模块项目的路径问题。如果你的项目是多模块结构代理有时会在查找类时找错模块。我在实践中发现让Codex在“分析项目结构”阶段输出一个模块依赖树能显著减少后续定位错文件的情况。虽然这个过程要多花一两分钟但比改错文件之后再返工便宜太多了。4. 实操流程与核心环节实现4.1 完整实操从零配置一个可用的superpowers工作环境这一节我把从零开始的全流程再串一遍给你一份可以直接按着敲的操作记录。注意我的环境是macOS zsh如果你用的是其他环境命令要按对应方式适配。第一步确认基础环境node -v npm -v codex --version我的版本分别是v20.11.0、10.2.4、以及Codex CLI的0.26.2。如果你的node版本低于18建议先把node升上去否则npm install过程中可能会遇到语法不支持的问题。第二步克隆并安装superpowersgit clone https://github.com/worksingh/superpowers.git ~/superpowers cd ~/superpowers npm install第三步建立配置目录链接mkdir -p ~/.codex ln -s ~/superpowers/config ~/.codex/superpowers第四步修改Codex配置文件。找到~/.codex/config.tomlmacOS路径Linux也是这个加上superpowers的声明。我贴一下我实际用的配置片段[sandbox] readonly_home false [superpowers] enabled true skills_path ~/.codex/superpowers这里有个细节readonly_home如果被默认设为true代理在读取某些配置时会受到权限限制导致技能加载异常。我之前被这个问题坑过代码看起来没错技能就是加载不出来后来发现是这个沙箱配置在捣鬼。第五步验证安装codex skills list看到技能列表输出就算成功。如果这里输出为空优先检查配置里的路径写法和实际目录是否一致不要把~直接用在toml里建议写成绝对路径比如/Users/你的用户名/.codex/superpowers。第六步用一个真实任务验证链路。我建议你选一个简单的小项目给代理下面这句指令请使用superpowers技能梳理当前项目的模块结构和核心调用链输出一份概要文档。如果代理开始按步骤分析、输出结构化报告安装就真正完成了。这一步跑通过一次你后面用起来心里就有底了。4.2 技能文件的自定义方法与模板superpowers真正值钱的地方在于你可以往里面添加自己的技能文件。这不需要写代码就是写Markdown。每个技能文件就是一份结构化的操作说明书编码代理会按里面的步骤执行。我自定义技能时的模板如下# 技能名称 ## 触发条件 什么样的任务应该触发这个技能描述要具体避免和其他技能重叠 ## 适用场景 描述这个技能解决的典型问题类型以及不适合使用的反例 ## 执行步骤 1. 第一步要做什么 2. 第二步要做什么 3. 第三步要做什么 ## 输入要求 代理在执行这个技能前需要确认哪些信息 ## 输出要求 代理完成任务后需要输出什么格式的结果举个例子我给团队写过一个“新增API接口的标准流程”技能里面的执行步骤是先读现有Controller代码确认路由风格和参数校验方式再读Service接口和实现确认事务和异常处理惯例然后按现状风格编写新接口最后补充测试用例并运行相关测试。写完之后放到~/.codex/superpowers/skills/目录下下次代理遇到新增接口的任务时就会自动匹配并调用。这个扩展能力的重要性怎么强调都不过分。它意味着superpowers不再是“别人的工具”而是能变成“你的团队的工具”。你们团队的代码规范、分支策略、测试要求都可以通过技能文件固化下来让编码代理遵守。4.3 参数配置与运行效果调优实际使用中有几个参数和设置对我的体验影响很大单独拎出来说一下。温度参数temperature这是控制生成随机性的参数默认值在0.7到0.8之间。在代码生成场景下我建议调到0.2到0.3。太高容易让代理写出“过于有创意”的代码太低会让输出变得机械。在Codex CLI里可以通过配置文件调我是放在用户的全局配置里覆盖的。最大输出长度max tokens代理一次能输出的文字数量上限。如果默认值偏小你会发现代理经常话说到一半就停了。这个参数因任务而异写代码的人通常希望一次能多输出一些。我把这个值调大了一些尤其是跑分析任务的时候太短的输出根本装不下结构化的报告。重试次数retry代理在遇到操作失败时自动重试的次数。我建议设成2到3次太少容易因偶发问题中断流程太多则可能在同一个错误上反复横跳浪费时间。工作目录限制建议给Codex限定到当前项目目录内避免它乱翻系统文件。这一步既是为了安全也是为了让它的注意力集中在项目本身。这些参数没有绝对的最优值跟你项目大小、模型能力、任务类型都有关系。我给你的建议是先用默认值跑一周记录你遇到的主要问题再针对性地调。不要一开始就追求复杂的配置先让流程跑通比什么都重要。5. 常见问题与排查技巧实录5.1 我踩过的五个高频坑用superpowers这段时间我遇到的典型问题五花八门但归纳下来有五个出现频率最高我把现象、原因、解决方式整理成了一张速查表现象可能原因解决步骤技能列表为空配置文件路径错误或未声明技能目录检查config.toml的skills_path是否为绝对路径确认目录确实存在代理不调用技能回答像普通对话技能触发条件不匹配或配置未生效修改技能文件的触发条件描述重启Codex CLI生成的代码风格和项目不一致代理未在动手前阅读现有代码在指令中明确要求“先分析现有代码风格再按惯例实现”或在项目根目录放规范说明文件运行测试时找不到测试类代理没识别到Maven的标准测试目录在指令中加入“使用Maven标准目录结构测试放src/test/java下”确认代理先读过pom.xml代理改文件改到一半迷失方向大任务没有拆解步骤明确要求使用任务编排技能把任务拆成摸底—规划—实施—验证或手动在指令里分步骤5.2 排查思路与调试技巧遇到问题不要急着怀疑superpowers本身。我给你一套我在实践中形成的排查思路这套思路帮我解决过至少七八次“看起来无解”的故障。第一步确认加载链路。问题是出在“配置没读到”还是“技能没触发”还是“生成了但执行失败”用codex skills list看技能有没有进来用codex --verbose启动调试模式观察日志里有没有技能加载记录。这条链路排查完至少能排除一半的配置类问题。第二步简化问题复现。我经常做一个“最小复现”操作把代理的任务缩小到最简单的单文件修改比如“给某个工具类加一个静态方法”看它在这个简单任务上是否正常走技能流程。如果简单任务都走不顺问题大概率在基础配置如果简单任务正常那问题出在复杂任务的触发条件上。第三步查看代理的“思考过程”。Codex命令行模式下代理有时会输出自己的推理过程。这些信息非常宝贵它让你看到代理是“读了技能文件但没理解”还是“根本没意识到这个任务可以触发技能”。前者是技能文件写得不清楚后者是触发条件描述不到位。5.3 独家避坑经验最后分享几条我在项目实战中积累的独家经验这些不属于任何官方文档纯属用时间换来的教训。第一每次跑重要任务之前先让代理输出项目结构。我经历过太多次“代理理解的项目结构和你实际的不一样”导致的返工。让它在动手前先输出一份结构摘要给你过目会浪费两分钟但能规避几十分钟的返工。第二不要把superpowers当代码搜索引擎用。它擅长的是“按流程执行任务”不是“回答你某个函数怎么用”。如果你问它“Java的Optional怎么用”它可能会套技能流程去分析半天反而绕晕。把问题包装成任务比如“在我的项目里找到可以用Optional简化空指针判断的地方并重构”效果会好得多。第三用好项目根目录的说明文件。我在Java项目里放了一个.superpowers.md里面写了项目简介、JDK版本、构建命令、测试命令、代码风格约定。代理进场读一遍这个文件后面几乎所有任务的质量都有提升。这个习惯建议你从第一天就开始养成比事后追加一百条指令有用得多。第四版本锁定的重要性。superpowers和Codex CLI更新频率都不低有时候两个版本之间的配合会有兼容性问题。我遇到过一次更新Codex后技能加载失效的情况回退Codex版本才恢复。有了这个教训之后我会在项目的package.json附近留一个版本说明记录当前使用的Codex和superpowers版本方便回溯。 
长河君 · 2026/10/15 23:44:47 · 阅读 1.2k superpowers：为Codex CLI编码代理装上工程化技能包
开发工具圈这两年的风向变得很快命令行工具一个接一个地冒出来。但“superpowers”这个名字第一次出现在我时间线上的时候我确实愣了一下——这名字起得够狂的。等我把它的文档翻完、在本地跑起来、又在几个真实项目里折腾一遍之后我得说这玩意儿配得上这个名字前提是你知道怎么用它。简单说superpowers是一个围绕编码代理coding agent打造的能力增强层目前最核心的落地场景是配合Codex CLI使用。它解决的是那个让人头疼的老问题编码代理很聪明但它不够“懂事”。你让它改代码它改了你让它跑测试它跑了但一旦遇到跨模块重构、需要先查一堆资料再动手、或者项目里有大量历史包袱需要摸清底细的活儿它就露怯了。superpowers的思路不是重新发明一个编码代理而是给现有的代理装上“外挂”——把检索、规划、执行、验证这些环节拆开用一套可复用的技能包把它们串起来让代理不再是“一问一答”的应声虫而是有方法、有套路地推进任务。这篇文章我会从零开始把superpowers是什么、为什么值得用、怎么装、怎么配、怎么在Java项目里真正跑起来以及我在实操中踩过的坑和排查思路完整过一遍。如果你手头正好有Codex CLI又想让它干更复杂的活儿这篇内容可以直接当操作手册参考。1. 项目概述与核心能力拆解1.1 superpowers到底做了什么先说结论superpowers不是一个独立的大模型也不是什么云服务它本质上是一个工程化的工作流增强套件。它的工作方式是在你的本地环境里给编码代理比如Codex CLI预先定义好一批高度结构化的“技能”每个技能都对应一类具体任务场景比如“梳理现有代码结构”“定位某个功能的实现链路”“规划一次跨模块重构”“执行完修改后做回归验证”等等。这里有个关键点值得展开为什么不能直接靠对话让编码代理干这些事因为对话式交互有两个天然短板。第一是上下文窗口有限项目稍微大一点代理记不住你前面说的关键约束容易跑偏。第二是缺少方法论约束你问它“帮我改一下支付模块”它可能上来就直接改代码忘了先看依赖关系、忘了先跑一遍现有测试、忘了改动会影响哪些调用方。superpowers通过把“正确的工作习惯”固化成技能文件让代理在执行任务时先走一遍标准流程再动手改代码这等于把资深工程师的工作套路复制给了机器。举个例子。你让代理“给用户模块加一个导出功能”如果没装superpowers它就是打开相关文件凭印象写一段代码然后停在那里等你验收。而装上superpowers之后它接到的指令可能是“先定位用户模块的领域模型和Repository接口再查一下现有导出相关的工具类然后按项目里既有的代码风格实现最后补一个单元测试”每个环节都有对应技能文件在底层指导它怎么做。这个差别用过的都懂。1.2 核心模块与工作流程从架构角度看superpowers的核心模块可以拆成三层技能定义层这一层是一堆Markdown格式的技能描述文件每个文件都包含技能的触发条件、适用场景、执行步骤、输入输出要求。Codex CLI读取这些文件之后就能在合适的时机主动调用对应的技能。这一层的好处是可扩展你完全可以自己写一份技能文件塞进去让代理学会你们团队的专属开发流程。任务编排层这一层负责把一个大任务拆成多个步骤并引导代理按顺序执行。比如一个重构任务会被拆成“摸底—规划—实施—验证”四个阶段代理不会跳过摸底直接动手。这种结构化编排是superpowers和普通prompt最大的区别——普通prompt是一段话superpowers是一套流程。验证反馈层这一层负责在执行完每个步骤后做检查比如要求代理运行相关测试、对照项目规范检查代码风格、确认没有破坏现有接口。验证反馈的存在让代理的错误能在早期被拦截而不是等到整个任务做完才发现方向错了。1.3 它能替你解决哪些实际问题我在几个不同类型的项目里试过之后归纳出superpowers真正能扛起来的四类任务一是遗留代码梳理。面对一个没文档、没注释的老项目直接问代理“这项目是干嘛的”往往会得到泛泛而谈的回答。有了superpowers代理会按技能要求先扫目录结构、再读入口文件、然后追踪核心业务流程最后给你一份有依据的整理报告每一步它都会说明信息来源你能去核对。二是跨模块改动的影响面分析。改一个公共方法最怕的就是不知道哪些调用方会受影响。superpowers会把“搜索调用方—分析依赖链—列出风险点”作为标准流程代理在动手前先出分析结论你确认了它才继续。三是带约束的代码生成。比如“按现有项目风格新增一个API接口”代理会先去读现有Controller和Service的写法再照着那个路子写而不是自己发挥一套新风格出来。这个我实测下来代码风格一致性提升非常明显。四是自动化验证闭环。改完代码之后代理会主动跑测试、跑编译、检查lint把报错信息带回来自己修修完再验证。这个闭环跑顺之后代理提交结果的可用性高了一大截。2. 环境准备与安装部署指南2.1 基础依赖与版本选择在动手装之前先把环境摸清楚。superpowers本身对系统没有特别离谱的要求但它依赖Codex CLI来执行具体操作所以你的机器上必须先有可用的Codex CLI环境。我目前用的组合是macOSApple Silicon、Node.js 20 LTS、Codex CLI最新稳定版。如果你用的是Linux比如Ubuntu 22.04或更新版本也没问题Windows的话我更建议用WSL2跑省去很多原生环境的老大难问题。Java项目本身不挑这个但后面做Java项目集成时你的机器上得有JDK 17及以上版本——这不是superpowers的要求而是现在主流Java项目的基础环境。版本选择上有一条我个人的建议不要追最新。superpowers这种迭代快的工具偶尔会有小版本引入行为变化影响你已有的工作流。比较稳妥的做法是先在GitHub仓库的Release页面挑一个最近的稳定版装完之后别急着升级等当前项目跑完再考虑更新。2.2 安装步骤与关键配置安装流程本身不复杂核心三步拉取项目仓库、安装依赖、把配置文件放到该放的位置。我按我实际敲过的命令走一遍。git clone https://github.com/worksingh/superpowers.git cd superpowers npm install装依赖这一步如果你的网络环境一般可能会有点慢或者直接卡住。我遇到过npm registry超时的问题解决办法是临时切换镜像源装完再切回来npm install --registryhttps://registry.npmmirror.com装完之后下一步是把配置目录设置好。superpowers的配置不像很多工具那样挤在一个config.json里它用的是目录结构。你需要把仓库里的配置目录链接到你本机的Codex CLI配置位置这样才能被正确加载。在macOS/Linux下通常是这样mkdir -p ~/.codex ln -s $(pwd)/config ~/.codex/superpowers这里有个容易被忽略的细节Codex CLI的配置文件里需要显式引用superpowers的技能目录。也就是说光把目录放过去还不够你还得在Codex的配置文件里声明这个目录让Codex知道去哪里找技能。这一步如果漏了你装完会发现superpowers毫无存在感——因为代理根本读不到那些技能文件。具体在Codex配置里加这样一段路径按你的实际情况调整{ skills: { superpowers: { path: ~/.codex/superpowers } } }配置完成之后跑一下自检命令确认安装结果codex skills list如果输出里能看到superpowers相关的技能清单安装就算成功了。我第一次装的时候这条命令返回空列表排查了好一阵子才发现是配置文件里的路径写成了相对路径导致Codex没找到目录。这个问题后面在排查章节里细说。2.3 安装后的自检清单装完不等于能用建议按这份清单过一遍避免后面真干活的时候才发现问题技能清单是否正常输出codex skills list是否能正常启动Codex CLI交互界面codex命令能进REPL随便让代理读一个你项目里的文件确认基本读写链路通畅在一个测试目录里跑一个简单的“技能触发”指令比如让代理“使用superpowers技能分析当前目录结构”确认它真的调用了技能文件而不是普通对话这个自检过程十分钟之内能跑完但能帮你省掉后面大量排查时间。尤其是第四步它能直观告诉你“技能调用”这个关键链路是否真的通了。如果你发现代理完全没提到技能回答还是那一套通用风格大概率是配置没生效别急着怀疑人生回头检查配置文件和路径。3. Java场景下的典型实践3.1 Java项目里能用它做什么很多Java开发者第一次听说superpowers第一反应是“这跟我用IDE重构有什么区别”。实话实说日常的小重构IDE确实够了但superpowers的价值恰恰在IDE覆盖不到的环节。IDE能帮你安全重命名、提取方法、查找引用这些是确定性操作。但面对“搞清楚这个遗留系统的会员积分计算链路”“分析这几个服务之间有没有隐藏的循环依赖”“给一个多模块Maven工程生成模块依赖报告”这类需要理解和推理的任务IDE给不了答案只能靠人读代码。superpowers的价值就在于它能驱动编码代理按一套系统性的思路去读、去盘、去归纳最后给你一个结构化的结论。我在一个老Spring MVC项目上做过一次试验。项目有六七个Maven模块代码量在几十万行级别没有README、没有架构文档。我让装了superpowers的Codex从入口开始梳理核心业务链路它先扫了web层的Controller找到了几个关键的RequestMapping然后顺着Service层往下追最后定位到MyBatis的Mapper层。整个过程中它不断记录每一步的发现中途还主动问我“是否要继续追踪某个扩展点”。最终产出了一篇包含调用链、关键类清单、潜在问题列表的梳理报告。这个过程我全程没有给它手把手指引一开始我只告诉它“请用superpowers分析这个项目的核心业务流程”后面就是它在自己的技能框架下一步步走完的。这个案例给我的感受是superpowersCodex的组合干活的方式更像一个初级工程师在导师带领下做任务拆解而不是一个搜索引擎。3.2 一个真实的Java功能开发案例理论说再多不如跑一个实际案例。我选了一个比较典型的小任务给用户模块新增一个“导出用户列表为CSV”的API接口。这个任务不复杂但涉及Controller、Service、工具类、测试四个层面足够展示superpowers的工作流。我给的指令是这样的请用superpowers规划并实现“导出用户列表为CSV”的功能。 要求输出UTF-8编码的CSV表头包含用户名、手机号、注册时间 数据源从UserService获取接口路径为GET /api/users/export。 请先分析现有代码风格再按项目惯例实现。后面发生的事情让我对这个工具彻底改观。代理没有直接写代码而是先按技能要求做了四件事第一摸清现有代码风格。它先读了UserController的全文看现有接口是怎么定义REST风格的、用什么方式包装返回值。又读了几个已有的Service实现确认事务注解和日志写法。它甚至注意到项目里用的是Lombok所以在实体类上自动使用了Data而不是手写getter/setter。第二规划文件改动清单。它列出了改动涉及的文件列表标注了哪些是新增、哪些是修改以及每个文件的操作要点。这一步非常关键因为Codex默认的行为是一次性给你整段代码但有了规划环节改动范围和设计意图在动手前就明确了。第三按步骤实现代码。它先写了CSV工具类导出时用OutputStreamWriter指定UTF-8编码避免Excel打开中文乱码。然后写了Controller层的接口方法复用了项目里已有的ApiResponseT包装类。接着改动了Service层加了一个返回ListUser的方法注意保持了现有方法命名习惯。每一步它都会停下来解释这段代码的设计理由而不是闷头写。第四验证和修正。写完之后它主动提议编译并运行项目已有的测试。因为项目里本来就有一套基于Spring Test的集成测试它照猫画虎补了一个导出接口的测试方法。运行测试时发现CSV工具类里的逗号转义没处理——用户昵称里如果包含逗号本来应该用引号包裹首版代码漏了。代理在测试报告中发现了这个失败用例自己回去改了工具类补上转义逻辑再跑测试直到通过。完整流程跑下来给我的体验像在跟一个靠谱的结对程序员工作。我把这个案例写下来是想说清楚一件事superpowers真正改变的不是代码生成能力而是代理的工作方式。它把“写完就交差”变成了“分析清楚—规划到位—按序实施—主动验证”。3.3 Java生态集成注意事项在Java项目里用superpowers有几点我踩过坑之后觉得必须提醒你。第一确保Codex CLI能正确解析项目结构。Codex不会真的去编译你的Maven工程所以它理解项目结构靠的是读取pom.xml、目录结构、已有代码之间的引用关系。如果你项目里用了大量Lombok的链式构造或者自定义的依赖注入框架它可能读到一半卡住。我的习惯是让代理先“分析项目整体结构”确认它的理解和实际一致再让它动手。第二告诉代理JDK版本和构建工具版本。我遇到过代理生成代码时使用了JDK 17才有的语法但项目实际跑在JDK 11上编译直接失败。后来我在项目根目录放了一个.superpowers.md的说明文件里面写清楚JDK版本、构建命令、测试命令代理每次进场都会先读这个文件。这个做法非常管用基本杜绝了“版本不匹配”这类低级错误。第三Maven多模块项目的路径问题。如果你的项目是多模块结构代理有时会在查找类时找错模块。我在实践中发现让Codex在“分析项目结构”阶段输出一个模块依赖树能显著减少后续定位错文件的情况。虽然这个过程要多花一两分钟但比改错文件之后再返工便宜太多了。4. 实操流程与核心环节实现4.1 完整实操从零配置一个可用的superpowers工作环境这一节我把从零开始的全流程再串一遍给你一份可以直接按着敲的操作记录。注意我的环境是macOS zsh如果你用的是其他环境命令要按对应方式适配。第一步确认基础环境node -v npm -v codex --version我的版本分别是v20.11.0、10.2.4、以及Codex CLI的0.26.2。如果你的node版本低于18建议先把node升上去否则npm install过程中可能会遇到语法不支持的问题。第二步克隆并安装superpowersgit clone https://github.com/worksingh/superpowers.git ~/superpowers cd ~/superpowers npm install第三步建立配置目录链接mkdir -p ~/.codex ln -s ~/superpowers/config ~/.codex/superpowers第四步修改Codex配置文件。找到~/.codex/config.tomlmacOS路径Linux也是这个加上superpowers的声明。我贴一下我实际用的配置片段[sandbox] readonly_home false [superpowers] enabled true skills_path ~/.codex/superpowers这里有个细节readonly_home如果被默认设为true代理在读取某些配置时会受到权限限制导致技能加载异常。我之前被这个问题坑过代码看起来没错技能就是加载不出来后来发现是这个沙箱配置在捣鬼。第五步验证安装codex skills list看到技能列表输出就算成功。如果这里输出为空优先检查配置里的路径写法和实际目录是否一致不要把~直接用在toml里建议写成绝对路径比如/Users/你的用户名/.codex/superpowers。第六步用一个真实任务验证链路。我建议你选一个简单的小项目给代理下面这句指令请使用superpowers技能梳理当前项目的模块结构和核心调用链输出一份概要文档。如果代理开始按步骤分析、输出结构化报告安装就真正完成了。这一步跑通过一次你后面用起来心里就有底了。4.2 技能文件的自定义方法与模板superpowers真正值钱的地方在于你可以往里面添加自己的技能文件。这不需要写代码就是写Markdown。每个技能文件就是一份结构化的操作说明书编码代理会按里面的步骤执行。我自定义技能时的模板如下# 技能名称 ## 触发条件 什么样的任务应该触发这个技能描述要具体避免和其他技能重叠 ## 适用场景 描述这个技能解决的典型问题类型以及不适合使用的反例 ## 执行步骤 1. 第一步要做什么 2. 第二步要做什么 3. 第三步要做什么 ## 输入要求 代理在执行这个技能前需要确认哪些信息 ## 输出要求 代理完成任务后需要输出什么格式的结果举个例子我给团队写过一个“新增API接口的标准流程”技能里面的执行步骤是先读现有Controller代码确认路由风格和参数校验方式再读Service接口和实现确认事务和异常处理惯例然后按现状风格编写新接口最后补充测试用例并运行相关测试。写完之后放到~/.codex/superpowers/skills/目录下下次代理遇到新增接口的任务时就会自动匹配并调用。这个扩展能力的重要性怎么强调都不过分。它意味着superpowers不再是“别人的工具”而是能变成“你的团队的工具”。你们团队的代码规范、分支策略、测试要求都可以通过技能文件固化下来让编码代理遵守。4.3 参数配置与运行效果调优实际使用中有几个参数和设置对我的体验影响很大单独拎出来说一下。温度参数temperature这是控制生成随机性的参数默认值在0.7到0.8之间。在代码生成场景下我建议调到0.2到0.3。太高容易让代理写出“过于有创意”的代码太低会让输出变得机械。在Codex CLI里可以通过配置文件调我是放在用户的全局配置里覆盖的。最大输出长度max tokens代理一次能输出的文字数量上限。如果默认值偏小你会发现代理经常话说到一半就停了。这个参数因任务而异写代码的人通常希望一次能多输出一些。我把这个值调大了一些尤其是跑分析任务的时候太短的输出根本装不下结构化的报告。重试次数retry代理在遇到操作失败时自动重试的次数。我建议设成2到3次太少容易因偶发问题中断流程太多则可能在同一个错误上反复横跳浪费时间。工作目录限制建议给Codex限定到当前项目目录内避免它乱翻系统文件。这一步既是为了安全也是为了让它的注意力集中在项目本身。这些参数没有绝对的最优值跟你项目大小、模型能力、任务类型都有关系。我给你的建议是先用默认值跑一周记录你遇到的主要问题再针对性地调。不要一开始就追求复杂的配置先让流程跑通比什么都重要。5. 常见问题与排查技巧实录5.1 我踩过的五个高频坑用superpowers这段时间我遇到的典型问题五花八门但归纳下来有五个出现频率最高我把现象、原因、解决方式整理成了一张速查表现象可能原因解决步骤技能列表为空配置文件路径错误或未声明技能目录检查config.toml的skills_path是否为绝对路径确认目录确实存在代理不调用技能回答像普通对话技能触发条件不匹配或配置未生效修改技能文件的触发条件描述重启Codex CLI生成的代码风格和项目不一致代理未在动手前阅读现有代码在指令中明确要求“先分析现有代码风格再按惯例实现”或在项目根目录放规范说明文件运行测试时找不到测试类代理没识别到Maven的标准测试目录在指令中加入“使用Maven标准目录结构测试放src/test/java下”确认代理先读过pom.xml代理改文件改到一半迷失方向大任务没有拆解步骤明确要求使用任务编排技能把任务拆成摸底—规划—实施—验证或手动在指令里分步骤5.2 排查思路与调试技巧遇到问题不要急着怀疑superpowers本身。我给你一套我在实践中形成的排查思路这套思路帮我解决过至少七八次“看起来无解”的故障。第一步确认加载链路。问题是出在“配置没读到”还是“技能没触发”还是“生成了但执行失败”用codex skills list看技能有没有进来用codex --verbose启动调试模式观察日志里有没有技能加载记录。这条链路排查完至少能排除一半的配置类问题。第二步简化问题复现。我经常做一个“最小复现”操作把代理的任务缩小到最简单的单文件修改比如“给某个工具类加一个静态方法”看它在这个简单任务上是否正常走技能流程。如果简单任务都走不顺问题大概率在基础配置如果简单任务正常那问题出在复杂任务的触发条件上。第三步查看代理的“思考过程”。Codex命令行模式下代理有时会输出自己的推理过程。这些信息非常宝贵它让你看到代理是“读了技能文件但没理解”还是“根本没意识到这个任务可以触发技能”。前者是技能文件写得不清楚后者是触发条件描述不到位。5.3 独家避坑经验最后分享几条我在项目实战中积累的独家经验这些不属于任何官方文档纯属用时间换来的教训。第一每次跑重要任务之前先让代理输出项目结构。我经历过太多次“代理理解的项目结构和你实际的不一样”导致的返工。让它在动手前先输出一份结构摘要给你过目会浪费两分钟但能规避几十分钟的返工。第二不要把superpowers当代码搜索引擎用。它擅长的是“按流程执行任务”不是“回答你某个函数怎么用”。如果你问它“Java的Optional怎么用”它可能会套技能流程去分析半天反而绕晕。把问题包装成任务比如“在我的项目里找到可以用Optional简化空指针判断的地方并重构”效果会好得多。第三用好项目根目录的说明文件。我在Java项目里放了一个.superpowers.md里面写了项目简介、JDK版本、构建命令、测试命令、代码风格约定。代理进场读一遍这个文件后面几乎所有任务的质量都有提升。这个习惯建议你从第一天就开始养成比事后追加一百条指令有用得多。第四版本锁定的重要性。superpowers和Codex CLI更新频率都不低有时候两个版本之间的配合会有兼容性问题。我遇到过一次更新Codex后技能加载失效的情况回退Codex版本才恢复。有了这个教训之后我会在项目的package.json附近留一个版本说明记录当前使用的Codex和superpowers版本方便回溯。