第一次看到 superpowers 这个词出现在 AI 编程工具的安装清单里我以为又是某个花哨的提示词合集。直到我正儿八经把它装进 Claude Code让 AI 按它的 TDD 技能重新走了一遍我改坏的一个 Java 模块我才意识到这东西的定位不是提示词而是一整套让 AI 编码助手变得有章法的工作流协议。安装、触发、让它自己拆解任务、按红灯-绿灯-重构的节奏改代码——整个过程像是给一个聪明但散漫的实习生配了一本详细到步骤级的操作手册。这篇文章主要写给三类人已经在用 Claude Code、Codex 这类命令行编程助手的开发者被 AI写得快但改不动、测不了折磨过的人以及那些在热搜里看到 superpowers java、codex superpowers、worbuddy 怎么用 superpowers 这些问题想搞清楚技能系统到底能不能搬到自己的工具链里用的人。我会从安装讲起拆到 SKILL.md 的底层机制再给一个完整的 Java 实战流程最后把 Codex 和 WorBuddy 这类非 Claude Code 环境的适配方法一起说清楚。1. 先弄明白 superpowers 到底解决什么问题1.1 一个让我决定重装工作流的场景我之前用编程助手的典型状态是让它改一个接口它五分钟内把代码写出来了看起来很合理但一跑测试就挂让它修 bug它凭感觉改了一个变量结果另一个模块跟着崩了。最烦的是每次对话都要重新强调一遍先写测试、先看报错、别一次性改一大片它在长对话里总是前脚答应后脚忘。后来在一个技术讨论里看到有人提到 obra/superpowers 这个仓库说它是给编程助手装技能的工具。我当时的理解是它可能是一份写得比较细的提示词模板。但实际用下来完全不是一回事——它不是告诉 AI你要专业一点而是给 AI 一套可以在运行时检索、按需加载、严格按步骤执行的技能文件。每个技能对应一个 SKILL.md 文件里面写着这个技能适用的场景、触发的关键词、以及完整的操作流程。AI 会根据当前任务的特征决定要不要加载某个技能。这个定位差别很关键。提示词是一次性口头嘱咐技能是随时能翻的手册。你不需要每次重新教它怎么 TDD、怎么排查 bug它自己会去翻手册。1.2 技能系统与一条龙提示词的本质区别很多人会把 superpowers 和网上的资深工程师角色提示词放在一起比较但它们在机制上有本质区别。一条龙提示词的问题是所有规则都塞进上下文里对话一长前面的约束就被冲淡了而且它是线性的AI 只能按你写死的顺序执行没法根据任务的实际情况选择用什么方法。superpowers 的方案是渐进式披露——AI 只先看到每个技能的一两行描述判断当前任务匹配哪个技能然后才去读取那个技能的完整内容。这样上下文窗口里始终只保留对当前任务真正有用的指令而不是把一万字规则从头到尾都压在里面。我用一个不太严谨但好懂的类比提示词像游客硬背的景点介绍走到哪背到哪技能系统像景区门口的导览图加每个景点门口的详细展板。导览图很轻AI 看一眼就知道该往哪走走到对应的展板前再读细节。2. 安装与初始化Claude Code 和本地目录两条路线2.1 安装前的环境检查先别急着复制安装命令花两分钟确认环境。superpowers 本身是纯 Markdown 文件集合对运行环境的要求其实不高但因为它主要依赖 Claude Code 的插件机制来加载所以 CLI 环境得先就绪。node -v git --version claude --version # Claude Code 命令行工具 codex --version # 如果后面要折腾 Codex 路线先确认它装了没我建议 Node 版本至少 18 以上实测在 Node 16 的老环境里插件的依赖解析偶尔会报错。Claude Code 需要先完成登录认证用订阅账号或者 API Key 都行这个按官方流程走一遍即可。2.2 方式一通过 plugin marketplace 装进 Claude Code这是目前最省事的路子。仓库维护者把技能打包成了 Claude Code 插件市场的格式你在 Claude Code 会话里直接执行两条斜杠命令/plugin marketplace add obra/superpowers-marketplace /plugin install superpowerssuperpowers-marketplace执行完第一条命令Claude Code 会把插件仓库地址加进本地配置第二条命令才真正把 superpowers 这个插件拉下来。装完建议重启一次会话让插件里的自定义斜杠命令生效。这里有个新手容易忽略的点装完不等于激活。你需要明确触发一次技能加载。最简单的方式是在会话里直接问你现在有哪些技能分别适合什么场景如果安装成功它会列出一串技能名比如测试驱动开发、调试、计划编写、创建新技能这类。如果它回答说我没有特殊技能那大概率是插件没装上或是版本太旧先更新 Claude Code 再重试。2.3 方式二把技能仓库直接拖进本地目录如果你不想用插件市场或者你用的是社区里的某个定制版本也可以直接 clone 仓库到本地git clone https://github.com/obra/superpowers ~/superpowers然后把仓库里的技能目录链接到 Claude Code 的 skills 目录或者直接在配置里指定技能路径。具体路径在不同版本里不完全一样我用的做法是创建一个符号链接ln -s ~/superpowers/skills ~/.claude/skills这招对想自己魔改技能内容的场景特别方便——技能文件就在本机想改哪条流程直接改 Markdown 就行改完重启会话即可生效不用重新装插件。2.4 第一次激活如何确认技能真的加载了我踩过的第一个坑就是装完插件后直接开始干活结果 AI 根本没按 TDD 流程走。后来我研究了一下发现 superpowers 的加载机制是显示触发加隐式匹配并存的。隐式匹配是指 AI 根据你任务里的关键词自动判断要不要读某个技能显示触发则是你直接说出技能名比如用 TDD 技能处理这个需求。新手阶段不要迷信隐式匹配直接显式触发等你能熟练控制对话节奏之后再让它自己判断。验证方法很简单让它把 TDD 技能的内容摘要给我看看。如果它能准确说出红灯、绿灯、重构这几个阶段说明技能已经进上下文了。3. 拆开看底层SKILL.md、前置描述与按需加载3.1 一个典型 SKILL.md 文件长什么样要真正驾驭 superpowers必须看懂它的文件格式。每个技能就是一个 Markdown 文件文件名随意但内部结构有约定最上面是 YAML 格式的 frontmatter包含 name 和 description 两个必填字段下面是正文。--- name: test-driven-development description: 在实施任何代码变更前先编写失败测试再实现最小代码最后重构。适合需求变更、bug修复、新功能开发等场景。当任务涉及修改业务逻辑时使用。 --- # TDD 技能 当任务涉及修改代码行为时必须按以下步骤执行 1. 红灯阶段先写一个能描述期望行为的失败测试。 2. 确认失败运行测试确认它因为功能未实现而失败而不是因为语法错误。 3. 绿灯阶段编写满足测试的最少代码。 4. 确认通过再次运行测试确认变绿。 5. 重构阶段在测试保护下清理代码结构。 6. 运行完整测试套件确认没有回归。注意 description 字段它决定了 AI 在什么情况下会想起这个技能。写得太笼统比如用于测试AI 在遇到具体任务时根本匹配不上写得太窄比如只在处理订单模块时使用其他类似场景又用不上。这是技能路由的核心后面我会专门说。3.2 渐进式披露为什么不会把上下文撑爆很多人担心一个问题装了几十个技能每个技能正文都有几千字那上下文窗口不是瞬间爆炸吗其实不会。superpowers 用的是渐进式披露默认情况下AI 看到的只是所有技能 description 的轻量列表这部分很短大概几十行。只有当它认定某个技能适用时才会去读那个技能的文件内容。这就像你手机里的 App 列表只显示图标和名称你不点开就不会加载它的完整页面。所以在实际使用中一个会话里通常只会加载两到三个相关技能上下文开销完全可以接受。这也解释了为什么技能文件写得好不好直接决定 AI 会不会在关键时刻想起它。3.3 技能路由AI 是怎么知道该用哪个技能的技能路由机制不复杂但理解它对你有实际帮助。AI 在每轮对话里会先扫描当前任务和技能列表里的 description 做语义匹配。匹配上了它就读文件匹配不上它就按默认方式干活。这就解释了为什么同一次会话里你说帮我修这个 bug它可能自动加载调试技能但你说帮我看看这个函数写得对不对它可能不加载任何技能直接给意见。你完全可以通过调整自己的提问方式来引导路由明确说出技能名、描述任务性质是修 bug 还是新功能、甚至直接要求它先决定用哪个技能再开始干活。4. 团队里用得最狠的四个内置技能含实战4.1 计划先行从边写边想变成先想后写我用的第一个技能是计划类技能。以前让 AI 改一个跨模块的功能它经常改到一半才发现设计有问题然后回头推翻重来。计划类技能的做法是在动手之前先拆解需求、列出变更点、评估影响面、写出实施步骤最后把计划给我确认。实际操作中我一般这么问有一个需求把现有的 CSV 导出改成异步生成前端通过下载链接轮询。先加载计划技能给我一份实施方案先不要写代码。它会先输出需求分析、涉及的文件、改动顺序、风险点以及一个分步计划。确认后我再让它执行。这套流程比直接让它写代码慢了几分钟但后面返工的时间省得更多。特别是涉及数据库表结构、接口契约这类牵一发动全身的改动没有计划就动工基本等于赌运气。4.2 TDD 技能用红灯-绿灯-重构对付改动TDD 技能是我目前使用频率最高的技能也是 superpowers 里最出名的技能。它的完整流程是这样的写出一个失败测试明确描述我希望这段代码有什么行为。运行测试亲眼确认它失败且失败原因是功能不存在而不是语法错误或环境问题。写最少量的代码让测试通过。再运行测试确认变绿。重构在测试保护下消除重复、调整结构、改善命名。运行整个测试套件确认没有破坏其他模块。听起来很基础但关键在于——AI 真的会严格按这个顺序执行而不是跳步。有一次我故意让它先写实现再补测试它直接拒绝说按 TDD 技能流程必须先写失败测试。这就是技能比提示词强硬的地方它是被当成规则执行的。4.3 调试技能逼着 AI 按证据链排查调试技能解决的是我最头疼的问题AI 瞎猜 bug 原因。传统的 AI 修 bug 方式是看到异常信息猜测一个可能原因直接改代码——有时候运气好能改对但更多时候是把 A 问题的补丁打到了 B 问题上。调试技能的流程是先复现 → 收集证据 → 提出假设 → 验证假设 → 修复 → 回归验证。它要求 AI 在给出修复方案之前先说明我依据什么证据判断是这个原因。如果证据不足它应该继续排查而不是硬给一个答案。我实测下来这套流程对两类情况特别有效一是偶发 bug二是跨模块的调用链问题。AI 被逼着按逻辑走而不是凭训练数据里的模式猜答案准确率提升非常明显。4.4 自举技能让 AI 自己写新技能superpowers 里有一个很特别的自举技能作用是让 AI 帮你创建新的 SKILL.md 文件。当你发现某个流程反复手工指导 AI 时就可以把这段流程沉淀成一个技能。比如我团队里有一个约定所有对外接口必须包含日志记录、超时设置和错误码规范。以前我每次都要在对话里重新贴一遍要求后来我直接用自举技能让 AI 把这套规范写成api-implementation技能的 SKILL.md 文件。从那以后只要提到实现一个新接口AI 就会自动加载这个技能把团队规范执行得毫不走样。这一步是把临时经验变成持久资产的关键。用工具的最高境界不是会用现成技能而是能把你自己团队的流程写成技能。5. 把 superpowers 用到 Java 项目上的完整流程5.1 场景设定用 TDD 技能做一个小工具热搜里有人搜 superpowers java说明不少人在 Java 项目里试过这玩意。我拿一个实际做过的例子拆给大家看需求是实现一个订单号生成器规则是日期 六位流水号流水号每天重置。第一步不是写代码而是让 AI 加载计划技能做拆解。我当时的提问是加载计划技能。我们要在现有 Java 工程里新增一个订单号生成器规则是日期加六位流水号每天重置。请先给出一个实施计划包含用到的类、依赖和测试策略。它给出的计划大概是新建OrderNoGenerator类、用DateTimeFormatter格式化日期、用AtomicInteger管理当日流水、考虑线程安全、用 JUnit 5 写测试验证跨天重置逻辑。这个计划本身平平无奇但关键是它在动手前明确了测试策略后面 TDD 技能才有得执行。5.2 实际操作一次由技能驱动的开发过程计划确认后我让 AI 按 TDD 技能执行。它第一步创建了一个测试类OrderNoGeneratorTest先写了两个测试用例一个验证当天生成的号格式正确另一个验证过了一天通过传入模拟时钟流水号重置。这里有个细节因为订单号生成依赖当前日期如果直接写死LocalDate.now()测试跨天重置会很麻烦。AI 在 TDD 过程中发现这个问题主动提出用Clock注入来解耦时间依赖——这个设计是从测试需求倒推出来的不是一开始就拍脑袋定的。之后流程就很标准了跑测试确认红灯写OrderNoGenerator最小实现跑测试确认绿灯重构把日期格式化和流水号生成拆成独立私有方法。全程我只需要在关键节点确认代码质量比我平时手写还规范。5.3 Java 环境下容易踩的反馈回路问题用了一个多月我要特别提醒 Java 项目里的一个坑TDD 技能要求快速失败、快速反馈但 Java 生态的测试链路往往不满足这个前提。如果你把 Spring Boot 上下文加载测试放进 TDD 回环里每次跑测试要起一个完整容器等三十秒起服务、再等三十秒跑用例AI 的耐心和上下文都会被拖垮。我的做法是在技能使用前明确限定单元测试用 JUnit 5禁止加载 Spring 上下文只有集成测试阶段才允许跑 SpringBootTest。配合 Maven 的 surefire 配置让mvn test只跑*Test.java把*IT.java留到专门的集成测试阶段。这样单测反馈控制在几秒内TDD 节奏才能成立。同样的问题在 Maven 和 Gradle 里都存在原理一样让单元测试的反馈回路尽量短。6. codex superpowers在 Codex 里复刻同一套流程6.1 为什么 Codex 不能直接装插件超级热搜词里有个 codex superpowers这问到了点子上。superpowers 原版做在 Claude Code 的插件机制上靠斜杠命令和/.claude/skills目录加载Codex 是 OpenAI 的命令行编程工具两边的插件体系不通用所以不能直接在 Codex 里敲/plugin install superpowers。但技能的载体是纯 Markdown 文件这就意味着只要有办法让 Codex知道去哪读文件、什么时候读文件同一套技能完全可以复刻过去。6.2 挂载方式AGENTS.md 技能目录Codex CLI 支持项目级指令文件AGENTS.md它会在会话开始时被读入上下文。我的做法是给项目根目录建一个AGENTS.md内容大致如下# 项目级 AI 工作约定 - 克隆的 superpowers 技能库位于 ~/superpowers/skills。 - 当任务涉及代码变更时先阅读 ~/superpowers/skills/test-driven-development/SKILL.md 并严格按步骤执行。 - 当任务涉及排查线上问题时先阅读 ~/superpowers/skills/debugging/SKILL.md。 - 动手前先输出实施计划计划确认后再写代码。这么做的本质是把AI 自动路由降级为启动时预先约定等价于告诉 Codex什么场景该翻哪本手册。由于 AGENTS.md 是常驻上下文的它比临时提示更可靠对话再长也不会被冲淡。另外有些社区维护的 codex-superpowers 分支会把这一步做成一条命令自动初始化 AGENTS.md原理完全一样只是帮你省了手写的功夫。6.3 我在 Codex 里实测的几个差异点第一个差异是显式加载。Claude Code 因为有插件系统AI 能看到技能列表并自动路由Codex 只靠 AGENTS.md 的规则跳转所以你必须把遇到什么任务读什么技能写得更具体越细越不容易偏。第二个差异是技能内部对工具调用的描述。原版技能里有些步骤预设了你用的是 Claude Code 的特定能力比如/add、/clear、/model这类斜杠命令。放到 Codex 里要手动把这些替换成 Codex 的等价操作或者干脆删掉只保留逻辑流程。第三个差异是反馈回路。Codex 的执行风格比较直接你让它按 TDD 走它可能会在红灯阶段一次性写五六个测试再跑。这不是大问题但如果发现它跳过了确认失败这个动作你需要在 AGENTS.md 里加一句强制要求每个测试写完后立即运行并确认失败原因。7. 别急着问worbuddy 怎么用 superpowers技能文件是通用资产7.1 先判断你的工具支持哪种挂载有朋友在搜索引擎上敲 worbuddy 怎么用 superpowers说明大家有一个共同的困惑这个技能系统是不是只有 Claude Code 能用答案是否定的。WorBuddy、WordBuddy 这类 AI 写作/办公类工具以及各种自己搭的 Agent 框架能不能用 superpowers 取决于一个判断它有没有自定义指令/技能/知识库的挂载位置。常见的有三种形态有独立的技能目录比如~/.worbuddy/skills/或 App 设置里的自定义技能入口这种情况直接把 SKILL.md 文件复制进去就行。只支持系统提示词或角色设定没有文件目录这种情况要把技能正文粘贴进提示词区技能不长的话完全可行。什么都不支持只有普通聊天这种情况只能靠对话时手动粘内容效率低一些但临时用也够。7.2 通用迁移三步走不管目标工具是哪一类迁移步骤都是三件事复制文件、改路径、写触发说明。第一步把 superpowers 仓库里你需要的SKILL.md文件找出来复制到目标工具的技能目录。第二步确认目标工具读取技能目录的规则——有些工具要求所有技能文件都在根目录有些支持子目录分类。第三步在工具的指令区或 AGENTS.md 等价物里写一句触发说明当任务属于某个技能描述的场景时必须读取并遵循对应技能的步骤。这一步的细节决定成败。我见过有人把技能文件复制进去了但忘了写触发说明结果工具根本不知道有这些文件存在。记住技能的 description 是给 AI 看的索引触发说明是给 AI 看的导航两者缺一不可。7.3 没有技能机制的编辑器怎么用如果你用的工具实在没有技能目录还有一个土办法把技能正文压缩成精简指令放进系统提示词。一个 TDD 技能的精华可以压缩成几十行虽然比不上完整技能文件那么严谨但比没有强得多。我自己在不同工具间迁移技能的经验是尽量让技能内容本身不依赖具体平台。看到原版技能里写了某个 CLI 专属命令就改写成通用的操作描述这样同一个技能文件放到哪个工具里都能跑。8. 一个多月用下来的复盘与避坑清单8.1 我踩过的四个坑及解法第一个坑是装完不生效。症状是 AI 完全不提技能解决方案是显式触发一次确认加载后再正常使用。第二个坑是技能文件路径配错症状是 AI 说我找不到这个技能解决方法是检查符号链接和目录权限用ls -la ~/.claude/skills确认文件真的可见。第三个坑是 TDD 回环太长。Java 项目里这个问题最严重解决方法前面说过把单元测试和集成测试分开只让单测参与 TDD 循环。第四个坑是技能内容过时。Claude Code 和 Codex 更新很频繁一段时间不更新技能库里面引用的命令可能就变了我每两周拉一次仓库更新顺带检查 AGENTS.md 里的命令是否还有效。8.2 关于装完就变强的幻觉我得泼一盆冷水superpowers 不是装上之后模型智商 50的补丁。它的作用是约束工作流程让 AI 按一套成熟的方法论执行但它不会让一个对项目一无所知的 AI 突然变成资深架构师。该做的需求分析、该查的历史代码、该验证的边界条件一个都少不了。我见过有人装上之后兴致勃勃让它重构整个模块结果因为需求没描述清楚技能再好也白搭。技能是放大器放大的是你输入质量和流程纪律不是凭空创造质量。8.3 我的建议从三个技能开始如果你刚接触这套东西我不建议一上来就把所有技能都装齐。先装计划、TDD、调试这三个实际跑一两个项目感受一下AI 被流程约束是什么体验。等你能熟练控制它的节奏了再去研究创建新技能。最后说一个我自己的体会技能系统的最大价值不是省掉了写提示词的功夫而是让你积累的工程经验可以沉淀成可复用的文件。以前我带人靠嘴说现在我把团队规范写成一个 SKILL.md扔给任何一个 AI 工具都能立刻执行。这份资产的长期价值可能比省下的那点时间更值得在意。