最近不少人在聊 superpowers。这个项目名字起得挺中二但实际解决的问题非常实在当 AI 编程助手的代码能力越来越强你会发现每次让它干活它都要重新理解一遍项目上下文你沉淀下来的技术规范、调试套路、代码审查清单它一概不知道。superpowers 要做的就是把这些经验资产变成一套可安装、可复用、可共享的技能包让 AI 助手在关键时刻真正展现出超能力。这篇文章我会从它的核心机制讲起然后完整走一遍安装流程再聊我在 Codex 上的适配尝试以及用它在 Java 项目里做 TDD 的一手体验。如果你正在用 Claude Code、Codex 这类工具又觉得每次对话都要反复交代上下文太痛苦那这篇应该能帮你在半小时内把 superpowers 用起来。1. Superpowers 到底解决了什么问题1.1 会话失忆AI 编程助手的最大痛点用过 Claude Code 或 Codex CLI 的人应该都有这种感觉单次对话内AI 的表现可能很惊艳但一旦开新会话它又变回一个聪明但健忘的新同事。你需要重新给它介绍项目结构、技术栈、代码风格、测试规范甚至上次已经排查过的坑还得再踩一遍。我一度靠维护一份超长的 CLAUDE.md / AGENTS.md 来缓解这个问题但很快发现另外两个问题一是文件越来越大模型每次都要读完大量冗余内容反而影响回答质量二是文档是静态的没法针对不同任务动态展示不同知识。比如我在调一个内存泄漏问题时它根本不需要先读一遍构建系统的全部细节。superpowers 的思路不一样。它把经验拆成许多独立的技能skills每个技能有自己的说明文件、触发条件和执行步骤。AI 收到任务时会先判断该调哪个技能再按技能文件里面的步骤走。这不是给模型塞上下文而是给模型一套遇到什么情况就查什么手册的规则。1.2 正确定位它不是插件而是一套方法论操作系统很多人第一次接触 superpowers会以为它类似一个 VS Code 插件给 Claude Code 加几个新命令。用下来你会发现它更像一套方法论操作系统——它规定了一个项目如何被 AI 理解、任务如何被拆解、代码如何被验证。它在项目里会生成一套结构化的目录比如存放项目记忆文件、技能定义和决策记录。会话启动时AI 会先读取这些文件了解项目背景和约定任务执行过程中AI 会根据需要动态加载对应技能任务结束后它能回写新的经验到项目记忆里。这一套启动-执行-沉淀的闭环才是它最核心的价值。从某种意义上说它是在给 AI 编程助手补上组织级经验管理的能力。单个 AI 是聪明的个体但一个团队能持续高效靠的往往是沉淀下来的规范、库和复盘记录。superpowers 就是在帮 AI 建立这套体系。1.3 什么人适合用什么人不适合我先说结论如果你主要用 AI 写一次性脚本、做临时分析或者只在一个小项目里随手改改代码那 superpowers 带来的收益有限甚至会因为多了一堆文件而觉得累赘。它真正发力的场景有几个特征项目有一定规模代码和约定比较复杂你长期围绕同一批项目工作需要 AI 记住大量背景团队里有多个成员共用 AI 助手统一工作流和经验沉淀很重要。在这些场景里superpowers 的价值才会完全释放出来。另外它设计上带有强烈的 TDD 和任务分解导向。如果你不打算让 AI先写测试再写实现也不喜欢让 AI 先给方案、再逐步执行的工作方式那它的很多技能用起来会别扭。我先把这个前提说清楚免得你装了以后发现理念不合。2. 安装 Superpowers两条路径与排错记录2.1 路径一通过 Marketplace 添加插件目前 superpowers 的主流安装方式是通过 Claude Code 的插件市场Marketplace机制。如果你已经在用 Claude Code整个操作就是两条命令的事# 添加插件市场源 claude plugin marketplace add obra/superpowers # 安装插件 claude plugin install superpowersobra安装完成后在项目目录里启动 Claude Code输入/superpowers:init工具会在项目根目录初始化一套 superpowers 结构包括项目记忆目录和技能配置。之后再启动会话AI 会自动加载这套体系。需要注意一点不同版本的 Claude Code 对插件市场的支持程度不太一样。如果你用的是较旧的版本可能会提示 marketplace 相关命令不存在这种情况建议先升级 Claude Code 本体再装插件。2.2 路径二本地克隆源码接入Marketplace 方式适合想快速体验的人。但如果你打算深入定制技能或者想完全掌控技能的更新节奏我建议用本地源码方式。# 把仓库克隆到本地固定目录 git clone https://github.com/obra/superpowers.git ~/.superpowers # 通过 Claude Code 的配置指向本地源码 claude plugin marketplace add ~/.superpowers claude plugin install superpowerslocal用本地方式的好处有两个一是你能直接修改技能文件比如给某个技能补充你们团队的专属规范二是避免远程仓库更新后新技能不兼容你的工作流你可以在确认稳定后再手动拉取。我自己目前就是本地方式。每次远程仓库有更新我先看 changelog再决定要不要合并。项目作者更新频率挺高的让生产环境的技能版本跟着上游盲跑心里不踏实。2.3 安装失败的三个常见原因我装了两次才成功第一次卡了半小时。总结下来安装失败基本就三个原因。第一个是命令名写错。插件市场里有多个以 superpowers 为前缀的项目或扩展如果你直接执行claude plugin install superpowers有时会装错对象。正确做法是先claude plugin install superpowersobra明确指定来源。第二个是版本兼容问题。Claude Code 对插件市场的支持是在某个版本之后才引入的老版本执行 marketplace 命令会直接报错。遇到这种情况升级到最新 Claude Code 就好。第三个是网络或缓存问题拉取市场信息失败或者缓存了旧数据。解决办法不算复杂把插件目录删掉重新拉一遍或者换一个网络环境再试。实际排查时我建议先用claude plugin list看当前插件状态再决定是重新安装还是手动指定本地路径。3. 核心机制拆解技能、斜杠命令与项目记忆3.1 SKILL.md 的结构superpowers 里最基础的单位是技能skill每个技能都是一个目录目录里至少有一个核心文件SKILL.md。这个文件不是普通的 Markdown 文档它头部有 YAML frontmatter声明技能的名称、描述、适用场景和依赖关系正文则是详细的操作步骤。举个例子它内置的 systematic-debugging 技能正文会一步步引导 AI先复现问题再缩小范围提出假设逐一验证最后记录根因。表面上看这就像一份很详细的提示词模板但关键在于这份文件是独立于对话存在的任何新会话都能加载同一个技能这就把调试方法论变成了项目的长期资产。除了官方技能你也可以自定义技能。我在 Java 项目里写过一个 flyway-migration-review 技能专门负责审查数据库迁移脚本的安全性。AI 每次遇到 Flyway 迁移文件变更就会自动加载这个技能按照里面的 checklist 逐项检查。SKILL.md的 frontmatter 里几个关键字段值得注意name是技能的唯一标识description决定了 AI 在什么情况下会想到调用它dependencies则声明了这个技能依赖哪些子技能。描述写得越精准AI 的调用判断就越准这是最值得花时间打磨的地方。3.2 技能的触发链路AI 也不是每次都把几百个技能的说明读完。superpowers 采用的机制是启动时先读取技能索引了解有哪些技能、各自解决什么问题遇到具体任务时根据索引里的描述判断是否调用某个技能一旦决定调用才真正读取该技能目录下的SKILL.md和配套文件。这套先看目录、按需读取的机制很聪明。它既保证 AI 知道工具箱里有什么又避免把所有工具的说明书一次性读进来有效节省了上下文窗口。实际使用中触发准确率并不是 100%。有时候 AI 会漏掉某个明显相关的技能有时候又会把两个相似技能混在一起。遇到这种情况我会直接在对话里补充一句按 xx 技能来处理这个问题AI 就会立刻加载对应文件。这里也顺带提醒一下技能描述里的关键词越贴近实际任务术语触发准确率越高。3.3 项目记忆让经验跨会话存活技能解决了方法论复用项目记忆Project Memory解决的则是项目上下文复用。初始化 superpowers 之后项目根目录会出现记忆目录里面存的是 AI 在历次会话里沉淀下来的关键信息项目目标、技术决策、踩坑记录、约定规范甚至是当前任务进度。这个机制在实际使用中有一个非常明显的影响我开新会话时不再需要长篇大论地描述项目背景AI 通过读记忆文件就能恢复到七八成状态。它知道我们技术栈是什么版本知道某些模块有历史包袱知道项目里测试命令用什么跑。那种新同事来了又要再讲一遍的疲惫感确实被消解了不少。不过要注意项目记忆不是自动魔法。它依赖 AI 在会话结束时主动总结并写入。superpowers 有一套流程引导 AI 做总结但如果你在对话中频繁打断或任务还没收尾就关闭会话记忆文件的更新就可能不完整。我的习惯是每个任务跑完一定要等 AI 走完总结-写入记忆这一步再关会话。4. 在 Codex 上使用 Superpowers适配与差异4.1 Codex 与 Claude Code 的机制差异既然热搜里总有人问 codex superpowers我也聊聊在 Codex 上折腾的体验。首先得说清楚superpowers 最初是为 Claude Code 的插件机制设计的它依赖斜杠命令、插件市场这些基础设施。而 Codex CLI 更强调轻量、本地优先它没有完全对等的插件市场机制。所以不能在 Codex 里直接claude plugin一把梭。但两者有一个共同点都支持通过项目根目录的指令文件注入上下文——Claude Code 读 CLAUDE.mdCodex 读 AGENTS.md。这意味着虽然 superpowers 不能作为插件直接装进 Codex它的技能内容却能通过 AGENTS.md 以另一种形态搬运过去。4.2 我的适配方案我的做法是先把 superpowers 的技能目录克隆到本地然后用脚本把技能索引和关键技能描述编译成一份结构化的 AGENTS.md。这份文件里会写明项目有哪些技能、每个技能的触发条件、以及执行技能时应该去哪个路径读取完整说明。Codex 在每次会话启动时会自动加载 AGENTS.md因此 AI 会知道自己应该去找哪些技能文件虽然不像 Claude Code 那样有斜杠命令直接调用但 Phase 1 的技能感知是具备的。遇到需要特定技能的任务时我会在 prompt 里主动要求它读取对应技能目录下的SKILL.md这样也能跑通大半个流程。我还在 Codex 里试过把某个技能的核心步骤直接内联到 AGENTS.md 里比如把 code-review 技能的完整 checklist 放进去。效果不错但文件体积膨胀很快。所以我的建议是通用技能放索引重量级技能的完整内容保留在技能目录按需加载。4.3 实际效果与注意点实测下来在 Codex 上使用这套适配方案能力大约能还原七八成技能感知、任务拆解、按步骤执行都没问题。差别主要在交互体验比如无法用斜杠命令快速切换技能也无法让 Codex 执行superpowers:create-skill之类的交互式命令来创建新技能。还有一点要提醒Codex 对AGENTS.md的处理方式和 Claude Code 的插件加载不同文件过长反而可能稀释核心指令。我试过把几百个技能的描述全塞进去结果 Codex 的选择反而变差了。最终我把 AGENTS.md 里的技能索引压缩到只保留最常用的二三十个高频技能准确率明显回升。如果你主要用 Codex又不想折腾太复杂我建议从挑选两三个最高频技能内联进 AGENTS.md开始别一上来就追求全量搬运。轻量适配带来的收益往往比完整移植更大。5. Java 项目实战Superpowers 辅助 Spring Boot 开发5.1 为 Java 定制技能包superpowers 本身跟语言无关它内置的技能大都是方法论层面的。但现实中的 Java 项目往往有一套约定包结构怎么分、Mapper 层要不要接口、DTO 和 VO 怎么转换、异常处理统一走哪个类。这些约定如果 AI 不知道写出来的代码总是差那么点味道。所以我在 Java 工程里自定义了几个技能包一个叫spring-boot-standards里面写清楚项目的分层规范、命名约定、依赖注入风格一个叫test-first-java规定写业务代码前必须先补测试测试框架用 JUnit 5 AssertJ还有一个build-diagnostics专门给 Maven 构建失败排查用。创建自定义技能不难在技能目录下新建一个文件夹写一个SKILL.md就能完成。关键是description字段要写得足够具体让 AI 在遇到我要新写一个查询接口时能明确地把spring-boot-standards抓出来用而不是绕开技能直接写。5.2 一次典型任务的全流程我拿一个实际的例子说说整体流程。最近有个任务是给订单模块加一个分页查询接口附带简单的关键字过滤。我把需求丢给 AI它第一件事不是写代码而是先加载了spring-boot-standards技能确认分层和命名规则然后按 TDD 技能先写测试。测试文件先定义好 Controller 返回的 JSON 结构、Service 层的方法签名、Mapper 的查询参数。紧接着它才开始补业务代码写完跑测试红了就回来改。最后 AI 还会照流程做一轮代码审查自动检查异常处理、参数校验和日志规范再更新项目记忆里关于订单模块的设计决策。整个过程看下来AI 的行为模式明显比裸用工具时更有章法不再一步到位直接甩出一个看似能跑、实际上结构混乱的实现。它像是一个熟悉团队规范的老开发在按流程办事而不是一个急着交差的新人。5.3 实测中的优点与局限优点很明显首先是代码风格一致性提升AI 这次写的代码和你上次手写的放在一起不会一眼看出位置不对其次是测试覆盖率有了兜底TDD 技能把先写测试变成硬性步骤你偶尔偷懒不让它写测试它还会主动提醒。这两个点在日常开发里非常加分。局限也不能忽视。第一个是 Java 项目的编译和测试周期比脚本类项目长AI 每做一步跑测试验证来回成本很高。如果你用的大模型对长任务不够稳定中间很容易出现上下文漂移导致它跑到一半忘了当前任务。第二个是自定义技能维护有成本团队规范一旦变化你得同步更新技能文件否则 AI 会照着一套过时规范写代码。总体我建议 Java 场景先小范围试点选一个模块跑通流程再逐步推广到核心业务。别一上来就把所有项目都接进去等你把技能文件打磨稳定了再全面铺开会更稳妥。6. 我的使用技巧与配置建议6.1 技能包的组织方式用了一段时间后我的技能包分成了三层。第一层是 superpowers 自带的核心技能比如系统化调试、代码审查、任务拆解这些直接开箱即用第二层是项目级自定义技能放在各项目内部记录该项目独特的规范和约定第三层是我自己的通用技能放在个人技能目录里所有项目共享比如 Git 提交信息规范、日志规范这类跨项目通用的经验。这种三层结构的好处是复用与隔离兼顾。通用技能改一处所有项目受益项目技能放在项目内部不会污染其他工程。如果你现在只装了官方技能我强烈建议从第二层开始补充写一个属于你自己项目的规范技能哪怕只有几条约定都会立刻感受到差别。6.2 两个值得养成的习惯第一个习惯是任务开始前先让 AI 读技能索引而不是直接甩需求。我现在开新会话后会先输入一句请先了解本项目的技能体系再开始处理我的任务。这句话成本极低但能大幅提高技能调用的准确率防止 AI 直接进入自由发挥模式。第二个习惯是定期检查项目记忆文件。我会每隔几天翻一次记忆目录看 AI 记录了哪些内容。很多时候你会发现它记住了不该记的细节或者漏掉了关键决策。对这个文件保持一点管理意识AI 的经验沉淀才不会是垃圾进垃圾出。我还建议你在用熟基础功能后试着动手改写一个内置技能。superpowers 的好处是它足够开放你完全可以把 AI 的行为方式调整成你自己的风格。我认识一些朋友把 code-review 技能改成了团队特有的检查规范也有团队把任务拆解技能改了让 AI 必须先出估算工时再做计划。这种定制深度是普通提示词工程很难企及的。6.3 最后的建议从我个人体验来说superpowers 的最大价值不是某个具体技能而是它提供了一套完整的方法论骨架。它逼着 AI 先理解再动手、先测试再实现、先记录再结束这一整套流程本身就是对 AI 编程工作方式的降维改造。如果你刚开始接触别急着把官方技能全装齐。挑一个你当前最痛的项目初始化之后先只用一个技能比如调试技能或 TDD 技能跑一周看看效果。等适应了这种工作节奏再逐步扩大配置范围。工具这东西用得顺手的才是最好的。