最近我把手里几个 AI 写代码的流程整个重构了一遍。起因很朴素我实在受不了每次让模型干活都要把同样的约束翻来覆去说三遍说少了它自由发挥说多了它又变复读机。后来在 GitHub 上翻到 obra 开源的 superpowers 项目才算找到一个真正能落地的解法。这东西不是插件不是独立 IDE更不是一个编程语言它就是一套给 Claude Code、Codex 这类命令行 AI 编程助手做“技能加载”的方案。核心是一堆可读、可改、可版本化的 Markdown 技能文件让助手在合适的时机自动翻出对应的做事流程而不是每次都在对话里临时现场发挥。这篇文章我会从设计思路讲到实际安装再到 Codex 环境适配和 Java 项目落地最后把我在真实项目里踩过的坑列出来。适合正在用 AI 写代码、但觉得它“没有章法、东一榔头西一棒子”的人参考。1. superpowers 到底是什么核心概念与设计思路拆解1.1 技能不是插件而是一套“操作手册”很多人第一次看到 superpowers 的仓库会愣住里面没有编译步骤没有守护进程也没有复杂的配置文件绝大多数内容就是一层一层的 Markdown 目录。初次使用的人会问这也能叫“技能”但恰恰是这种“笨办法”让它变得异常可靠。传统插件的工作方式是给编辑器加按钮、加命令、加右键菜单。superpowers 的思路完全反过来它给 AI 助手提供一张“什么时候该干什么事”的流程图。每个技能对应一个目录目录里是带 YAML frontmatter 的 SKILL.md 文件。frontmatter 里写技能的名称和描述正文里写具体的工作流。AI 助手在对话过程中会读到这些描述觉得当前任务跟我这个技能匹配就自己把这份操作手册“翻开”照做。我用一个生活类比解释普通插件像是给厨师配了一把专用的刀superpowers 更像是给厨师一本菜谱。菜谱不会替你切菜但它能保证你每次做的步骤一致、火候一致、起锅时机一致。对于 AI 编程这件事“流程一致”比“工具更多”重要得多。1.2 三个设计原则人主导、分角色、可追踪superpowers 的整个设计建立在三个原则上理解这三点就能明白它为什么好用。第一是“人主导AI 执行”。它默认 AI 不是自主的天才而是配合度极高的执行者。大的方向、需求和验收标准永远由人来定AI 负责把大方向拆解成步骤、把步骤写成代码、把代码跑出测试结果。这个定位避免了 AI 最常见的毛病——自作主张改需求、换架构、动无关文件。第二是“分角色协作”。superpowers 本身不只是一个技能包它还配套了一套 subagents子代理配置类似“架构师”“实现者”“研究员”这些虚拟角色。实际运行时AI 会按任务性质把活儿派给不同角色。这看起来像玄学但体验过就知道差别同一个任务让“架构师”先输出方案再由“实现者”按方案写代码比一个角色边想边写要稳得多。第三是“过程可追踪”。因为技能是纯文本的每一步怎么走都在 Markdown 里写得清清楚楚。AI 每次产出计划、测试、代码都能对应回技能的某一小节。出了问题你可以直接打开 SKILL.md 看是哪个环节没执行到位而不是对着聊天记录猜。2. 安装与初始化从零开始把它跑起来2.1 前置条件与版本要求在动手之前先确认环境。superpowers 主要服务的是 Claude Code 和 Codex CLI 这类命令行编程助手所以最小依赖是已安装 Node.js 18 以上版本并确认node -v能正常输出已安装并初始化好 Claude Code 或 Codex CLI能正常启动交互式对话本机有 git安装脚本要拉取仓库我建议把 Claude Code 升级到当前最新版因为技能加载机制在老版本上表现不稳定尤其是带子代理的技能旧版本经常出现角色配置不生效的情况。Codex CLI 同理太老的版本对 AGENTS.md 和 skills 目录的支持不完整。2.2 克隆仓库并执行安装脚本安装过程非常简单我直接贴命令git clone https://github.com/obra/superpowers.git cd superpowers ./install.sh脚本会自动把技能文件复制到你当前用的编程助手能读取的本地目录。对 Claude Code 来说默认位置是~/.claude/skills/。装完之后你去看一眼这个目录ls ~/.claude/skills/正常情况下你会看到 brainstorming、writing-plans、test-driven-development、debugging 等一批子目录每个目录里都有 SKILL.md。看到这些文件安装就算成功了。顺带说一句这个项目也支持以插件市场的方式安装。如果你用的是 Claude Code可以直接在交互式终端里输入/plugin marketplace add obra/superpowers-marketplace然后按提示把插件启用。两种安装方式的区别在于脚本方式更朴素适合想要自己改技能文件的人插件方式更干净卸载升级都方便。我个人习惯用脚本装因为我会改不少内部流程插件方式每次升级都会把我的改动覆盖掉。2.3 验证安装是否真正生效的“土办法”装完之后怎么确认 AI 真的加载了技能最直接的办法是开一个新的对话随便丢一句话比如“帮我看看当前项目有哪些可以优化的点”。如果 AI 开始主动用 brainstorming 技能的思路来回应问你目标的背景、约束、验收标准而不是直接甩一段优化清单说明技能已经生效了。另一个更狠的测试是直接问“你现在能读取哪些 skill说出它们的目录结构和用途。”如果它能精确说出~/.claude/skills/下的目录名说明加载链路是通的。如果它支支吾吾甚至说“我没有技能”那大概率是目录放错了位置或者编程助手没有开启技能读取功能。3. 核心技能逐个拆解brainstorming、writing-plans、TDD 的实战意义3.1 brainstorming把“模糊想法”逼成“明确需求”brainstorming 这个技能我一开始是当鸡肋看的。AI 做头脑风暴那不是脱裤子放屁吗但用了之后才知道它解决的问题不是“AI 没有想法”而是“人没有把想法说清楚”。这个技能的工作流是强制先提问再回答。AI 不会上来就给你方案列表而是一步一步问你你是不是想解决某个具体问题这个问题目前的约束是什么你能接受哪些取舍等你回答完了它会把对话里的碎片信息整理成一份需求描述再跟你确认。确认通过之后才进入方案发散阶段。我实际感受最明显的一个场景是个人工具类项目。以前我直接跟 Claude 说“帮我写一个批量重命名文件的脚本”它三分钟交活但经常漏掉“要保留原有扩展名”“大小写要统一”“遇到重名要跳过”这些隐含条件。用 brainstorming 技能之后它会在动手前把这几个问题全部问到。虽然前期多花了两分钟对话但后期改代码的时间省回来十倍不止。3.2 writing-plans把方案拆成可执行的颗粒度brainstorming 结束之后紧接着要用的就是 writing-plans。这个技能的职责是把确认好的方案转成一份分步执行计划每一步都要写清楚“做什么”“涉及哪个文件”“怎么验证完成”。这里有个很容易被忽略的设计计划不是给人看的文档而是给 AI 自己执行的“任务清单”。所以它天然要求颗粒度足够细。比如写“优化登录模块”等于没写但写“把 authService.login 方法拆成 validateParams、checkCredentials、generateToken 三个函数单测覆盖前两个”就是合格的计划。如果你自己也在写这类技能文件我建议在计划模板里强制加上“完成标准”这一栏。没有完成标准的计划AI 执行完一步之后很容易不知道下一步该干什么或者自以为干完了就进入下一阶段。3.3 test-driven-development用红绿灯流程管住 AI 的手在所有技能里test-driven-development 是我最推崇的一个也是 superpowers 最出圈的技能。它的核心逻辑就是工程师都懂的 Red-Green-Refactor 循环但神奇的是这套循环放在 AI 身上同样成立甚至更管用。具体执行时AI 会先根据计划写出测试代码然后跑一遍确认它是失败的红灯再写最小实现让测试通过绿灯最后做重构保持行为不变。关键一点在于这个顺序被技能文件写死AI 不能跳过红灯直接写实现。我试过让 AI 用它开发一个简易的文件监听工具它老老实实地先写了三个失败测试再一点一点把实现补到位。整个过程没有出现“自以为正确其实根本没跑过”的情况这在不用技能的时候几乎不可能。我后来复盘为什么 TDD 对 AI 这么有效AI 在没有约束时会走“最快给出像样答案”的路径而像样和正确是两回事。测试就是那个“正确”的硬标准AI 没办法糊弄一个失败的测试用例。给 AI 写代码的过程加测试护栏本质上是在给它装刹车。3.4 辅助技能debugging、commit 这些容易忽略的细节除了上面三个主力技能superpowers 还带了一批辅助技能其中最常用的两个是 debugging 和 commit。debugging 的结构化排障流程让我印象很深。它在处理 bug 时会强制按四步走先稳定复现再缩小排查范围然后用二分定位可疑代码最后修复并回归验证。这里真正的难点不是修复本身是“稳定复现”。AI 默认行为是看到报错就猜原因然后直接改这十次里有八次改不对。有了 debugging 技能之后它首先会拉长焦距让我提供复现步骤甚至让我把报错堆栈里出现次数最多的那一行先圈出来。这种“先搞清楚敌人是谁再开枪”的做事方式用在 AI 身上反而比用在人身上更有必要。commit 技能则负责生成符合规范的提交信息。它不搞花活就是按 type、scope、subject 的格式从 diff 里提取要点。用了它之后我的项目历史干净很多回滚的时候也敢直接看提交信息决定 revert 哪一条。4. Codex 环境适配codex superpowers 的具体配置方式4.1 为什么 Codex 也能用同一套技能很多人在网上搜“codex superpowers”其实是在问superpowers 不是给 Claude Code 写的吗能不能让 OpenAI 的 Codex CLI 也用答案是可以原理并不复杂。Claude Code 和 Codex CLI 这类工具的底层逻辑是一样的它们都是让大模型在一个终端环境里理解自然语言指令然后执行读文件、写文件、跑命令这些动作。superpowers 之所以能在 Claude Code 上生效靠的是技能文件被放在模型能读取的目录下。Codex CLI 同样支持通过 AGENTS.md 之类的指令文件来注入规则所以只要把技能目录指到 Codex 能读到的位置规则就成立了。社区里最常见的做法是软链接。假设你已经在~/.claude/skills/里装好了 superpowers那么在 Codex 的用户目录下建一个指向它的链接即可mkdir -p ~/.codex ln -s ~/.claude/skills ~/.codex/skills然后在你的项目根目录或用户全局目录写一份 AGENTS.md里面加一段说明明确告诉 Codex你可以在~/.codex/skills/里找到技能当任务匹配技能描述时先读取对应 SKILL.md 再执行。把这个说明写进去之后Codex 在处理任务时会主动去寻找技能。初次接入建议先测试一个简单任务比如让 Codex 用 brainstorming 技能和你确认需求验证它是否会先脚本化提问。4.2 双环境共存时要注意的路径问题如果你同时用 Claude Code 和 Codex我的建议是不要让两边的技能目录各自维护一份。因为 superpowers 升级比较频繁每次拉新版都要同步两份很麻烦。用软链把两边的目录指到同一份是维护成本最低的方案。但这里有个坑软链方式依赖 Codex 对技能目录的读取逻辑。如果 Codex 后续版本改了目录规则软链可能静默失效。我的排查方法很简单直接问 Codex“你有 superpowers 的哪个技能把 brainstorming 的技能描述念给我听。”如果它能准确念出来链路就通如果它答非所问优先检查 AGENTS.md 的写法再看软链的目标路径是否正确。定向检查比重新安装靠谱得多。5. Java 项目实战superpowers 在真实工程里的落地流程5.1 准备工作与项目脚手架搜“superpowers java”的人多半是想知道这套技能在 Java 这种偏重型、强类型、构建链路长的项目里能不能用。我的答案是能但准备工作比脚本语言要繁琐一点。我用一个基于 Maven 的标准 Java 项目举例。首先确保本机有 JDK 17 和 Maven然后用模板先把项目骨架搭起来mvn archetype:generate \ -DgroupIdcom.example \ -DartifactIddemo \ -DarchetypeArtifactIdmaven-archetype-quickstart接着把 JUnit 5 的依赖写进 pom.xml确认mvn test能跑出一个空的成功结果。很多人在这一步会偷懒觉得反正 AI 会写代码测试环境晚点配也行。但 superpowers 的 TDD 技能默认会大量执行测试命令如果测试跑不起来AI 会被卡在红灯阶段反复报错。所以先把测试链路打通是使用这套工作流的前提。5.2 从 brainstorming 到 TDD 的完整流程演示我在这个 Java 项目上实际跑过一遍完整流程目标是写一个简单的字符串压缩工具类。过程如下。第一步用 brainstorming 技能确认需求。AI 问我空字符串怎么处理连续字符超过字典上限怎么办输出格式是“字符次数”还是“次数字符”这些问题如果不提前定后面实现必定返工。第二步用 writing-plans 技能生成计划。计划里明确写了要在src/main/java/com/example/StringCompressor.java里实现核心方法同时在src/test/java/com/example/StringCompressorTest.java里写五个针对性用例包括空串、单字符、普通重复、全串不重复、超出计数上限这五种情况。第三步进入 TDD 循环。AI 先写测试并执行mvn test确认红灯再写最小实现跑到绿灯最后做重构时去掉一个不必要的中间变量。我当时盯着终端看整个过程最大的感慨是它每一步都卡得很死没有自作聪明地跳过测试直接“顺手优化”。第四步让 AI 用 commit 技能提交代码。提交信息清晰地写成feat: add StringCompressor with run-length encoding完全没有我讨厌的那种“update code”式废话。5.3 Java 场景下的三个独有注意点用 superpowers 做 Java 项目有三个注意事项是脚本语言场景里遇不到的。第一AI 在写测试时容易把测试框架版本和实际 classpath 搞混。如果mvn test报出No tests found别急着怪技能先检查 JUnit 版本是否是 5并确认maven-surefire-plugin版本足够新。第二Java 的编译错误信息很长很吓人AI 有时会对着编译错误反复“盲改”。这时候把它切换到 debugging 技能强制先缩小范围通常比一头扎进修复快得多。实际操作时我会直接说“用 debugging 技能处理这个编译失败”它就会停下来先让我确认复现条件再逐层分析。第三Maven 下载依赖慢会严重影响 AI 的耐心。它不是人不会烦躁但它会把超时的网络请求当成环境错误误判为代码问题。我建议在项目里配好 maven 镜像或者提前执行一次mvn dependency:go-offline把依赖拉全再开始用技能流程能少很多无谓的“诊断”。6. 第三方客户端的使用姿势与常见问题速查6.1 不用官方终端用第三方客户端也能接入搜“worbuddy 怎么用 superpowers”这类问题的朋友大概率不是直接用官方 CLI而是用了某个封装了 Claude Code 或 Codex 能力的第三方客户端。不管客户端叫什么名字接入的思路是通用的。这类客户端本质上还是在调底层大模型只要它保留了“读取用户目录配置”的能力superpowers 就依然能生效。你需要做的只是两件事第一确认客户端确实读取了~/.claude/skills/或你指定过去的软链目录第二在客户端的全局指令配置里加一句类似“当任务匹配技能时读取对应 SKILL.md 并按流程执行”的描述。很多客户端在设置界面里都有“自定义指令”或“角色提示词”的入口把这段话说清楚效果和官方终端几乎一致。如果你用的客户端不支持读取本地技能目录那我只能说声遗憾了。这种时候不妨退一步思考你需要的不是 superpowers 这个名字而是它提炼出来的“先确认需求、再写计划、再写测试、再实现”的流程。你完全可以把这个流程用网上的生成式提示词模板写进客户端的自定义指令里拿到七成的效果。工具是死的流程是活的。6.2 高频问题排查速查表我把自己使用过程中遇到过的典型问题整理成了一张表遇到同类情况可以直接对着查。现象可能原因处理方式对话里 AI 完全不理技能直接给出方案技能目录没有被加载检查~/.claude/skills/是否存在确认安装脚本执行成功技能描述能念出来但不按流程执行编程助手版本过旧升级 Claude Code / Codex CLI 到最新版执行 TDD 时不停请求跑测试但测试命令报错测试框架或构建工具配置残缺先手动跑一次测试命令确保红灯绿灯链路顺畅Codex 环境里提示找不到技能软链断开或 AGENTS.md 缺少说明检查软链目标确认能直接读到 SKILL.md技能文件被升级覆盖自己的改动丢了升级方式选成了覆盖式改成用插件方式安装或者把自定义改动单独放一个目录第三方客户端里技能完全不生效客户端没有读取本地技能目录改用全局自定义指令手写流程或用编辑器插件的“规则文件”功能6.3 更新、卸载与保留个人改动的技巧最后说两个维护层面的技巧。更新 superpowers 很简单。脚本安装的话回到仓库目录执行git pull然后再跑一次./install.sh覆盖旧文件。插件安装的话在客户端里执行插件的 update 命令即可。但如果你像我一样改过内部技能流程覆盖式更新会把所有改动冲掉。我的做法是需要改动的技能先在目录里复制一份改个名字再编辑技能描述里注明是新版这样升级后原来的定制版本还在不会冲突。卸载则更简单把~/.claude/skills/下对应的目录删掉或者移除插件的 marketplace 引用。因为它是纯文本文件没有任何服务需要停止也不会有残留进程。我实际用下来的体会是superpowers 的真正价值不在于它提供的某一个技能多聪明而在于它把 AI 写代码这件事从“对话式猜谜”变成了“流程化施工”。它不试图让 AI 变得更聪明而是让 AI 变得更稳。我踩过几次坑之后也逐渐明白一件事对大多数项目来说一个能力平庸但每一步都走对流程的助手比一个能力很强但完全不可控的助手可靠得多。如果你也想让你的 AI 助手从“想到哪写到哪”变成“按套路出牌”这套技能值得花一个下午装上试试。往后再开新项目我建议你从第一个需求对话起就打开 brainstorming 技能养成流程化习惯后面会少走很多弯路。