最近不少人在聊 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 superpowers@obra安装完成后，在项目目录里启动 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 superpowers@local用本地方式的好处有两个：一是你能直接修改技能文件，比如给某个技能补充你们团队的专属规范；二是避免远程仓库更新后，新技能不兼容你的工作流，你可以在确认稳定后再手动拉取。
我自己目前就是本地方式。每次远程仓库有更新，我先看 changelog，再决定要不要合并。项目作者更新频率挺高的，让生产环境的技能版本跟着上游盲跑，心里不踏实。
2.3 安装失败的三个常见原因
我装了两次才成功，第一次卡了半小时。总结下来，安装失败基本就三个原因。
第一个是命令名写错。插件市场里有多个以 superpowers 为前缀的项目或扩展，如果你直接执行claude plugin install superpowers，有时会装错对象。正确做法是先claude plugin install superpowers@obra明确指定来源。
第二个是版本兼容问题。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.md，Codex 读 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 技能，跑一周看看效果。等适应了这种工作节奏，再逐步扩大配置范围。工具这东西，用得顺手的才是最好的。
