★ FEATURED ARTICLE 最近 AI 编程圈的几个群里superpowers 这个词出现的频率高得吓人。不是中二病也不是什么漫画梗它是一套给 AI 编程代理用的技能扩展框架主要跑在 Claude Code、Codex 这类命令行工具上。简单说你可以把它理解成给 AI 装上的一套标准化作业手册——原来你问一句它答一句现在你丢一个任务它会自己走完先聊清楚需求、再拆计划、再写测试、再动手实现、最后重构收尾的完整流程。我用它大概有三周了最大的感受是AI 写出来的东西不再是能跑就行而开始像同事手里交出来的活。如果你最近也在折腾 superpowers 安装、superpowers 使用教程或者想在 Codex、Java 项目里把它用起来这篇文章应该能帮你省不少时间。我会从它到底解决什么问题讲起再给到完整的上手路径和我在实际项目中踩过的坑。1. 项目解读superpowers 到底在解决什么问题1.1 一句话讲清它是什么superpowers 是一个开源项目由 Jesse Vincent网名 obra发起本质上是给 AI 编程代理准备的一套技能包。它不是 IDE 插件也不是独立的 AI 模型而是一堆高度结构化的 Markdown 技能文件外加一个把它们加载进 AI 工作流的框架。每个技能文件都定义了一个完整的工作流程AI 在对话中调用它就相当于进入了按套路干活的模式。比如你想让 AI 实现一个新功能它不会直接甩出一大段代码而是先跟你确认验收标准然后写计划再按测试驱动开发的节奏把功能做出来。打个比方你让实习生写个登录功能他大概率能写出来但可能漏掉参数校验、密码加密、错误提示。可你要是给他一本带检查清单的《登录功能作业规范》他至少不会漏掉该有的步骤交上来的东西也有章法。superpowers 就是那本规范。1.2 为什么叫 superpowers从回答者到执行者用过 Claude Code 或 Codex 的人应该都有类似的体验AI 很聪明但没耐心。你让它写一个函数它五分钟就写完了你让它重构一个模块它改了三分之一就停下来等你确认下一步。这不是能力问题是工作方法问题——模型本身缺乏一套稳定的做事的节奏。superpowers 解决的就是这个问题。它把领域里被验证过的好方法比如测试驱动开发、小步重构、计划先行、规范的提交信息固化成 AI 的默认行为。让 AI 从你问什么我答什么的回答者变成拿到任务自己规划、自己执行、自己检查的执行者。我用一个真实场景对比一下。没有 superpowers 时我让 AI 给 UserService 加一个 findByEmail 方法它可能直接给你一个能编译通过的实现然后问你还需要什么吗。有 superpowers 时它会先问email 不存在时应该抛异常还是返回空然后写一个失败的测试再写实现最后跑一遍测试确认全绿。同样是完成一个需求后者交付的东西明显更可维护。1.3 哪些人最该用哪些人可以先不用先说适合用的天天泡在终端里用 Claude Code 或 Codex 写代码的人。想让 AI 输出的代码有测试、有文档、可维护的人。带团队、想统一大家 AI 使用姿势的人——技能包可以放进 Git 仓库全组共用一套标准。再说暂时不用的偶尔用 AI 写个脚本、处理一次临时需求的人技能包会显得重。完全没有版本控制概念的新手。因为 superpowers 里的很多技能高度依赖 Git比如它会频繁查看 diff、创建分支、用提交信息模板如果对 Git 不熟容易不知道自己正在被 AI 引导着干什么。2. 核心设计技能Skills机制拆解2.1 技能 可复用的标准作业程序superpowers 里最核心的概念就是 Skill。一个技能文件通常由两部分组成开头是一段 YAML 格式的 frontmatter写着技能名称、描述、适用场景正文是完整的操作指引告诉 AI 遇到这类任务应该按什么顺序执行、每一步要产出什么、有哪些要点。这种设计本质上就是把一个资深工程师脑子里那套遇到问题怎么做的流程变成一份机器能读取、模型能执行的文档。它和普通提示词最大的区别是提示词是临时的用完就忘技能文件是持久的可以反复调用可以被其他技能引用可以放进 Git 里做版本管理。我刚开始以为这就是换了个方式写 prompt用了一段时间才发现区别很大。普通 prompt 是请按测试驱动开发来写模型大概率会回答好的我按 TDD 来然后依然是先写实现再补测试。技能文件不一样它把先写失败测试拆成了一个不可跳过的步骤模型在每一步都会读到现在你在这个 Skill 的第 2 步请先完成这一步的产出这样就不会蒙混过去。2.2 内置技能盘点superpowers 仓库里预置了不少技能我用得比较多的是下面这几个技能名称触发场景主要产出物brainstorming需求模糊需要先讨论方案明确的功能描述、验收标准、边界情况清单writing-plans任务较大需要拆解步骤带依赖关系的执行计划test-driven-development实现新功能或修复 Bug先失败的测试、最小实现、重构后的最终代码refactoring既有代码需要调整结构分步完成的多次小提交而不是一次大改commit-message提交代码前规范化的 Git 提交信息using-git需要安全地操作版本库对 git 操作安全性的检查结论debugging遇到难以定位的问题基于假设验证的调试过程和根因结论这些技能不是孤立的它们可以互相调用。比如 test-driven-development 在执行中途发现实现很糟糕可能自动调用 refactoring 来整理结构在所有代码改完后又会调用 commit-message 来生成提交信息。组合起来AI 的工作流就变成了流水线而不是一个孤零零的问答。2.3 为什么技能优于普通提示词这个问题我问过自己很多遍最终总结出三个关键点。第一稳定复现。模型嘴上说我按 TDD 来和真的按 TDD 做是两回事。技能文件用步骤清单和检查点约束模型的行为让它每次都能做出差不多质量的事而不是看心情发挥。第二可组合嵌套。普通提示词写完之后你很难让另一个提示词去调用它。技能文件可以把任务拆成多个技能的串联比如先 brainstorming 澄清需求再 writing-plans 制定计划然后用 TDD 分步实现。这种组合能力让 AI 面对复杂任务时不至于乱套。第三集体进化。技能文件是纯文本放在 Git 里就能做版本管理和多人维护。我自己就 fork 了一个技能把团队内部的一些规范加了进去比如提交信息里必须带任务单号。这样 AI 在开发时使用的就不再是互联网通用的最佳实践而是你们团队自己的最佳实践。2.4 技能文件长什么样很多人对 superpowers 的印象是一堆神秘脚本我拆开看之后发现其实特别朴素。一个技能文件大概长这样--- name: test-driven-development description: 使用测试驱动开发流程实现新功能先写测试再写实现最后重构。 --- 执行本技能时 1. 和用户确认功能的验收标准包括正常情况和异常情况。 2. 先编写一个会失败的测试覆盖验收标准中的关键场景。 3. 运行测试确认它确实失败。 4. 用最小实现让测试通过。 5. 检查实现是否有重复或坏味道有小步重构的空间就重构。 6. 重新运行全部测试确认没有回归。结构清楚、意图明确、没有玄学。它之所以有效就是因为它把写代码这事应该有什么节奏讲得非常具体。模型读到的不只是一句你要遵守 TDD而是一套可以用代码逐行解释的操作序列。这也是我建议所有想深入了解 superpowers 的人都去通读一遍技能文件的原因——你会发现原来 AI 的超能力不是什么魔法而是把好习惯写成了文档。3. 实操从安装到在项目里真正用起来3.1 安装前的基础环境先把前提条件说清楚免得你装到一半发现缺东西。你需要准备一个能跑 AI 编程代理的终端环境。目前主流的宿主就是 Claude Code 和 Codex CLI至少装其中一个。Node.js 18 及以上版本。虽然 superpowers 本身很大程度上是 Markdown 文件但它的加载脚本和命令工具是用 JavaScript 生态跑的所以 Node 环境绕不开。Git 环境。技能文件本身要 clone 下来而且很多技能在运行时会调用 git 来查看差异、创建提交所以 Git 必须可用。安装前我习惯先跑一遍版本检查比如node --version、git --version确认没有奇怪的报错再去装技能。一个小坑如果你用的是公司内网环境clone GitHub 仓库前记得先把代理配好不然极容易卡在下载那一步。注意不同宿主的技能加载机制差异很大版本更新也快下面的步骤我以最常见的做法为准具体细节请以项目 README 的最新说明为准。不要把这篇博文当成永远不变的官方文档。3.2 两种常见安装方式方式一宿主支持插件机制以 Claude Code 为例。新版 Claude Code 有插件系统直接用命令行安装claude plugin install superpowers装完之后在对话界面里输入/应该就能看到 superpowers 相关的斜杠命令比如/superpowers、/thinking之类。这种方式最省事升级也方便适合绝大多数人。方式二手动把技能目录挂到宿主能读到的位置。如果你用的宿主暂时没有插件市场或者你想自己 fork 一份技能文件来改可以用手动安装。先把仓库 clone 下来git clone https://github.com/obra/superpowers.git然后把 skills 目录链接到宿主的技能加载位置。Claude Code 默认会读~/.claude/skills所以可以这样ln -s $(pwd)/superpowers/skills ~/.claude/skills如果你希望只在某个项目里启用就把技能目录放进项目的.claude/skills目录这样不同项目可以用不同版本的技能。手动安装的核心逻辑是搞清楚你的宿主从哪个目录读取技能文件然后让 superpowers 的 skills 目录出现在那里。理解了这一点你就不会因为换了个宿主就手足无措。3.3 验证安装是否成功装完之后别急着开干先花两分钟验证。在对话里直接输入/superpowers正常会列出可用的技能列表。如果宿主没有斜杠命令机制你直接问一句你现在能使用哪些技能请列出文件名和适用场景模型应该能报出一串名字。我更推荐用一个真实的小任务来验证。比如丢给它一个空模块说帮这个模块补一个测试然后观察它的行为。如果它会先跟你确认测试目标、再写失败用例、再跑测试那基本可以确定技能已经被加载并生效了。如果它直接开始噼里啪啦写实现说明技能文件没被正确加载回到 3.2 检查目录路径。3.4 Codex 里怎么用 superpowers热词里 codex superpowers 被问得很多因为 Codex CLI 没有 Claude Code 那样完整的插件市场很多人在这一步卡住。Codex 的约定是读项目里的 AGENTS.md 文件这个文件相当于给 AI 的项目工作手册。你可以这样操作第一步把 superpowers/skills 目录放进项目的某个路径比如.claude/skills或docs/skills路径本身不重要重要的是在 AGENTS.md 里写清楚位置。第二步在 AGENTS.md 里加上一段本项目启用 superpowers 技能框架。技能文件位于 .claude/skills 目录。 所有开发和修改任务先阅读技能列表然后按对应技能的步骤执行。第三步重启 Codex 会话让它重新读取 AGENTS.md。然后随便丢一个任务测试看它是否会先去翻技能文件。Codex 的加载方式不像插件那么自动化但反而更透明——你能清楚地看到 AI 是怎么理解你给它的规则手册的。如果你发现它不遵守多半是 AGENTS.md 里的描述不够强硬可以改成你必须先读取 xxx skill不得跳过其中任何步骤。3.5 Java 项目实战给 Spring Boot 服务加一个查询接口热搜词里有 superpowers java我特意用 Java 场景演示一遍因为 Java 项目往往对工程规范要求更高也更适合体现技能框架的价值。我本地有一个 Spring Boot 项目核心服务类长这样Service public class UserService { private final UserRepository userRepository; public UserService(UserRepository userRepository) { this.userRepository userRepository; } // 需要一个按邮箱精确查找用户的方法 }我直接在对话里说用 superpowers 的 TDD 技能给 UserService 加一个 findByEmail 方法邮箱不存在时抛 UserNotFoundException。随后 AI 开始按技能流程走。它先是跟我确认验收标准邮箱存在时返回用户对象邮箱不存在时抛 UserNotFoundException参数为空时抛 IllegalArgumentException。 确认完它先写了测试Test void findByEmail_shouldReturnUser_whenUserExists() { User user new User(aliceexample.com, Alice); userRepository.save(user); User found userService.findByEmail(aliceexample.com); assertThat(found.getEmail()).isEqualTo(aliceexample.com); } Test void findByEmail_shouldThrowException_whenUserNotExists() { assertThatThrownBy(() - userService.findByEmail(nobodyexample.com)) .isInstanceOf(UserNotFoundException.class); }然后跑测试确认它失败再写最小实现public User findByEmail(String email) { if (email null || email.isBlank()) { throw new IllegalArgumentException(email must not be blank); } return userRepository.findByEmail(email) .orElseThrow(() - new UserNotFoundException(email)); }最后再跑一遍测试全部通过。整个过程和没有技能时的差别很明显AI 不会跳步骤它从头到尾都知道自己要干什么也没出现那种写到一半开始自由发挥的毛病。Java 项目尤其适合这套玩法因为测试文化本来就是 Java 工程里绕不开的一环AI 主动帮你把测试补上后续合并代码时省很多沟通成本。3.6 如果宿主是 WordBuddy 这类集成工具也有朋友问worbuddy 怎么用 superpowers或者 WordBuddy 这类集成工具能不能用。这类工具本质上是把多个 AI 能力包了一层入口superpowers 对它们来说就是一套可挂载的技能集合。我的建议是先去工具设置里找技能目录或外部 Skills之类的配置入口然后把 superpowers/skills 的路径指过去。如果没有这个入口再看它支持不支持自定义指令通常在设置里叫 Custom Instructions 或 System Prompt把技能文件的加载规则写进去让模型每次启动时先读取技能列表。不过说实话如果你用的是这类工具说明你更看重开箱即用那 superpowers 的收益会被打一些折扣。它的优势是裸奔在终端里时带来的完全控制感集成工具层层封装反而会让技能的加载过程变得不可见出问题时不好排查。4. 常见问题与排查技巧实录4.1 装了技能但 AI 完全不按流程走这是最常见的坑。现象是技能明明装了但让它做任务时它还是老一套——直接给实现、跳过测试、也不问验收标准。优先检查这三件事看宿主工具版本。Claude Code 的技能机制是后面才加的如果你的版本太老斜杠命令可能根本不存在。看技能是否被加载。在对话里输入命令列出技能如果列表是空的说明目录没接上。看模型版本。太弱的模型即使读到了技能文件也可能执行不好建议使用 Claude 3.5 Sonnet 以上的模型或同等能力的模型。还有一个土办法直接把技能文件全文贴给 AI告诉它现在按这个技能的步骤执行我这个任务。如果这样它还不遵守那就是模型能力或版本问题如果这样能遵守说明是加载环节出了问题回 3.2 检查目录路径。4.2 技能目录加载失败手动安装最常见的问题是符号链接坏了或者路径写不对。clone 完之后先自己看一眼目录结构ls -la ~/.claude/skills如果发现是空的多半是软链没建成功。还有朋友 clone 到一半网络断了导致 skills 目录里缺文件也会表现为加载失败。这种情况重跑一次git clone或者git pull就好。Windows 下还要注意ln -s可能需要管理员权限或者改用 mklink。如果是在 Git Bash 里操作直接用ln -s通常没有大问题但在 CMD 或 PowerShell 里就得用不同的命令。4.3 多个项目之间技能版本打架如果你同时维护多个项目全局只放一份技能文件可能会出问题。比如 A 项目用 v1.0 的技能B 项目需要 v1.2 的新规则全局目录一更新所有项目跟着变。我的做法是全局目录只放最通用的技能项目目录放和当前项目强相关的技能然后在项目里锁版本。具体可以用 Git submodule 或者直接在项目里用单独的目录放一份 fork 出来的技能文件。这样做的成本是多一份文件收益是可控性。尤其团队协作时大家统一用项目里的技能版本才不会出现我的机器上 AI 会写测试你的机器上 AI 不写测试这种事。4.4 AI 生成的测试质量太差技能框架能保证流程但保证不了质量。如果 AI 写的测试都是为了通过而通过的写法比如断言一个函数返回了某个固定值但没有真正覆盖行为问题往往出在两处一是模型对业务理解不够二是技能里的验收标准不够具体。我的经验是在任务描述里把边界情况写清楚比如邮箱为空时是什么行为不存在时是什么行为“大小写敏感不敏感”。验收标准越明确AI 写的测试就越有针对性。别指望技能文件替你理解业务它是流程外套不是领域专家。4.5 常见问题速查表症状可能原因解决动作斜杠命令不存在宿主版本过旧或插件未启用升级宿主重装插件技能列表为空技能目录路径不对检查软链和目录结构AI 不遵守技能加载失败或模型太弱直接贴技能文本测试技能版本混乱全局和项目技能混用项目内单独锁版本测试质量差验收标准不明确在任务描述中补充边界情况Clone 到一半失败网络不稳定重跑 git clone 或 git pull我的建议是每次升级 superpowers 之前先把你 fork 出来的技能文件 diff 一下看看官方改了什么。不要盲目合并因为新规则很可能和你团队的现有流程冲突看清楚再动。我在自己项目里用得最多的其实是 brainstorming 和 TDD 两个技能。刚开始也会怀疑无非是一堆 Markdown凭什么让 AI 变强直到有一天我让 AI 为一个前端组件补测试它老老实实先写了一个渲染后出现错误提示的失败用例然后才写实现——那一刻我意识到模型缺的从来不是知识而是一套工作方法。superpowers 就是把老工程师脑子里的那套标准流程固化给 AI 的黏合剂。工具迭代很快功能边界一直在变但思路是通的。建议你装好之后别急着投入生产先把两三个技能文件从头到尾读一遍你会比 AI 更了解它自己。
阅读完成 · 觉得有帮助？
