Superpowers技能框架：Claude Code与Codex CLI实战指南

1. 从"superpowers"这个词说起：它到底指什么

第一次看到"superpowers"这个标题，很多人会以为是某个超级英雄题材的项目，或者是一个泛泛的口号式概念。但如果你最近在开发者社区里泡过，就会发现这个词正在被反复提及，而且总是和另外几个词绑在一起出现——agentic skills framework、software development methodology、Claude Code、Codex CLI。这几个词凑在一起，指向的其实是一个非常具体的东西：一套围绕AI编程助手构建的、让开发者获得"超能力"的技能框架与方法论。

说白了，superpowers 不是一个可以下载安装的软件包，也不是某个具体的命令行工具。它更像是一套"心法"——一套关于如何把AI编程助手真正用出生产力的系统性方法。你可以把它理解成：以前你用AI写代码，是"我问一句它答一句"；而 superpowers 这套框架想解决的，是"如何让AI像一个真正靠谱的结对编程伙伴一样，持续、稳定、高质量地参与你的整个开发流程"。

这个定位非常关键。因为现在市面上关于 Claude Code、Codex CLI 这类工具的教程已经很多了，但绝大多数都停留在"怎么装、怎么跑通第一个命令"的层面。而 superpowers 关注的是更上层的问题：装好之后呢？怎么组织你的工作流？怎么让AI理解你的项目上下文？怎么在多个模型、多个工具之间切换而不乱套？这些才是真正决定你效率的东西。

这篇文章适合几类人看：一是已经装好了 Claude Code 或 Codex CLI，但用起来总觉得"差点意思"的开发者；二是还在观望，想搞清楚这套东西到底值不值得投入时间学习的工程师；三是团队里负责技术选型，需要评估这类工具能否落地的人。我会尽量把原理讲透，把操作步骤写细，同时把我在实际使用中踩过的坑和总结的技巧都摊开来说。

需要提前说明的是，superpowers 作为一个"技能框架"，它的具体形态会随着你使用的底层工具不同而变化。用 Claude Code 有一套玩法，用 Codex CLI 又有另一套玩法。所以下面我会先讲清楚这套框架的通用逻辑，再分别针对两个主流工具展开具体的配置和使用方法。

2. superpowers 框架的底层逻辑：为什么"技能"比"提示词"更重要

2.1 从提示词工程到技能框架的范式转变

过去两年，大家聊AI编程，聊得最多的是"提示词工程"（Prompt Engineering）。怎么写出一个好的提示词，怎么让模型输出更准确的代码，怎么通过 few-shot 示例引导模型。这些技巧当然有用，但用久了你会发现一个根本性的问题：提示词是一次性的、碎片化的。你这次写了一个很棒的提示词让AI帮你重构了一个函数，下次遇到类似的任务，你还得重新组织语言，重新交代上下文。

superpowers 这套框架的核心洞察就在这里：真正提升效率的不是单次提示词的技巧，而是把重复性的、有固定模式的工作，沉淀成可复用的"技能"（skills）。一个 skill 本质上是一段结构化的指令集，它告诉AI：在这个特定场景下，你应该按照什么步骤、遵循什么规范、输出什么格式的结果。

打个比方。提示词工程像是你每次做饭都临时想菜谱，而技能框架像是你把自己拿手的几十道菜写成了标准化的菜谱卡片，需要的时候直接抽一张出来照着做。前者依赖你的临场发挥，后者依赖你的积累和沉淀。长期来看，后者的效率和稳定性要高得多。

2.2 一个 skill 的典型结构长什么样

虽然 superpowers 没有强制规定 skill 的格式，但根据社区里流传的实践和我在自己项目里的摸索，一个高质量的 skill 通常包含这么几个部分：

• 触发条件：什么情况下应该调用这个 skill。比如"当用户要求对某个模块进行代码审查时"。
• 前置检查：执行前需要确认哪些信息。比如"确认目标文件的路径、确认项目的技术栈、确认是否有测试覆盖"。
• 执行步骤：具体的操作流程，一步一步写清楚。这部分是 skill 的核心。
• 输出规范：结果应该以什么形式呈现。是生成一个 Markdown 报告，还是直接修改文件，还是输出一段可执行的命令。
• 边界与例外：什么情况下这个 skill 不适用，遇到异常情况怎么处理。

你会发现，这个结构其实和写一份好的 SOP（标准作业程序）非常像。没错，superpowers 本质上就是把软件工程里"流程标准化"的思想，搬到了AI协作的场景里。

2.3 为什么这套框架现在才火起来

你可能会问，这种"把流程沉淀成技能"的想法并不新鲜，为什么偏偏是现在火起来了？原因有几个。

第一，AI编程助手的能力到了临界点。早期的代码补全工具只能做行级别的建议，你没法让它执行一个多步骤的复杂任务。但现在 Claude Code、Codex CLI 这类工具已经能够理解整个项目结构、执行终端命令、读写多个文件。能力上来了，才谈得上"框架"和"方法论"。

第二，多模型并存带来了管理复杂度。现在你可以在 Claude Code 里接入不同的模型，也可以用 Codex CLI 调用本地的或其他来源的模型。模型一多，怎么保证输出质量的一致性就成了问题。技能框架提供了一层抽象，让你的工作流不依赖于具体某个模型。

第三，开发者的学习曲线需要被拉平。新工具层出不穷，每个人都在重新摸索。如果有一套经过验证的技能框架，新人可以直接站在前人的肩膀上，不用从零开始踩坑。

3. Claude Code 环境搭建：从安装到第一次跑通

3.1 安装前的环境确认

在动手安装之前，有几件事必须先确认清楚，否则后面会浪费大量时间在排错上。

首先是操作系统版本。Claude Code 对系统版本有要求，Windows 用户需要特别注意，某些旧版本的 Windows 会因为兼容性问题导致安装失败。如果你在 Windows 上遇到"与64位版本不兼容"之类的提示，大概率是系统版本太老，需要先升级系统。

其次是 Node.js 环境。Claude Code 和 Codex CLI 都是基于 Node.js 生态的工具，所以你需要先装好 Node.js。这里有个坑：很多人用系统自带的包管理器安装 Node.js，版本往往偏旧。建议直接去 Node.js 官网下载 LTS 版本，或者用 nvm（Node Version Manager）来管理版本。用 nvm 的好处是，你可以在不同项目之间切换 Node.js 版本，避免版本冲突。

第三是网络环境。安装过程中需要从 npm 仓库拉取包，如果网络不稳定，安装会非常慢甚至失败。这一点在安装 Codex CLI 时尤其明显，很多人反馈"node安装codex cli很慢"。解决办法是配置一个稳定的 npm 镜像源，具体命令后面会讲。

3.2 安装 Claude Code 的完整步骤

假设你已经装好了 Node.js（建议 18.x 或更高版本），接下来就可以安装 Claude Code 了。

第一步，打开终端，确认 Node.js 和 npm 的版本：

node -v npm -v

如果这两个命令都能正常输出版本号，说明环境没问题。

第二步，配置 npm 镜像源。这一步不是必须的，但强烈建议做，能显著提升安装速度：

npm config set registry https://registry.npmmirror.com

第三步，执行安装命令：

npm install -g @anthropic-ai/claude-code

这里的-g表示全局安装，装完之后你可以在任何目录下使用claude命令。

第四步，验证安装是否成功：

claude --version

如果能正常输出版本号，说明安装成功了。

3.3 首次启动与账号配置

安装完成之后，直接在终端输入claude就可以启动。第一次启动会引导你完成一些初始配置，主要是账号相关的设置。

这里有一个很多人关心的问题：注册账号和不注册账号有什么区别？简单来说，注册账号后你可以使用官方的云端模型服务，享受更稳定的响应和更完整的功能。不注册的话，某些功能会受限，但如果你打算接入第三方模型或者本地模型，不注册也能用。

如果你在启动时看到类似"your organization has disabled claude subscription access"的提示，这通常是因为你的账号所属组织限制了访问权限。遇到这种情况，可以尝试用个人账号，或者联系组织管理员确认权限设置。

另外，如果你看到"claude code might not be available in your country"这类提示，说明当前地区的服务可用性有限制。这种情况下，可以考虑使用第三方模型接入方案，后面会详细讲。

3.4 在 VS Code 中配置 Claude Code

很多开发者习惯在 VS Code 里工作，不希望频繁切换到终端。Claude Code 提供了 VS Code 插件，可以把它的能力直接集成到编辑器里。

安装插件的方法很简单：打开 VS Code，进入扩展市场，搜索 "Claude Code"，找到官方插件后点击安装。安装完成后，你需要配置插件的一些参数，主要是指定 Claude Code 的可执行文件路径，以及设置默认的模型。

插件配置里有一个容易忽略的点：工作目录的设置。默认情况下，插件会在你当前打开的文件夹下工作。如果你的项目结构比较复杂，建议在配置里明确指定项目根目录，这样AI在读取文件时不会找错位置。

配置完成后，你可以通过命令面板（Ctrl+Shift+P 或 Cmd+Shift+P）调用 Claude Code 的相关命令，也可以直接在编辑器里选中一段代码，右键选择让 Claude Code 处理。

4. Codex CLI 的安装与核心命令详解

4.1 Codex CLI 和 Claude Code 的定位差异

在讲 Codex CLI 的安装之前，先说说它和 Claude Code 的区别，这样你才知道什么时候该用哪个。

Claude Code 更偏向于"全流程助手"，它能理解整个项目、执行复杂的多步骤任务、和你的开发环境深度集成。Codex CLI 则更偏向于"命令行里的快速助手"，它的强项是在终端里快速完成代码生成、命令解释、文件操作等任务。两者不是替代关系，而是互补关系。很多开发者的做法是两个都装，根据任务类型切换使用。

Codex CLI 还有一个特点是它对模型的支持比较灵活，你可以配置它调用不同的模型后端，包括本地运行的模型。这对于有数据隐私要求或者想控制成本的团队来说很有吸引力。

4.2 安装 Codex CLI 并解决速度问题

安装 Codex CLI 的命令是：

npm install -g @openai/codex-cli

如果你在国内网络环境下执行这个命令，很可能会遇到下载速度极慢的问题。除了前面提到的配置 npm 镜像源之外，还有几个技巧可以加速：

• 使用--prefer-offline参数，优先使用本地缓存。
• 如果之前装过旧版本，先卸载再重装，避免残留文件导致的冲突。
• 在网络状况好的时段执行安装，比如清晨。

安装完成后，同样用codex --version来验证。

4.3 必须掌握的 Codex CLI 命令

Codex CLI 提供了一系列命令，其中几个是日常使用频率最高的，必须熟练掌握。

/compact命令用于压缩对话上下文。当你和AI的对话变得很长时，上下文会占用大量资源，响应速度会下降。/compact会把之前的对话历史压缩成更精简的形式，保留关键信息，丢弃冗余内容。这个命令在长时间连续工作时特别有用。

/model命令用于切换模型。你可以在会话中途切换到不同的模型，比如从快速模型切换到高精度模型来处理复杂任务。切换后，后续的对话会使用新模型。

/resume命令用于恢复之前的会话。如果你不小心关闭了终端，或者想接着昨天的进度继续工作，用/resume可以找回之前的对话上下文。

除了这些斜杠命令，Codex CLI 还支持一些直接执行的指令，比如让它读取某个文件、执行某条终端命令、生成某个函数的实现等。具体的命令列表可以在启动后用/help查看。

4.4 删除和升级 Codex CLI

有时候你需要卸载 Codex CLI，比如要换一个版本，或者遇到了无法修复的问题。卸载命令是：

npm uninstall -g @openai/codex-cli

升级到最新版本的命令是：

npm update -g @openai/codex-cli

如果你用的是 Claude Code，升级命令类似：

npm update -g @anthropic-ai/claude-code

这里有个经验：不要频繁升级。新版本虽然可能带来新功能，但也可能引入新的问题。建议在升级前先看看社区的反馈，确认新版本没有严重的 bug 再动手。另外，升级前最好记录一下当前版本号，万一新版本有问题，可以回退。

5. 接入第三方模型：让 Claude Code 和 Codex CLI 用上你想要的模型

5.1 为什么要接入第三方模型

官方模型服务虽然稳定，但有几个现实问题：一是成本，高频使用的话费用不低；二是可用性，某些地区或某些账号可能无法正常访问；三是灵活性，你可能想针对特定任务使用特定模型，比如用某个擅长数学推理的模型来处理算法问题。

接入第三方模型可以解决这些问题。你可以选择云端的中转服务，也可以在本地跑一个模型。本地模型的好处是数据不出本机，隐私性最好，而且没有网络延迟。缺点是对硬件有要求，需要一块像样的显卡。

5.2 用 cc switch 切换模型后端

社区里有一个叫 cc switch 的工具，专门用来管理 Claude Code 的模型配置。它的作用是让你可以在多个模型后端之间快速切换，不用每次手动改配置文件。

使用 cc switch 的基本流程是：先安装这个工具，然后配置好各个模型后端的连接信息，之后就可以用一条命令切换了。比如你想从官方模型切换到某个第三方模型，只需要执行对应的切换命令，Claude Code 下次启动时就会使用新的配置。

这个工具特别适合需要在多个模型之间频繁切换的开发者。比如白天用官方模型处理正式项目，晚上用本地模型做一些实验性的工作。

5.3 在 Claude Code 中调用本地模型

如果你在本地跑了一个模型服务（比如通过 LM Studio 之类的工具），可以让 Claude Code 调用它。核心思路是修改 Claude Code 的配置文件，把 API 端点指向本地的服务地址。

具体步骤大致是：找到 Claude Code 的配置文件（通常在用户目录下的.claude文件夹里），编辑其中的模型配置部分，把base_url改成你本地服务的地址，比如http://localhost:1234/v1，然后填入对应的 API Key（本地服务通常不校验 Key，随便填一个就行）。

配置完成后，重启 Claude Code，它就会使用你本地的模型来响应请求。这里要注意的是，本地模型的上下文窗口通常比云端模型小，所以处理大文件时可能会遇到截断的问题。解决办法是分段处理，或者选择上下文窗口更大的本地模型。

5.4 第三方 API 使用的注意事项

使用第三方 API 时，有几个坑需要提前知道。

第一是兼容性问题。不是所有第三方 API 都完全兼容官方接口的格式。有些 API 在参数命名、返回结构上有细微差异，可能导致 Claude Code 无法正常解析响应。遇到这种情况，需要查看第三方服务的文档，看是否有兼容模式或者需要额外的配置。

第二是稳定性问题。第三方服务的可用性参差不齐，有些服务在高峰期会限流或者超时。建议配置一个备用方案，主服务不可用时能快速切换。

第三是数据安全问题。使用第三方 API 意味着你的代码片段会发送到第三方的服务器。如果项目涉及敏感信息，要么使用本地模型，要么确保第三方服务有足够的数据保护措施。

6. 把 superpowers 落地到日常开发：我的实操心得

6.1 从一个小场景开始，不要贪多

很多人一上来就想把 superpowers 的全套框架应用到所有项目里，结果往往是配置太复杂、流程太重，用几天就放弃了。我的建议是，先选一个具体的、高频的小场景来试点。

比如"代码审查"这个场景。你可以先写一个简单的 skill，规定AI在审查代码时要检查哪些点：命名规范、边界条件、错误处理、性能隐患。然后在你日常的代码提交前，用这个 skill 跑一遍。用上一两周，你会发现两个变化：一是审查速度明显快了，二是你开始有意识地优化这个 skill，把新发现的检查点加进去。

等这个场景跑顺了，再扩展到其他场景，比如"写单元测试""生成接口文档""排查线上问题"。一个场景一个场景地积累，半年下来你就有了自己的一套技能库。

6.2 上下文管理是效率的关键

用这类工具时间长了，你会发现一个规律：AI输出质量的高低，很大程度上取决于你给它的上下文是否充分、准确。

什么叫充分的上下文？举个例子，你让AI帮你优化一个函数，如果你只把函数代码贴给它，它只能从代码本身出发给建议。但如果你同时告诉它这个函数在什么业务场景下被调用、性能瓶颈在哪里、有哪些不能改的约束条件，它给出的建议就会精准得多。

Claude Code 和 Codex CLI 都支持读取项目文件，所以你可以让AI自己去"看"相关的代码。但要注意，不要让它一次性读取太多文件，否则上下文会被无关信息占满。正确的做法是，先告诉它你需要解决什么问题，让它自己判断需要看哪些文件，然后有针对性地读取。

6.3 关于"直接执行终端命令"这件事

Claude Code 有一个很强大的能力：它可以直接在你的终端里执行命令。比如你让它"帮我看看当前目录下有哪些大文件"，它会自己执行du命令并把结果整理给你。

这个能力用好了效率极高，但也要注意安全边界。我的做法是：对于只读类的命令（查看文件、搜索内容、检查状态），放手让它执行；对于写操作类的命令（删除文件、修改配置、安装软件），一定要让它先告诉你它打算执行什么，你确认后再执行。

Claude Code 本身也提供了权限控制机制，你可以配置哪些命令需要人工确认，哪些可以自动执行。建议在初期把权限收紧一些，等熟悉了它的行为模式后再逐步放开。

6.4 多工具协作的实际工作流

我现在的工作流是这样的：日常的代码编写和快速问答用 Codex CLI，因为它在终端里响应快、切换方便；复杂的重构任务和需要深度理解项目的任务用 Claude Code，因为它能读取更多上下文、执行更复杂的操作；需要特定模型能力时，通过 cc switch 切换到对应的模型后端。

这套工作流不是一天建成的，而是在使用过程中逐步调整出来的。关键是你要清楚每个工具的强项和边界，然后在合适的场景用合适的工具。不要试图用一个工具解决所有问题，也不要为了用工具而用工具。

6.5 常见问题速查

这张表里的问题都是我实际遇到过的，处理方式也经过验证。当然，具体情况可能因环境而异，如果遇到表里没覆盖的问题，建议先查看官方文档，再去社区搜索是否有类似案例。

7. 关于这套框架，我踩过的几个坑

第一个坑是过度配置。刚开始用的时候，我花了两天时间写了一大堆 skill，把各种场景都覆盖了。结果实际用起来发现，大部分 skill 根本用不上，反而因为配置太多导致启动变慢、切换混乱。后来我删掉了八成，只保留最常用的几个，效率反而提升了。教训是：skill 不在多，在于精，在于你真的会反复用。

第二个坑是忽视版本兼容。有一次我升级了 Claude Code 到最新版，结果之前写的几个 skill 因为接口变化全部失效了。从那以后，我养成了一个习惯：升级前先备份配置文件和 skill 定义，升级后先在一个小项目上测试，确认没问题再全面切换。

第三个坑是上下文污染。有段时间我发现AI的回答质量明显下降，总是答非所问。排查了半天才发现，是因为我在一个会话里连续处理了太多不相关的任务，上下文里堆积了大量无关信息。解决办法很简单：一个任务一个会话，任务完成后用/resume开新会话，不要在一个会话里混着做多件事。

第四个坑是盲目信任输出。AI生成的代码看起来往往很合理，但实际跑起来可能有各种问题。我现在养成了一个习惯：AI生成的任何代码，在合并到主分支之前，必须经过测试。这不是不信任AI，而是对自己代码质量负责。

这套东西说到底，是工具，是方法，不是魔法。它能放大你的能力，但前提是你自己得有清晰的思路和判断力。用得好的人，是那些本来就懂开发、懂流程、懂质量的人，AI只是帮他们把这些能力执行得更快更稳。如果你指望装个工具就能自动变成高手，那大概率会失望。但如果你本身就有扎实的基础，这套框架确实能让你如虎添翼。