第一次听说 superpowers 时我下意识以为是什么游戏模组或者励志课程的名字。直到在技术社区里反复看到“codex superpowers”“superpowers 使用教程”这些热词才意识到这其实是当前 AI 编程圈子里很热的一套技能增强方案。简单说superpowers 是一个专门为终端型 AI 编程助手准备的专业技能库里面把代码审查、重构、测试驱动开发、技术方案设计、文档生成这些日常开发动作包装成一份份结构化的技能文件让 AI 不仅能“听懂”你的命令还能按一套成熟的工作流程把事做完。它适合谁正在用 Claude Code、Codex 这类命令行编程工具的开发者或者已经在用 AI 写代码但总嫌输出不够专业的人以及想在团队里统一 AI 协作规范的技术负责人都值得抽一晚上把这套东西跑起来。1. 项目概览superpowers 到底解决什么问题1.1 AI 写代码的“行活”问题我先把一个比较普遍的场景放在前面。很多人刚开始用 AI 编程助手的时候都是这么玩的打开终端输入一句“帮我写一个用户登录接口”AI 确实能给你生成一段代码但这段代码往往是“行活”——能用但经不起推敲。比如没有异常处理没有参数校验没有日志埋点更没有单元测试。你让它重构一下它可能就把变量名改好看了逻辑还是那套逻辑。问题的根源不在模型能力而在使用方式。模型本质上是一个“极度顺从的实习生”你给它的指令越模糊它就越倾向于给出一个“看起来差不多”的答案。如果你指望每次都能通过灵光一现的提示词让 AI 输出架构合理、测试完备、文档齐全的高质量代码那基本是在碰运气。superpowers 这个项目的思路就是把“碰运气”变成“走流程”。它把 AI 可能参与的每一项开发任务都拆成了一份结构化的操作手册。比如“代码审查”这份技能它会要求 AI 先逐文件读取再按严重程度分级输出问题清单最后给出修改建议“测试驱动开发”这份技能则会强制 AI 先写失败测试再写实现代码最后运行测试确认变绿。每一步都有明确的输入、输出和验收标准。1.2 技能文件的组织方式从我实际用下来的感受看superpowers 的核心概念就是“Skill技能”。每个技能是一个独立目录里面通常包含三部分SKILL.md 是技能说明书描述这个技能适用于什么场景、具体步骤是什么、产出物是什么scripts 目录放一些辅助脚本references 目录放着参考资料比如代码规范、架构模板之类的。在安装层面Claude Code 会读取~/.claude/skills目录Codex CLI 会读取~/.codex/skills目录。superpowers 仓库本身就是按这个目录结构组织好的所以安装过程本质上就是把仓库里的内容复制到你的 skills 目录。这一设计让我这种喜欢折腾工具的人非常舒服——所有技能都是纯文本没有编译过程没有二进制依赖想改哪一步直接改 Markdown 就行。还有个很聪明的设计渐进式披露。所有技能安装后不会一股脑塞进 AI 的上下文窗口那样 token 消耗太大而且会让模型变得迟钝。实际机制是你在对话里提到某个技能名字时AI 才去读取对应的 SKILL.md。比如你输入“用 tdd 技能给我写一个订单模块”模型才知道去翻~/.claude/skills/tdd/SKILL.md然后按里面的步骤执行。这个设计对于 API 调用成本控制来说尤其重要。1.3 和“直接说需求”的本质区别我用一个简单类比来解释为什么技能文件有效。你公司里来了个新同事你每天直接给他说“把这个功能做一下”他大概率会按自己的想法做质量波动很大。但如果你给他一份《需求开发 SOP》规定了他要先写设计文档、再做技术评审、然后写测试、最后实现代码那他的输出就会稳定得多。superpowers 就是这份 SOP而且是用 Markdown 写的可以随时改。所以答案已经很明确了superpowers 本身并不“生产”代码它改变的是 AI 的工作方式。从“生成一段代码”升级为“执行一套开发流程”。这也是为什么社区里有人称它为“给 AI 编程助手装上肌肉记忆”。2. 安装与基础配置从仓库到能用的三步2.1 先确认你的 AI 工具版本和环境开始装之前先确认几件事。首先你用的是哪个工具。如果你用的是 Claude Code那主目录是~/.claude/skills如果你用的是 Codex CLI 这类 OpenAI 的命令行编程工具那对应目录是~/.codex/skills。我先以 Claude Code 为例因为这是目前技能体系最成熟的宿主环境。其次确认你的终端能正常执行 git 命令并且有权限写入用户主目录。这个要求不高绝大多数系统的默认环境都满足。唯一要注意的是如果你之前已经装过其他技能库先看一眼现有 skills 目录里有没有同名技能避免后面复制时互相覆盖。2.2 获取 superpowers 仓库并安装安装的常规路径是先克隆仓库到临时目录再把内容复制到 skills 目录。命令如下# 进入临时目录 cd /tmp # 克隆 superpowers 仓库 git clone https://github.com/crystal-lab/superpowers.git # 创建目标 skills 目录如果不存在 mkdir -p ~/.claude/skills # 复制技能内容 cp -R superpowers/skills/* ~/.claude/skills/如果你用 Codex CLI最后一条命令把目标路径换成~/.codex/skills/即可。有些版本的仓库自带安装脚本会在执行时询问“你要装到 Claude Code 还是 Codex”按提示选择就行。我更喜欢手动复制的方式因为我能清楚地知道每一步发生了什么排查问题的时候也更有底。装完之后检查一下目录结构ls -la ~/.claude/skills/正常情况下你会看到code-review、tdd、plan、refactor、documentation等一系列以技能名命名的子目录。每个目录下至少包含一个 SKILL.md 文件。如果只有一堆散落的文件没有按目录组织那技能是不会被识别的。2.3 验证安装是否生效目录结构对了不代表 AI 一定能读到。我建议做两个验证动作。第一个是重启你的 AI 工具会话因为大部分工具启动时会扫描一次 skills 目录运行中的会话不会自动发现新技能。第二个是问一句“你现在有哪些技能可用”如果工具正确加载了技能库它会列出已经识别的技能名称。如果它说“没有找到技能”那就回头检查目录位置是否正确、子目录下是否有 SKILL.md、文件名是否包含大写字母。这里有个容易踩的坑技能目录名不能有空格有些仓库里的技能名带空格复制到本地后要检查一遍尽量避免。一个额外的小建议如果你用的是 Codex直接把 superpowers 塞进 skills 目录只是第一步调用方式会有差异。我后面会单独用一节讲 Codex 场景的实操细节。3. 核心技能拆解我实际用得最多的几个能力3.1 plan开工之前先逼 AI 出方案我在所有 superpowers 技能里用得最多的就是plan。它的作用和“让 AI 先想清楚再动手”这句话一样但落地方式非常具体当你用 plan 技能下达任务时AI 不会直接给你代码而是先输出一份技术方案里面要包含需求理解、技术选型、任务拆分、风险点、验收标准最后会问你“确认后我再开始实现”。为什么这个设计有效因为大多数开发任务的失败都发生在目标不清晰的时候。你让 AI“写一个订单导出功能”它可能直接给你一个 Excel 导出的方法但没考虑数据量、查询性能、文件存储、权限校验。如果用 plan 技能AI 会在方案阶段就把这些问题列出来。我在实际项目里体验过一次后就再也没跳过这一步——哪怕是一个很小的改动让 AI 先花两分钟列个方案最后来回返工的次数都明显减少了。plan 技能的另一层价值是给人类一个“否决点”。AI 生成方案后你可以直接说“方案太复杂不要用消息队列”它就调整方向。这个交互模式和真实团队里的技术评审是一样的只不过评审对象变成了 AI。3.2 tdd让 AI 先写测试再写实现tdd技能是我从怀疑到真香转变最大的一个。最初我心想让 AI 写测试再写代码不就是多绕一道弯吗后来我试了一次发现它的价值不在于“测试优先”这个理念而在于它对 AI 输出质量的约束。具体执行时tdd 技能会要求 AI 先根据需求列出测试场景清单然后编写测试代码运行测试看到失败结果再进入实现阶段最后回头跑测试直到全部通过。这一套流程走完AI 生成的代码天然就有测试覆盖而且逻辑更紧凑。因为它在写实现的时候脑子里要同时满足测试里已经固化的边界条件。在 Java 项目里用这个技能尤其合适。Java 生态里 JUnit 5 和 Mockito 的组合本来就适合测试先行的方式。有一次我让 AI 给 Spring Boot 的支付回调接口写代码它先用 Mockito 模拟了支付服务接口然后写了几组边界测试包括签名错误、订单不存在、重复通知这些恰恰是我自己容易漏掉的场景。最后才给出 Controller 实现。那次体验让我认识到tdd 技能的价值不只是流程正确而是它逼着 AI 去思考“什么情况下会出错”这个问题。3.3 code-review把 AI 变成你的代码评审人code-review技能解决的是“AI 能看懂代码不一定能发现问题”的痛点。用过这个技能之后我才理解到评审和阅读是两种完全不同的操作。直接对 AI 说“帮我看看代码有什么问题”它倾向于给你一些泛泛的建议比如“代码风格不够统一”“可以考虑增加注释”。但 code-review 技能会强制它按一套标准流程走先逐文件读取分析业务逻辑然后按严重程度把问题分为阻断性、严重、一般、建议四个等级最后输出修改建议。我把这个技能用在两个场景上。一个是提交代码前让我生成的代码先过一遍“AI 评审”另一个是 review 团队同事的 PR 时先用 code-review 技能跑一遍把明显的问题找出来再人工复核。坦白说它不能完全替代人评审但在发现空指针风险、事务边界遗漏、资源未关闭这类确定性问题上表现得相当稳定。3.4 refactor不带心理负担的重构重构这件事对 AI 来说是逆来顺受的对开发者来说却常常伴随着恐惧——“万一改坏了呢”refactor技能的做法是先要求 AI 识别出重复代码、过长函数、不合理的命名然后分步骤重构每一小步都要保持行为不变并且明确建议在重构前后都运行测试。这个技能最适合处理那些“看着碍眼但不敢动”的老代码。我接手过一个遗留模块里面有个 300 行的方法逻辑深不可测。我让 AI 用 refactor 技能处理它出来的结果是一系列小步骤先提取私有方法、再消除重复分支、最后重命名变量每个步骤之间保持代码可编译。整个操作很像我手动重构的节奏但速度快得多。这一节想强调的实操心得是重构前务必确保有测试基线否则 AI 也无法判断行为有没有被改变。4. 在 Codex 和 Java 开发中的实战记录4.1 Codex 环境下的使用差异如果你最初是通过“codex superpowers”这个关键词了解到这个项目的那大概率想知道在 Codex CLI 里到底能不能用、怎么用。从我实测的结果看Codex CLI 在较新版本里已经支持了 skills 目录机制读取的是~/.codex/skills。所以安装步骤基本一致只是目标目录不同。真正有差异的是调用方式。Claude Code 里你直接说“用 plan 技能做某某事”模型通常能正确识别并读取对应技能。Codex 的表现略有不同它更依赖会话里明确触发。我第一次用 Codex 的时候安装了技能库之后直接发了一句“帮我设计方案”结果它完全没走技能流程。后来我把命令改成“请先读取 ~/.codex/skills/plan/SKILL.md然后按里面的步骤执行方案设计”它就很听话地按流程走了。在 Codex 里我的建议是把“技能名 明确指令”写在一起不要只靠技能名触发。比如“使用 tdd 技能为 UserService 写测试”比“写 UserService 测试”稳定得多。这种差异属于工具实现层面的习惯差异不算 bug但新人很容易在这里碰壁。4.2 在 Java 项目里跑通 plan - tdd - refactor 完整链路我拿一个真实的 Java 项目片段来说明这条链路怎么配合。假设现在要给一个订单服务增加“超时自动关闭”功能。第一步用 plan 技能。AI 输出的方案包含状态机设计、定时任务轮询还是延迟消息、异常订单的处理策略、是否需要幂等控制。方案确认后第二步用 tdd 技能。AI 会基于 Mockito 写测试模拟OrderRepository、OrderCloseService等依赖测试场景包括“订单已支付不处理”“订单已关闭不重复处理”“超时未支付则标记关闭”这几类。第三步在测试全绿后用 refactor 技能把重复的订单状态判断抽取成公共方法让主逻辑更清晰。这个流程走完代码质量和测试覆盖率都明显好于直接让 AI“写个订单关闭功能”。过程中我发现一个 Java 场景特有的事项要在提示词里主动告诉 AI 项目的构建工具和版本。比如“这是一个 Maven 工程使用 Java 21”否则它可能生成 Gradle 风格或者用了高版本 API 导致编译报错。superpowers 的技能是语言无关的但它没有读你项目文件的能力上下文得靠你补充。4.3 自定义技能让 superpowers 真正长在你的项目里用熟了之后你会开始不满足于仓库自带的那十几个技能想加一点自己团队的东西。比如我所在团队有《接口返回值规范》文档我就给它单独做了一个技能叫api-style。结构非常简单# 技能api-style ## 适用场景 编写或重构 Controller / API 接口时统一返回值结构。 ## 操作步骤 1. 读取项目内的 ApiResponse 类确认结构字段 2. 所有接口返回必须使用 ApiResponse.ok() 或 ApiResponse.fail() 3. 失败场景需输出错误码和用户可读提示语 4. 生成代码前先对照项目内 controller 示例 ## 交付物 符合团队规范的接口代码片段把这个目录放到~/.claude/skills/api-style/下重启会话就能用。自建技能的这个体验非常好——它不需要任何编程基础只要会写 Markdown就能把团队的开发规范变成 AI 的肌肉记忆。5. 常见问题与排查技巧实录5.1 技能不生效先按这个清单排查我把常见问题整理成了一个速查表基本都是我自己或者朋友踩过的坑现象大概率原因解决办法重启后 AI 说找不到任何技能skills 目录位置不对或者子目录下缺少 SKILL.md检查~/.claude/skills路径确认每个技能目录里都有 SKILL.md技能目录存在但 AI 不主动用会话是旧的没扫描到新技能重启会话或直接采用“读取 SKILL.md 再执行”的强指令方式AI 把 references 里所有文档都读了一遍token 烧得飞快没理解按需加载机制检查技能配置不要让 SKILL.md 引用过多文件保持渐进式披露Codex 里技能完全不理会Codex 更依赖明确指令在命令中写出技能文件路径并指示其读取后执行技能生成了但结果不稳定模型版本差异导致对流程遵循度不同在 SKILL.md 里写更细的步骤减少模型自由发挥空间这个表格可以当成排查手册来看遇到问题先对号入座。5.2 上下文过长和 token 消耗问题另一个我实际碰到的高频问题是上下文消耗。技能装多了之后AI 有时候会自作主张把多个技能拼接使用导致references目录里的内容被大量读取一轮对话没结束就烧掉上万 token。这个问题的根源在于技能定义里的“引用”写得太宽。我的建议是每个技能的 SKILL.md 里只保留最必要的步骤描述参考资料目录不要直接写“读取本目录所有文件”而是明确指定“仅当需要查询数据库设计规范时读取 references/db-standards.md”。这样能把 AI 的读取范围约束住。除了这种精细化控制如果用的是 API 调用方式还可以在系统提示词里写明“除非用户明确要求不允许读取 references 目录”。5.3 团队协作把 superpowers 变成团队资产最后分享一个团队落地的方案。如果你准备把这个技能库引到团队里不建议让每个人各自从 GitHub 拉仓库因为版本会很快漂移。更好的做法是 fork 一份仓库在内部维护把团队自己的技能也提交进去然后团队成员的 skills 目录直接同步内部仓库。我踩过的一个坑是某次升级 AI 工具之后版本对 skills 目录的扫描逻辑变了团队里几个同事的技能同时失效。排查了很久才发现是新版工具默认关闭了第三方技能读取需要在配置里显式开启。遇到这类问题先看工具更新日志里关于 skills 的变动比自己在配置里瞎试要高效得多。最后的实操心得如果你也想尝试我的建议是一次别装太多先用 plan、tdd、code-review 这三个技能跑两个真实需求感受一下流程差异。我最初犯的错误是把整个技能库一次性塞进去结果 AI 反而变得“选择困难”不知道优先用哪个技能。后来我精简到常用五个技能效果反而明显提升。另外技能文件本身是可以随意改的遇到某个技能输出风格不对你的胃口直接打开 SKILL.md 改描述。比如我觉得默认的 code-review 太温和就加了一条“问题描述要具体到文件和行号”之后输出质量立刻就变严格了。这一层可定制性才是 superpowers 真正的后劲所在——它不只是一个工具包更像一套可以长期迭代的 AI 工作方法论。