1. 从"superpowers"这个词说起：它到底指什么
第一次看到"superpowers"这个词，很多人会以为是某个超级英雄题材的游戏或者影视项目。但在开发者圈子里，尤其是近一年围绕 AI 编程助手生态的讨论中，superpowers 指的是一套面向 AI 编程代理的技能框架（agentic skills framework），它试图回答一个非常实际的问题：当 AI 已经能写代码、能跑命令、能读文件之后，怎么让它像一名有经验的工程师那样，按一套稳定的方法论去推进软件任务，而不是每次都给出一堆看似合理、实际跑不通的片段。
我最初接触这套东西，是因为在 Claude Code 和 Codex CLI 这两个命令行 AI 编程工具之间来回切换时，发现同一个需求，换个工具、换个会话，输出质量波动极大。有时候它能一口气把一个模块从设计到测试全部搞定，有时候连项目结构都没搞清楚就开始瞎改文件。后来才意识到，问题不在于模型本身，而在于缺少一套约束 AI 行为的"技能层"。superpowers 就是干这个的——它把软件开发的常见动作拆成一个个可复用的技能单元，让 AI 代理在合适的时机调用合适的技能，从而把"随机发挥"变成"按流程办事"。
这套框架的核心价值，可以概括成三点。第一，它把软件工程方法论显式地写成了 AI 能理解的指令集，比如需求澄清、方案对比、增量实现、测试先行、回归验证这些环节，都有对应的技能描述。第二，它强调技能的可组合性，一个复杂任务可以被拆成若干技能按顺序执行，而不是让模型一次性生成几百行代码。第三，它天然适配多种 AI 编程工具，Claude Code、Codex CLI 这类支持技能或插件机制的 CLI 工具，都能挂载这套框架。
适合谁来了解？如果你已经在用 Claude Code 或 Codex CLI 写代码，但总觉得"AI 不够听话""改着改着就跑偏了"，那这套东西值得花时间研究。如果你还没上手这类工具，只是想搞清楚 AI 编程代理到底怎么用才靠谱，那把它当成一个"方法论样板"来看也很有价值。下面我会从安装配置、技能机制、实际使用、常见故障排查几个角度，把我知道的、踩过的、验证过的都摊开讲。
2. 环境准备：Claude Code 与 Codex CLI 的安装差异
2.1 两个工具定位不同，别混为一谈
很多人把 Claude Code 和 Codex CLI 当成同一类东西，其实它们的定位有细微差别。Claude Code 更像是一个深度集成在终端里的 AI 编程助手，它强调对项目上下文的持续理解，支持技能（skills）机制，能读取项目里的配置文件来决定行为。Codex CLI 则更偏向轻量级的命令行代理，启动快、依赖少，适合快速执行单次任务或者脚本化调用。
这个差异直接影响到 superpowers 的挂载方式。Claude Code 有比较成熟的技能目录约定，你把手写的技能文件放到指定位置，它就能识别；Codex CLI 的技能支持相对更依赖运行时的参数和配置。所以如果你打算两个工具都用，建议先想清楚主用哪个，另一个作为补充。
2.2 Claude Code 安装：几个容易卡住的点
在 Ubuntu 上装 Claude Code，最常见的做法是通过包管理器或者官方提供的安装脚本。这里有个经验：不要一上来就装最新版。我遇到过好几次新版刚发布时依赖没对齐，装完启动报错，回退到上一个稳定版反而一切正常。所以我的习惯是先查一下当前稳定版本号，再指定版本安装。
安装完成后，第一件事是验证命令能不能跑起来：
claude --version如果提示找不到命令，八成是安装路径没进 PATH。这时候别急着重装，先看看安装脚本把二进制放哪了，通常是在用户目录下的隐藏文件夹里，手动加一下环境变量就行。
Windows 用户要注意，Claude Code 在 Windows 上的支持一直是个话题。原生 Windows 环境下有些依赖行为跟 Linux 不一致，我个人的建议是优先用 WSL，也就是在 Windows 里跑一个 Linux 子系统，然后在子系统里按 Ubuntu 的方式装。这样能避开大量路径和权限相关的怪问题。如果你非要在原生 Windows 上装，那就做好心理准备，遇到报错先搜错误信息里的关键词，多半有人踩过同样的坑。
还有一个高频问题：启动时提示"当前地区可能不支持"。这个提示本身只是工具的地区检测逻辑，遇到这种情况，先确认自己的网络环境和账号状态是否正常，然后检查工具版本是不是太旧。很多时候升级到最新稳定版，或者换一个网络环境，提示就消失了。我不建议在这上面花太多精力折腾，工具能用就行，重点是后面的技能配置。
2.3 Codex CLI 安装：那个让人头疼的报错
Codex CLI 安装过程中，有一个报错几乎人人都会遇到：
unable to locate the codex cli binary or required runtime components. check这个报错的意思是：系统找不到 codex 的可执行文件，或者缺少运行时组件。我第一次遇到时也懵了，明明刚装完，怎么就找不到了。后来排查发现，原因通常有三类。
第一类是安装没真正完成。有些安装方式只是下载了包，但没有把二进制链接到全局路径。这时候你需要手动确认二进制文件的位置，然后建一个软链接，或者把所在目录加到 PATH 里。
第二类是运行时组件缺失。Codex CLI 依赖某些系统库，尤其是在比较干净的 Ubuntu 环境或者 Docker 容器里，这些库可能没预装。解决办法是根据报错信息里提到的组件名，用系统包管理器补装。
第三类是版本冲突。如果你之前装过旧版，新版装完后系统里存在多个版本，调用时可能指向了错误的那个。这时候需要先彻底卸载旧版，清理残留配置，再重新安装。
在 Windows 上装 Codex CLI，情况类似但更麻烦一些。我的建议还是那句话：能用 WSL 就用 WSL。原生 Windows 下，路径分隔符、权限模型、环境变量加载顺序都跟 Linux 不一样，同样的安装步骤可能结果完全不同。如果你确实需要在原生 Windows 上用，装完之后务必用where codex确认一下实际调用的是哪个文件。
2.4 更新与卸载：别留下垃圾
Codex CLI 的更新，不同安装方式对应不同命令。用包管理器装的，走包管理器的更新流程；用脚本装的，可能需要重新跑一遍安装脚本。这里有个坑：更新前先记下当前版本号，万一新版有问题，方便回退。
卸载这件事，很多人装完就不管了，结果系统里堆了好几个版本，环境变量指向混乱。我的做法是，卸载时不仅删二进制，还要清理配置目录和缓存目录。这些目录通常在用户主目录下，名字里带工具名，删之前确认一下里面没有你自定义的技能文件或者重要配置。
Claude Code 的卸载同理。如果你在里面配置过技能、改过默认行为，卸载前先把这些配置备份出来，不然重装后又要从头配一遍。
3. superpowers 技能框架的核心机制
3.1 技能不是插件，是"行为约束"
理解 superpowers 的关键，是搞清楚"技能"到底是什么。很多人第一反应是把它当成插件——装上就多几个功能。但实际上，技能更像是一份写给 AI 看的操作手册。它不增加工具本身的能力，而是告诉 AI：遇到这类任务时，你应该按什么步骤做，先做什么后做什么，哪些事情不能做。
举个例子，一个"需求澄清"技能可能会这样描述：当用户提出一个模糊需求时，不要立刻开始写代码，而是先列出三到五个关键问题，确认清楚输入输出、边界条件、性能要求，然后再进入设计阶段。这种约束看起来简单，但效果非常明显——AI 从"急着表现"变成了"先想清楚再动手"。
3.2 技能的组织方式与调用时机
superpowers 框架下的技能，通常按开发阶段或者任务类型来组织。按阶段分，可以有需求分析、方案设计、编码实现、测试验证、文档整理这几大类；按任务类型分，可以有重构、调试、性能优化、代码审查这些。具体怎么分，取决于你的项目习惯。
调用时机是另一个关键点。技能不是越多越好，也不是每个任务都要把所有技能跑一遍。我的经验是，把技能分成"必选"和"可选"两档。必选的是那些每次都要走的流程，比如需求确认和测试验证；可选的是针对特定场景的，比如处理遗留代码时才用的重构技能。这样既保证了基本质量，又不会让流程变得臃肿。
3.3 为什么这套框架能提升输出稳定性
回到最开始的问题：为什么加了技能层之后，AI 的输出就稳定了？我的理解是，它把隐式的工程经验变成了显式的执行步骤。大模型本身是概率性的，你给它一个模糊指令，它会在无数种可能的输出里采样，结果自然波动大。但如果你给它一份明确的步骤清单，它的采样空间就被大幅压缩了，输出自然更可控。
这就像带新人。你只说"把这个功能做了"，他可能给你一堆能跑但结构混乱的代码；但如果你说"先写接口定义，再写单元测试，测试通过后再实现，最后补文档"，他做出来的东西质量就完全不一样。superpowers 干的就是把后面这种带教方式固化下来。
4. 把 superpowers 用起来：从配置到实战
4.1 技能文件的存放位置与格式
Claude Code 识别技能，靠的是约定目录。通常是在项目根目录或者用户主目录下，有一个专门的技能文件夹，里面每个技能是一个独立文件，用 Markdown 或者特定格式的文本描述。文件名一般就代表技能名，内容里写清楚这个技能解决什么问题、什么时候用、具体步骤是什么。
我建议项目级技能和用户级技能分开。项目级的放在项目目录里，跟着代码一起版本管理，团队共享；用户级的放在主目录下，是你个人的通用习惯，不跟项目绑定。这样换项目时，通用技能还在，项目特有的技能也不会污染其他项目。
技能文件的写法，我的经验是越具体越好。不要写"优化代码质量"这种空话，要写"检查函数是否超过五十行，如果超过，拆分成职责单一的小函数；检查是否有重复代码块，如果有，提取成公共方法"。具体的指令，AI 执行起来才不容易跑偏。
4.2 在 Claude Code 里挂载技能
在 Claude Code 里用 superpowers，基本流程是：先把技能文件放到约定目录，然后启动 Claude Code，它会自动扫描并加载。加载成功后，你可以在会话里通过特定指令触发某个技能，或者让 AI 根据任务类型自动选择。
这里有个实操细节：技能加载是有顺序的。如果两个技能描述有冲突，后加载的可能会覆盖先加载的。所以如果你发现某个技能没生效，先检查是不是被别的技能覆盖了。解决办法是调整文件命名或者目录结构，让优先级符合你的预期。
另外，技能不是加载了就一定会用。AI 会根据当前任务判断该不该调用某个技能。如果你发现它该用的时候没用，可以在指令里显式点名，比如"请用需求澄清技能处理这个需求"。多试几次，你就知道哪些技能需要显式触发，哪些可以放心让它自动判断。
4.3 在 Codex CLI 里使用技能
Codex CLI 的技能使用方式跟 Claude Code 略有不同，它更依赖运行时参数。你可以在启动命令里指定技能目录，或者在配置文件里写好默认技能路径。具体参数名各版本可能有差异，建议以你安装版本的帮助文档为准。
我的做法是，把常用技能路径写进 shell 的别名或者脚本里，这样每次启动不用重复输入一长串参数。比如定义一个别名，把技能目录、模型选择、输出格式这些常用配置都带上，用起来就顺手多了。
Codex CLI 还有一个特点是适合脚本化调用。你可以把它嵌到 CI 流程或者自动化脚本里，让它在特定环节执行代码审查或者生成测试。这时候技能的作用就更明显了——它保证了每次自动化调用的行为是一致的，不会这次严格下次宽松。
4.4 一个完整的实战流程示例
假设你要给一个现有项目加一个新功能。用 superpowers 的流程大概是这样：
第一步，触发需求澄清技能。AI 会问你几个关键问题：这个功能的输入是什么，输出是什么，有没有性能要求，跟现有模块怎么交互。你回答完，它整理成一份简短的需求说明。
第二步，触发方案设计技能。AI 基于需求说明，给出两到三个实现方案，分别说明优缺点和适用场景。你选一个，或者让它综合一下。
第三步，触发测试先行技能。AI 先写测试用例，覆盖正常流程和边界情况。这时候测试是跑不过的，因为功能还没实现。
第四步，触发增量实现技能。AI 按测试用例逐个实现功能，每实现一部分就跑一次测试，确保不破坏已有功能。
第五步，触发回归验证技能。功能全部实现后，跑一遍完整测试套件，确认没有引入回归问题。
第六步，触发文档整理技能。AI 更新相关文档，说明新功能的用法和注意事项。
这套流程走下来，比直接让 AI"把功能做了"要慢一些，但产出质量高得多，而且后续维护成本低。我自己的体会是，前期多花十分钟澄清和设计，后期能省下几个小时的调试和返工。
5. 踩坑实录：那些让我折腾半天的故障
5.1 技能不生效的排查链路
技能配好了，但 AI 就是不用，这是最常见的问题。我的排查顺序是这样的：
先确认技能文件真的被加载了。Claude Code 一般会在启动时打印加载信息，或者有专门的命令查看已加载技能列表。如果列表里没有你的技能，那就是路径或者格式问题。
再确认技能格式正确。有些格式要求比较严格，比如必须有特定的头部字段，或者标题层级有规定。格式不对，文件在但加载失败，表现就是技能不生效。
然后确认没有冲突。前面说过，技能加载有顺序，冲突时可能被覆盖。把技能文件暂时移走几个，只留一个测试，能快速定位是不是冲突问题。
最后确认触发条件。有些技能需要显式调用，有些需要任务类型匹配。如果 AI 判断当前任务不需要这个技能，它就不会用。这时候要么显式点名，要么调整技能描述，让它覆盖更多场景。
5.2 Codex CLI 找不到二进制的完整解决过程
回到那个经典报错。我完整走一遍排查过程，你可以照着复现。
第一步，确认安装是否真的完成。检查安装目录下有没有可执行文件，文件名对不对。有时候安装脚本下载了一半失败了，但没报错，你以为装好了，其实文件是残缺的。
第二步，确认 PATH 配置。用echo $PATH看看安装目录在不在里面。不在的话，手动加进去，然后重新打开终端或者 source 一下配置文件。
第三步，确认运行时组件。如果报错信息里提到了具体组件名，用系统包管理器查一下装没装。没装就补上，装了就检查版本对不对。
第四步，确认没有多版本冲突。用which -a codex看看系统里有几个 codex，实际调用的是哪个。如果指向了旧版，把旧版清理掉。
第五步，如果以上都排除了，试试重新安装。但重装前一定要彻底卸载，包括配置和缓存目录，不然残留文件可能继续干扰。
这套流程走下来，九成以上的"找不到二进制"问题都能解决。剩下那一成，通常是系统环境本身有问题，比如权限配置异常或者系统库损坏，那就需要更底层的排查了。
5.3 地区提示与网络环境的处理思路
启动时看到地区相关的提示，先别慌。这类提示通常是工具的检测逻辑触发的，不代表工具不能用。我的处理思路是：先确认工具版本是不是最新稳定版，旧版可能检测逻辑有 bug；再确认网络环境是否正常，有些检测依赖外部服务，网络不通时会误报；最后如果提示不影响实际使用，就忽略它，把精力放在功能上。
我不建议为了消除一个提示去折腾系统配置，性价比太低。工具的核心价值是帮你写代码，只要这个功能正常，其他都是次要的。
5.4 技能写得太"聪明"反而坏事
这是我踩过的一个比较隐蔽的坑。一开始写技能，总想写得全面一点、智能一点，结果技能描述里塞了太多条件判断和分支逻辑，AI 执行时反而无所适从，经常在某个分支上卡住或者做出奇怪的选择。
后来我学乖了，一个技能只干一件事，描述尽量线性。需要多个步骤的，拆成多个技能，按顺序调用。这样每个技能都简单明确，AI 执行起来成功率高，出问题也容易定位是哪个环节的锅。
这个经验其实适用于所有跟 AI 协作的场景：你给它的指令越简单直接，它的表现越稳定。复杂的逻辑判断，留给你自己来做，让 AI 做它擅长的执行部分。
6. 进阶玩法：把 superpowers 融进日常工作流
6.1 跟版本控制结合
技能文件本身应该纳入版本控制。项目级的技能跟着项目走，每次技能调整都有记录，团队成员拉下来就能用同一套流程。用户级的技能可以单独建一个仓库管理，换机器时同步过去。
我还会在提交信息里标注这次改动用了哪些技能，比如"用重构技能整理了 utils 模块"。这样回头看历史时，能清楚知道哪些改动是走了标准流程的，哪些是临时发挥的。时间长了，你会发现走流程的改动，后续出问题的概率明显更低。
6.2 团队协作中的技能共享
团队里推广 superpowers，最大的阻力不是技术，是习惯。大家都习惯了直接让 AI 干活，突然要按流程走，会觉得麻烦。我的做法是先从痛点场景切入。比如团队经常遇到 AI 生成的代码没测试，那就先推测试先行技能，让大家看到效果——测试覆盖上去了，线上问题少了，自然就愿意用更多技能。
技能文件本身也要有维护机制。定期回顾哪些技能用得多、哪些从来没用过，没用的删掉，常用的优化描述。技能库跟代码库一样，需要持续清理，不然会越来越臃肿。
6.3 针对不同项目类型的技能组合
不同类型的项目，适合的技能组合不一样。Web 后端项目，重点在接口设计、数据库操作、错误处理这几块；前端项目，重点在组件拆分、状态管理、样式组织；数据处理项目，重点在输入校验、异常处理、结果验证。
我的建议是先建一套通用技能，再针对项目类型加专用技能。通用技能包括需求澄清、测试先行、增量实现这些，哪个项目都用得上。专用技能按项目类型配，不用一开始就求全，用着用着发现缺什么再补。
6.4 技能效果的评估与迭代
怎么知道技能有没有用？我的方法是记录关键指标。比如用了测试先行技能之后，测试覆盖率变化多少；用了重构技能之后，代码复杂度指标变化多少；用了需求澄清技能之后，返工次数变化多少。
这些数据不用很精确，有个大致趋势就行。如果某个技能用了一段时间，指标没变化甚至变差了，那就要检查是技能本身有问题，还是使用方式不对。技能不是写完就完事，需要根据实际效果持续迭代。
7. 一些零散但有用的经验
关于 Claude Code 的存储位置，配置和缓存一般在用户主目录下的隐藏文件夹里。如果你要迁移环境或者备份配置，找到这个目录整体拷走就行。注意里面可能有跟机器绑定的信息，换机器后可能需要重新登录或者重新授权。
关于在 VSCode 里配置 Claude Code，核心是把终端环境配好，让 VSCode 的集成终端能调用到 claude 命令。如果 VSCode 里调不到，但系统终端里可以，通常是 VSCode 的环境变量加载方式跟系统终端不一样。解决办法是在 VSCode 设置里指定终端的环境变量，或者用登录 shell 启动终端。
关于 Claude Code 接入其他模型服务，这属于进阶配置，涉及 API 地址和密钥的设置。我的建议是，如果你对这块不熟，先用默认配置跑通基本流程，等熟悉了再折腾模型切换。切换模型可能影响技能的执行效果，换之前最好在测试项目上验证一下。
关于手动安装 GitHub 上的技能，流程一般是下载技能文件，放到技能目录，然后重启工具让它重新加载。注意检查技能文件的格式跟你用的工具版本是否匹配，版本不匹配可能导致加载失败。
关于上下文长度，不同工具和模型的支持范围不一样。长上下文适合处理大项目或者长文档，但也不是越长越好。上下文太长时，AI 的注意力会被分散，关键信息反而容易被忽略。我的做法是按需提供上下文，当前任务涉及哪些文件就给哪些文件，不要一股脑全塞进去。
最后说一个心态上的经验。superpowers 这类框架，本质是帮你把工程经验固化下来，它不能替代你的判断。技能写得再好，也需要你根据实际情况调整。把它当成一个靠谱的助手，而不是一个全能的替身，用起来会舒服很多。我见过一些人，装了框架之后就完全放手，结果 AI 按流程走完，产出看着挺规范，但方向从一开始就错了。流程能保证执行质量，但方向对不对，还是得你自己把关。