superpowers 实战指南：用 skills framework 约束 Claude Code 与 Codex CLI 的 AI 编程行为

1. 从“装完就吃灰”说起：superpowers 到底解决了什么问题

装过 Claude Code 或者 Codex CLI 的人，大概率都经历过同一个心理曲线：刚跑通那会儿觉得“这东西真神”，用了两周之后发现它开始胡说八道，改一个函数顺手把隔壁模块删了，让它写测试它给你写了个永远返回 true 的断言。问题不在于模型不行，而在于你只给了它一个裸的对话窗口，没给它任何“工作纪律”。

superpowers 就是冲着这个痛点来的。它本质上是一套agentic skills framework，翻译成人话就是“给 AI 编程助手装上的一整套技能包和行为规范”。你可以把它理解成给一个刚入职的实习生发了一本《团队开发手册》——告诉他先读需求再动手、改代码前先看上下文、写完必须自测、提交前要过检查清单。superpowers 把这些“手册条目”做成了可安装、可组合、可复用的 skill 模块，挂载到 Claude Code 或 Codex CLI 这类命令行 agent 上。

它解决的核心问题有三个。第一是行为一致性：同一个任务，今天让它做和明天让它做，输出质量天差地别，因为纯靠 prompt 约束太脆弱。第二是上下文管理：大型项目里 agent 容易“看一半就开干”，superpowers 通过结构化的 skill 强制它先做信息收集。第三是可复现性：团队里每个人用的 agent 行为不一样，导致代码风格和流程混乱，skills framework 让整个团队的 agent 行为对齐到同一套标准。

适合谁来用？如果你只是偶尔让 AI 帮你写个正则、改个报错，那没必要折腾。但如果你已经把 Claude Code 或 Codex CLI 当成日常开发的主力工具，每天要它处理多文件改动、跨模块重构、写测试、跑 CI 这类正经活儿，那 superpowers 带来的收益是肉眼可见的。尤其是团队协作场景，一套统一的 skills 配置能让所有人的 agent 输出质量拉到同一条线上。

我自己的体感是：裸用 Claude Code 大概能发挥它 40% 的能力，挂上 superpowers 之后能到 75% 以上。剩下的 25% 取决于你的项目结构、文档质量和模型本身的边界。这个提升幅度，值得花一个下午把它配好。

2. 核心机制拆解：skills framework 是怎么“管住”AI 的

2.1 skill 的本质：不是插件，是行为约束层

很多人第一次接触 superpowers 会误以为它是某种插件市场，装一堆功能扩展。其实不是。一个 skill 的核心不是“增加能力”，而是“约束行为”。它更像是一份写给 agent 的 SOP（标准作业程序），里面定义了：什么情况下触发、触发后按什么步骤执行、每步的输入输出是什么、什么条件下必须停下来问人。

举个具体的例子。一个“代码修改”类的 skill，它内部可能长这样：先要求 agent 读取目标文件的完整内容而不是片段，然后要求它列出所有受影响的调用点，接着要求它在修改前输出一份变更计划，最后要求它修改后自己跑一遍 lint 或测试。这一串动作，如果没有 skill 约束，agent 大概率会跳过前三步直接改代码——然后你就收获了一个“改对了但改崩了别处”的经典事故。

所以理解 superpowers 的第一层，就是理解它把“资深工程师的肌肉记忆”显式化了。老手改代码之前会下意识地看依赖、看调用方、看测试覆盖，新手不会。agent 默认就是新手，skill 就是把它训练成老手的那套规矩。

2.2 为什么选 Claude Code / Codex CLI 作为宿主

superpowers 本身不是一个独立的 CLI 工具，它是挂载在现有 agent 运行时上的。目前主流的两条路线就是 Claude Code 和 Codex CLI。这两个宿主各有特点，选择哪个取决于你的工作流。

Claude Code 的优势在于它的 skill 机制相对成熟，支持通过配置文件挂载自定义 skill，而且它的上下文窗口管理做得比较细腻，适合处理大型代码库。Codex CLI 的优势在于它和 OpenAI 生态的衔接更顺，如果你本身就在用 GPT 系列模型做开发，迁移成本低。两者都支持在终端里直接操作文件系统、跑命令、读 git 历史，这是它们能承载 superpowers 的前提。

选宿主的逻辑其实很简单：你日常用哪个模型写代码多，就用哪个宿主。superpowers 的 skill 定义本身是相对模型无关的，虽然不同模型对同一份 skill 的执行效果会有差异，但框架层面是通用的。我见过有人两边都配，根据任务类型切换，这也完全可行。

2.3 安装路径的差异：npm 全局 vs 项目本地

superpowers 的安装方式直接影响它的作用范围，这是很多人踩坑的地方。全局安装（比如通过 npm 全局包或者放到用户级配置目录）意味着你所有项目都会加载这套 skills，好处是省事，坏处是不同项目的技术栈差异大，一套 skill 未必通用。项目本地安装则是把 skill 配置放在项目仓库里，跟着代码走，团队拉下来就有一致的 agent 行为。

我的建议是混合策略：把通用的、和具体技术栈无关的 skill（比如“改代码前先读上下文”“提交前自检”）放在全局，把和项目强相关的 skill（比如“这个项目的测试怎么跑”“这个项目的目录规范”）放在项目本地。这样既保证了基础行为一致，又允许项目定制。

注意：项目本地的 skill 配置一定要提交到 git，否则团队里只有你一个人享受到了约束，其他人的 agent 还是野生的，协作时照样乱。

2.4 skill 的触发机制：自动 vs 手动

skill 的触发方式有两种。一种是自动触发，agent 根据当前任务类型自己判断该用哪个 skill；另一种是手动触发，你在 prompt 里显式点名要用某个 skill。自动触发体验好但不可控，手动触发可控但需要你记得用。

实际用下来，最稳的模式是“关键流程手动点名 + 日常操作自动触发”。比如你要做一次跨模块重构，这种高风险操作就手动指定重构相关的 skill，确保 agent 走完整流程。日常的小修小补就让它自动判断，不用每次都干预。superpowers 的 skill 定义里通常会写明触发条件，你可以根据这些条件来设计自己的使用习惯。

3. 从零到跑通：完整安装与配置实操

3.1 环境准备：先把宿主装明白

在装 superpowers 之前，你得先有一个能跑的 Claude Code 或 Codex CLI。这一步看起来简单，但实际卡住的人不少，尤其是国内网络环境下。

Claude Code 的安装，官方推荐的方式是通过 npm 全局安装。你需要先确保本机有 Node.js 环境，版本建议 18 以上。装完之后在终端里跑claude命令，如果能进入交互界面就说明宿主 OK 了。如果提示找不到命令，大概率是 npm 全局 bin 目录没加到 PATH 里，这个在 Windows 上尤其常见。

Codex CLI 的安装类似，也是通过包管理器。Windows 用户如果遇到unable to locate the codex cli binary or required runtime components这类报错，通常是运行时依赖没装全，检查一下 Node 版本和系统架构（x64 vs arm64）是否匹配。Ubuntu 用户相对省心，apt 和 npm 配合基本不会出幺蛾子。

提示：安装宿主时优先用官方文档给的命令，别去第三方教程里抄那些来路不明的安装脚本。版本不匹配导致的诡异问题，排查起来非常耗时。

3.2 superpowers 的安装：三条路径对比

superpowers 的安装目前主要有三种方式，我按推荐度排序。

第一种是包管理器安装，如果你的宿主支持通过 npm 或类似机制加载 skill 包，这是最干净的。一条命令搞定，升级也方便。缺点是包管理器里的版本可能滞后于仓库最新版。

第二种是手动克隆仓库。把 superpowers 的 skill 定义仓库 clone 到本地，然后在宿主的配置里指向这个目录。这种方式最灵活，你可以随时改 skill 定义、加自己的 skill，也方便跟进最新改动。缺点是需要你手动管理更新。

第三种是项目内嵌。直接把需要的 skill 文件复制到项目仓库的特定目录下，跟着代码走。这种方式适合团队统一，但更新时要每个项目单独改。

我自己的选择是手动克隆到用户目录，然后在每个项目的配置里引用。这样一份 skill 定义可以服务多个项目，改一处全局生效，同时项目层面还能覆盖特定 skill。

3.3 配置文件怎么写：一个可抄的模板

superpowers 的配置核心是告诉宿主“去哪里找 skill”以及“哪些 skill 启用”。不同宿主的配置格式不一样，但逻辑相通。以 Claude Code 为例，通常是在用户级或项目级的配置文件里加一段 skill 路径声明。

一个典型的配置结构大概是这样：先声明 skill 根目录，然后列出启用的 skill 名称或通配符。有些实现还支持给 skill 传参数，比如指定测试命令、指定代码风格规则等。这部分的具体字段名要以你用的版本为准，但思路是固定的——路径 + 启用列表 + 可选参数。

配置写完之后，一定要验证。最直接的验证方式是启动宿主，问它“你现在加载了哪些 skill”，看它能不能正确列出来。如果列不出来，说明路径配错了或者格式不对。另一个验证方式是故意触发一个 skill 的条件，看 agent 的行为有没有变化。

注意：配置文件里的路径尽量用绝对路径，相对路径在不同工作目录下启动宿主时容易解析错误，这个坑我踩过不止一次。

3.4 验证安装是否成功：三个检查点

装完之后别急着上生产任务，先做三个检查。

第一，skill 列表检查。让 agent 输出当前加载的 skill 清单，确认数量和你预期一致。少了说明路径或启用配置有问题。

第二，单 skill 触发检查。挑一个行为特征明显的 skill，构造一个能触发它的任务，观察 agent 是否按 skill 定义的步骤走。比如一个“先读后写”的 skill，你就看它改代码前有没有先读文件。

第三，冲突检查。如果你装了多个 skill，要确认它们之间没有行为冲突。比如两个 skill 都要求“修改前输出计划”，但格式要求不同，agent 可能会混乱。这种情况要么合并 skill，要么调整触发优先级。

这三个检查跑完，基本就能确认 superpowers 在你的环境里正常工作了。

4. 实战场景：superpowers 在真实开发里怎么用

4.1 场景一：跨文件重构不再“改一处崩三处”

跨文件重构是裸 agent 最容易翻车的地方。你让它把某个函数的参数从位置参数改成关键字参数，它改了这个函数定义，改了直接调用点，但漏掉了通过*args间接传参的地方，也没注意到有个测试文件里 mock 了这个函数的签名。结果就是代码看着改完了，一跑测试红一片。

挂上 superpowers 之后，一个合格的重构 skill 会强制 agent 走这样的流程：先用搜索工具找出所有引用点（包括间接引用），然后分类列出直接调用、间接调用、测试 mock、文档示例，接着输出一份变更清单让你确认，确认后才逐个修改，最后跑测试验证。这个流程比人肉重构还严谨，因为 agent 不会因为“觉得差不多了”就跳过搜索步骤。

我实测过一个中等规模的重构任务，涉及 7 个文件、23 处引用。裸 agent 第一遍漏了 4 处，第二遍补了 2 处又引入 1 个新 bug。挂 skill 之后一遍过，虽然耗时多了大概 30%，但省下了来回排查的时间，净收益是正的。

4.2 场景二：让 agent 写测试，而不是写“假测试”

让 AI 写单元测试，最大的问题是它倾向于写“能过但没意义”的测试。比如断言一个函数返回了非 null，或者 mock 掉所有依赖然后断言 mock 被调用了。这种测试覆盖率数字好看，实际一点用没有。

superpowers 里针对测试的 skill 会约束几件事：要求 agent 先读被测函数的实现，理解它的分支逻辑；要求测试覆盖每个分支而不是只测 happy path；要求断言具体值而不是模糊的存在性；要求不 mock 被测逻辑本身。这几条约束下去，写出来的测试质量明显不一样。

具体操作上，你可以在 prompt 里显式点名测试 skill，然后给出被测文件路径。agent 会先输出一份测试计划，列出它打算覆盖哪些分支、用什么输入、期望什么输出。你审一遍计划，觉得没问题就让它写。这个“先计划后执行”的模式，是 superpowers 相比裸 agent 最大的行为差异之一。

4.3 场景三：接手陌生代码库时的“侦察”流程

新加入一个项目，面对几十万行陌生代码，裸 agent 很容易迷失。你问它“这个功能在哪实现的”，它可能给你一个看起来合理但实际错误的答案，因为它只读了几个文件就开始猜。

superpowers 里的代码库侦察类 skill 会强制 agent 做系统性探索：先读 README 和目录结构，再读入口文件和路由配置，然后顺着调用链往下追，每追一层就记录关键文件和函数。这个过程它会输出一份“代码地图”，你可以基于这份地图继续追问。虽然慢，但准确率高得多。

这个场景下我常用的做法是：先让 agent 用侦察 skill 生成一份项目结构说明，然后我人工核对一遍，把错误的地方纠正掉，再让它基于修正后的理解去回答具体问题。这样相当于给 agent 建立了一个准确的“心理模型”，后续所有回答都建立在这个模型上，而不是每次重新猜。

4.4 场景四：把 skill 用在非编码任务上

superpowers 虽然主要面向编码，但它的 skill 机制是通用的。我试过用它来约束 agent 做技术文档写作、做需求分析、甚至做会议纪要整理。核心思路是一样的：把“好文档的标准”写成 skill，让 agent 按标准执行。

比如写技术文档的 skill 可以约束：先列大纲再写正文、每个概念先定义再使用、代码示例必须可运行、避免“显然”“简单”这类主观词。这些约束对输出质量的提升，和编码场景是同一个道理。所以别把 superpowers 局限在写代码上，它的本质是“行为约束框架”，能约束的行为远不止编码。

5. 踩坑实录：那些文档里不会写的问题

5.1 skill 不生效的排查顺序

skill 装了但没反应，是最常见的问题。排查顺序建议这样走：先确认宿主版本是否支持 skill 机制（老版本可能不支持），再确认配置文件路径是否正确（绝对路径优先），然后确认 skill 文件格式是否符合宿主要求（YAML 头、字段名等），最后确认触发条件是否满足（有些 skill 只在特定任务类型下激活）。

我遇到过一次诡异的情况：skill 文件本身没问题，路径也对，但就是不生效。最后发现是文件编码问题，skill 文件存成了带 BOM 的 UTF-8，宿主的解析器把 BOM 当成了内容的一部分，导致 YAML 头解析失败。改成无 BOM 的 UTF-8 就好了。这种问题文档里不会写，只能靠排查经验。

5.2 多个 skill 打架怎么办

当你装了十几个 skill 之后，冲突几乎不可避免。典型表现是 agent 行为变得犹豫，或者输出格式混乱，因为它同时收到了多个 skill 的指令，而这些指令之间有矛盾。

解决办法有两个。一是分层：把 skill 分成基础层和场景层，基础层永远生效，场景层按任务类型激活，避免同时激活太多。二是合并：如果两个 skill 经常一起用且指令有重叠，干脆合并成一个，消除矛盾。

提示：skill 不是越多越好。我现在的配置里常驻 skill 不超过 8 个，场景 skill 按需加载。装太多反而拖累 agent 的判断力。

5.3 上下文窗口被 skill 吃满

skill 定义本身要占上下文。如果你装了太多 skill，或者某个 skill 写得特别长，agent 的可用上下文就被压缩了，处理大文件时容易“失忆”。

优化方向：精简 skill 定义，把冗长的说明改成简洁的规则条目；把不常用的 skill 改成按需加载而不是常驻；对于超长 skill，拆成多个小 skill 按流程阶段加载。我见过有人一个 skill 写了三千字，结果 agent 每次启动先吃掉一大块上下文，得不偿失。

5.4 更新 skill 后行为突变

skill 仓库更新后，行为可能和你预期的不一样。这时候别急着回滚，先看更新日志，理解改了什么。如果确实是破坏性变更，可以在项目本地覆盖那个 skill，锁定到你验证过的版本。全局 skill 跟最新，项目 skill 锁版本，这个策略能兼顾尝鲜和稳定。

5.5 常见问题速查表

6. 进阶玩法：把 superpowers 改造成你自己的框架

6.1 写第一个自定义 skill

自定义 skill 没想象中难。一个最小可用的 skill 通常包含三部分：触发条件（什么任务类型下激活）、执行步骤（按顺序做什么）、输出要求（产出什么格式）。你把这三点用清晰的条目写出来，就是一个 skill 的雏形。

写的时候有个原则：规则要可判定。别写“写出高质量的代码”这种没法验证的话，要写“每个函数不超过 50 行”“所有公共方法必须有类型标注”这种 agent 能自己检查的规则。可判定的规则才能真正约束行为，模糊的规则只会被 agent 忽略。

6.2 把团队规范翻译成 skill

团队里那些“口头约定”的规范，比如提交信息格式、分支命名规则、代码审查检查项，都可以翻译成 skill。翻译的过程本身就是一次规范梳理，很多平时说不清道不明的约定，写成 skill 的时候被迫说清楚了。

我帮一个团队做过这件事，把他们散落在 wiki、聊天记录、老员工脑子里的规范整理成了 6 个 skill。结果是新人的 agent 行为直接对齐了团队标准，代码审查的返工率明显下降。这个投入产出比相当高。

6.3 skill 的版本管理与团队分发

skill 也是代码，应该纳入版本管理。建议单独建一个仓库放团队共用的 skill，项目仓库里只放项目特有的 skill。分发方式可以是 git submodule，也可以是包管理器，看团队习惯。

关键是变更要有记录。skill 改了之后，团队要知道改了什么、为什么改、影响哪些项目。没有变更记录的 skill 仓库，用不了多久就会变成一团乱麻，谁也不敢改。

6.4 和 CI/CD 的结合思路

superpowers 目前主要在本地开发环节发挥作用，但它的思路可以延伸到 CI。比如把 skill 里的检查项抽出来，做成 CI 里的自动化检查。agent 在本地按 skill 自检，CI 在远端按同样的规则复检，两道防线。

更进一步，可以让 CI 里的 agent 也加载同一套 skill，做自动代码审查。这样本地和远端的标准完全一致，不会出现“本地过了 CI 挂了”的割裂感。这个方向我还在摸索，目前跑通了一部分，效果不错。

7. 一些实际使用中的体会

superpowers 这类框架的价值，不在于它让 agent 变聪明了，而在于它让 agent 变稳定了。聪明是模型的事，稳定是工程的事。裸 agent 像一个天赋很高但没纪律的天才，偶尔惊艳，经常掉链子。挂上 skill 之后，它变成了一个靠谱的普通工程师，不惊艳但可预期。

我现在的习惯是：任何要动到三个文件以上的任务，先确认相关 skill 已加载；任何要提交的代码，先让 agent 按自检 skill 过一遍；任何新项目，先把基础 skill 配好再开始写第一行代码。这三个习惯养成之后，agent 翻车的频率下降了一个数量级。

最后分享一个小技巧：skill 写完之后，别自己闷头用，找团队里最挑剔的那个人试用一周。他挑出来的毛病，往往就是 skill 定义里最模糊、最容易被 agent 钻空子的地方。把这些地方补严实了，skill 才算真正可用。