Superpowers：为AI编程助手装一个技能库，告别临时记忆

最近半年我一直在折腾各种 AI 编程助手从最开始的新鲜感到后来总觉得差点意思再到现在的顺手高效中间确实走了不少弯路。最难受的阶段是助手明明什么都会一点但你每次都要重新告诉它你的代码风格、你们团队的工程规范、项目的历史包袱——它像是一个记忆只有七秒的天才每次对话都是从零开始。后来我找到了一个叫 Superpowers 的开源工具专门给 Claude Code、Codex 这类 AI 编程代理装上“技能系统”算是彻底解决了这个痛点。这篇文章就从一个普通开发者的视角讲讲我为什么放弃“每次现场调教 AI”转而用 Superpowers 沉淀可复用的技能库以及它到底是怎么安装、怎么用、怎么在 Java 这类大型项目里真正发挥价值的。如果你是 AI 辅助编程的深度用户或者在团队里推广 AI 工具但总被吐槽“上次教它的又忘了”这篇文章应该对你有用。1. 先搞清楚 Superpowers 解决的是哪个痛点AI 助手的“临时记忆”困局1.1 为什么你总觉得 AI 编程助手“不够聪明”很多人第一次用 Claude Code 或 Codex 的时候都挺惊艳的让它写个脚本、改个 bug、补个测试它都能干。可一旦你让它做稍微复杂一点的活——比如“按照我们团队的异常规范重构这个模块”它就开始犯迷糊了。它不是不懂 Java 异常处理而是它根本不知道“你们团队的异常规范”具体长什么样。你当然可以在每次对话的开头把规范贴进去但问题来了规范文档动辄几千字每次贴完上下文就占掉一大截你贴了 A 规范它可能就忘了你最开始提的 B 需求换一个项目、换一个助手同样的规范还得再贴一遍。这就是我所说的“临时记忆困局”——AI 助手本身的能力上限其实很高但大多数普通用户根本没有一套机制把这些能力固定在“你最常用的那几条工作流”上。1.2 技能Skill机制把“它会”升级成“它擅长”Superpowers 的思路非常简单与其每次对话都重新描述你想要的做事方式不如把这些方式写成一个个结构化的“技能Skill”文件放在项目的.superpowers目录里。每个技能其实就是一个 Markdown 文件夹里面写清楚这个技能是干什么的、在什么场景下触发、遇到以后按什么步骤执行。AI 助手在启动后会读取这些技能清单当你的某句话触发了某个技能的关键词或意图它就会加载这个技能文件夹里的完整指引然后按照里面定义好的流程去干活。用一句人话说就是原生助手是“你问一句它答一句”装上 Superpowers 之后它是“你起个头它知道后面整套流程该怎么走”。1.3 一个生活化的类比你可以把 Superpowers 想象成给 AI 助手准备的“岗位手册”。一个新员工入职你再厉害也不可能指望他第一天就懂你们公司的报销流程、会议节奏、代码评审标准。但如果你给他一本写满套路的手册他照着走几遍很快就变成熟手。Superpowers 干的就是这件事它不改变 AI 的“智商”而是给 AI 配一本属于你的团队的“工作手册”。不同的项目、不同的团队可以有不同的手册互不干扰。2. 安装 Superpowers从零到跑通的全过程2.1 环境准备Node.js 版本是第一个坑Superpowers 本身是 JavaScript 生态的工具所以第一件事是确认你的机器上有 Node.js。我是在 macOS 上装的用的 nvm 管理版本装的是 Node.js 20 LTS。这里有一个容易踩的坑如果你的 Node.js 版本太老比如 16 以下装的时候会报一个很莫名的依赖错误建议直接上 18 或 20。如果你的机器上还没有 Node.js我的建议是macOS 用户用brew install nvm然后nvm install 20避免直接用官网 pkg 包因为后面你可能会在多个 Node 版本间切换Windows 用户用 nvm-windows同样装 LTS 版本Linux 用户直接 apt 或 yum 装 nodejs 的时候注意版本号很多默认源里的版本偏旧。装好之后终端里跑一下node -v和npm -v确认输出正常环境部分就算过了。2.2 安装本体两种典型场景Superpowers 目前最主流的两种使用场景是配合 Claude Code 和配合 Codex CLI。先说 Claude Code 场景。它现在支持插件机制安装超级简单claude plugin install superpowers装完之后进入一个项目目录启动claude它会在初始化时自动发现超级技能清单。如果你是想全局生效也可以把技能装在~/.claude/plugins/下这样任何项目都能用到同一套技能库。再说 Codex 场景。Codex 是 OpenAI 出的一个终端编程代理本身也支持加载外部技能文件。最常见的做法是先把 Superpowers 仓库 clone 到本地git clone https://github.com/obra/superpowers.git ~/superpowers然后在你的 Codex 配置里把技能目录指过去。具体配置字段不同版本略有差异最稳的办法是看仓库 README 里最新推荐方式但总体思路就是把.superpowers这个技能目录暴露给 Codex 的上下文加载器。2.3 验证安装让 AI 主动“报出”技能装完之后最要紧的是验证它真的生效了而不是装了个寂寞。我会在项目目录里启动助手然后直接问它这样一句话你现在加载了哪些技能请列出技能名称和一句话说明。如果 Superpowers 生效它会像背菜单一样报出一串技能列表如果没生效它只会含糊地说“我没有技能”。这一招是我验证安装是否成功的首选方法比看日志直观得多。还有一个更暴力的验证方式随便挑一个技能描述里的关键词去触发它比如它有个技能是“编写规范的 Git 提交信息”你就说“帮我按照技能规范把本次改动整理成提交信息”看它是否表现出明显不同的执行流程。3. 拆解技能库开箱即用的超能力清单与触发逻辑3.1 一个技能文件夹到底长什么样在项目根目录的.superpowers下每个技能都是一个独立文件夹里面至少有一个核心文件叫做SKILL.md。这个文件的头部是一段 YAML 格式的元信息--- name: code-review description: 当用户要求进行代码审查、评审 Pull Request、寻找潜在 bug 时触发本技能 ---下面就是正文写清楚这个技能的执行流程。比如代码审查技能会规定先看变更范围再逐文件分析最后按严重程度输出问题清单同时给出修改建议。你可能会觉得这也太简单了不就是个 Markdown 文件吗对就是 Markdown。Superpowers 的高明之处在于它把所有复杂逻辑都抽象成“人也能读懂的文本规则”这让技能的编写、审查、迭代变得极其轻量。3.2 几个让我印象深刻的预置技能Superpowers 自带了一批技能基本覆盖了日常开发的高频场景我挑几个最常用的说一下。第一个是需求拆解。以前我让 AI 帮忙做需求分析它给的答案总是太空泛动不动就是“确保系统稳定”这种车轱辘话。加载了技能之后它会按固定的格式走先拆用户故事再定位涉及的模块然后列出潜在的技术风险最后给出一份验证清单。输出质量明显从“聊天”变成了“干活”。第二个是测试用例生成。这个技能厉害的地方在于它不只是简单生成测试而是要求 AI 先理解被测代码的分支覆盖情况再按“正常路径、边界条件、异常输入”三个维度去设计用例最后还要你确认覆盖率是否达标。我实测下来它生成的用例比默认状态完整得多。第三个是Git 提交信息规范。如果你的团队有提交前缀规范比如 feat、fix、refactor这个技能会让 AI 自动扫描 diff生成符合规范的提交信息并且支持你一次提交多个文件时快速分类。第四个是代码重构建议。这个技能特别适合老项目它会先分析模块的依赖关系指出循环依赖和重复代码然后按“风险从小到大”的顺序给出重构路线而不是上来就让你推倒重写。3.3 触发逻辑技能不是被“命令”的而是被“识别”的新手最容易误解的一点是以为触发技能要喊口号比如“启动代码审查技能”。其实不是。Superpowers 的触发逻辑是基于描述的自动识别。你有一次刚改完一个类顺手打了一行字“帮我看看这个类最近改动有没有隐患”就这一句话AI 会自动匹配到code-review技能因为它的描述里包含“审查”“隐患”“找 bug”这类关键词。这个设计的好处是用起来完全不需要记忆成本你只管用人类的语言提需求剩下的匹配工作交给系统。但坏处也有如果你不小心把技能描述写得太宽泛会导致误触发。关于这个问题我在后面的踩坑章节会展开讲。4. 手写一个技能把你们团队的规范“喂”成肌肉记忆4.1 最小可用的技能结构光靠预置技能肯定不够每个团队都有自己的特殊规范。我这里用一个非常实际的例子来讲怎么写自定义技能。假设你们团队有一条铁律所有的对外接口参数校验必须在 Service 层完成Controller 层只做参数透传不写任何业务逻辑。这条规则你跟 AI 说十遍它下个项目照样忘但如果你把它写进技能里它就变成了肌肉记忆。先建目录mkdir -p .superpowers/service-validation然后创建SKILL.md--- name: service-validation description: 当用户要求新增或修改 Controller 或 Service 层代码时必须按照团队分层规范进行参数校验 --- # 分层校验规范 ## 执行步骤 1. 识别用户涉及的接口属于 Controller 层还是 Service 层。 2. 如果新增或修改 Controller 层方法禁止在方法体内编写参数校验逻辑一律只做参数透传。 3. 参数校验统一放在 Service 层入口处使用统一的 ValidationException 抛出。 4. 输出代码之前先自查一遍Controller 里是否出现 if/else 业务判断。写完之后你还要在技能目录里加一个references/子目录放一个你们团队实际的 Controller 和 Service 代码片段作为示例。Superpowers 在加载技能时会一并读取这些参考文件让 AI 对“正确写法”有一个具体印象而不只是一堆抽象规则。4.2 技能文件里的灵魂给 AI 一个可执行的决策树很多初学者写技能容易写成一堆教条比如“团队规范代码质量要高”。这种话 AI 看了等于没看。我在写了几个技能之后总结出一个经验每个技能正文都应该包含一个“如果遇到 X就做 Y”的决策树。以我刚才那个接口校验技能为例它不是笼统地说“注意分层”而是明确告诉 AI如果涉及 Controller 层接口检查方法体内有无业务校验逻辑有则移动到 Service 层如果涉及 Service 层方法检查入口处是否缺少参数校验缺少则补上如果涉及新增依赖优先使用团队封装的ValidationUtils禁止直接引入新校验库。只有细化到这个程度AI 才能在执行过程中真正“按套路办事”而不是自由发挥。4.3 把技能放进团队共享仓库单个技能写完之后可以把它放到 Git 仓库的.superpowers目录里提交。队友拉下来之后他们机器上的 AI 助手也会自动加载这个技能。我自己建议的做法是在团队仓库的根目录放一套共用的.superpowers然后让每个人在.gitignore里保留本地私有技能目录。这样既能保证团队规范统一又不妨碍个人定制自己的工作流。5. Java 项目实战Superpowers 在大型代码库里的真实提效场景5.1 为什么 Java 老项目尤其需要技能沉淀可能有人觉得技能这东西对于写脚本、写小 Demo 没什么用因为小项目上下文短每次现场交代也来得及。但 Java 大型项目完全不是一回事。我手上有一个维护了好几年的 Spring Boot 老项目模块多、依赖复杂、历史代码风格不统一。过去我让 AI 帮忙改代码经常出现两种尴尬场面要么它给出的代码风格和现有模块格格不入要么它忽略了我们项目里的公共组件自己另起炉灶。有了 Superpowers 之后我把项目里几个核心公共组件的用法、数据库访问层的约定、接口返回体的包装格式分别做成了技能。从那以后AI 生成的代码就像在这个项目里写了好几年一样从我需要反复纠正变成了我只需要做代码评审。5.2 实战让 AI 带“技能”做一轮代码审查我挑一个真实操作过的场景说说。上个月我负责的一个支付模块要重构改了将近 30 个文件。靠人肉 review 不现实我直接在项目根目录启动助手输入帮我把这 30 个文件按代码审查技能过一遍重点关注并发安全和事务边界。因为代码审查技能已经定义好了完整流程AI 没有直接给出一堆零散的修改建议而是输出了一份结构化的审查报告按文件分组每个文件标出风险等级并发安全类问题单独列一节并指出锁的粒度是否合理事务边界问题直接给到具体方法并指出传播行为是否可能引发大事务每个问题附带一个最小改动的修补 Diff 示例。整个过程下来我自己只重点看了 AI 标记为高风险的 4 个文件其余低风险的直接照着补丁改。这要放在以前我自己涮一遍所有 diff 至少要大半天。5.3 实测中的收益与边界说实话Superpowers 并不能让 AI 从一个“平庸的程序员”变成“架构师”它真正的作用是消除 AI 在“不知道你们团队怎么做”这件事上的随机性。我把收益和边界分开说。收益方面第一代码风格一致性明显提升AI 生成的代码不再出现“外国味儿”的命名习惯第二公共组件的误用率下降因为它参考的参考资料里就有正确用法第三重复性的规范审查从人工变成了自动省下的是真时间。边界方面第一它不能替你理解业务技能文件写的是“怎么做”不是“为什么做”第二对于特别复杂的跨模块需求技能只能提供流程框架最终的设计判断还是得人来第三技能的维护成本是持续的如果团队规范更新了你忘了改技能文件AI 就会按照旧规范干活。6. 我踩过的坑技能冲突、上下文膨胀与团队协作6.1 技能描述写太宽导致 AI 每次都“抢答”这个坑我是在写第一个自定义技能时踩的。当时我给一个“代码生成”技能写的描述是“当用户要求生成代码时触发”结果后来每次让 AI 写任何一行代码它都优先加载这个技能反而把其他更具体的技能挤掉了。后来我才明白技能描述要尽量写窄宁可漏触发也不要误触发。比如“生成代码”这种描述应该改成“当用户要求生成 Controller 到 Service 到 Mapper 的完整三层代码时触发”。这样它只在真正需要全套代码时介入其他时候还是让更专门的技能各司其职。6.2 技能数量失控之后上下文被“吃”掉一大截Superpowers 虽然每个技能文件都不算大但如果你一口气装了上百个技能每次启动时 AI 都要把技能清单全部读一遍这会明显挤占本来就宝贵的上下文窗口。我现在的做法是全局只保留 10 个以内的高频技能项目级技能控制在 20 个左右。如果一个技能超过三个月没被触发过我就会考虑把它挪到归档目录。记住技能库不是集邮册装的越多单个技能的命中率反而越低。6.3 团队共享时的同步问题技能文件放在 Git 仓库里共享听起来很美好实际操作时有一个很现实的问题队友更新技能后本地 AI 助手不一定能立刻感知到。尤其是 Claude Code 这类长驻进程它可能在启动时只扫描了一次技能目录。我建议在每个技能的文档里写清楚生效时机同时在团队里约定拉取代码后如果发现.superpowers目录有变化重启一下 AI 会话。另外也可以在 CI 里加一个脚本检查技能文件的前置描述是否重复提前发现冲突。6.4 版本兼容的坑最后提醒一下Superpowers 本身迭代速度不慢技能格式偶尔会有小变化。如果你发现某个技能之前能触发更新后突然不生效了先检查 SKILL.md 的头部 YAML 是否还符合新版的字段要求。我自己遇到过的最离奇的一个故障是技能文件里的描述使用了半角冒号解析器把整个 YAML 拦腰截断了导致那个技能静默失效。从那以后我给自己立了一条规矩所有技能文件的元信息写完必须在本地先跑一遍解析检查确认无误再提交。现在这个技能库已经成了我日常开发的标配不管换到哪个项目第一件事就是把适合那个项目的技能目录拉下来。从实际体验来看它并不能让你一步登天但它确实能让 AI 干活的方式从一个“随手帮忙的实习生”变成一个“懂规矩、知分寸的老同事”。如果你最近也在为 AI 编程助手的“记性差”头疼不妨从一个小技能开始试起把你们团队最烦人的那条规范先写进去剩下的自然会跟着顺起来。