★ FEATURED ARTICLE 最近我把 Superpowers 装进了本地的 AI 编码助手用了一周之后我对“AI 辅助写代码”这件事的看法发生了实质性的变化。Superpowers 不是某个新出的模型也不是一个 IDE 里的补全插件而是一套开源技能包专门给 Claude Code、Codex CLI 这类终端型 AI 编码助手做能力增强。你可以把它理解成给 AI 配了一整套“老师傅的作业流程”生成测试、重构代码、定位 bug、梳理任务它都能按照一套相对成熟的方法论来做而不是想到哪写到哪。如果你已经在用终端型 AI 助手或者正打算入手这篇 Superpowers 使用指南应该能帮你少踩不少坑。这套东西我刚开始看到名字时以为是某个“一键让 AI 变强”的黑科技实际折腾完才发现它做的事情非常朴素把那些你反复让 AI 干的活固化成可复用的技能。与其每次写“请你给这个方法生成几个单元测试覆盖正常和异常情况”不如直接调用一个技能让 AI 按照固定的步骤去分析、设计测试用例、再生成代码。这个转变才是 Superpowers 真正有价值的地方。1. Superpowers 到底解决了什么问题1.1 为什么默认的 AI 编码助手总让你觉得“不够靠谱”先说一个很多人都遇到过的场景你让 AI 助手给一个 Java 方法写单元测试它确实写了但经常出现三种情况测试只覆盖了最顺的那条路径异常分支全是摆设测试代码风格和项目里已有的完全不搭更让人头疼的是它根本不先问你这个方法到底该有什么行为拿到代码就开始编。这不是模型能力不够而是缺少流程约束。终端型 AI 助手在普通对话模式下更像是一个“极速接单员”你给什么指令它就顺着往下写。可写代码这件事尤其是写测试、做重构、查 bug是有固定套路的。老手拿到一段代码会先看输入输出、看边界条件、看依赖关系然后才动手。这些套路没有写进默认 Prompt 里AI 就只能临场发挥结果自然不稳定。Superpowers 的核心思路就是把这类“老师傅套路”做成一个个技能文件。每个技能文件里包含清晰的触发条件、执行步骤、输出格式和自查清单。AI 调用技能后相当于被拉进了一条预设的工作流行为方式会稳定很多。用工程化的思维去理解就是你给 AI 定义了若干个可复用的“函数”而不是每次都让它自由发挥。1.2 技能包、插件和 MCP 到底有什么不一样经常有人把 Superpowers、插件、MCP 这三个概念混在一起。MCPModel Context Protocol解决的是“AI 怎么访问外部工具和数据”比如读取数据库、操作浏览器本质是给 AI 接上手和眼睛。普通的 IDE 插件则是围绕编辑器做集成作用是改 UI、加按钮、启动调试器。而 Superpowers 这类技能包解决的是“AI 拿到一个任务后应该按什么步骤思考”它改的是 AI 的工作方法不是工具接口。这个区别非常重要。如果你只是想给 AI 加一个“能查数据库”的能力MCP 是正确的选择。但如果你希望 AI 写出的测试更接近你们团队的编码规范或者希望它在重构时先建立安全网再动手那就需要技能包。Superpowers 恰好在这方面做得比较完整它的技能不是一句简单的 Prompt而是一个个结构化的 Markdown 文件里面配有示例、检查代码清单、支持直接执行命令。AI 在调用技能时能看到“应该怎么做”也能看到“做到什么程度才算完成”。1.3 一个技能文件长什么样为什么它能约束 AI 的行为我用一个实际的技能文件来举例。Superpowers 里的技能文件通常分成几个区块技能名称和描述、何时使用、执行步骤、完成标准、以及一些常见错误的提醒。名称和描述是为了让 AI 在遇到任务时能自动匹配到正确的技能执行步骤则是把任务拆成有序的操作完成标准给了 AI 一个自查的边界避免它“写完了就算完事”。比如生成测试的技能它的步骤大致是先读取被测代码梳理出输入、输出和边界条件然后识别外部依赖决定要 mock 哪些对象接着设计用例列表覆盖正常路径、异常路径和边界值最后才生成测试代码并按照项目的测试命名规范调整。这套流程不算复杂但如果不用技能约束AI 经常会跳过前两步直接输出代码。Superpowers 的价值就是把这些“默认应该做但模型不一定会做”的步骤固化下来。明白这一点之后你自己想给 AI 定制什么技能也就有思路了。2. 安装与配置把技能包挂到你的 AI 助手身上2.1 前置条件先准备好环境在动手安装 Superpowers 之前先把环境理清楚。这个项目主要面向 Claude Code 和 Codex CLI 这两类终端型 AI 编码工具它不依赖某个特定的 IDE核心要求是你能在终端里正常使用这两个工具之一。另外建议确认你的终端环境支持 Git因为最常用的安装方式就是从 GitHub 克隆仓库。Windows 用户最好使用 Git Bash 或 WSL我在纯 cmd 环境下遇到过一次路径解析问题切到 Git Bash 后就顺畅了。还要提醒一句如果你是在公司内网环境可能需要先配置好代理否则克隆仓库这一步就会卡住。Node.js 环境虽然严格来说不是必须的但我建议装好。因为 Superpowers 有些辅助脚本和联动 MCP 的功能会用到 Node而且 Claude Code 本身也基于 Node 生态。装好之后可以用node -v确认版本最好在 18 以上。2.2 安装步骤我推荐市场化的方式打开 Claude Code 的交互界面直接用插件市场命令来安装这是最省事的路径/plugin marketplace add obra/superpowers执行完这条命令后再输入/plugin install superpowers安装完成后建议重启一次会话让插件加载生效。我一开始没有重启直接调用技能时提示找不到重开会话后就好了。如果你更喜欢手动管理也可以直接把仓库克隆到本机git clone https://github.com/obra/superpowers.git ~/.claude/plugins/superpowers这种方式的好处是方便自定义你可以直接编辑仓库里那些技能文件改成自己团队的习惯。坏处是后续更新需要自己拉代码而且如果目录位置和配置文件里的路径对不上AI 会找不到技能。还要特别注意一点安装插件只是第一步很多技能需要额外的支持工具。比如有些脚本类技能依赖 Node 环境有些测试生成技能需要项目里本身有测试框架。当初我用在一个 Python 项目上AI 生成的技能说要先跑pytest项目里根本没有这个依赖于是技能在第一步就卡住了。建议在正式使用前先给 AI 一句话说明你的项目技术栈比如“这是 Maven 管理的 Java 17 项目测试用 JUnit 5”。2.3 验证安装怎么确认技能真的生效了装完之后不要急着开工先做一次简单验证。在会话里输入/plugin看看插件列表里有没有 superpowers。如果有再输入/superpowers:list-skills不同版本的命令可能略有差异能列出技能清单就说明加载成功了。如果命令不存在先检查是不是没重启会话。如果/plugin marketplace add时报错大概率是网络问题确认一下对 GitHub 的访问是否正常。另一种常见情况是版本兼容问题Superpowers 的更新节奏比较快而 Claude Code 的插件机制偶尔会调整遇到这种情况就去仓库的 README 或 Issues 里翻一眼基本都有解决方案。验证通过之后我的习惯是先让它跑一个最基础的“列出可用技能”操作看 AI 是否能正确识别所有技能。这一步能确认两件事一是技能被正确加载二是 AI 能理解技能描述不会在触发时选错。我之前就遇到过 AI 把“生成测试”的技能理解成“调试代码”结果跑出来的流程完全不对。后来发现是旧版本的技能描述有歧义更新到新版本后就正常了。3. 上手实操核心技能怎么用3.1 先搞清楚有哪些常用技能Superpowers 的技能数量不少但日常开发中真正高频的就那几个。我把常用的整理成了一个速查表方便快速对照技能名典型触发场景通俗理解Test-Driven Development写新功能前想先写测试让 AI 严格按“红-绿-重构”的节奏推进Generate Tests给已有代码补测试先设计用例再生成代码Refactoring代码异味明显、结构混乱先建安全网再小步重构Debugging行为不符合预期先复现、再定位、再修复Code Review改动合并前需要审核按检查项逐条审查不只拍脑袋Documentation需要给模块补文档先用代码梳理逻辑再写说明这个列表里有几个点值得展开。TDD 技能不是一个简单的“写测试”指令它会让 AI 先跟你确认行为预期然后写一个会失败的测试再写最小实现让测试通过最后做重构。这个过程如果靠提示词硬逼 AI 做它很容易跳步但有技能约束后它会在每个阶段停下来确认。比如 Generate Tests 这个技能它会先要求 AI 读源码并列出“输入-输出-边界条件”表格然后再写测试。这个“先列表再动手”的环节是我觉得整个技能包里最有价值的部分。因为模型一旦把思路外化你再去看它的测试设计就能很清楚地知道哪些边界漏了而不用等测试跑挂了才去补。3.2 实操演示让它给一个 Java 工具类补测试我拿一个真实的场景来演示。项目里有一个DateUtils工具类里面有个方法formatDate作用是把LocalDate转成指定格式的字符串。我给 AI 的指令很简单“用测试生成技能给 formatDate 方法补全单元测试。”启用Generate Tests技能后它没有立刻写代码而是先给出了分析输入参数有两个LocalDate和格式模板字符串。边界条件日期为空、格式模板非法、日期为周一年的边界比如 2024 年 12 月 30 日属于 2025 年第一周如果格式化带周数这里容易误导。依赖没有外部依赖不需要 mock。测试用例清单正常日期、边界日期、空值、非法格式。看到它列出“周边界”这种用例我其实是有点意外的。因为如果只是直接写提示词它往往只会写出正常日期和空值这两个用例。这就是技能的价值它在分析阶段就会强制模型去思考容易出错的边界而不是直接跳到代码实现。接下来它生成了对应的 JUnit 5 测试类命名规范也自动用了项目里现有的ClassNameTest风格。最后它没有直接说“写完了”而是列了一个自查清单测试是否能覆盖所列边界、有没有用断言而不是打印输出、测试有没有依赖外部资源。这一整套流程走下来质量明显比默认对话高。3.3 怎么让 AI 能在合适的时候自动调用技能Superpowers 的技能有两种触发方式一种是你在提示词里明确指定“用某某技能”另一种是让 AI 根据任务描述自动匹配。实际用下来自动匹配有惊喜也有翻车。比如你说“帮我看看这个类有什么问题”它可能会自动命中 Code Review 技能但你说“给这段代码写几个测试”它有时候会匹配到 TDD 技能而不是 Generate Tests两者虽然相似但流程差异很大。为了让 AI 不选错我的做法是在项目根目录写一个AGENTS.md文件里面用简单的规则说明什么场景用什么技能。比如“当要求是补测试时使用 Generate Tests 技能当要求是新功能时使用 TDD 技能”。这个文件其实不挑工具Claude Code 和 Codex 都能识别项目上下文里的这种约定文档。加了这层约束之后技能的命中率会明显提升减少你反复纠正的成本。还有一个细节值得注意技能触发后AI 可能会执行一些命令比如跑测试、运行静态检查。在终端型工具里如果项目本身构建很慢这一步会消耗不少时间。建议给技能加上“先询问再执行”的心理预期也就是当它准备跑耗时命令时你可以直接打断它。Superpowers 的设计比较克制大部分步骤会先输出计划让你确认但定制技能时仍然建议把“是否执行命令”做成一个显式确认步骤避免它自作主张。4. Codex 场景与 Java 专项4.1 Codex CLI 里怎么接入 Superpowers很多人在 Codex CLI 上也想用 Superpowers但一开始会有点蒙因为它的插件体系和 Claude Code 不一样。Codex 对上下文的加载更依赖项目里的约定文件因此接入方式会更“手工作业”一些。常见做法是把 Superpowers 仓库里的skills目录整体复制到 Codex 能读取的位置然后在项目根目录的AGENTS.md里声明技能路径。另一种做法是在 Codex 的全局配置目录下建一个skills文件夹把技能拷进去这样所有项目都能共享。两种方式我都试过项目级声明更推荐因为不同项目用的技能可能不同而且团队协作时技能路径跟着项目走别人拉下代码就能用。需要注意一点Codex 的上下文窗口和文件读取方式与 Claude Code 存在差异直接把整个技能目录塞进上下文会占用很多 token。我的做法是让 Codex 只读取当前需要的技能文件而不是把所有技能一次性加载。你可以在 AGENTS.md 里写清楚“当处理测试生成时阅读 skills/generate-tests.md并严格遵循其步骤”。这样既能让技能生效又不会因为上下文过长导致响应变慢。4.2 Java 项目的技能落地不要只是“生成测试”Superpowers 在 Java 项目上能发挥作用的场景远不止生成测试。我最近在一个基于 Maven 的 Spring Boot 项目里做了几件事都是靠技能完成的用 Refactoring 技能把一个 600 行的 Controller 拆分成 Service 和 DTO用 Documentation 技能给一个复杂的配置类生成了说明文档甚至用 Debugging 技能配合本地日志梳理了一个诡异的问题。以重构为例我按照 Refactoring 技能的步骤操作它并没有急着改代码而是先让我确认入口测试是否存在。项目里这个 Controller 恰好几乎没有单元测试于是技能给出建议先写一个覆盖行为快照的测试再做结构拆分。这个“先测试后重构”的顺序其实很多资深工程师都知道但在没有技能约束时AI 很容易直接动手改代码改完你根本不敢合进去。Java 项目另一个痛点是对构建工具的依赖。Maven 项目的测试是mvn test而 Gradle 是./gradlew test如果技能里默认跑错了命令测试结果就会被误判。Superpowers 的技能本身不会自动适配你的项目它需要你在上下文里说明构建方式。我的建议是在 AGENTS.md 里写上完整命令构建工具版本、测试命令、代码风格规范。这一步做不好后面所有涉及命令执行的技能都会磕磕绊绊。4.3 案例从“生成测试”到“测试通过”的完整闭环我挑一个完整案例讲透。项目里有一个OrderService其中有个方法逻辑比较多依赖OrderRepository和PaymentClient。我用 Superpowers 的 Generate Tests 技能来补测试整个过程的推进是这样的技能先读取OrderService源码识别出两个外部依赖然后建议用 Mockito 生成 mock 对象。它先列出用例设计包括正常下单、库存不足、支付超时、订单已存在等情况。在支付超时这个用例上它让我确认异常是否需要被包装成业务异常而不是直接抛原始异常。这一步“向用户确认预期行为”的行为在普通对话模式中很少出现。确认后它生成了完整的测试类并主动执行了mvn test。第一次测试有两个用例失败原因是它 mock 的仓库方法返回值和实现不一致。它读取了失败信息修正了 mock 数据再次运行测试最终所有测试通过。整个过程虽然不是每次都零失败但它会把失败当成“信息”而不是停留在“生成完就结束”。这种“生成-执行-反馈-修复”的闭环才是技能包在 Java 项目里最值钱的部分。5. 常见问题与排坑实录5.1 问题速查表使用过程中最容易遇到的问题我汇总成了下面这张表现象可能原因解决办法/plugin看不到 superpowers插件没有成功添加重新执行 marketplace add然后重启会话调用技能提示不存在会话没有加载最新插件输入/plugin确认安装或重启技能执行时乱跑命令项目上下文缺少约束在 AGENTS.md 中写明构建命令和技能使用规则AI 不按技能步骤走版本过旧或技能描述冲突更新仓库检查技能描述是否与任务匹配Java 测试命令执行失败不知道项目用的是 Maven 还是 Gradle在上下文里明确构建工具和具体命令Windows 路径报错终端路径解析兼容问题改用 Git Bash 或 WSL网络超时无法正常访问 GitHub配置网络代理后重新安装这张表看起来简单但每一条背后都是实打实的教训。Windows 路径那个问题当初折腾了我半小时AI 一直提示找不到插件目录最后才发现是 cmd 里波浪号路径没有正确展开。换成 Git Bash 后一切正常。5.2 几个容易忽略的细节第一技能文件本身是可以改的。不要把这套东西当成不可变黑盒它是一个普通目录里的普通文本文件你可以针对团队规范调整技能描述。比如我想让 AI 在生成测试时强制使用 AssertJ 而不是 JUnit 原生的断言直接把技能文件里“断言风格”部分改一下就行。这个灵活性极大提升了实用性。第二技能触发依赖模型的理解能力。Superpowers 不是魔法它只是提高了 AI 按流程走的概率。如果你的模型本身上下文理解较差即使技能文件写得再清楚它也可能会跑偏。我用的经验是当 AI 跑偏时不要急着重新给指令先检查它是否读取了技能文件全文。如果它只截取了开头部分很可能是上下文被其他内容挤占可以开个新会话再试。第三token 消耗会比普通对话大。因为技能文件本身也是上下文的一部分AI 在思考时会“阅读”这些外部文件。用 Superpowers 处理一些简单问题时我会觉得性价比不高但遇到复杂场景时多一点 token 开销换稳定输出是划算的。建议不要在一个会话里堆积大量任务做完一件事就开新会话既能节省上下文也能减少技能被其他内容干扰的概率。5.3 我的几点使用心得我把 Superpowers 当成一套“团队工作规范的外挂”而不只是一个工具。它的真正意义不在于“让 AI 变强”而在于“让 AI 的行为变得可预期、可约束”。对我来说使用它的最优姿势不是每次手动指定技能而是通过 AGENTS.md 把技能与项目绑定让 AI 在合适场景下自然落进预设流程。我的一个具体习惯是在每个项目的 AGENTS.md 里都写清楚哪些任务必须使用哪个技能哪些命令必须遵守。比如测试生成统一用 Generate Tests代码评审统一用 Code Review。这个习惯带给我最大的好处是后来换人接手项目时AI 的行为完全一致不会因为提问方式不同而得到风格迥异的代码。最后再分享一个小技巧不要把所有技能一次性全倒给 AI。Superpowers 虽好但技能列表过长会稀释模型的注意力。我现在只会在项目里声明与当前工作相关的几个技能其他的一律不加载。选择性地暴露技能比越多越好要有效得多。这套东西目前已经成了我日常开发中不可缺的一部分建议你从 Generate Tests 这一个技能开始试跑通之后再逐渐扩展。
阅读完成 · 觉得有帮助？
