不绕弯子直接说结论superpowers不是某个炫酷的新编程语言也不是某款灵异IDE插件它是一套专门给 AI 编程工具尤其是 Codex CLI 这类终端型助手做“外挂式增强”的配置与技能集。说白了它就是把你平时反复敲给 AI 的提示词、代码规范、工作流约定打包成一堆能直接调用的“技能模块”让 AI 从“一个啥都会但需要你不断叮嘱的实习生”变成一个“懂你项目规矩、上手就按你习惯干活的老同事”。这类东西目前在开发者圈子里讨论热度很高尤其是当你发现 AI 写代码“第一版总是不尽如人意”、或者说“每次都要重复交代背景和规范”的时候superpowers就是冲着解决这几个痛点来的。这篇文章我会从设计思路、安装配置、Java 实战、以及我实际踩过的坑这几个维度展开尽量写得实操一些。无论你是刚接触 AI 编程辅助的开发者还是已经在用 Codex、想进一步榨干它能力的进阶玩家都值得往下看。1. 它到底是什么superpowers 的设计思路与核心价值1.1 从“临时工 AI”到“老熟人 AI”的转变先想一个问题为什么很多人用 AI 写代码感觉“也就那样”我的体会是问题往往出在上下文管理上。直接跟 Codex 说“帮我写个订单模块”它当然能写但写出来的东西大概率是泛泛的、不符合你项目现有风格的——因为你没有告诉它你的分层习惯、异常处理规范、命名风格、数据库表设计约定。superpowers的思路很直接既然 AI 记不住你的偏好而且每次会话都要重新说一遍那就把这些偏好、规范、常用任务的执行步骤固化成一个个“技能文件”。你只需要在对话里说一句“用 Java 重构这个类并生成单元测试”AI 就会自动去加载对应的技能定义按照里面写好的步骤和规则来执行。所以它的核心价值有三点减少重复沟通规范只写一次之后每次调用都自动生效。稳定输出质量把“碰运气”式的 AI 生成变成“走流程”式的标准作业。沉淀团队经验谁踩过的坑、总结出的最佳实践都能写进技能文件里共享。1.2 它是怎么组织“技能”的我拿自己用的配置来举例。superpowers装完之后通常会有一个固定的目录结构每个子目录或者文件就代表一个技能。比如常见的技能有code-review代码审查write-tests编写测试refactor重构explain-code解释代码implement-feature按需求实现功能每个技能文件里面写的不是代码而是给 AI 看的指令模板。包括这个技能的目标、执行步骤、输入要求、输出格式、注意事项等。你可以把它理解为“给 AI 写的岗位说明书”。当你在对话里明确提到code-review或者使用 code-review 技能时Codex 就会把这个文件的内容注入到当前上下文中AI 接下来的行为就会被这份说明书约束。生活化类比你第一次请人装修要在现场反复说“瓷砖要工字铺、踢脚线要做暗藏式、开关插座要离地 30 公分”。但如果给装修队长一份写清楚的“工艺标准手册”他看一眼就知道怎么干你也不用每句话重复三遍。superpowers就是给 AI 的那本“工艺标准手册”。1.3 为什么不是所有增强工具都叫 superpowers跟一些单纯的提示词合集相比superpowers这类工具更强调“结构化”和“可执行”。它不只是在.txt文件里堆一堆话术而是把技能、规则、工作流分开管理通过 CLI 的机制动态加载。我之前也试过把一大段提示词直接粘到对话里效果其实很不稳定。原因在于提示词一长AI 容易“抓不住重点”而且每次都要粘贴稍微改一下项目场景就得再编辑一遍。而superpowers的设计是把“技能描述”和“具体任务输入”分开。技能文件里越写越精炼任务输入反而是临时的、动态的。这样逻辑清晰迭代也方便。另外它跟 Codex 的配合尤其自然。Codex 本身是命令行工具而superpowers正好也是面向命令行的配置体系两者亲近感天然就强。不过要注意它并不绑定某个特定工具理论上凡是支持读取外部指令文件的 AI 编程助手都能用上这一套思路。2. 从零搭建安装 superpowers 与初始配置2.1 安装前需要确认的环境别急着复制粘贴命令先把基础环境检查一遍不然容易卡在一些莫名其妙的报错上。我建议按这个清单核对Node.js 版本很多基于 CLI 的配置工具都依赖 Node 运行环境superpowers也不例外。要求不高但至少 Node 16 以上比较稳妥。我用的 18.x没出过兼容问题。Git装superpowers通常需要从远程仓库拉取配置模板没有 Git 寸步难行。Codex CLI或等效工具如果你还没装过任何 AI 编程 CLI建议先装好 Codex并完成至少一次成功的对话调用确认 API Key 配置没问题。这一步不能省因为很多人后面排查半天最后发现是密钥没配好。终端环境在 Mac/Linux 下体验最好Windows 的话建议用 WSL 或者 Git Bash纯 PowerShell 有时候会遇到脚本执行权限问题。确认没问题后就可以开始了。2.2 安装步骤实操我用的是 npm 安装方式整个过程其实不复杂三步走# 1. 全局安装 superpowers 命令行工具 npm install -g superpowers # 2. 在你要应用的工作目录里初始化 cd your-project/ superpowers init # 3. 按照交互提示选择你需要的技能包第三步它通常会问你“要启用哪些技能”比如 code-review、write-tests 等选完之后会在项目根目录生成一个.superpowers/文件夹里面就是技能定义和配置文件。我实际安装时踩的第一个坑初始化命令执行完提示“No skills found”——我明明选了技能包为什么还说没有查了一会儿才发现是因为当前项目目录名里带了中文导致路径解析异常。这个概率其实不小只能说很玄学。后面我会在排查部分细说。初始化完成后比较合理的习惯是先打开 .superpowers/ 目录看一眼了解里面每个文件的作用。比如.superpowers/ ├── config.json # 全局配置启用哪些技能、默认语言模型等 ├── skills/ │ ├── code-review.md │ ├── write-tests.md │ └── ... └── custom/ # 自定义技能的存放位置把结构看清楚再动手后面改起来心里才有底。2.3 验证是否安装成功一个简单的验证方法是直接在项目目录开启 Codex随便说一句“列出当前可用技能”。如果配置正常它会返回一串技能名字列表。如果它回复“没有找到技能”或者显示一堆“无效指令”那就是安装或者路径上有问题。再更直接一点你可以在 Codex 会话里引用某个技能比如使用 write-tests 技能为 utils/MathHelper.java 生成单元测试看看它是不是会比平时更“懂规矩”地输出测试用例。如果它输出的测试结构、命名、覆盖方式明显比之前规范说明技能已经注入成功。2.4 初始配置里的几个关键参数打开config.json我建议重点关注这几个配置项defaultSkill默认注入到每次会话里的技能。比如你大部分时间都在做 Java 开发可以把java-project这类技能设为默认省得每次手动指定。maxContextTokens技能文件占用的上下文窗口大小。不是越大越好因为总上下文是有限的留给实际代码对话的空间会被挤占。我个人的习惯是保持默认最多微调。customSkillsPath自定义技能目录路径。如果你打算把团队规范沉淀成技能把这个路径指向团队共享目录就行。提示配置文件修改完务必重启 Codex 会话再测试否则修改不生效。这是很多人忽略的一点我本人也在这上面白费过十分钟。3. 真正发挥威力Java 项目中的 superpowers 实战3.1 为什么拿 Java 场景举例superpowers这种工具其实不分语言但我特意选 Java 来说是因为 Java 项目的特点特别适合体现这类技能系统的价值工程结构严格分包分层、接口与实现分离技能文件可以很精准地规定“什么代码放哪层”。测试文化重JUnit、Mockito 是家常便饭write-tests技能在这种场景下能发挥出极大的提效作用。框架约定繁琐Spring、MyBatis 等把常用注解、配置规律写进技能AI 生成的代码能少很多低级错误。3.2 实战一用技能包生成规范的单测先说我以前不用superpowers时让 Codex 给 Java 类写测试会遇到什么情况它会生成一个测试类但常常出现的问题包括——测试方法命名没有规律、用System.out.println做验证、没有覆盖边界条件、Mock 用法稀奇古怪。不能说它不会写只能说写得不够“像我们团队的代码”。用了write-tests技能之后我在技能文件里定义了这样几类规则测试类与被测类位于相同包路径放在src/test/java下。测试方法命名统一为方法名_场景_预期结果例如calculateTotal_whenEmptyList_returnsZero。优先使用 Mockito 做依赖隔离禁止在单测里启动 Spring Context。要求覆盖正常路径、异常路径、边界条件。断言必须使用 AssertJ 或 JUnit 的 Assertions禁止使用 if 语句做验证。在完成了这个技能文件的配置后我可以直接在 Codex 里说使用 write-tests 技能为 service/OrderService.java 生成单元测试它生成的代码基本能做到“拿过来就能提交”。甚至有好几次它连 Mock 的when(...).thenReturn(...)都跟我自己手写的一模一样。这里面的区别就是技能文件里明确写了“依赖隔离优先用 Mockito不要 mock 具体类要 mock 接口”。3.3 实战二用 refactor 技能做安全重构重构是一件很考验“纪律性”的事情。人都会偷懒时间紧的时候直接大改结果测试挂了都不知道是哪一步引起的。superpowers的refactor技能能帮我们约束 AI 按流程来。我配置的refactor技能里写明了以下步骤先分析目标类的当前结构和调用关系。列出潜在风险点如公共方法签名变更的影响范围。建议拆分成多个小步每一小步保持可编译、可测试。每完成一步执行一次项目构建命令比如mvn compile。最后运行相关测试用例确认无回归。实际用下来最爽的一次是让它帮我将一个几百行的老式 Service 类按业务域拆分成三个新类。我给它下达指令使用 refactor 技能将 OrderService 按照职责拆分成 OrderQueryService、OrderCommandService、OrderValidateService它真的就一步一步来先分析原类方法再建议如何分配然后逐个类生成代码每生成一个类就提醒我跑编译。虽然最终我还是人工 review 了一遍但整体心理负担小了很多因为每一步都验证过不像以前那样“一夜回到解放前”。3.4 自定义、可复用的团队技能这里我想特别强调一下自定义技能的思维。由于superpowers本质上是“规则文件”你可以把团队里很多约定都写进去。比如不允许在 Controller 层直接操作数据库。所有接口返回统一使用ResultT包装。异常必须抛出业务异常类型不允许裸抛RuntimeException。数据库时间字段一律使用LocalDateTime禁止使用字符串时间。把这些约定写入自定义技能之后每次让 AI 写接口、写分层代码它都会自动遵守。这就相当于把代码规范 review 这个环节前置了AI 生成时就把规范考虑了进去评审压力会小很多。一个团队往往只需要集中精力维护好那几个自定义技能文件收益是全方位的。不过话说回来技能文件也不是越多越好。文件太多、内容太长反而会让 AI 的上下文窗口被占满影响生成质量。我个人的建议是单个技能文件控制在 50 行以内求精不求多。4. 踩坑记录常见问题与排查技巧实录4.1 症状与原因速查表我在使用superpowers的过程中确实遇到了不少奇奇怪怪的问题。这里总结成一张速查表方便大家对照排查常见症状可能原因解决思路技能没有被识别技能文件路径配置错误或技能文件名与 config.json 不一致检查.superpowers/skills/下的文件和config.json里的启用的技能名称是否一致模型回答不遵循技能指令技能文件内容写得太含糊不够具体把模糊表达改成可执行的细粒度步骤比如“写出高质量代码”改成“每个方法必须有注释禁止使用魔法值”上下文频繁溢出技能文件太长或者默认技能开得太多精简技能文件减少默认技能数量把部分规范移到“按需调用”的技能中初始化失败项目路径有特殊字符中文、空格或 Node 版本过低移除路径特殊字符升级 Node 到 16再重试 initJava 相关技能不起作用技能文件里没有明确绑定 Java 语言规则在技能文件头部加上language: java之类的显式说明让 AI 识别适用范围修改了配置但没有生效未重启会话或 Codex 自身有缓存强制重启 CLI 或开新会话再测试4.2 排查思路才是最重要的很多朋友一遇到问题就搜报错其实效率不高。我的习惯是先按下面的顺序排查第一步确认技能文件本身能被读取。直接打开文件看格式对不对有没有语法错误——是的Markdown 也有“语法错误”比如代码块没闭合、列表符号混用这些都会影响 AI 解析。第二步确认当前会话确实加载了技能。在 Codex 里问一句“你现在加载了什么技能”比啥都直观。第三步确认技能内容跟任务匹配。经常有人让 AI “用 write-tests 技能给 Python 模块写测试”但技能文件里写满了 Java/JUnit 的内容那结果当然不对劲。第四步确认是不是 prompt 的锅。有一阵子我明明调用了 code-review 技能却发现它还在写代码而不是给建议最后发现是我自己的 prompt 表述成“用 code-review 技能改进这个类”……这语义是模糊的。把它改成“用 code-review 技能审查这个类只提建议不直接改代码”后一切正常。4.3 关于性能与体验的优化心得最后再分享几个提升长期使用体验的建议这些都是我实际测下来比较有用的不要把技能当成万能的AI 的上下文窗口有限技能文件太多太长一定会稀释注意力。宁可把大而全的技能文件拆成多个小技能按需调用。技能文件也要“版本管理”我是直接把.superpowers/目录纳入 Git 管理的。这样每次对技能定义的改动都有历史记录哪天改坏了git diff一下马上知道哪里出了问题回滚也方便。定期审视技能文件里每条规则的实际价值我每过一段时间就会删掉一些“理想主义”的规则。比如我之前写过“所有方法长度不得超过 10 行”听起来很美但在很多业务场景下就是不现实最后 AI 反而为了凑 10 行以内写出了一堆难读的代码。这种规则留着就是坑。跟团队的协作工具搭配使用如果你们团队有用 Worbuddy 这类交互协作工具做任务同步或工作流管理可以把技能文件里的关键步骤也同步到工作流中AI 生成完代码后进行人工 review再进入自动化测试整个链路配合起来会比较顺。我自己用下来最深的感受是superpowers这类工具真正改变的不是 AI 本身的能力而是你在使用 AI 前“有没有把自己的标准梳理清楚”。你先想明白什么是对的代码、什么是好的流程然后才能把它们固化成技能文件让 AI 稳定执行。如果没有这一层思考装再多工具也只会得到一堆概率性的、时好时坏的代码。先把自己的标准定下来这个工具才真正值回票价。最后再补充一个小技巧如果你发现某个技能的使用频率特别高不妨把它设为默认技能但内容里只保留最核心的约束其他细节拆成“按需加载”的补充技能文件。这样既保证了基本行为符合预期又不至于一次性占用太多上下文。我自己就是因为“把大招全默认开着”吃过亏精简之后效果反而稳定得多。