从Codex CLI这类AI编程助手出现开始我就一直在倒腾怎么让它从“聊天窗口”变成“真正的结对程序员”。坦白说大部分时间是又爱又恨写个工具函数、跑一遍单测、修个lint警告Codex确实很溜但只要任务稍微复杂一点比如“帮我实现新模块并重构掉旧接口”它就开始表现得像个记性很差的外包新员工——做到一半忘了需求改了A文件忘了同步B文件编译报错后又原地绕圈。直到我发现了superpowers这个项目才算是补上了最关键的短板。这篇文章不啰嗦直接把我从安装到实战的经验摊开讲重点是Java项目里的真实场景希望对那些正在折腾Codex、Claude Code这类Agent CLI的朋友有帮助。1. 为什么Codex需要superpowers从一次失败的迭代实验说起1.1 裸用Codex时的三大痛点先说我在裸用Codex CLI时踩过的坑理解了这三个痛点你就知道superpowers到底解决了什么。第一个是缺乏全局视角。Codex一次只能处理有限上下文当项目有十几个文件、多个模块互相调用时它经常“只见树木不见森林”。我让它给一个Spring Boot服务加个新接口它能吭哧吭哧把Controller和Service写了但忘了在配置里注册拦截器数据库字段的映射也跟现有实体对不上。不是模型能力不够是它没有一套机制去强制自己先梳理全局、再动手。第二个是任务拆解能力弱。复杂任务需要拆成小步骤、逐步验证但裸Codex通常倾向于一口气生成一大段代码。结果就是表面上代码量惊人实际上一次性引入十几个Bug排查难度反而翻倍。这就好比让新手直接炒一桌宴席指望他同时处理切菜、配菜、起锅、勾芡手忙脚乱是必然的。第三个是缺少自我校验闭环。Codex改完代码如果没有人明确告诉它“你必须跑一遍构建、必须执行测试、必须检查变更影响范围”它大概率会拍拍胸口说“改完了”实际上编译都过不去。我在项目里盯着它连续五次出现这种情况后彻底意识到不是工具不行是我缺少一层“约束层”。1.2 superpowers的核心设计理念把Agent当成有章法的工程师superpowers的思路其实特别朴素既然裸Agent像“野路子”那就给它一套岗位说明书和作业流程把它从“什么都能聊一点的助手”变成“按SOP执行的工程师”。这套说明书的载体就是技能Skill文件每个技能对应一类任务场景比如调试、代码审查、重构、性能优化、构建与测试。技能文件内部包含了任务目标、前置条件、执行步骤、验收标准甚至写明了“遇到某类错误应该如何处理”。当Codex调用到某个技能时它就相当于拿到了一张检查清单step by step去执行。这种模式最大的好处是把“一次性生成正确答案”的赌运气模式变成了“分步逼近正确答案”的工程模式。我打一个生活化的比方裸Codex像一个聪明但没受过培训的新员工你让他“把客户投诉处理一下”他可能直接写封邮件发过去内容还不一定对。superpowers等于给他发了一本《客户投诉处理SOP手册》告诉他先查订单、再核实物流、然后按话术模板回复最后记录工单。流程一固定交付质量自然就稳了。1.3 使用superpowers前后的体验差异我这里有一个很直观的感受对比。没有superpowers时我给Codex的任务是“帮我修好登录接口500错误”它的典型反应是扫一眼代码 - 猜一个可能原因 - 改掉 - 告诉我修好了。至于它改完之后有没有影响其他接口、日志里是否还有残留异常、有没有补回归测试全看我有没有想起来提醒它。接入superpowers之后同样的任务Codex会先进入调试技能流程定位日志 - 复现问题 - 分析堆栈 - 修改代码 - 跑关联用例 - 输出变更说明。整个过程中它还会主动把重要决策记录下来方便我review。这个差异几乎是“从实习生到高级工程师”的级别一点不夸张。我用了一段时间后最明显的感受是代码review的负担轻了因为AI交付的东西不再“神头鬼脸”。2. 安装与初始化让superpowers跑起来2.1 前置环境先保证Codex能正常工作在折腾superpowers之前务必先把基础环境确认清楚。我见过太多人装了之后发现技能不触发排查到最后发现其实是Codex CLI版本太老或者Node环境不对。需要准备的基础条件按优先级排列如下可用的Codex CLI建议版本不要太旧最好是用官方最新稳定版Git用来克隆superpowers仓库Node.js运行时部分辅助脚本和技能依赖它执行一个真实的项目目录建议先用测试项目试跑别一上来就打生产仓库。这里强调一下Codex CLI是superpowers的地基如果你平时用Codex就不太稳定比如频繁断连、上下文经常丢失那先解决基础问题再上superpowers。不要指望这个框架能修复底层连接的问题它的定位是“行为增强”而不是“运行时修复”。2.2 安装步骤克隆、初始化和验证以我目前使用的版本为例整体安装流程不算复杂。我的做法是先从GitHub把superpowers仓库克隆到本地放到一个固定目录比如~/tools/superpowers然后用它自带的初始化脚本把技能结构和全局配置生成出来。具体流程可以参照下面这些步骤来走克隆仓库到本地固定目录查看README确认需要执行哪个初始化命令不同版本用的命令略有差异在项目根目录运行初始化脚本生成.superpowers或类似名称的目录在Codex的配置中指定技能目录路径让Codex启动时能读到技能列表用一个简单的测试任务验证技能触发生效。在执行第4步时需要注意不同项目接入方式可能不一样。我目前比较推荐的做法是在项目根目录放一份全局指令文件在文件里引用superpowers的技能目录相当于告诉Codex“咱们的项目有一套SOP请先读它”。这种方式的好处是技能文件可以随着项目走团队协作时一人配置全员复用。2.3 初始化之后目录里到底多了什么初始化完成后常见的目录结构大致是这样的项目根目录/ ├── .superpowers/ │ ├── skills/ │ │ ├── debug/ │ │ │ └── SKILL.md │ │ ├── code-review/ │ │ │ └── SKILL.md │ │ ├── build-and-test/ │ │ │ └── SKILL.md │ │ └── ... │ └── config.md └── codex_instructions.md逐个说下作用。skills目录里按场景分类放了若干技能文件每个技能的核心是一个SKILL.md里面定义了该场景下的完整工作流。config.md是全局配置文件可以放一些团队级约定比如“禁止修改generated/目录下的文件”“所有变更必须附带测试”。根目录的指令文件则相当于“入口”Codex启动后会先读它然后按图索骥去加载对应技能。这里要特别说一句技能目录的路径和读取权限一定要确认好。如果Codex运行时没有读取到技能文件它执行任务时完全不会按照技能流程走看起来就像“superpowers没装”。这个坑我后面在常见问题部分会展开讲。2.4 一个小技巧从最小技能集开始不要一上来全量加载我最初把superpowers里几乎所有技能都塞到项目里结果Codex每次读取配置都要损耗一片上下文而且技能之间还会出现指令冲突。后来我学乖了单个项目只挂载三五个核心技能比如调试、构建测试、代码审查缺什么再加什么。举个例子纯前端项目我就挂载前端调试和代码审查两个技能Java项目就换成构建测试、调试、依赖分析那一组。技能不是越多越好而是越对症越好。这个理念跟你给员工发SOP手册一样你不可能让一个人背完全公司所有流程他只需要掌握自己岗位那几本就够了。3. 技能Skills系统深入拆解别把它当黑盒子3.1 SKILL.md到底是什么一份机器可读的SOP很多人第一次打开SKILL.md会觉得这玩意儿长得有点奇怪既有自然语言可读的说明又有结构化的字段。其实它本质上就是一份让Agent遵循的标准作业程序只是将人类可读的SOP改写成了模型更容易逐条执行的格式。一个典型的SKILL.md会包含以下几个部分技能名称与触发条件说明什么情况下该用这个技能目标描述定义这个技能要达成的最终结果前置条件检查如果环境不满足则先处理环境执行步骤按编号列出每一步要做什么每步尽量清晰无歧义验收标准如何判断任务真正完成不是“我觉得行了”而是“构建通过、测试通过、变更记录完整”常见错误处理如果出现某种异常应该走哪个分支。我拿一个简单例子说明。假设你写了一个“处理编译错误”的技能它的步骤可以是这样读取编译器输出的第一处错误信息定位到报错文件的对应行号分析错误类型是语法错误、类型不匹配还是缺少依赖按错误类型采取对应修复方案重新执行构建命令若继续报错则重复步骤1但最多重试N次避免死循环修复完成后整理变更说明。看到区别了吗裸Codex遇到编译错误是无头苍蝇式试探而挂了技能之后它会像一个老练的工程师一样按部就班处理而且明确知道“最多重试N次”这种边界约束。3.2 技能的触发机制显式调用、上下文自动触发和用户指定我实测下来技能的触发主要有三种方式。第一种是显式调用也是最可靠的方式。在输入任务时直接把技能点名比如“使用调试技能分析这个崩溃”“按代码审查技能检查最新改动”。这种方式下Codex基本不会跑偏因为指令直接指定了路径。第二种是上下文自动触发。当你没有点名技能但任务内容明显匹配某个技能场景时Codex会根据项目指令文件里的规则自动调用对应技能。这种情况的效果取决于配置质量如果项目指令写得清晰自动触发的准确率会明显提升。第三种是用户中途指定。任务进行到一半你发现它的处理路径偏了可以直接说“停一下改用构建测试技能来处理当前问题”。大多数情况下Codex会乖乖切换到对应技能流程。我建议重要任务优先用显式调用因为自动触发偶尔会“自作主张”选错技能。比如我见过一次明明是要调试性能问题Codex却调用了代码审查技能虽然也有一定帮助但明显不对症。3.3 自己写技能从现有模板改起别从零创造自定义技能是superpowers最有价值的部分但很多新手一上来就想从零发明一套流程这其实没有必要。社区里已经沉淀了大量经过验证的技能模板正确做法是先抄后改、逐步迭代。要自定义一个技能我的套路如下从已有技能中挑一个最接近的比如“代码审查”配“调试”复制它的SKILL.md重命名成新的技能删掉不适用于自己团队的步骤补充团队特有要求在小项目上试运行观察Codex是否严格走完流程根据试运行结果微调步骤顺序和措辞直到稳定。有一点要特别提醒技能文件的措辞会影响Agent行为。比如你写“检查代码质量”它就比较含糊但如果你写“检查是否存在未处理的空指针风险、未关闭的连接以及缺少边界校验的参数”它就执行得很精准。所以写技能时多用可验证的动词少用抽象形容词。4. 实战走一遍superpowers Codex 在Java项目里的完整迭代4.1 实战背景一个订单服务的遗留模块改造光说不练没意思下面我把最近一个真实的Java项目迭代过程拆开给大家看。这是一个典型的Spring Boot订单服务核心业务是订单创建和状态流转技术栈是Java 17 Maven Spring Data JPA PostgreSQL。这次迭代的需求是给订单模块添加“支付超时自动取消”功能同时把原来散落在Service里的状态判断逻辑收敛到状态机里。这样的任务对AI来说难度不低因为它既是新功能开发又是老代码重构还得兼顾数据库变更和既有测试。老实说裸Codex接这种活大概率会翻车但挂上superpowers的技能体系之后整个流程就变得可以预期了。4.2 第一步需求分析与任务拆解接到任务后我先让Codex进入“规划技能”的流程它不是上来就写代码而是先输出任务理解、影响面分析和拆解后的子任务列表。Codex给我的输出大致结构如下理解现有订单状态模型找出所有状态判断点设计状态机流转规则待支付 - 已超时取消新增定时扫描任务处理超时未支付订单创建数据库变更脚本补充必要的索引编写单元测试和集成测试覆盖正常和异常路径更新接口文档和相关注释。看到这个列表我就知道这次稳了。因为拆解是合理的它没漏掉数据库和测试这两个非常容易被忽略的环节。放在以前裸Codex可能直接给你掏出半个状态机的实现然后完全忘了加索引。这个阶段我自己其实只做了两件事一是确认任务理解有没有偏差二是拍板用哪种状态机方案。方案层面的技术决议还是要人来做AI负责把决议落地。4.3 第二步构建测试技能保障“每一步都可验证”整个迭代过程中最令我满意的是superpowers的“构建测试技能”一直在起作用。Codex每完成一个子任务就会主动运行Maven编译和对应的测试用例不像以前那样攒到最后一口气验证。我记得在执行“状态流转规则实现”这一步时Codex写完了状态机核心类然后立刻执行了mvn compile接着运行了现有的订单测试。结果测试挂了——原因是旧代码里有几处直接对订单状态做字符串比较的写法和新的枚举定义不兼容。放在以前这种情况Codex可能自己都没发现因为它写完代码就以为完事了。但挂了“构建测试技能”之后它会自动进入修复循环定位失败断言 - 检查断言和字段映射 - 修改旧的比较逻辑 - 重新跑测试 - 确认全绿。这个过程一共迭代了三轮最终所有测试通过。最难得的是Codex在修复过程中没有破坏原有接口因为它每次都先跑全量测试来防止回归。这种“边写边验”的节奏正是工程交付的基本素养。4.4 第三步Java专项技能组合应用我这次项目里同时对几个Java专项技能进行了挂载和调用分享一些实战中的配置思路。Maven构建与依赖技能是必备的。我让Codex在改动涉及依赖时主动检查pom.xml变更并确认mvn dependency:tree没有意外冲突。这次任务里新引入了一个定时任务调度库Codex会自动检查它与项目现有库的版本兼容性避免了一上来就踩jar包冲突的地雷。JUnit测试技能也很关键。Codex生成的测试不再是一堆“断言非空”的假大空用例而是会主动识别边界条件。比如测试“超时取消”时它会覆盖支付超时临界点前后各1分钟的场景还会测试订单已经手动取消的情况下不会被定时任务重复处理。这种测试设计思路基本达到了有经验的开发者的水平。代码审查技能适合在迭代后期做一次全局扫描。Codex会就本次改动输出一份审查报告包含修改过的文件清单、潜在风险点、以及具体建议。它的风险点发现能力在superpowers的加持下确实提升了不少比如它注意到我项目里现有的事务管理方式可能导致超时取消操作不受事务保护提议补充Transactional。这个是真有用避免了一次线上隐患。4.5 实测对比有技能和没技能差了多少我特意用同样需求做了一组对比实验。裸Codex完成整个“超时取消”功能大约花了30分钟我全程盯了5次纠正了2次重大方向偏移Codex自己写了约1200行代码变更但测试一度全红最后在我辅助下才转化为全绿。接入superpowers后同一功能大约花了35分钟但我只review了2次Codex主动执行构建和测试超过15次写出的变更约900行测试从一开始就保持绿色或者可快速修复。改动的代码反而更少说明技能约束让它的产出更精准、不绕远路。个人感受是superpowers没有让AI变聪明但让它变得靠谱。它把模型现有的能力按照项目需要的质量规范组织起来大大减少了“AI胡说”的代价。5. 高频问题与避坑指南5.1 安装好了但Codex完全没反应排查思路这是群里被问得最多的问题“技能文件都在也按教程配了怎么Codex表现得跟平时一模一样”我总结下来多数是下面几个原因。第一指令文件没有被Codex读取。我建议你用一个极简任务测试一下比如“根据当前的构建测试技能输出本项目的构建命令列表”。如果它输出的是通用答案而不是技能里定义的详细步骤那基本可以肯定技能没加载。第二路径写错了。注意检查技能目录路径是否正确特别是Windows下盘符和分隔符问题。我吃过一次亏路径写错之后Codex静默跳过没有任何报错整得我排查了半个小时。第三版本不匹配。superpowers有些版本的指令格式和旧版Codex不兼容建议直接升级Codex到最新版再试别在兼容性问题上一根筋较劲。5.2 技能频繁触发但执行不完上下文窗口管理技巧接了superpowers后Codex每次执行技能都会多消耗上下文如果你项目指令文件里挂了一堆技能定义上下文压力会非常明显。表现就是任务执行到一半AI“忘了”先前的步骤或者开始压缩执行步骤最终产出质量下降。我的习惯做法是把技能文件写得短而精每个技能不超过120行。如果步骤特别多拆成主技能和子技能主技能负责分发子技能负责具体执行。此外在任务一开始就明确“只使用某几个技能”避免Codex把所有技能描述都加载一遍。还有一个小技巧把大段的不变内容放到仓库的固定文件里技能文件里只写引用路径比如“环境信息见docs/environment.md”这样每轮对话都少带一段重复内容上下文压力能小不少。5.3 技能效果不稳定同一任务两次结果差异大这个问题本质上不是superpowers的锅而是大模型自身的随机性。技能文件约束的是流程和检查点但不能完全消除生成内容的随机性。最有效的方式是关键决策点做确认我在技能里明确要求“涉及数据库变更、公共接口或安全相关代码时必须停顿并输出方案请求确认后再执行”。这样流程还是稳定的但遇到真正的高风险环节Agent不会自作主张。就我的经验这类“卡点确认”机制比指望模型每次都乖乖听话可靠得多。5.4 与现有CI/CD流程的融合建议最后说下团队协作场景。superpowers产出的技能文件本质是文本完全可以提交到代码仓库里进行版本管理。这意味着团队可以围绕技能做评审和迭代就像review代码一样review你的SOP指南。新成员clone仓库后就自动拥有了全套工程规范比看文档、听培训高效得多。我也建议在CI流程里增加一个检查步骤专门校验SKILL.md的文件格式和路径引用防止有人改了目录结构导致Agent失灵。一开始可能觉得多余但当你团队里超过三个人在同时维护技能文件时这种自动化校验的价值就会体现出来。最后再分享一个我自己摸索出来的技巧我在项目里给superpowers加了一个“变更总结”技能要求Codex每完成一次迭代后输出一份结构化总结包含改动了哪些文件、为什么这么改、测试覆盖率变化、遗留风险点以及回滚建议。这个东西一开始只是为了让review更方便后来发现它对知识沉淀的帮助更大。几周下来项目里积累的AI迭代记录几乎变成了一份最真实的项目维护日志新人看一眼就能搞明白历史决策的来龙去脉。所以我的建议是不要只把superpowers当成“AI听话的开关”它更大的价值在于逼着你想清楚“我们希望AI以什么流程工作”然后把这个流程固化下来。这个思考本身就会让你的工程交付体系往前迈一大步。 
长河君 · 2026/10/3 0:15:13 · 阅读 1.2k superpowers实战：用技能系统把Codex CLI变成靠谱结对程序员
从Codex CLI这类AI编程助手出现开始我就一直在倒腾怎么让它从“聊天窗口”变成“真正的结对程序员”。坦白说大部分时间是又爱又恨写个工具函数、跑一遍单测、修个lint警告Codex确实很溜但只要任务稍微复杂一点比如“帮我实现新模块并重构掉旧接口”它就开始表现得像个记性很差的外包新员工——做到一半忘了需求改了A文件忘了同步B文件编译报错后又原地绕圈。直到我发现了superpowers这个项目才算是补上了最关键的短板。这篇文章不啰嗦直接把我从安装到实战的经验摊开讲重点是Java项目里的真实场景希望对那些正在折腾Codex、Claude Code这类Agent CLI的朋友有帮助。1. 为什么Codex需要superpowers从一次失败的迭代实验说起1.1 裸用Codex时的三大痛点先说我在裸用Codex CLI时踩过的坑理解了这三个痛点你就知道superpowers到底解决了什么。第一个是缺乏全局视角。Codex一次只能处理有限上下文当项目有十几个文件、多个模块互相调用时它经常“只见树木不见森林”。我让它给一个Spring Boot服务加个新接口它能吭哧吭哧把Controller和Service写了但忘了在配置里注册拦截器数据库字段的映射也跟现有实体对不上。不是模型能力不够是它没有一套机制去强制自己先梳理全局、再动手。第二个是任务拆解能力弱。复杂任务需要拆成小步骤、逐步验证但裸Codex通常倾向于一口气生成一大段代码。结果就是表面上代码量惊人实际上一次性引入十几个Bug排查难度反而翻倍。这就好比让新手直接炒一桌宴席指望他同时处理切菜、配菜、起锅、勾芡手忙脚乱是必然的。第三个是缺少自我校验闭环。Codex改完代码如果没有人明确告诉它“你必须跑一遍构建、必须执行测试、必须检查变更影响范围”它大概率会拍拍胸口说“改完了”实际上编译都过不去。我在项目里盯着它连续五次出现这种情况后彻底意识到不是工具不行是我缺少一层“约束层”。1.2 superpowers的核心设计理念把Agent当成有章法的工程师superpowers的思路其实特别朴素既然裸Agent像“野路子”那就给它一套岗位说明书和作业流程把它从“什么都能聊一点的助手”变成“按SOP执行的工程师”。这套说明书的载体就是技能Skill文件每个技能对应一类任务场景比如调试、代码审查、重构、性能优化、构建与测试。技能文件内部包含了任务目标、前置条件、执行步骤、验收标准甚至写明了“遇到某类错误应该如何处理”。当Codex调用到某个技能时它就相当于拿到了一张检查清单step by step去执行。这种模式最大的好处是把“一次性生成正确答案”的赌运气模式变成了“分步逼近正确答案”的工程模式。我打一个生活化的比方裸Codex像一个聪明但没受过培训的新员工你让他“把客户投诉处理一下”他可能直接写封邮件发过去内容还不一定对。superpowers等于给他发了一本《客户投诉处理SOP手册》告诉他先查订单、再核实物流、然后按话术模板回复最后记录工单。流程一固定交付质量自然就稳了。1.3 使用superpowers前后的体验差异我这里有一个很直观的感受对比。没有superpowers时我给Codex的任务是“帮我修好登录接口500错误”它的典型反应是扫一眼代码 - 猜一个可能原因 - 改掉 - 告诉我修好了。至于它改完之后有没有影响其他接口、日志里是否还有残留异常、有没有补回归测试全看我有没有想起来提醒它。接入superpowers之后同样的任务Codex会先进入调试技能流程定位日志 - 复现问题 - 分析堆栈 - 修改代码 - 跑关联用例 - 输出变更说明。整个过程中它还会主动把重要决策记录下来方便我review。这个差异几乎是“从实习生到高级工程师”的级别一点不夸张。我用了一段时间后最明显的感受是代码review的负担轻了因为AI交付的东西不再“神头鬼脸”。2. 安装与初始化让superpowers跑起来2.1 前置环境先保证Codex能正常工作在折腾superpowers之前务必先把基础环境确认清楚。我见过太多人装了之后发现技能不触发排查到最后发现其实是Codex CLI版本太老或者Node环境不对。需要准备的基础条件按优先级排列如下可用的Codex CLI建议版本不要太旧最好是用官方最新稳定版Git用来克隆superpowers仓库Node.js运行时部分辅助脚本和技能依赖它执行一个真实的项目目录建议先用测试项目试跑别一上来就打生产仓库。这里强调一下Codex CLI是superpowers的地基如果你平时用Codex就不太稳定比如频繁断连、上下文经常丢失那先解决基础问题再上superpowers。不要指望这个框架能修复底层连接的问题它的定位是“行为增强”而不是“运行时修复”。2.2 安装步骤克隆、初始化和验证以我目前使用的版本为例整体安装流程不算复杂。我的做法是先从GitHub把superpowers仓库克隆到本地放到一个固定目录比如~/tools/superpowers然后用它自带的初始化脚本把技能结构和全局配置生成出来。具体流程可以参照下面这些步骤来走克隆仓库到本地固定目录查看README确认需要执行哪个初始化命令不同版本用的命令略有差异在项目根目录运行初始化脚本生成.superpowers或类似名称的目录在Codex的配置中指定技能目录路径让Codex启动时能读到技能列表用一个简单的测试任务验证技能触发生效。在执行第4步时需要注意不同项目接入方式可能不一样。我目前比较推荐的做法是在项目根目录放一份全局指令文件在文件里引用superpowers的技能目录相当于告诉Codex“咱们的项目有一套SOP请先读它”。这种方式的好处是技能文件可以随着项目走团队协作时一人配置全员复用。2.3 初始化之后目录里到底多了什么初始化完成后常见的目录结构大致是这样的项目根目录/ ├── .superpowers/ │ ├── skills/ │ │ ├── debug/ │ │ │ └── SKILL.md │ │ ├── code-review/ │ │ │ └── SKILL.md │ │ ├── build-and-test/ │ │ │ └── SKILL.md │ │ └── ... │ └── config.md └── codex_instructions.md逐个说下作用。skills目录里按场景分类放了若干技能文件每个技能的核心是一个SKILL.md里面定义了该场景下的完整工作流。config.md是全局配置文件可以放一些团队级约定比如“禁止修改generated/目录下的文件”“所有变更必须附带测试”。根目录的指令文件则相当于“入口”Codex启动后会先读它然后按图索骥去加载对应技能。这里要特别说一句技能目录的路径和读取权限一定要确认好。如果Codex运行时没有读取到技能文件它执行任务时完全不会按照技能流程走看起来就像“superpowers没装”。这个坑我后面在常见问题部分会展开讲。2.4 一个小技巧从最小技能集开始不要一上来全量加载我最初把superpowers里几乎所有技能都塞到项目里结果Codex每次读取配置都要损耗一片上下文而且技能之间还会出现指令冲突。后来我学乖了单个项目只挂载三五个核心技能比如调试、构建测试、代码审查缺什么再加什么。举个例子纯前端项目我就挂载前端调试和代码审查两个技能Java项目就换成构建测试、调试、依赖分析那一组。技能不是越多越好而是越对症越好。这个理念跟你给员工发SOP手册一样你不可能让一个人背完全公司所有流程他只需要掌握自己岗位那几本就够了。3. 技能Skills系统深入拆解别把它当黑盒子3.1 SKILL.md到底是什么一份机器可读的SOP很多人第一次打开SKILL.md会觉得这玩意儿长得有点奇怪既有自然语言可读的说明又有结构化的字段。其实它本质上就是一份让Agent遵循的标准作业程序只是将人类可读的SOP改写成了模型更容易逐条执行的格式。一个典型的SKILL.md会包含以下几个部分技能名称与触发条件说明什么情况下该用这个技能目标描述定义这个技能要达成的最终结果前置条件检查如果环境不满足则先处理环境执行步骤按编号列出每一步要做什么每步尽量清晰无歧义验收标准如何判断任务真正完成不是“我觉得行了”而是“构建通过、测试通过、变更记录完整”常见错误处理如果出现某种异常应该走哪个分支。我拿一个简单例子说明。假设你写了一个“处理编译错误”的技能它的步骤可以是这样读取编译器输出的第一处错误信息定位到报错文件的对应行号分析错误类型是语法错误、类型不匹配还是缺少依赖按错误类型采取对应修复方案重新执行构建命令若继续报错则重复步骤1但最多重试N次避免死循环修复完成后整理变更说明。看到区别了吗裸Codex遇到编译错误是无头苍蝇式试探而挂了技能之后它会像一个老练的工程师一样按部就班处理而且明确知道“最多重试N次”这种边界约束。3.2 技能的触发机制显式调用、上下文自动触发和用户指定我实测下来技能的触发主要有三种方式。第一种是显式调用也是最可靠的方式。在输入任务时直接把技能点名比如“使用调试技能分析这个崩溃”“按代码审查技能检查最新改动”。这种方式下Codex基本不会跑偏因为指令直接指定了路径。第二种是上下文自动触发。当你没有点名技能但任务内容明显匹配某个技能场景时Codex会根据项目指令文件里的规则自动调用对应技能。这种情况的效果取决于配置质量如果项目指令写得清晰自动触发的准确率会明显提升。第三种是用户中途指定。任务进行到一半你发现它的处理路径偏了可以直接说“停一下改用构建测试技能来处理当前问题”。大多数情况下Codex会乖乖切换到对应技能流程。我建议重要任务优先用显式调用因为自动触发偶尔会“自作主张”选错技能。比如我见过一次明明是要调试性能问题Codex却调用了代码审查技能虽然也有一定帮助但明显不对症。3.3 自己写技能从现有模板改起别从零创造自定义技能是superpowers最有价值的部分但很多新手一上来就想从零发明一套流程这其实没有必要。社区里已经沉淀了大量经过验证的技能模板正确做法是先抄后改、逐步迭代。要自定义一个技能我的套路如下从已有技能中挑一个最接近的比如“代码审查”配“调试”复制它的SKILL.md重命名成新的技能删掉不适用于自己团队的步骤补充团队特有要求在小项目上试运行观察Codex是否严格走完流程根据试运行结果微调步骤顺序和措辞直到稳定。有一点要特别提醒技能文件的措辞会影响Agent行为。比如你写“检查代码质量”它就比较含糊但如果你写“检查是否存在未处理的空指针风险、未关闭的连接以及缺少边界校验的参数”它就执行得很精准。所以写技能时多用可验证的动词少用抽象形容词。4. 实战走一遍superpowers Codex 在Java项目里的完整迭代4.1 实战背景一个订单服务的遗留模块改造光说不练没意思下面我把最近一个真实的Java项目迭代过程拆开给大家看。这是一个典型的Spring Boot订单服务核心业务是订单创建和状态流转技术栈是Java 17 Maven Spring Data JPA PostgreSQL。这次迭代的需求是给订单模块添加“支付超时自动取消”功能同时把原来散落在Service里的状态判断逻辑收敛到状态机里。这样的任务对AI来说难度不低因为它既是新功能开发又是老代码重构还得兼顾数据库变更和既有测试。老实说裸Codex接这种活大概率会翻车但挂上superpowers的技能体系之后整个流程就变得可以预期了。4.2 第一步需求分析与任务拆解接到任务后我先让Codex进入“规划技能”的流程它不是上来就写代码而是先输出任务理解、影响面分析和拆解后的子任务列表。Codex给我的输出大致结构如下理解现有订单状态模型找出所有状态判断点设计状态机流转规则待支付 - 已超时取消新增定时扫描任务处理超时未支付订单创建数据库变更脚本补充必要的索引编写单元测试和集成测试覆盖正常和异常路径更新接口文档和相关注释。看到这个列表我就知道这次稳了。因为拆解是合理的它没漏掉数据库和测试这两个非常容易被忽略的环节。放在以前裸Codex可能直接给你掏出半个状态机的实现然后完全忘了加索引。这个阶段我自己其实只做了两件事一是确认任务理解有没有偏差二是拍板用哪种状态机方案。方案层面的技术决议还是要人来做AI负责把决议落地。4.3 第二步构建测试技能保障“每一步都可验证”整个迭代过程中最令我满意的是superpowers的“构建测试技能”一直在起作用。Codex每完成一个子任务就会主动运行Maven编译和对应的测试用例不像以前那样攒到最后一口气验证。我记得在执行“状态流转规则实现”这一步时Codex写完了状态机核心类然后立刻执行了mvn compile接着运行了现有的订单测试。结果测试挂了——原因是旧代码里有几处直接对订单状态做字符串比较的写法和新的枚举定义不兼容。放在以前这种情况Codex可能自己都没发现因为它写完代码就以为完事了。但挂了“构建测试技能”之后它会自动进入修复循环定位失败断言 - 检查断言和字段映射 - 修改旧的比较逻辑 - 重新跑测试 - 确认全绿。这个过程一共迭代了三轮最终所有测试通过。最难得的是Codex在修复过程中没有破坏原有接口因为它每次都先跑全量测试来防止回归。这种“边写边验”的节奏正是工程交付的基本素养。4.4 第三步Java专项技能组合应用我这次项目里同时对几个Java专项技能进行了挂载和调用分享一些实战中的配置思路。Maven构建与依赖技能是必备的。我让Codex在改动涉及依赖时主动检查pom.xml变更并确认mvn dependency:tree没有意外冲突。这次任务里新引入了一个定时任务调度库Codex会自动检查它与项目现有库的版本兼容性避免了一上来就踩jar包冲突的地雷。JUnit测试技能也很关键。Codex生成的测试不再是一堆“断言非空”的假大空用例而是会主动识别边界条件。比如测试“超时取消”时它会覆盖支付超时临界点前后各1分钟的场景还会测试订单已经手动取消的情况下不会被定时任务重复处理。这种测试设计思路基本达到了有经验的开发者的水平。代码审查技能适合在迭代后期做一次全局扫描。Codex会就本次改动输出一份审查报告包含修改过的文件清单、潜在风险点、以及具体建议。它的风险点发现能力在superpowers的加持下确实提升了不少比如它注意到我项目里现有的事务管理方式可能导致超时取消操作不受事务保护提议补充Transactional。这个是真有用避免了一次线上隐患。4.5 实测对比有技能和没技能差了多少我特意用同样需求做了一组对比实验。裸Codex完成整个“超时取消”功能大约花了30分钟我全程盯了5次纠正了2次重大方向偏移Codex自己写了约1200行代码变更但测试一度全红最后在我辅助下才转化为全绿。接入superpowers后同一功能大约花了35分钟但我只review了2次Codex主动执行构建和测试超过15次写出的变更约900行测试从一开始就保持绿色或者可快速修复。改动的代码反而更少说明技能约束让它的产出更精准、不绕远路。个人感受是superpowers没有让AI变聪明但让它变得靠谱。它把模型现有的能力按照项目需要的质量规范组织起来大大减少了“AI胡说”的代价。5. 高频问题与避坑指南5.1 安装好了但Codex完全没反应排查思路这是群里被问得最多的问题“技能文件都在也按教程配了怎么Codex表现得跟平时一模一样”我总结下来多数是下面几个原因。第一指令文件没有被Codex读取。我建议你用一个极简任务测试一下比如“根据当前的构建测试技能输出本项目的构建命令列表”。如果它输出的是通用答案而不是技能里定义的详细步骤那基本可以肯定技能没加载。第二路径写错了。注意检查技能目录路径是否正确特别是Windows下盘符和分隔符问题。我吃过一次亏路径写错之后Codex静默跳过没有任何报错整得我排查了半个小时。第三版本不匹配。superpowers有些版本的指令格式和旧版Codex不兼容建议直接升级Codex到最新版再试别在兼容性问题上一根筋较劲。5.2 技能频繁触发但执行不完上下文窗口管理技巧接了superpowers后Codex每次执行技能都会多消耗上下文如果你项目指令文件里挂了一堆技能定义上下文压力会非常明显。表现就是任务执行到一半AI“忘了”先前的步骤或者开始压缩执行步骤最终产出质量下降。我的习惯做法是把技能文件写得短而精每个技能不超过120行。如果步骤特别多拆成主技能和子技能主技能负责分发子技能负责具体执行。此外在任务一开始就明确“只使用某几个技能”避免Codex把所有技能描述都加载一遍。还有一个小技巧把大段的不变内容放到仓库的固定文件里技能文件里只写引用路径比如“环境信息见docs/environment.md”这样每轮对话都少带一段重复内容上下文压力能小不少。5.3 技能效果不稳定同一任务两次结果差异大这个问题本质上不是superpowers的锅而是大模型自身的随机性。技能文件约束的是流程和检查点但不能完全消除生成内容的随机性。最有效的方式是关键决策点做确认我在技能里明确要求“涉及数据库变更、公共接口或安全相关代码时必须停顿并输出方案请求确认后再执行”。这样流程还是稳定的但遇到真正的高风险环节Agent不会自作主张。就我的经验这类“卡点确认”机制比指望模型每次都乖乖听话可靠得多。5.4 与现有CI/CD流程的融合建议最后说下团队协作场景。superpowers产出的技能文件本质是文本完全可以提交到代码仓库里进行版本管理。这意味着团队可以围绕技能做评审和迭代就像review代码一样review你的SOP指南。新成员clone仓库后就自动拥有了全套工程规范比看文档、听培训高效得多。我也建议在CI流程里增加一个检查步骤专门校验SKILL.md的文件格式和路径引用防止有人改了目录结构导致Agent失灵。一开始可能觉得多余但当你团队里超过三个人在同时维护技能文件时这种自动化校验的价值就会体现出来。最后再分享一个我自己摸索出来的技巧我在项目里给superpowers加了一个“变更总结”技能要求Codex每完成一次迭代后输出一份结构化总结包含改动了哪些文件、为什么这么改、测试覆盖率变化、遗留风险点以及回滚建议。这个东西一开始只是为了让review更方便后来发现它对知识沉淀的帮助更大。几周下来项目里积累的AI迭代记录几乎变成了一份最真实的项目维护日志新人看一眼就能搞明白历史决策的来龙去脉。所以我的建议是不要只把superpowers当成“AI听话的开关”它更大的价值在于逼着你想清楚“我们希望AI以什么流程工作”然后把这个流程固化下来。这个思考本身就会让你的工程交付体系往前迈一大步。