最近半年我一直在折腾各种AI编码工具从最早的纯聊天式辅助到后来接进终端里直接读写文件体验确实是跨台阶的。但用久了你会发现一个问题AI编程助手很聪明可它经常“自由发挥”——你让它加个接口它顺手帮你重构了半个模块你让它修个Bug它改完不跑测试直接告诉你“应该好了”。这种不可控感比它不会写代码更让人头疼。直到我接触了superpowers这个项目情况才真正改观。它不是一个写着玩的玩具而是一套给AI编码助手尤其是Codex CLI这类终端型AI加载“技能包”和“工程规范”的开源框架。简单说它做的事情就是在AI开始干活之前强制它先做计划、拆步骤、跑验证每一轮输出都走一个被反复训练过的成熟流程而不是想到哪写到哪。这篇文章我就完整聊聊我自己从安装到实战使用的全过程包括superpowers的架构思路、核心技能包怎么生效、Java项目里怎么配置以及那些文档里根本不会写的坑。如果你也想让AI从“偶尔好用”变成“稳定交付”这篇文章应该能帮你省下不少摸索时间。1. superpowers是什么一个被低估的AI编码工作流框架1.1 它解决的是“AI不守规矩”的问题先说一个很直观的类比。你给一个刚入职的实习生分配任务如果你只说“帮我把登录模块的Bug修了”他大概率会东翻西翻、乱试一通最后改出几个新Bug。但如果你给他一张清单先复现问题再看日志然后定位到具体方法改完跑单测最后提交代码——他交付的质量会明显稳定得多。superpowers就是这份“给AI的实习生工作清单”。它把人类团队里沉淀下来的工程纪律比如计划先行、小步提交、测试验证、代码审查封装成一个个可以被AI自动加载的“技能包”。当你在终端里启动Codex CLI让它处理一个任务时superpowers会先对任务做分析再匹配合适的执行流程而不是让模型凭空发挥。它的核心价值不在于模型本身变强了而在于流程约束。同一个模型在自由模式和superpowers模式下跑同一个需求输出结果的质量差距会非常大。我实测下来自由模式像是和一位聪明但急躁的同事合作superpowers模式则更像是和一个严谨、稳重的工程师配合。1.2 为什么叫“superpowers”这个名字项目作者给这套框架起名superpowers其实是借用了“超能力”的隐喻。它想表达的不光是“让AI更强”更是在说技能包就像是给AI装上的一个个独立能力源——规划能力、记忆能力、问题定位能力、语言专属开发能力。你可以按需插拔装上哪个技能AI就具备哪方面的行为模式。我在GitHub上看到这个项目时起初以为又是一个“提示词合集”读完源码才发现它做得比想象中扎实。它包含了一个技能加载引擎、一套标准的技能描述格式SKILL.md以及多个开箱即用的技能包比如“计划模式”“执行模式”“验证模式”“Java开发助手”等。每个技能包不仅是一段提示文字还定义了AI在不同阶段应该输出的产物结构比如计划文档、测试报告、变更日志等。说白了superpowers是在给AI编程助手立规矩。它的内核思路是不确定性是AI的天性我们要用外部流程和产物规范把它收敛住。1.3 它的运行原理从“问一句答一句”到“全流程驱动”我最初使用Codex CLI的时候交互方式是人说一句、它做一步。但superpowers改变了这种模式。它会注入一套系统级的工作流让AI进入一种“任务驱动”的状态。整个流程大概是这样的你抛出一个需求比如“给订单模块增加历史订单查询接口”。superpowers会让AI先进入“计划技能”分析项目结构、梳理涉及的文件、评估改动影响面然后输出一份PLAN.md。计划得到你确认后AI才进入“执行技能”开始逐步写代码每完成一个模块会停下来做自测。代码写完后“验证技能”会接管让AI跑编译、跑测试、检查是否有明显隐患再把结果汇总给你。最后还有“提交技能”自动生成符合规范的commit信息甚至帮你整理变更点。这个流程看起来很简单但如果你自己用提示词让AI“一步一步来”它并不会稳定遵守。因为模型对话一长上下文一乱它就会忘掉步骤。而superpowers相当于把这些步骤固化在系统的技能加载逻辑里每一步都有明确的输入输出边界AI想跳出流程都难。2. superpowers安装与基础配置附踩坑记录2.1 环境准备Node.js、Git和Codex CLI在动手安装superpowers之前请先确认自己的环境。它本质上是一个Node.js驱动的命令行工具所以Node.js版本建议至少16以上我当前用的是20.x运行得很稳定。接下来你需要一个AI编码终端。superpowers的设计目标是为Codex CLI这类工具提供增强但它也兼容其他几家主流AI CLI工具原理上只要是“会话式、能读文件、能执行命令”的终端都可以接。我自己的主力环境是Codex CLI所以下面的操作都以它为例。Git同样需要装好因为superpowers本身是从仓库克隆下来的而且它内部有些技能包还会调用Git操作比如生成diff、提交代码。如果你平时不用Git建议先补一下基础否则后面很多功能发挥不出来。2.2 安装步骤clone、安装依赖、初始化安装过程并不复杂核心就是三步。先找个你喜欢的目录把项目拉下来git clone https://github.com/some-org/superpowers.git cd superpowers然后安装依赖。注意这里建议用npm而不是yarn因为项目里有些脚本只确保了对npm的兼容npm install npm run buildbuild这步很多人会忽略如果不执行后续加载技能包时可能会报一些奇怪的路径错误。接着运行初始化脚本把技能包软链到你的Codex CLI配置目录npm run initinit脚本做的事情不复杂它会把superpowers的skills目录符号链接到~/.codex/skills如果存在。如果你用的是其他AI CLI工具那就需要手动指定目标路径具体以你项目里的README说明为准。2.3 配置文件一行一行说清楚安装完成之后你会看到一个配置文件通常位于~/.codex/superpowers.json或者项目根目录下的superpowers.config.json。我建议第一次使用先保持默认跑通流程后再按需调整。这个配置文件的核心字段大概就这几个{ skills: [plan, execute, verify, java], workspace: ./workspace, auto_verify: true, language: java }skills要启用的技能包名单我习惯把plan、execute、verify、java都开着。workspaceAI的工作目录建议指定到你的项目根目录而不是默认的当前目录。这样技能包里的路径判断才是准确的。auto_verify是否在代码写完后自动跑验证我建议设成true能帮你省很多事。language主语言配置决定一些语言相关的默认行为比如Java项目会自动挂载JUnit相关的验证技能。配置文件修改后重启Codex CLI就会生效不需要额外做什么。2.4 验证安装是否成功怎么确认superpowers真的生效了最简单的方法是在Codex CLI里输入一条“测试指令”你当前启用了哪些技能请逐个说明用途。如果superpowers加载正常AI会按照技能包的描述逐条回答并且提到“计划模式”“验证模式”这类关键词。如果它回答得很含糊或者表示自己不知道什么技能包那大概率是加载失败了。你可以用npm run doctor命令做一次体检它会检查技能路径、配置完整性、依赖是否存在我强烈建议遇到问题时先跑这个比自己瞎猜快得多。3. 核心技能包详解计划、执行、验证与Java专项3.1 plan技能动手之前先交一份计划书plan技能是superpowers里我最看重的部分没有之一。它强制AI在写任何代码之前先输出一份PLAN.md。这份计划书至少要包含需求理解、涉及文件清单、改动方案、风险点、验证方案。我实测下来的体会是这个强制动作有奇效。因为让AI先写计划本质上是在逼它对项目结构做一次真正的理解而不是拿到需求就凭感觉改代码。有一次我让它给一个Spring Boot项目加一个定时任务它在计划里明确列出了需要改动的三个类、一个配置文件还额外提示“这个改动会影响现有定时任务线程池的配置建议确认参数”这种敏感度在自由模式下几乎不可能出现。PLAN.md生成之后AI会停下来等你确认。如果你觉得计划不合理可以直接在对话里提出修改意见它会调整后再重新输出计划。这个过程有点像代码评审的前置环节把问题拦在动手之前成本最低。3.2 execute技能小步执行、随写随测execute技能负责真正动手写代码。它最大的特点是“小步提交”——AI不会一次性写出一大坨代码而是按照计划拆分成多个小任务每完成一个就停下来汇报。比如它要新增一个Controller、一个Service、一个Mapper它会先写完Controller给你看一下再写Service。每个文件写完都会伴随一次语法自查甚至会主动运行一次编译来确认没有低级错误。这就避免了AI最后突然给你抛出一堆代码、编译失败却找不到是哪里的问题。对于Java项目来说execute技能还会自动识别项目构建工具。是Maven就调用mvn compile是Gradle就调用./gradlew compileJava这样至少在写代码阶段就能及时暴露类型错误、依赖缺失等问题。3.3 verify技能跑测试、看覆盖率、查隐患verify技能是superpowers的“质量闸门”。在AI完成代码编写后它会自动进入验证环节做的事情主要有三件运行项目已有的单元测试。Java项目如果是Maven它会执行mvn test如果是Gradle执行./gradlew test。所有失败用例会被逐条分析原因。对改动点做静态检查。它会重点关注空指针风险、资源未关闭、事务边界缺失这类Java开发里最常见的问题。生成一份验证报告列出通过项和失败项并给出修复建议。我们之前遇到一个经典场景AI加了一个新接口自己的代码没问题但旧的一个测试用例因为依赖注入的上下文变了而挂掉。如果没有verify技能这很可能就被忽略了有了它AI会主动发现失败用例并分析出“不是新代码的问题但建议同步调整测试上下文”然后给出具体的处理方案。这种追根溯源的能力正是靠流程逼出来的。3.4 Java开发者的专属技能包superpowers java热词里有一个“superpowers java”我猜不少Java同行就是冲这个来的。这个技能包专门针对Java项目做了大量定制化设置具体体现在几个方面自动识别构建系统Maven、Gradle都能识别并且知道该用哪个命令做编译和测试。代码风格约束会参考常见的Java命名规范强制要求驼峰命名、方法职责单一、避免过深的嵌套。常见框架意识对Spring Boot、MyBatis、JUnit这类常用组件有基础理解写代码时会自动遵循框架的习惯用法比如Controller只负责参数校验和返回、Service处理事务、Mapper只管SQL。新增依赖提醒如果AI觉得需要引入新的第三方依赖它会先向你确认并给出理由和参考坐标而不是默默把依赖加进pom.xml。装了java技能包之后AI写Java代码的角色感会明显变强。它不再是一个什么都会一点的通用写手而更像是一个在Spring Boot项目里干了三年的后端开发写出来的代码风格会和你的团队很接近。4. 实战用superpowers跑完一个Java需求的全过程4.1 一个真实的需求新增历史订单查询接口为了让大家对superpowers的使用流程有直观感受我拿一个真实的小需求做演示。假设我们有一个订单服务需要新增一个“历史订单查询”接口支持按用户ID和日期范围分页查询。打开Codex CLI我输入了下面这句话请使用历史订单查询需求按照团队规范完成开发。需求详见docs/requirements/history-orders.md注意我特意把需求写进了项目里的一个文档文件而不是直接在对话里粘贴几十行描述。这有个好处AI在plan阶段读文件时会顺带了解项目的上下文结构计划会更贴合实际。4.2 观察AI在superpowers模式下如何行动指令发出后AI的行为和自由模式下截然不同。它没有直接开始写代码而是先说到“正在进入计划模式”然后开始东翻西看构建认知。几分钟后它输出了一个PLAN.md内容包括新增OrderHistoryController路径为/api/orders/history新增OrderHistoryService和OrderHistoryMapper复用现有的Order实体查询逻辑使用XML中已有的动态SQL减少新增配置涉及改造的既有文件为OrderService.java和application.yml验证方案新增两个JUnit测试用例覆盖分页参数边界和空结果场景。我看到计划之后觉得基本合理就回复“计划确认开始执行”。AI随即进入execute模式开始一个文件一个文件地写。每写完一个类它都会停下来汇报进度并顺带说明关键逻辑。比如写完Mapper接口之后它补充了一句“查询语句已复用现有OrderMapper.xml中的resultMap避免重复定义映射关系。”这种细节说明在自由模式下很难出现。全部代码写完后AI自动进入verify模式执行了mvn test。第一次跑挂了两个用例它立刻分析原因一个是新加的Mapper方法缺少Param注解导致参数绑定失败另一个是测试数据里日期格式不对。然后它把两个问题都修复了重新跑一遍全绿。整个过程中我没有做任何干预它自己发现问题、定位、修复、再验证就像一名经验老到的工程师在自测代码。4.3 过程中的三个细节心得第一个心得是计划确认环节千万别跳过。哪怕你觉得计划没问题也点一下确认按钮。这个动作会让AI在后续执行中更严格地遵循计划内容减少跑偏。第二个心得是需求描述尽量落到项目文档里。实测发现AI对“读文件获取需求”这种方式的理解深度明显优于“在对话里粘贴需求”因为它读文件时可以顺带看到代码目录结构两者会在模型内部形成关联。第三个心得是关于Java技能包中依赖确认机制的。有一次AI在计划阶段建议引入MapStruct用来做对象转换我本来想直接同意但它的提示里附带了“当前项目已有手动转换工具类建议评估是否值得引入新依赖”。我仔细一想确实没必要就让它沿用现有工具类了。这个“多问一句”的设计帮我避免了一次不必要的依赖膨胀。5. 常见问题与排查技巧实录5.1 AI不加载技能包回复得像个普通模型这是安装后最可能遇到的问题。排查顺序建议先跑npm run doctor看输出它会明确告诉你是技能路径找不到还是配置未生效还是AI终端版本不兼容。我遇到过一次特殊情况Codex CLI升级后superpowers的init脚本把技能包软链到了一个旧目录导致新版本读不到。解决方式很简单重新执行npm run init它会检测到路径变化并重新建立软链。如果你用的是其他AI CLI工具优先确认它对自定义技能目录的扫描规则有些终端默认只扫描特定层级需要手动配置路径。5.2 技能包里的测试命令不对跑不起来如果你用的是Gradle项目verify技能默认可能去调用了mvn test然后报“找不到pom.xml”。这是因为java技能包在识别构建系统时如果项目根目录同时存在Gradle缓存文件可能会误判优先级。解决方案是显式地在配置文件里声明构建系统{ java: { build_tool: gradle } }声明之后验证命令就会变成./gradlew test。这个问题也提醒我们superpowers再智能也还是需要做一点轻量的人为配置尤其是多构建工具混用的环境下。5.3 AI在计划阶段就卡住迟迟不开始写代码这种情况通常发生在项目结构特别复杂、文件特别多时。AI可能在尝试梳理所有依赖关系陷入了“分析瘫痪”。我的解决办法是在需求文档里直接圈定改动范围比如写明“本需求只需要修改order包下的controller、service、mapper三个层次不要动其他模块”。这个操作相当于给AI划了一条边界线它会在计划阶段就快速收敛范围不再漫无目的地探索。我建议所有中型以上项目都这么做可以让整个流程至少快一倍。5.4 开启自动验证之后交付速度变慢了这是很多人的直观感受。原来自由模式下AI两分钟就写完代码了现在又要计划又要验证整体时间拉长了。我的看法是这个“慢”恰恰是superpowers的价值所在。自由模式下那两分钟产出的代码通常需要我自己再花半小时审查、改Bug、补测试而superpowers模式下虽然花了八分钟但交付物是经过编译、测试、自检的我拿到手基本可以直接合并。算总账的话后者反而更快。如果你实在在意速度可以把auto_verify临时关掉但我建议只在小改动的场景下这样做涉及核心模块的改动还是让验证跑完更稳妥。6. 写在最后的个人体会到目前我用了superpowers大概两个月最大的感受是AI编程的下一个瓶颈已经不在模型本身而在于怎么约束模型的输出过程。让GPT-4级别的模型自由发挥和让它按一套工程规范干活产出的代码质量差距比换一个更强的模型还要明显。我现在的日常已经离不开这套工作流了。新开一个需求先丢给superpowers做计划确认后再执行最后让它自己验证一遍。我做的最多的动作反而变成了“看计划”和“审查结果”画风从写代码变成了做评审。这个转变让我真正体会到了什么叫“超级能力”——不是AI替你写代码而是你把AI驯化成了一支纪律严明、快速响应的开发小队。如果你也正在用Codex CLI或类似的AI编码终端强烈建议试试superpowers。刚开始可能会有点不习惯觉得流程繁琐但跑完两三个真实需求之后你会爱上这种“凡事有计划、交付有验证”的踏实感。