最近一个月我把 Superpowers 接进了日常使用 Codex CLI 的工作流里最大的感受是它治好了 AI 编码助手“眼高手低”的老毛病。Superpowers 并不是某个跟超级英雄有关的炫酷框架而是一套以**技能卡Skills**为核心的 AI 编程辅助增强包目标是让 Codex CLI 这类工具在动手前先学会“拆任务、排计划、写测试、做复盘”。如果你是刚接触 AI 编程工具的新手或者团队里已经有同事在用 AI 写代码但经常要返工这篇文章应该能帮你省下不少时间。我会从“它到底解决什么问题”开始把安装、配置、核心技能、Java 项目实战和常见坑位一次讲透最后分享一点我自定义技能卡的经验。现在直接进入正题。1. 为什么用 SuperpowersAI 编码助手最大的短板就在这写代码这件事其实很像做菜。你让一个实习生做一道红烧肉只丢一句“今天晚饭就做这个”他大概率能做出东西但火候、糖色、焯水顺序都可能翻车。传统的 AI 编码助手就是这种实习生你给一个笼统需求它立刻开始“表演”拽出一大段代码结果边界条件漏了、测试没补、甚至需求本身都没对齐。Superpowers 的做法相当于在你和 AI 之间塞了一本《厨师操作手册》先让它讲清楚“今晚要做几个菜、口味是什么、备料清单是怎样的”再一步步往下走。1.1 传统 Prompt 方式的“三宗罪”第一目标模糊。直接写下“帮我写一个订单模块”对模型来说太宽泛了。它没有先追问“订单状态怎么流转、需不需要退款、支付回调怎么兼容”而是顺着最常⻅的模式把代码生成出来看起来完整实际上缺失了核心业务规则。第二过程不可控。模型一步步生成代码时不会主动停下来让用户确认直到最后才发现方向错了只能推倒重来。第三缺乏质量闭环。“写完代码”和“写完能跑的代码”之间隔着测试、边界和回归。传统 Prompt 往往默认模型能在一次回答里把这些全考虑周全这显然不现实。我踩过最典型的一次坑是让 AI 写一个 Java 的批量导入功能。它很顺利地生成了几十行代码看起来像模像样。结果一跑它根本没处理空行、重复主键和事务回滚。问题并不在于模型变笨了而是我在提问时没有给它一个“先思考需求边界再动手编码”的机制。Superpowers 恰好补上了这个缺口。1.2 Superpowers 的核心设计技能卡我用的这套 Superpowers核心概念是“技能卡”Skill Card。你可以把它理解成一个带触发条件的结构化 Prompt 文件一般用 Markdown 或 YAML 写成。每张技能卡至少包含这几个关键部分名称与描述让模型知道这张卡什么时候该被触发。问题清单进入该技能后模型要先主动向用户确认的信息。执行步骤模型应该按什么顺序做哪些事。检查清单收尾前必须逐项核对的质检项。比如项目里有一张task-decomposition技能卡描述写的是“当你需要把一个复杂需求拆成多个子任务时触发”。模型读到这个描述后会根据当前用户输入的语义自动决定是否调用。如果需求本身很简单它不会硬套。这种“用到才加载”的机制比我以前把所有要求塞进 system prompt 的做法聪明得多。以前每次启动对话都要带一大段“规则”现在只需要让它在恰当的时候去读对应的卡。这里我想强调一个容易误解的点技能卡不是插件也不是安装后可自动执行的脚本。它本质上还是 Prompt只是通过结构化的方式把专家经验固化下来。真正执行代码的还是 Codex CLI 背后的模型。Superpowers 的价值在于它改变了模型处理任务的“姿势”而不是给模型装上了某种魔法。2. Superpowers 安装教程从拉取仓库到配置 Codex CLI2.1 准备环境安装之前我的环境是 macOS 加已装好的 Codex CLI项目本身不需要额外安装 JDK 或 Maven因为 Superpowers 对 Java、JavaScript、Python 项目都能支持并没有绑定某一种语言。它的底层只是一堆技能卡文件真正干活的是 Codex CLI 背后的模型。你最少需要准备三样东西Git用于拉取技能仓库Node.js 18 或更高版本日常运行 Codex CLI 通常依赖它Codex CLI 这类支持技能目录的 Agent 工具。我没有单独安装任何 Java 相关的插件因为 Java 工程的支持是被 Codex CLI 和技能卡共同“带”出来的。后面我会用一个实际的OrderService例子讲 Java 场景尽量还原真实使用过程。2.2 拉取技能仓库并初始化我的做法是手动 clone 一份到本地固定目录不污染系统全局路径。先打开终端执行git clone superpowers 仓库地址 ~/.superpowers cd ~/.superpowers把superpowers 仓库地址替换成项目主页提供的真实地址。如果你不确定该用哪个地址去 GitHub 搜 “superpowers” 就能找到社区活跃维护的版本。克隆下来之后先看一眼README和目录结构通常会有一个skills文件夹里面按不同场景放了多张技能卡。如果项目自带初始化脚本通常执行一句./install.sh或者make install就能完成安装。不过我这次是手动模式所以直接把skills目录指向了 Codex CLI 的配置。在 Codex CLI 的~/.codex/config.toml里增加一行告诉它技能卡放在哪[project] skills_path ~/.superpowers/skills这里提醒一句具体字段名在不同版本里可能有差异有人用skills_dir有人用环境变量CODEX_SKILLS_PATH。我建议先查阅当前版本配置文件支持哪种写法不要死记硬背某一种配置。2.3 验证技能是否生效配置完成后重启 Codex CLI输入一个触发任务来测试请使用 task-decomposition 技能把这个需求拆解成任务清单 为一个电商系统新增优惠券批量发放功能。如果配置生效模型的回答不会一上来就贴代码而是先输出“功能概述”“涉及模块”“需要确认的问题”再列出带[ ]符号的任务清单。如果它仍然直接写代码大概率是技能卡路径没被读取到或者技能卡的描述写得不够显眼导致模型没识别出触发条件。我还建议你做一个反向测试输入一个简单到不需要拆解的任务比如“帮我把n改成count”。正常情况下模型应该直接改而不是强行套技能。如果它连这种小事都要走任务拆解流程说明某张卡的触发条件写得太宽泛了需要回头改卡。3. 核心技能实战需求拆解、TDD、Debug 一次讲透3.1 需求澄清与任务拆解先当“乙方”再当“程序员”Superpowers 里我最常用的一张卡叫requirement-clarification。它会让模型先扮演需求分析师把一句话需求翻译成几个关键问题再给出你确认后的“事实清单”。对 Java 项目来说这一步尤其重要因为类结构、接口设计、数据库表结构都受需求细节影响。我让 AI “用 TDD 方式给订单模块增加老用户 9 折优惠”时模型的回答大致是这样确认点 1老用户的判定标准是注册时长还是历史订单金额确认点 2折扣是否与满减、无门槛券叠加确认点 3折扣计算在服务端完成还是直接在数据库 SQL 里处理这些问题看着简单但直接写代码时 AI 通常不会主动问而是自己拍脑袋假设。等需求澄清完它再调用task-decomposition生成任务清单1. 编写 OrderService 的测试用例含普通订单、老用户订单、打折叠加订单 2. 运行测试确认失败 3. 实现 discountRate 计算逻辑 4. 运行全量测试并重构 5. 输出变更说明这个流程对 Java 项目特别友好因为 JUnit 测试天然适合这种“先红后绿”的节奏。我只需要在项目里提前放一个测试脚手架剩下的事情就能交给 AI 一步步执行。3.2 TDD 技能落地一个 Java 示例这一步给没怎么写过 Java 的同学也看一眼。假设我有这样的OrderServicepublic class OrderService { public BigDecimal calculateFinalAmount(Order order) { // 现状返回原始金额不考虑折扣 return order.getAmount(); } }带上 TDD 技能之后AI 会先在src/test/java/.../OrderServiceTest.java里生成测试Test void shouldApplyTenPercentDiscountForOldUser() { Order order new Order(new BigDecimal(100.00)); order.setOldUser(true); OrderService service new OrderService(); BigDecimal actual service.calculateFinalAmount(order); assertEquals(new BigDecimal(90.00), actual); }接着运行测试让它失败再进到实现环节public BigDecimal calculateFinalAmount(Order order) { BigDecimal amount order.getAmount(); if (order.isOldUser()) { amount amount.multiply(new BigDecimal(0.90)); } return amount; }最后再跑全量测试和重构。这和我之前用 AI 直接给代码的最大区别是测试是首次产物而不是代码的附属品。没有 Superpowers 时我催一句“写个测试”AI 可能会补一个很水的、总是能通过的测试有了 TDD 技能它会在写实现前就把边界问题暴露出来。这个例子看起来简单但真正复杂的需求也是一样的逻辑。比如增加“满 100 减 10老用户再打 9 折优惠券叠加”这种规则时模型会先在测试里穷举组合场景而不是先写实现再补测试。听到这里你应该能理解为什么大家把这种能力称作“超能力”了。3.3 Debug 与重构技能遇到问题别急着“盲猜”除了正向开发Superpowers 在排查 bug 时也很有用。它有一张debugging技能卡核心是让模型不要“听风就是雨”。比如我说“订单金额偶尔不对”模型会先列出需要的信息复现概率和触发条件是什么日志里异常金额出现前后的完整输入是什么是服务端计算错误还是前端展示错误然后它建议用二分法缩小范围先看calculateFinalAmount的输入和输出再用独立的单元测试锁定是哪段逻辑。整个过程像极了老工程师在带新人只是这个新人变成了 AI。再看refactoring技能。它会在改动前先检查当前代码的测试覆盖率要求“在测试不挂的前提下小步重构”每次只提取一个私有方法或调整一个条件表达式。我会把一些需要保持兼容的旧代码交给它它不会顺势把 API 签名改得面目全非。这一点对维护老项目很重要因为很多时候 AI 一重构就想“顺手优化结构”结果把调用方全搞挂了。4. 常见问题与排查技巧技能失效、Token 飙升、Java 识别不准4.1 安装与配置速查表下面是这段时间我身边同事踩得最多的问题整理成表格可以直接对照排查。症状可能原因解决办法技能完全不触发skills_path没配对检查 Codex CLI 配置文件字段或用绝对路径模型总是忽略技能卡技能描述和当前任务匹配度低把技能卡 description 改得更具体或放在目录靠前位置只在某些语言下生效项目上下文不够让 AI 先跑find src -name *.java或tree确认工程结构Token 消耗突然变大更多技能卡被加载到上下文剪掉不常用技能保留少量核心卡改代码时把测试删了技能卡缺少“不许删除测试”约束在技能卡检查清单里显式声明Java 工程识别不准没有把类路径和依赖关系交代清楚先导入代码库索引或给出pom.xml/build.gradle的关键依赖4.2 排查思路技能失效时先从哪查起如果你发现技能卡没生效我的排查顺序是先确认当前 Agent 版本是否支持技能卡目录再确认配置文件的路径解析是否正确最后检查技能卡文件的 frontmatter 是否完好。注意文件内部如果有关键字拼错、字段名和版本不匹配模型也会认为它“不存在”。遇到这种情况我一般会删掉缓存后重启 CLI再跑一次冒烟测试。另外一个容易被忽略的问题技能卡里如果写了“你应该做 A”这种指示模型不一定照做。因为技能卡本质还是 Prompt它只是建议不是命令。要让模型更听话最好在触发条件里写上什么时候不要用。比如debugging卡的 description 里加上“如果错误信息明确且有堆栈直接进入定位阶段不要反复追问用户”这样能减少 AI 的无效确认也能省下不少 token。4.3 我的避坑心得第一不要贪多。我一开始把整个技能库都塞给 Codex CLI结果每次请求都带一大堆提示词又贵又慢。后来只保留项目最常用的五到六张卡效果反而稳定。第二把技能卡当成团队规范来维护。我建议你把自己团队要求的代码风格、测试覆盖率标准、提交信息格式写进技能卡这样 AI 生成出来的东西会天然贴近团队约定而不是“通用正确”但“团队不可用”。还有一个小技巧给技能卡加版本号。我习惯在每张卡前面写version: 1.0当某个技能行为不对时可以快速回溯是卡的问题还是模型升级导致的问题。这种看似不起眼的细节在长期维护时能省不少力气。5. 自定义技能卡把 Superpowers 变成团队专属外挂5.1 如何设计一张真正管用的自定义技能卡Superpowers 的真正威力在于它的可扩展性。我自己写了一张team-convention卡用来约束日常提交--- name: team-convention version: 1.0 description: 在代码生成结束时检查是否满足团队规范 --- - 提交信息必须以 [JIRA-账号] 开头 - 禁止把 TODO 注释提交到 main 分支 - 单元测试覆盖率不低于 80% - 不得删除既有测试用例放在skills目录后再跑到生成代码的任务模型在收尾时会自动对照这张卡做检查。这种自定义卡我建议放到独立 Git 仓库方便团队里其他同事一起拉取。设计技能卡有个关键原则尽量写“可观测”的评价标准。比如“代码质量要高”这种描述模型不知道怎么检查但“不得删除既有测试用例”“每个 public 方法必须有 Javadoc”就非常明确。你希望模型怎么遵守就要把规则写得像 CI 检查项一样而不是写“风格建议”。5.2 控制成本与效果平衡每次引入技能卡都会增加上下文 tokens尤其是在模型需要“思考”的时候你可能会发现单次请求费用比原来高 20% 到 50%。我的做法是先按“最简可用”原则只保留需求澄清、任务拆解、TDD、调试四张卡跑通一个完整迭代后再根据实际短板逐步添加。对于复杂度低的任务比如“帮我把这个常量抽出来”可以不触发任何技能让它直接改避免杀鸡用牛刀。另外一个值得记录的观察是Superpowers 更适合“中等复杂度、偏工程化”的任务。大型架构设计和代码重构它提供的是流程约束和检查项最终拍板的还是你。你可以在它输出任务清单后先自己审一遍再让它执行效率比让它一口气生成完再返工高得多。这也是我最推荐的一种用法把 AI 当成一个“流程感很强但不完全可靠的工程师”你先当 Tech Lead它按你确认的流程往前推。这种合作方式才是 Superpowers 真正值钱的地方。
