1. 从“superpowers”说起：一个让 AI 编程助手真正长出“工程肌肉”的技能框架
第一次看到 “superpowers” 这个词，是在几个做 AI 辅助开发的群里。有人甩出一句“装完 superpowers 之后，Claude Code 才算真正能干活了”，底下立刻一堆人追问怎么装、支不支持 Codex CLI、跟原生 agent 有什么区别。我当时的反应是：又一个包装概念？但耐着性子把它的设计思路、目录结构、技能组织方式摸了一遍之后，我改主意了——这东西解决的是一个非常具体、非常痛的问题：大模型本身很聪明，但它在真实软件项目里缺一套稳定的“工作方法论”。
superpowers 本质上是一个agentic skills framework，翻译成人话就是“给 AI 代理用的技能框架”。它不是一个模型，也不是一个 IDE 插件，而是一层架在 Claude Code、Codex CLI 这类命令行 AI 编程工具之上的软件工程方法论封装。你可以把它理解成给一个刚入职、智商极高但完全不懂公司规矩的天才新人，发了一本厚厚的《团队开发手册》，而且这本手册不是摆设，是会被强制执行的——写代码前先想清楚需求，改代码前先读上下文，提交前先自检，遇到不确定的地方先问而不是瞎猜。
它要解决的问题，凡是深度用过 Claude Code 或 Codex CLI 的人都懂。原生状态下，你给 AI 一个任务，它往往上来就噼里啪啦写代码，写完你一看：文件放错目录了、命名风格跟项目不一致、没考虑边界情况、测试也没跑。你得反复纠正，来回几轮下来，token 烧了一大把，人还累。superpowers 的思路是：把这些“工程常识”固化成可复用的技能（skills），让 AI 在动手之前先加载对应的技能，按既定流程走。这就把“靠运气抽卡”变成了“按流程施工”。
这篇文章适合谁看？如果你已经在用 Claude Code 或 Codex CLI，但总觉得它“差点意思”，那这篇就是写给你的。如果你还没入门，只是想搞清楚这套工具链到底怎么回事，也能从里面摸到完整的安装、配置、使用脉络。我会从设计思路、核心机制、安装实操、常见坑几个维度，把 superpowers 这套东西拆开讲透，尽量做到你看完就能自己动手复现。
2. 核心设计思路拆解：为什么是“技能框架”而不是“提示词合集”
2.1 原生 AI 编程助手的三个结构性缺陷
要理解 superpowers 为什么这么设计，得先看清楚原生工具的短板在哪。我用 Claude Code 和 Codex CLI 加起来跑了大概小半年，踩出来的问题基本集中在三个地方。
第一个是上下文漂移。一个稍微大点的任务，比如“给用户模块加一个手机号登录”，AI 干着干着就忘了最初的需求边界，开始顺手重构旁边的代码，或者引入一个项目里根本没用的依赖。这不是模型笨，是它在长对话里缺少一个稳定的“任务锚点”。
第二个是流程缺失。人类工程师接到任务，脑子里会自动跑一套流程：理解需求 → 看现有代码 → 设计方案 → 写代码 → 自测 → 提交。AI 默认没有这套流程，它倾向于“最短路径直达代码”。结果就是方案没想清楚就开写，写到一半发现方向错了，返工成本极高。
第三个是知识不可复用。你这次教会它“我们这个项目用 pnpm 不用 npm”“测试文件放在tests目录”，下次开新会话它又忘了。每次都要重新交代，效率极低。
superpowers 的设计，几乎是精准地对着这三个缺陷来的。它用技能文件解决知识复用，用强制流程解决流程缺失，用技能加载机制解决上下文漂移。
2.2 技能（Skills）作为最小复用单元的设计哲学
superpowers 里最核心的概念就是 skill。一个 skill 通常是一个 Markdown 文件，里面写清楚了“在什么场景下用”“具体步骤是什么”“有哪些注意事项”。比如可能有一个叫write-tests-first的技能，内容就是告诉 AI：接到功能开发任务时，先写测试，再写实现。
这种设计的高明之处在于它把“方法论”变成了“可加载的资源”。传统做法是把这些要求塞进系统提示词里，但系统提示词一长，模型注意力就被稀释了，而且改起来麻烦。superpowers 的做法是：平时不加载，需要的时候按需加载。这跟人类专家的工作方式很像——你不需要时刻记住所有规范，而是在做具体事情时去查对应的手册。
我实测下来，这种按需加载的机制对 token 消耗的控制相当友好。一个项目里可能有几十个 skill，但一次任务只会加载相关的两三个，不会把上下文撑爆。
2.3 与 Claude Code、Codex CLI 的协作边界
这里要澄清一个容易混淆的点：superpowers 不是要取代 Claude Code 或 Codex CLI，它是寄生在这两个工具之上的。Claude Code 和 Codex CLI 负责“跟模型对话、执行终端命令、读写文件”这些底层能力，superpowers 负责“告诉模型该怎么组织工作”。
打个比方，Claude Code 是一台性能强劲的挖掘机，superpowers 是操作手册加施工图纸。没有手册，挖掘机也能挖，但可能挖歪、挖漏、把管线挖断。有了手册，施工质量就稳定多了。
所以安装 superpowers 的前提，是你得先把 Claude Code 或 Codex CLI 装好、跑通。下面我就按这个顺序，把整条链路讲清楚。
3. 环境准备与工具链安装：从 Node 到 Claude Code 再到 Codex CLI
3.1 Node 环境：一切的地基
Claude Code 和 Codex CLI 都是基于 Node 生态的命令行工具，所以第一步是把 Node 装好。这一步看着简单，但坑不少，尤其是国内网络环境下。
我推荐用 nvm 来管理 Node 版本，而不是直接装系统级 Node。原因很简单：不同项目可能依赖不同 Node 版本，nvm 切换起来一条命令的事，系统级 Node 升级降级都麻烦。
# macOS / Linux 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 装完之后重开终端，或者 source 一下配置文件 source ~/.bashrc # 或 ~/.zshrc # 安装 Node 20 LTS（Claude Code 和 Codex CLI 都兼容） nvm install 20 nvm use 20 nvm alias default 20 # 验证 node -v # 应输出 v20.x.x npm -vWindows 用户建议用 WSL2，把 Ubuntu 环境跑起来再按上面的步骤走。原生 Windows 下有些终端交互会有兼容问题，WSL2 能省掉一堆麻烦。
注意：Node 版本不要低于 18，否则部分依赖会报错。我试过用 Node 16 装 Codex CLI，卡在依赖解析阶段半天不动，换 20 之后秒过。
3.2 Claude Code 安装与账号配置
Claude Code 的安装本身不复杂，官方推荐用 npm 全局安装：
npm install -g @anthropic-ai/claude-code # 验证安装 claude --version装完之后第一次运行claude，它会引导你登录。这里有个很多人关心的问题：注册账号和不注册有什么区别。简单说，注册账号（走官方订阅）能用上完整的模型能力和最新的功能更新，配额也相对稳定；不注册的话，通常需要自己接第三方 API，灵活度高但需要自己处理 key 管理和额度问题。
如果你打算用第三方 API 接入 DeepSeek、Qwen、GLM 这类模型，社区里有个叫 cc switch 的工具可以帮你切换不同的 API 端点。它的作用是管理多套配置，让你在不同模型之间快速切换，不用每次手动改环境变量。
# 以环境变量方式指定 API 端点（示例结构，具体值按你的服务商填） export ANTHROPIC_BASE_URL="你的服务商地址" export ANTHROPIC_API_KEY="你的key"提示：第三方 API 的兼容性参差不齐，有些对 Claude Code 的工具调用协议支持不完整，会出现“能对话但不能执行终端命令”的情况。选服务商之前最好先小额度试一下工具调用是否正常。
3.3 Codex CLI 安装：慢是常态，有解
Codex CLI 的安装命令是：
npm install -g @openai/codex但很多人反馈node 安装 codex cli 很慢，这个我深有体会。原因是它的依赖树比较大，加上默认走 npm 官方源，国内拉取速度感人。解决办法有两个：换镜像源，或者用 pnpm 装。
# 方案一：临时换淘宝镜像 npm install -g @openai/codex --registry=https://registry.npmmirror.com # 方案二：用 pnpm，速度通常快一截 npm install -g pnpm pnpm add -g @openai/codex如果装到一半卡死，先别急着反复重试，很可能是缓存坏了。清一下缓存再装：
npm cache clean --force卸载 Codex CLI 的命令是npm uninstall -g @openai/codex，有时候装出问题了，卸干净重装比修更快。
3.4 VS Code 接入：让编辑器成为主战场
命令行用久了会想念编辑器的便利，尤其是看 diff、跳转文件这些操作。Claude Code 和 Codex CLI 都有 VS Code 的接入方式。
Claude Code 有官方的 VS Code 扩展，装完之后可以在编辑器里直接唤起对话，而且它能感知你当前打开的文件和选中的代码，上下文给得很准。配置上主要注意两点：一是确保扩展能找到你本地的 claude 可执行文件路径，二是如果用了第三方 API，环境变量要在 VS Code 能读到的位置配置好（比如写进 shell 的 profile 文件，而不是只在某个终端会话里 export）。
Codex CLI 在 VS Code 里通常是通过集成终端使用，配合一些快捷键绑定，体验也还行。我个人的习惯是：大范围重构和探索用编辑器里的 Claude Code 扩展，纯命令行批处理任务用 Codex CLI，各取所长。
4. superpowers 的安装与技能体系落地
4.1 安装 superpowers 的完整流程
superpowers 的安装方式跟前面两个工具不太一样，它更像是一个“技能包”，需要放到 AI 工具能读取到的位置。常见的做法是把它克隆到本地某个目录，然后通过配置让 Claude Code 或 Codex CLI 在启动时加载。
# 克隆到本地（放在你习惯的工具目录下） git clone <superpowers仓库地址> ~/.superpowers # 进入目录看看结构 cd ~/.superpowers ls -la典型的目录结构里会有skills/文件夹，里面按类别放着一个个技能文件；还可能有config/或者templates/之类的辅助目录。安装的核心动作，就是让 Claude Code 或 Codex CLI 知道“技能库在这里”。
对于 Claude Code，通常是在项目根目录或用户配置目录下放一个配置文件，指向技能库路径。对于 Codex CLI，机制类似但配置项名称可能不同。具体配置方式建议以你所用版本的官方说明为准，因为这类工具的配置格式迭代比较快。
注意：安装 superpowers 之前，务必确认 Claude Code 或 Codex CLI 本身能正常工作。我见过有人工具还没跑通就急着装技能框架，结果排查问题时分不清是底层工具的问题还是框架的问题，白白浪费时间。
4.2 技能加载机制：按需触发而非全量注入
superpowers 最值得说道的设计，就是技能的按需加载。它不会在会话一开始就把所有技能塞进上下文，而是通过一套触发机制，在识别到当前任务类型后，加载对应的技能。
这套机制的好处，我用一个具体场景说明。假设你的技能库里有 30 个技能，涵盖测试、重构、文档、部署、代码审查等。当你让 AI“修一个登录页的样式 bug”时，它只需要加载跟 UI 修改和测试相关的两三个技能，其余 27 个不参与，上下文干净，模型注意力集中。
如果换成全量注入，30 个技能的说明文字加起来可能上万 token，模型在这么长的上下文里找重点，效果反而下降。这跟人开会一样，议题越聚焦，结论越清晰。
4.3 一个技能文件的解剖：以“先写测试”为例
我拿一个典型的技能文件结构来拆解，让你看清楚它到底长什么样。假设有个技能叫test-first-development：
# Test-First Development ## When to use 接到新功能开发任务，或修改现有功能的行为时。 ## Steps 1. 先阅读相关模块的现有测试，理解测试风格和断言习惯。 2. 针对新需求写一个会失败的测试用例。 3. 运行测试，确认它确实失败（而不是因为语法错误失败）。 4. 编写最小实现让测试通过。 5. 重构实现，保持测试绿色。 6. 补充边界情况的测试。 ## Notes - 不要一次性写完所有测试再写实现，容易过度设计。 - 如果项目没有测试框架，先跟用户确认是否引入。你看，这个文件本身没有任何代码，全是流程和判断。这正是 superpowers 的价值所在——它把资深工程师脑子里的“隐性知识”显性化了。AI 加载这个技能后，行为模式就会从“直接写实现”切换到“先写测试”。
4.4 自定义技能：把你的团队规范喂进去
superpowers 真正强大的地方，是它允许你写自己的技能。每个团队都有自己的规矩：命名用驼峰还是下划线、日志怎么打、错误怎么处理、PR 描述模板长什么样。这些都可以写成技能文件。
我的建议是，从你最常纠正 AI 的那几件事开始写。比如你发现自己每次都要提醒 AI“不要用 any 类型”，那就写一个strict-typing技能。写个三五次之后，你会发现纠正次数明显下降。
技能文件的写法有几个要点：一是When to use要写得具体，模糊的触发条件会导致技能该加载时不加载；二是Steps要可执行，避免“注意代码质量”这种没法落地的表述；三是Notes里放那些“踩过坑才知道”的经验，这部分往往最值钱。
5. 实操全流程：用 superpowers 跑一个真实任务
5.1 任务设定与技能预加载
我拿一个真实场景来演示：给一个已有的 Node 项目加一个“导出用户数据为 CSV”的功能。这个任务不大不小，正好能体现 superpowers 的价值。
启动 Claude Code 后，我先不急着让它写代码，而是明确告诉它任务背景，并观察它是否加载了相关技能。理想情况下，它会加载类似feature-development、test-first-development、code-review这几个技能。
如果它没自动加载，我会手动提示：“请先加载 feature-development 技能再开始。”这一步很关键，不要跳过流程直接要代码，否则就退回到原生模式了。
5.2 需求澄清阶段：让 AI 先问再动手
加载技能后，AI 的行为会明显变化。它会先问几个问题：CSV 的列有哪些？数据量大概多大？需不需要分页导出？导出是同步还是异步？
这一步的价值极高。原生模式下，AI 会直接假设一堆东西然后开写，写完你发现假设全错。有了技能约束，它倾向于先澄清。我实测下来，需求澄清阶段多花的两三分钟，能省掉后面十几分钟的返工。
5.3 实现与自测：观察 AI 的流程执行
澄清完需求，AI 开始按技能流程走：先看现有代码结构，找到数据访问层，然后写测试，再写实现。这个过程中我会盯着它的每一步，尤其是它跑测试的时候。
有个细节值得注意：superpowers 约束下的 AI，在测试失败时不会急着改测试让它通过，而是会分析是实现错了还是测试写错了。这个判断能力，是区分“会用 AI”和“被 AI 带偏”的关键。
# AI 执行测试的典型命令 npm test -- --grep "export users to csv"如果测试通过，它会进入自检环节，检查代码风格、边界情况、错误处理。这些检查项，很多都来自技能文件里的Notes。
5.4 提交前的自检清单
任务快结束时，AI 会跑一遍自检清单。这个清单通常包括：测试是否全绿、有没有遗留的 console.log、命名是否符合规范、有没有更新相关文档。
我建议你在这个阶段亲自过一遍 diff，不要完全放手。AI 再守规矩，也可能有它理解偏差的地方。我踩过的坑是：AI 把导出功能实现得很好，但顺手改了一个不相关的工具函数，理由是“顺手优化”。这种改动如果没有人工 review，很容易埋雷。
6. 常见问题与排查技巧实录
6.1 安装类问题速查
| 问题现象 | 可能原因 | 解决思路 |
|---|---|---|
node 安装 codex cli 很慢 | 默认源网络差 | 换镜像源或用 pnpm |
| 安装卡死不动 | npm 缓存损坏 | npm cache clean --force后重装 |
| 命令找不到 | 全局 bin 目录不在 PATH | 检查 npm 全局路径并加入 PATH |
| 版本冲突 | 多个 Node 版本混用 | 用 nvm 统一管理 |
| 权限报错 | 全局安装权限不足 | 避免 sudo，改用 nvm 管理的 Node |
6.2 运行类问题：模型不听话怎么办
最常见的问题是“AI 不按技能流程走”。排查顺序是这样的：先确认技能库路径配置对不对，再确认技能文件的触发条件写得够不够具体，最后看是不是当前任务类型压根没匹配到任何技能。
还有一种情况是上下文太长导致技能被稀释。如果一个会话跑了很久，前面塞了大量代码和对话，后面加载的技能可能就不那么“有存在感”了。这时候开个新会话，重新加载技能，往往比在旧会话里挣扎更有效。
6.3 模型接入类问题：第三方 API 的坑
用 cc switch 接 DeepSeek、Qwen、GLM 这些模型时，最容易遇到的是工具调用不兼容。表现是 AI 能正常聊天，但让它执行终端命令时没反应，或者返回格式错误。
这个问题的根源在于，Claude Code 的工具调用协议是特定的，第三方模型如果没完整实现这套协议，就会出问题。解决办法是选那些明确声明支持 Claude Code 协议的服务商，或者退而求其次，只用它做对话和代码生成，终端操作自己来。
提示：
claude code harness 可以不登录用其他模型吗这个问题，答案是技术上可行，但体验取决于第三方模型的兼容程度。建议先小范围试用，别一上来就把重要任务交出去。
6.4 命令速查：那些高频操作
Claude Code 和 Codex CLI 里有一些高频命令，熟练之后效率提升明显。比如/compact用来压缩上下文，长会话里定期跑一下能省 token；/model切换模型；/resume恢复之前的会话。这些命令的具体行为可能随版本变化，建议以你所用版本的帮助信息为准。
# 查看可用命令 claude --help # 在会话内查看命令列表 /help7. 我踩过的坑和几条实在建议
装 superpowers 这套东西，我前后折腾了大概两周，中间踩的坑不算少，挑几个最有代表性的说说。
第一个坑是贪多。一开始我往技能库里塞了二十多个技能，结果 AI 加载的时候反而犹豫，经常加载错技能。后来砍到八个核心技能，效果立刻好了。技能不是越多越好，覆盖你最高频的纠正场景就够了。
第二个坑是技能写得太抽象。我最早写的技能里有一句“保证代码质量”，AI 看了跟没看一样。后来改成“所有函数必须有明确的返回类型标注，禁止隐式 any”，立刻就有效果了。技能文件要写成“可执行的指令”，不是“美好的愿望”。
第三个坑是忽略版本兼容。Claude Code 和 Codex CLI 更新挺频繁的，有次升级之后 superpowers 的加载机制就失效了，排查半天才发现是配置格式变了。所以升级工具之后，记得回归测试一下技能加载是否正常。
最后分享一个实用技巧：把技能文件和项目代码放在同一个仓库里管理。这样团队里每个人拉下代码，技能规范就是现成的，新人上手直接继承老手的经验。这比写一堆没人看的文档强多了。
这套东西后续还能怎么扩展？我最近在尝试把代码审查的 checklist 也做成技能，让 AI 在提交前自动跑一遍。另外就是把常见的线上故障排查流程固化下来，出问题时让 AI 按流程走一遍，避免慌乱中漏掉关键检查项。这些还在摸索，等跑顺了再单独写一篇。
