superpowers技能框架：让Claude Code与Codex CLI从被动响应到主动工作

1. 从"superpowers"说起：这套技能框架到底在解决什么问题

第一次看到 "superpowers" 这个词，是在几个做 AI 辅助开发的群里。有人甩出一张截图，说 Claude Code 装上一套叫 superpowers 的技能包之后，写代码的流程完全变了——不再是"你问一句它答一句"，而是它会主动拆任务、主动查资料、主动跑测试、主动复盘。当时我的第一反应是：这不就是把提示词工程包装成了一个框架吗？后来自己上手折腾了两周，才发现事情没那么简单。

superpowers 本质上是一套agentic skills framework，翻译过来就是"智能体技能框架"。它不是一个独立的软件，也不是一个模型，而是一层架在 Claude Code、Codex CLI 这类命令行 AI 编程工具之上的"方法论 + 技能库"。你可以把它理解成给 AI 编程助手装了一套"工作手册"：什么场景该用什么流程、遇到问题该按什么顺序排查、写代码之前该先做什么、写完代码之后该验证什么，全部被固化成了可复用的技能模块。

它解决的问题很具体。用过 Claude Code 或者 Codex CLI 的人都知道，这类工具默认状态下是"被动响应"的——你给一个指令，它执行一个动作。但真实的软件开发不是这样的。真实的开发是：接到需求先想清楚要做什么，然后拆解成小任务，逐个实现，中间不断验证，最后还要回头检查有没有遗漏。superpowers 就是把这套"人类工程师的工作习惯"翻译成了 AI 能执行的技能流程。

适合谁看这篇内容？三类人。第一类是用过 Claude Code 或 Codex CLI，但觉得"也就那样"的开发者——你可能只是没装技能包，裸奔的 AI 编程工具和装了技能框架的完全是两个东西。第二类是想把 AI 编程工具真正用进生产流程的团队技术负责人——superpowers 的流程化思路对团队协作很有参考价值。第三类是纯粹好奇"agentic skills framework 到底是个啥"的技术爱好者——这篇会从安装到实战把整个链路讲透。

需要提前说明的是，superpowers 本身是开源项目，它的技能定义文件是 Markdown 格式的，这意味着你完全可以自己改、自己加。这一点很重要，后面会展开讲。

2. 核心设计思路拆解：为什么是"技能"而不是"提示词"

2.1 从提示词工程到技能框架的演进逻辑

大部分人接触 AI 编程工具的第一阶段都是"调提示词"。比如在 Claude Code 里输入"帮我写一个 Python 脚本，读取 CSV 文件并做数据清洗"，然后根据输出结果不断调整措辞。这种方式在简单任务上够用，但一旦任务复杂起来就会暴露问题：上下文丢失、步骤跳跃、验证缺失。

superpowers 的设计者显然想明白了这件事：提示词是一次性的，技能是可复用的。一个"代码审查"技能，定义好了审查的维度、顺序、输出格式，每次调用都按同样的标准执行，不会因为今天提示词写得好就审查得细，明天写得随意就审查得粗。这种一致性在工程实践里比"偶尔惊艳"重要得多。

从架构上看，superpowers 的技能定义通常包含几个部分：技能名称、触发条件、执行步骤、验证标准、输出格式。这跟人类工程师的 SOP（标准作业程序）几乎一模一样。比如一个"调试"技能，触发条件是"代码运行报错"，执行步骤是"先读错误信息 → 定位相关代码 → 提出假设 → 验证假设 → 修复 → 回归测试"，验证标准是"错误消失且原有功能不受影响"。

2.2 为什么选择 Markdown 作为技能定义格式

superpowers 的技能文件用的是 Markdown，不是 JSON、不是 YAML、也不是什么专门的 DSL。这个选择乍看随意，实际上很讲究。

Markdown 的优势在于人和 AI 都能读。JSON 和 YAML 对机器友好，但人写起来容易出错，尤其是步骤描述这种需要自然语言表达的内容。Markdown 则天然适合写"流程说明"——标题分级、有序列表、代码块、引用块，这些元素刚好对应技能定义需要的结构。而且 Claude Code 和 Codex CLI 本身就是在大量 Markdown 语料上训练的，对 Markdown 结构的理解非常到位。

另一个好处是可版本控制。技能文件就是普通的文本文件，可以放进 Git 仓库，可以 diff，可以 code review。团队里谁改了什么技能、为什么改，一目了然。这比把提示词存在某个平台的数据库里要透明得多。

2.3 与 Claude Code、Codex CLI 的协作关系

这里需要理清一个容易混淆的点：superpowers 和 Claude Code、Codex CLI 不是竞争关系，而是互补关系。

Claude Code 和 Codex CLI 提供的是"能力底座"——模型调用、文件读写、命令执行、上下文管理。superpowers 提供的是"工作方法"——在什么场景下按什么流程使用这些能力。打个比方，Claude Code 是一把功能齐全的瑞士军刀，superpowers 是一本"什么情况下用哪个刀片"的使用手册。

实际运行时，superpowers 的技能会被注入到 Claude Code 或 Codex CLI 的上下文中。当你的指令触发了某个技能的条件，AI 就会按照技能定义的流程来执行，而不是自由发挥。这就是为什么装了 superpowers 之后，AI 的行为会变得"更有章法"。

注意：superpowers 的技能注入会占用上下文窗口。如果你的任务本身就需要大量上下文（比如分析一个大型代码库），技能定义太多反而会挤占空间。建议按需启用，不要一股脑全开。

3. 安装与配置实操：从零把环境跑起来

3.1 Claude Code 的安装与基础配置

先说 Claude Code 的安装。不同系统下的方式不太一样，我按自己实际折腾过的顺序讲。

macOS 和 Linux 下最省事的方式是通过 npm 全局安装。前提是你机器上已经有 Node.js 环境，建议版本在 18 以上。命令很简单：

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

装完之后在终端输入claude就能启动。第一次启动会引导你做认证配置，按提示走就行。

Windows 下稍微麻烦一点。原生 Windows 终端对这类 CLI 工具的支持一直不太理想，我的建议是直接用 WSL2。在 WSL2 的 Ubuntu 环境里按上面的 npm 方式装，体验和 Linux 一致。如果你非要在原生 Windows 下跑，需要确保 Node.js 和 npm 都在 PATH 里，然后用 PowerShell 执行同样的 npm 命令。实测下来原生 Windows 偶尔会有路径分隔符的问题，WSL2 省心得多。

Ubuntu 下如果 npm 全局安装遇到权限问题，不要用sudo npm install -g，那样容易把全局目录的权限搞乱。正确做法是配置 npm 的用户级全局目录：

mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc

然后再执行安装命令，就不需要 sudo 了。

VS Code 里用 Claude Code 的话，直接在集成终端里跑claude就行，不需要额外装插件。有些人会去装所谓的"Claude Code 插件"，其实没必要，集成终端已经够用了。

3.2 Codex CLI 的安装与常见报错处理

Codex CLI 的安装逻辑类似，但坑稍微多一点。最常见的报错就是那个unable to locate the codex cli binary or required runtime components。这个错误的意思是：系统找不到 codex 的可执行文件，或者缺少运行时依赖。

排查顺序是这样的。第一步，确认 codex 是否真的装上了：

which codex codex --version

如果which codex没有输出，说明根本没装上，或者装了但不在 PATH 里。这时候检查 npm 的全局 bin 目录是否在 PATH 中。第二步，如果which codex有输出但codex --version报错，那多半是运行时依赖缺失。Codex CLI 依赖 Node.js 运行时，确认一下node --version是否正常。

Windows 下这个报错尤其常见，因为 Windows 的 PATH 管理和 Unix 差异很大。我的经验是：在 WSL2 里装，基本不会遇到这个问题。如果必须在原生 Windows 下用，装完之后手动把 npm 全局目录加到系统环境变量里，然后重启终端。

Codex CLI 的更新也很简单：

npm update -g @openai/codex

或者直接重新安装最新版。更新完之后建议清一下缓存，避免旧版本残留导致行为异常。

3.3 superpowers 的安装与技能加载

superpowers 的安装方式取决于你用的是哪个宿主工具。它的核心是一组技能定义文件，安装的本质就是把这些文件放到宿主工具能读取的位置。

对于 Claude Code，技能文件通常放在项目根目录的.claude/skills/目录下，或者用户级的~/.claude/skills/目录下。项目级的技能只对当前项目生效，用户级的对所有项目生效。我的建议是：通用技能放用户级，项目特定技能放项目级。

安装步骤大致是：从 superpowers 的仓库克隆或下载技能文件，然后复制到对应目录。具体命令取决于你获取文件的方式，如果是 Git 仓库：

git clone <superpowers-repo-url> cp -r superpowers/skills/* ~/.claude/skills/

对于 Codex CLI，技能加载机制类似，但目录路径可能不同，需要参考 Codex CLI 的文档确认。有些版本的 Codex CLI 支持通过配置文件指定技能目录，这种方式更灵活。

装完之后怎么验证技能是否加载成功？在 Claude Code 里输入一个会触发技能的场景，观察它的行为是否符合技能定义的流程。比如你输入"帮我审查这段代码"，如果它按照"先看整体结构 → 再查边界条件 → 再看错误处理 → 最后给修改建议"的顺序来，说明审查技能加载成功了。

提示：手动安装 GitHub 上的 skills 时，注意技能文件之间的依赖关系。有些技能会引用其他技能，如果只复制了部分文件，运行时可能报"找不到引用的技能"。最稳妥的做法是整个 skills 目录一起复制。

4. 技能框架的实战用法：把 AI 编程工具用出"章法"

4.1 需求拆解技能：让 AI 先想清楚再动手

裸奔状态下的 Claude Code 有个通病：你说什么它做什么，但不会主动帮你把模糊需求变清晰。比如你说"帮我做个用户管理模块"，它可能直接就开始写代码了，但用户管理到底包含哪些功能、用什么数据库、要不要权限控制，这些它都没问。

superpowers 里的需求拆解技能就是解决这个问题的。触发之后，AI 会先跟你确认需求边界，然后输出一个任务清单，每个任务都有明确的输入输出定义。这个过程很像一个靠谱的技术 leader 在接需求时的做法：先问清楚，再拆细，最后才动手。

我实际用下来的感受是，这个技能最大的价值不是"拆得有多细"，而是"逼着你想清楚"。很多时候我们自己提需求也是模糊的，AI 反问几句之后，需求自然就清晰了。

4.2 代码实现技能：分步骤执行与自我验证

代码实现技能的核心是"小步快跑 + 每步验证"。它不会一次性生成几百行代码然后让你自己测，而是把实现拆成若干小步骤，每完成一步就做一次验证。

具体流程通常是：先写接口定义 → 验证接口是否合理 → 写核心逻辑 → 跑单元测试 → 处理边界情况 → 再跑测试 → 重构。每一步都有明确的验证标准，不通过就不进入下一步。

这种方式的优势在于问题定位快。如果最终结果有问题，你能很快知道是哪一步出的问题，而不是面对一大坨代码无从下手。劣势是整体耗时可能更长，因为验证本身要花时间。但对于复杂功能来说，这个时间花得值。

4.3 调试排查技能：系统化定位问题

调试是 superpowers 里我觉得最实用的技能之一。它的流程是：读错误信息 → 定位相关代码 → 提出假设 → 设计验证方法 → 执行验证 → 根据结果修正假设 → 循环直到找到根因 → 修复 → 回归测试。

这个流程听起来很"教科书"，但实际用起来效果很好。因为人在调试时容易跳步，看到报错就凭直觉改代码，改完发现不对再改，来回折腾。技能框架强制你按顺序走，反而更快。

我遇到过一个典型案例：一个 Python 脚本偶尔报编码错误，但不是每次都报。裸奔状态下 AI 可能会直接建议加encoding='utf-8'，但用了调试技能之后，它会先分析"为什么是偶尔报错"，然后定位到是某个特定输入触发的，最后发现是读取文件时没有指定编码，而系统默认编码在不同环境下不一致。根因找到了，修复方案自然就对了。

4.4 代码审查技能：多维度检查清单

代码审查技能会从几个固定维度检查代码：正确性、边界条件、错误处理、性能、可读性、安全性。每个维度都有具体的检查点。

比如边界条件这一项，它会检查：空输入怎么处理、超大输入怎么处理、非法输入怎么处理、并发场景怎么处理。这些检查点都是预先定义好的，不会遗漏。

实际用的时候，你可以把它当成一个"永远不会累的初级审查员"。它不会替代人工审查，但能帮你过滤掉大量低级问题，让人工审查聚焦在架构和业务逻辑上。

5. 常见问题与排查技巧实录

5.1 安装类问题速查

5.2 运行时的典型坑

第一个坑是上下文溢出。技能定义会占用上下文，如果同时启用太多技能，再加上你的代码文件，很容易超出模型上下文窗口。表现是 AI 开始"忘事"，前面说过的内容后面就不记得了。解决办法是按需启用技能，或者把大文件拆成小块处理。

第二个坑是技能冲突。如果两个技能对同一场景有不同的处理流程，AI 可能会困惑。比如一个技能说"先写测试再写实现"，另一个说"先写实现再补测试"，同时触发就会打架。解决办法是理清技能的优先级，或者在技能定义里明确适用场景。

第三个坑是过度流程化。有些简单任务其实不需要走完整流程，比如改一个变量名，没必要触发需求拆解技能。这时候需要手动干预，告诉 AI"这个任务很简单，直接改就行"。

5.3 性能与体验优化建议

技能文件不要写得太长。一个技能定义控制在 200 行以内比较合适，太长了 AI 读取和理解都会变慢。如果流程确实复杂，拆成多个技能，用主技能引用子技能的方式组织。

定期清理不用的技能。装了一堆技能但从来不用，除了占上下文没有任何好处。我一般每个月回顾一次，把过去一个月没触发过的技能删掉。

技能定义里的步骤描述要具体，不要用"检查代码质量"这种模糊表述，要用"检查是否有未处理的异常、是否有硬编码的密钥、是否有明显的性能问题"这种可执行的描述。AI 对具体指令的执行效果远好于模糊指令。

6. 我踩过的坑和几条实在建议

折腾 superpowers 这段时间，最大的体会是：技能框架的价值不在于让 AI 变聪明，而在于让 AI 变稳定。裸奔的 Claude Code 有时候表现惊艳，有时候让人抓狂，波动很大。装了技能框架之后，上限可能没提高多少，但下限明显抬高了，这对工程实践来说更重要。

另一个体会是，不要指望装完就万事大吉。技能框架需要调优，需要根据你的实际工作流去改技能定义。superpowers 提供的是"一套可用的默认值"，但每个团队、每个人的工作习惯不同，默认值不一定适合你。花点时间改技能文件，回报比想象中大。

还有一点：技能框架不能替代基本功。它能让 AI 帮你把流程走得更规范，但流程本身对不对、技术方案合不合理，还是得靠人来判断。我见过有人把 superpowers 当成"银弹"，觉得装上之后 AI 就能自动写出生产级代码，结果发现该出的问题还是出。工具是放大器，放大的是你原本的能力，不是凭空创造能力。

最后分享一个实用技巧：把你最常重复的提示词固化成技能。比如你每次让 AI 写代码前都要说"先写接口定义，再写实现，最后写测试"，那就把这个流程写成一个技能文件。下次直接触发技能，不用再重复输入。这个习惯坚持下来，效率提升很明显。