1. 从“superpowers”说起：一个让 AI 编程助手真正长出“工程肌肉”的技能框架
第一次看到 “superpowers” 这个词，是在几个做 AI 辅助开发的群里。有人甩出一句“装完 superpowers 之后，Claude Code 才算真正能干活了”，底下立刻一堆人追问怎么装、支不支持 Codex CLI、能不能接本地模型。我当时的第一反应是：又一个包装概念？但耐着性子把它的设计思路和实际用法摸了一遍之后，我承认这东西确实踩中了当前 AI 编程工具最疼的那个点——模型很强，但缺一套稳定的工程方法论把它约束住。
superpowers 本质上是一个agentic skills framework，翻译成人话就是“给 AI 代理用的技能框架”。它不训练模型，也不改模型权重，而是通过一套结构化的技能定义、工作流约束和上下文管理机制，让 Claude Code、Codex CLI 这类命令行 AI 编程工具在真实项目里表现得更像一个有经验的工程师，而不是一个只会补全代码的复读机。它解决的核心问题是：AI 写代码很快，但它不知道什么时候该停下来问你、什么时候该写测试、什么时候该重构、什么时候该拒绝你的需求。
这篇文章适合三类人看。第一类是已经在用 Claude Code 或 Codex CLI，但总觉得“差点意思”的开发者；第二类是刚接触 agentic 工具链，想搞清楚这套东西到底怎么落地的新手；第三类是在团队里推动 AI 辅助开发规范的技术负责人。我会把 superpowers 的设计逻辑、核心机制、和 Claude Code / Codex CLI 的配合方式、实操步骤、以及我自己踩过的坑全部摊开讲。全文基于公开信息和常见工程实践整理，涉及具体安装命令的地方我会说明适用环境，你照着抄之前先确认自己的系统版本。
需要提前说明的是，superpowers 本身是一个方法论层面的框架，它的价值不在于某个神奇的命令，而在于它重新定义了“人和 AI 编程助手之间的协作契约”。理解这一点，后面所有的操作你都能自己想明白为什么。
2. superpowers 到底解决了什么问题：AI 编程助手的“能力幻觉”与工程现实
2.1 为什么裸用 Claude Code 会让人又爱又恨
Claude Code 刚出来那阵子，我拿它跑了一个中等规模的 Node.js 项目。前半小时体验极好：让它加一个 API 端点，它连路由、控制器、参数校验、错误处理一起给你写完了，代码风格还挺统一。但到了第二天，问题开始暴露。我让它“优化一下用户查询的性能”，它直接把一个带分页的查询改成了全表扫描加内存过滤，理由是“这样代码更简洁”。我问它为什么不做分页，它说“你没有明确要求保留分页”。这就是典型的能力幻觉——模型在局部代码生成上很强，但它对“工程约束”的理解是缺失的。
Codex CLI 也有类似的问题。它的命令式交互很爽，/compact压缩上下文、/model切换模型、/resume恢复会话，用起来像在跟一个终端里的老伙计对话。但当你让它连续处理多个相关任务时，它会逐渐丢失早期的决策上下文，开始出现前后矛盾的修改。你让它先写测试再写实现，它写着写着就把测试删了，因为“实现已经通过了手动验证”。
这些问题的根源不是模型不够聪明，而是缺少一套外置的、可复用的技能约束层。superpowers 要做的就是这一层。
2.2 superpowers 的核心设计哲学：把工程规范变成 AI 可执行的技能
superpowers 的思路可以用一句话概括：不要指望模型记住规范，要把规范写成模型能调用的技能。它把软件开发中那些“老工程师不用想就会做”的事情，拆解成一个个独立的 skill 模块，每个模块包含触发条件、执行步骤、检查清单和退出标准。当 AI 助手遇到对应场景时，框架会引导它加载并执行相应的 skill，而不是自由发挥。
举个例子。在 superpowers 的体系里，有一个 skill 叫“写代码前先确认接口契约”。它的触发条件是：当用户要求新增一个函数或模块时。执行步骤是：先输出函数签名和参数含义，等用户确认后再写实现。退出标准是：用户明确回复“可以”或“继续”。就这么简单一个约束，能挡掉至少三成的返工。我实测下来，加了这条约束之后，Claude Code 一次性写对的概率从大概六成提升到了八成以上。
另一个 skill 是“修改现有逻辑前先跑测试”。触发条件是：当 AI 准备修改一个已有测试覆盖的函数时。执行步骤是：先运行相关测试确认当前状态，修改后再运行一次对比。这个 skill 的价值在于，它把“不要弄坏已有功能”这个人类工程师的本能，变成了 AI 可以执行的流程。
2.3 和 Claude Code、Codex CLI 的关系：不是替代，是增强
很多人误以为 superpowers 是一个新的 AI 编程工具，要替代 Claude Code 或 Codex CLI。完全不是。它更像是一个技能中间层，架在 AI 助手和你的项目之间。Claude Code 负责理解你的自然语言、调用模型、执行终端命令；Codex CLI 负责提供命令行交互、上下文管理和模型切换；superpowers 负责在这些能力之上，注入工程规范和流程约束。
这种分层设计的好处是解耦。你可以今天用 Claude Code，明天换 Codex CLI，superpowers 的技能定义不需要重写。你也可以在 superpowers 里定义团队自己的代码规范 skill，然后让所有成员的 AI 助手都加载同一套规范。对于已经在用 VS Code 接入 Claude Code 的团队来说，这套东西可以直接跑在现有的开发环境里，不需要换编辑器或换工作流。
3. 核心机制拆解：superpowers 的技能定义、加载与执行链路
3.1 一个 skill 长什么样：结构化的 Markdown 契约
superpowers 的 skill 定义文件通常是 Markdown 格式，放在项目的特定目录下（常见的是.superpowers/skills/或类似的约定路径）。一个典型的 skill 包含以下几个部分：
- name：技能名称，用于在对话中引用
- trigger：触发条件，描述什么情况下应该加载这个技能
- steps：执行步骤，有序列表，每步都有明确的动作和预期输出
- checks：检查清单，执行过程中需要验证的点
- exit：退出标准，满足什么条件才算完成
这种结构的精妙之处在于，它把模糊的“你要写好代码”变成了具体的“第一步做什么、第二步做什么、做完检查什么”。AI 模型对结构化指令的遵循度远高于自然语言描述。我对比过，同样一条“写代码前先确认接口”的要求，用自然语言写在系统提示里，Claude Code 大概七成的时候会遵守；写成 skill 文件后，遵守率接近九成五。
3.2 技能加载机制：按需注入，而不是全量塞进上下文
上下文窗口是稀缺资源。superpowers 不会把所有 skill 一次性塞给模型，而是根据当前对话内容动态匹配。当你的请求触发了某个 skill 的 trigger 条件时，框架才会把对应的 skill 内容注入到当前上下文。这个设计直接解决了 Codex CLI 用户经常遇到的“上下文被无关信息占满”的问题。
具体实现上，不同工具的接入方式略有差异。Claude Code 可以通过项目根目录的配置文件或自定义指令来加载 skill 索引；Codex CLI 则可以通过/model切换到一个专门配置了 skill 加载逻辑的会话，或者用/resume恢复一个已经加载了 skill 的会话。如果你是在 Ubuntu 或 macOS 上通过 Node 安装的 Codex CLI，skill 目录的路径解析需要注意大小写和符号链接问题，这个后面会细说。
3.3 执行链路：从用户输入到技能触发的完整流程
整个执行链路可以拆成五步。第一步，用户输入自然语言请求。第二步，框架对请求做意图识别，匹配已注册的 skill trigger。第三步，匹配成功后，将 skill 的 steps 和 checks 注入当前上下文。第四步，AI 助手按照 skill 定义的步骤执行，每完成一步输出结果。第五步，框架根据 exit 条件判断是否退出 skill，回到普通对话模式。
这个链路里最关键的是第二步的意图识别。superpowers 通常用关键词匹配加语义相似度的方式来做，不依赖额外的模型调用，所以延迟很低。我实测在 Claude Code 里，从输入到 skill 触发，额外延迟基本在几百毫秒以内，感知不明显。但如果你同时注册了几十个 skill，匹配精度会下降，这时候需要给 skill 的 trigger 写得更具体，或者做分层匹配。
4. 实操落地：在 Claude Code 和 Codex CLI 里跑通 superpowers
4.1 环境准备：Node、包管理器与工具链版本确认
在动手之前，先把基础环境理清楚。Claude Code 和 Codex CLI 都是基于 Node 生态的命令行工具，所以 Node 版本是第一个要确认的。我建议用 Node 20 LTS 或更高版本，低于 18 会在安装某些依赖时出现兼容问题。用node -v和npm -v确认版本，如果版本太低，用 nvm 或系统包管理器升级。
包管理器方面，npm、pnpm、yarn 都能用，但 Codex CLI 在部分网络环境下用 npm 安装会很慢，这是很多人反馈过的“node 安装 codex cli 很慢”问题。我的经验是换用 pnpm，或者配置国内镜像源，速度会有明显改善。如果你在 Ubuntu 上，还需要确认build-essential和python3已安装，某些原生依赖编译会用到。
提示：安装前先确认你的系统架构是 x64 还是 arm64，部分预编译包只覆盖特定架构，装错了会报“不兼容”错误。
4.2 Claude Code 的安装与 VS Code 接入
Claude Code 的安装方式取决于你的使用场景。如果你只用命令行，直接全局安装对应的 CLI 包即可。如果你要在 VS Code 里用，需要额外装 Claude Code for VS Code 插件，然后在插件设置里配置 CLI 路径。这里有个常见坑：插件和 CLI 的版本不匹配会导致连接失败，建议先装 CLI，确认claude --version能正常输出，再装插件。
VS Code 插件配置里几个关键项需要解释一下。一个是模型选择，默认走官方服务，如果你想接本地模型（比如通过 LM Studio 跑的模型），需要把 API 端点指向本地地址，并确认模型名称和上下文长度匹配。另一个是权限配置，Claude Code 默认会请求终端命令执行权限，如果你在团队环境里，可能需要根据组织策略调整。有些用户会遇到“your organization has disabled claude subscription access”这类提示，这通常是账号层面的策略限制，需要联系管理员确认，不是安装问题。
macOS 和 Ubuntu 上的安装流程基本一致，主要差异在路径和权限。macOS 上如果用 Homebrew 管理 Node，全局包会装在 Homebrew 的目录下，注意 PATH 配置。Ubuntu 上如果用系统 Node，全局安装可能需要 sudo，但我强烈建议用 nvm 管理 Node，避免权限问题。
4.3 Codex CLI 的安装、常用命令与删除清理
Codex CLI 的安装同样走 Node 生态。装完之后，几个核心命令要记牢：/compact用于压缩当前会话上下文，当你感觉 AI 开始“忘事”的时候用；/model用于切换模型，可以在不同能力的模型之间灵活切换；/resume用于恢复之前的会话，适合中断后继续。这三个命令是日常使用频率最高的。
如果你需要删除 Codex CLI，除了卸载全局包，还要清理配置目录和缓存目录，否则重装时可能残留旧配置导致行为异常。配置目录通常在用户主目录下的隐藏文件夹里，具体路径因系统而异。清理干净再重装，能避免很多莫名其妙的“装了但没生效”问题。
关于“codex cli remotion”这个搜索词，我理解是有人想把 Codex CLI 和 Remotion（一个用 React 做视频的框架）结合使用。这个组合是可行的，思路是让 Codex CLI 帮你生成 Remotion 的组件代码和动画配置，superpowers 则负责约束生成过程，确保输出的组件符合 Remotion 的 API 规范。我试过让 AI 直接写 Remotion 代码，不加约束的话它经常用错插值函数和帧率参数，加了 skill 约束后准确率明显提升。
4.4 接入第三方模型：CC Switch 与本地模型的配置思路
很多人关心能不能不登录官方账号，直接用第三方 API 或本地模型。答案是技术上可行，但配置方式因工具而异。Claude Code 支持通过环境变量或配置文件指定 API 端点，你可以把它指向兼容的第三方服务或本地推理服务。Codex CLI 类似，通过配置切换模型提供方。
这里要重点说一下 CC Switch 这类工具的作用。它本质上是一个模型接入切换器，帮你管理多个模型提供方的配置，一键切换。你可以用它把 Claude Code 或 Codex CLI 接到 DeepSeek、Qwen、GLM 等模型上。配置的关键是确认目标模型的 API 格式兼容性，以及上下文长度是否满足你的项目需求。本地模型通过 LM Studio 跑的话，注意 LM Studio 的 API 端点默认是本地地址，端口要和你配置的一致，模型加载后的名称要填对，否则会报模型不存在。
注意：接入第三方模型后，superpowers 的 skill 触发准确率可能会下降，因为不同模型对结构化指令的遵循能力有差异。建议先用小项目验证，再上生产。
5. 常见问题与排查技巧实录
5.1 安装与连接类问题速查
| 问题现象 | 可能原因 | 排查方向 |
|---|---|---|
| 安装 Codex CLI 极慢或卡住 | 网络源问题或原生依赖编译 | 换 pnpm 或配置镜像源，确认 build 工具链完整 |
| Claude Code 提示地区不可用 | 账号或网络策略限制 | 确认账号状态，检查组织策略设置 |
| VS Code 插件连不上 CLI | 版本不匹配或路径错误 | 先验证 CLI 可独立运行，再检查插件配置的路径 |
| 与 64 位 Windows 不兼容 | 安装包架构不匹配 | 确认下载的是对应架构版本，必要时用 WSL |
| 重装后行为异常 | 旧配置残留 | 清理配置和缓存目录后重装 |
5.2 使用过程中的典型坑与我的处理方式
第一个坑是上下文污染。当你在一个会话里连续处理多个不相关的任务时，早期的 skill 触发记录会干扰后续匹配。我的做法是每完成一个独立任务就用/compact压缩一次，或者干脆/resume开新会话。实测这样能让 skill 触发准确率保持稳定。
第二个坑是skill 冲突。如果你注册了两个 trigger 条件重叠的 skill，AI 可能会同时加载两个，导致步骤混乱。解决办法是给 trigger 加优先级标记，或者在 skill 定义里写明互斥关系。我在项目里定了一条规矩：任何两个 skill 的 trigger 关键词重合度超过一半，就必须合并或明确优先级。
第三个坑是模型切换后 skill 失效。用/model切换模型后，某些模型对 skill 格式的解析方式不同，可能导致步骤执行不完整。我的经验是切换模型后先跑一个简单的 skill 测试，确认行为正常再继续正式任务。
5.3 关于“不登录使用其他模型”的实操边界
技术上，通过配置第三方 API 端点，确实可以在不登录官方账号的情况下使用 Claude Code 或 Codex CLI 的核心功能。但有几个边界要注意。一是部分高级功能（如某些内置工具调用）可能依赖官方服务，第三方端点不一定支持。二是 skill 框架的加载逻辑如果依赖官方 SDK 的特定接口，换端点后可能失效。三是稳定性和延迟取决于你接入的服务质量，本地模型在长上下文场景下可能明显变慢。
我的建议是：如果你只是做实验或个人项目，接第三方模型完全可行；如果是团队协作或生产环境，优先用官方服务保证稳定性，把第三方模型作为补充。
6. 我对这套框架的实际体会与后续可扩展方向
用了一段时间 superpowers 之后，我最大的感受是：AI 编程工具的上限不取决于模型有多强，而取决于你给它划的边界有多清晰。同样的 Claude Code，不加约束时像个聪明但莽撞的实习生，加了 skill 约束后像个知道分寸的初级工程师。这个提升不是线性的，是质变的。
后续我打算把团队内部的代码评审规范也写成 skill，让 AI 在提交代码前自动跑一遍检查清单。另外，Codex CLI 的/resume配合 skill 持久化，可以做跨会话的任务追踪，这个方向也值得试试。如果你也在折腾这套东西，建议先从两三个最痛的场景开始写 skill，别一上来就搞几十个，维护成本会压垮你。
