1. 从“superpowers”这个标题说起：它到底指什么
第一次看到“superpowers”这个词，很多人会以为是某个超级英雄题材的游戏或者娱乐项目。但如果你最近在开发者社区里泡过，就会发现它其实指向一个很具体的东西——一套围绕 AI 编程助手构建的智能体技能框架（agentic skills framework）。它的核心思路是：把软件开发方法论拆解成一个个可复用的“技能包”，让 AI 编程助手在写代码时不只是“补全下一行”，而是能按照一套结构化的流程去理解需求、拆解任务、编写实现、验证结果。
这个框架最早是在 Claude Code 和 Codex CLI 这两个 AI 编程工具的使用场景中被频繁提及的。Claude Code 是 Anthropic 推出的命令行编程助手，Codex CLI 则是 OpenAI 生态下的命令行工具。两者都支持通过“技能”或“插件”的方式扩展能力边界，而 superpowers 就是在这个扩展层上做文章——它提供了一套预定义的技能集合，覆盖从需求分析、代码生成、测试编写到重构建议的完整开发链路。
为什么这个标题值得单独拿出来讲？因为大多数人对 AI 编程助手的理解还停留在“你问它答”的层面，而 superpowers 代表的是一种更系统化的用法：把 AI 当成一个需要被“编排”的团队成员，而不是一个随叫随到的代码搜索引擎。这个思路的转变，直接决定了你是在“用 AI 写代码”还是在“用 AI 做工程”。
我最初接触这个概念时，也是半信半疑。毕竟市面上各种“AI 编程神器”的噱头太多了，真正能落地的没几个。但实际用下来发现，superpowers 这套框架的价值不在于它提供了多少炫酷的功能，而在于它把“怎么让 AI 稳定地产出可用代码”这件事，从玄学变成了有章可循的流程。接下来我会从它的核心机制、安装配置、实际使用中的坑和技巧几个维度，把这件事讲透。
2. superpowers 框架的底层逻辑：为什么需要“技能”这层抽象
2.1 直接让 AI 写代码的问题在哪里
很多人用 Claude Code 或 Codex CLI 的方式很直接：打开终端，输入一句“帮我写一个用户登录功能”，然后等着 AI 吐出一大段代码。这种方式在简单场景下确实能用，但一旦项目稍微复杂一点，问题就暴露了。
第一个问题是上下文漂移。AI 在生成长代码时，很容易忘记前面定义的接口规范或者变量命名约定，写着写着就“跑偏”了。第二个问题是缺乏验证闭环。AI 生成的代码对不对、能不能跑，它自己不知道，你如果不手动测试，很可能拿到一堆看起来像模像样但实际有 bug 的代码。第三个问题是不可复现。同样的需求，你今天问它和明天问它，得到的代码结构可能完全不同，这在团队协作中几乎是灾难。
superpowers 要解决的就是这三个问题。它的做法是：把“写代码”这件事拆成多个阶段，每个阶段对应一个“技能”，每个技能有明确的输入输出规范和执行步骤。AI 在执行时不是自由发挥，而是按照技能定义的流程走，这样就大大降低了随机性。
2.2 技能框架的核心组成
从实际使用来看，superpowers 的技能框架大致包含以下几个层面的抽象：
技能定义层：每个技能是一个结构化的描述文件，里面写清楚了这个技能叫什么、解决什么问题、需要什么输入、产出什么结果、执行步骤是什么。这有点像给 AI 写了一份“操作手册”，告诉它遇到这类任务时应该按什么顺序做什么事。
上下文管理层：框架会维护一个项目级的上下文，包括代码库的结构、已有的接口定义、命名规范等。当 AI 执行某个技能时，它会先读取这些上下文，确保生成的代码和现有项目保持一致。
验证反馈层：每个技能执行完后，框架会触发一轮验证，比如运行测试、检查语法、对比接口签名等。如果验证不通过，AI 会收到反馈并尝试修正，而不是直接把有问题的代码丢给你。
组合编排层：多个技能可以组合成一个工作流。比如“实现一个新功能”这个工作流可能包含“分析需求”“设计接口”“编写实现”“编写测试”“运行验证”五个技能，它们按顺序执行，前一个的输出是后一个的输入。
这套抽象的价值在于，它把 AI 编程从“单次对话”变成了“流程执行”。你不再需要每次都想清楚怎么问 AI，而是定义好流程，让 AI 按流程走。这对于需要反复执行的开发任务来说，效率提升非常明显。
2.3 和传统代码生成工具的本质区别
有人可能会问：这不就是代码模板或者代码生成器吗？区别在于，传统的代码生成器是基于规则的，你输入参数，它按固定模板输出。而 superpowers 是基于 AI 的，它能理解自然语言描述的需求，能根据上下文调整输出，能在验证失败时自主修正。
另一个区别是适应性。传统代码生成器只能处理它被设计来处理的那类任务，换个场景就不行了。而 superpowers 的技能是可以自定义和扩展的，你可以根据自己项目的技术栈和规范，写一套专属的技能定义，让 AI 按照你的方式来写代码。
我自己的体会是，superpowers 更像是一个“AI 编程的操作系统”，它提供了一套基础能力，具体的“应用”需要你自己去搭建。这也是为什么它的学习曲线比直接用 Claude Code 要陡一些，但一旦搭好了，后续的收益是持续的。
3. 环境搭建：Claude Code 与 Codex CLI 的安装与配置
3.1 安装前的准备工作
在开始安装之前，有几个前置条件需要确认。首先是运行环境，Claude Code 和 Codex CLI 都是命令行工具，理论上支持 macOS、Linux 和 Windows（通过 WSL）。如果你用的是 Windows，强烈建议在 WSL2 环境下操作，因为原生 Windows 环境下经常会遇到路径解析和权限相关的问题。
其次是账号和网络条件。这两个工具都需要连接对应的服务端才能工作，所以你需要确保网络环境能够正常访问相关服务。具体怎么配置这里不展开，但这是安装前必须解决的前提。
第三是基础工具链。你需要有 Node.js 环境（建议 18 以上版本），因为这两个工具都是通过 npm 分发的。另外，Git 也是必须的，因为 superpowers 的技能包通常是通过 Git 仓库来管理和分发的。
提示：在 Ubuntu 上安装时，建议先用
node -v和npm -v确认版本，如果 Node.js 版本过低，后续安装可能会报错。
3.2 Claude Code 的安装步骤
Claude Code 的安装相对直接。在终端中执行：
npm install -g @anthropic-ai/claude-code安装完成后，运行claude命令，它会引导你完成登录和初始化配置。第一次运行时，它会要求你授权访问，按照提示操作即可。
如果你在 Ubuntu 上遇到权限问题，可以在命令前加sudo，但更推荐的做法是配置 npm 的全局目录权限，避免每次都要提权。具体做法是：
mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' export PATH=~/.npm-global/bin:$PATH然后把上面这行 export 加到你的.bashrc或.zshrc里，这样就不用每次手动设置了。
安装完成后，你可以通过claude --version来验证是否安装成功。如果输出了版本号，说明基本环境没问题。
3.3 Codex CLI 的安装与常见报错处理
Codex CLI 的安装命令类似：
npm install -g @openai/codex但这里有一个非常常见的报错，很多人第一次装都会遇到：
unable to locate the codex cli binary or required runtime components. check这个报错的原因通常是 npm 的全局 bin 目录没有加到 PATH 里，或者安装过程中某些依赖没有正确编译。解决办法分两步：先确认npm bin -g输出的路径是否在你的 PATH 中，如果没有，手动加进去；然后重新执行安装命令，加上--force参数强制重新编译。
如果还是不行，可以尝试先卸载再重装：
npm uninstall -g @openai/codex npm cache clean --force npm install -g @openai/codex在 Windows 上安装 Codex CLI 时，如果遇到codex cli windows安装相关的问题，大概率是 WSL 和 Windows 文件系统之间的路径映射导致的。建议把项目文件放在 WSL 的文件系统内（比如/home/username/projects），而不是挂在/mnt/c/下面，这样能避免很多莫名其妙的错误。
3.4 superpowers 技能包的安装
Claude Code 和 Codex CLI 本身只是“壳”，superpowers 是跑在它们上面的技能包。安装方式通常是从 Git 仓库克隆技能定义文件到本地配置目录。
对于 Claude Code，技能文件一般放在~/.claude/skills/目录下。你可以手动创建这个目录，然后把 superpowers 的技能包克隆进去：
mkdir -p ~/.claude/skills cd ~/.claude/skills git clone <superpowers技能仓库地址>对于 Codex CLI，配置目录可能是~/.codex/skills/或类似路径，具体取决于版本。安装完成后，重启你的 CLI 工具，它应该能自动识别到新的技能。
注意：不同版本的 Claude Code 和 Codex CLI 对技能目录的路径要求可能不同，建议先查看官方文档或运行
claude --help确认。
4. 实际使用：superpowers 技能在开发流程中的落地方式
4.1 从需求到代码的完整链路
装好之后，怎么用才是关键。我拿一个实际场景来演示：假设你要在一个现有的 Java 项目里加一个“用户积分查询”接口。
不用 superpowers 的做法是：打开 Claude Code，输入“帮我写一个用户积分查询接口”，然后拿到一段代码，自己再手动调整。用 superpowers 的做法是：先调用“需求分析”技能，让 AI 读取项目现有的接口规范和数据模型，产出一份接口设计草案；然后调用“代码生成”技能，基于设计草案生成实现代码；最后调用“测试生成”技能，自动写出对应的单元测试。
这个流程的好处是每一步都有明确的输入输出，你可以随时介入调整。比如在需求分析阶段，你发现 AI 对某个字段的理解不对，可以直接修正，而不是等到代码写完才发现问题。
4.2 技能的组合与自定义
superpowers 预置的技能覆盖了常见的开发场景，但每个项目的技术栈和规范都不一样，所以自定义技能是迟早要做的事。
自定义技能的核心是写一个技能描述文件。这个文件通常是一个 Markdown 或 YAML 格式的文档，里面定义了技能的名称、触发条件、执行步骤和输出格式。比如你可以写一个“按照团队规范生成 Controller 层代码”的技能，在里面明确规定：所有接口必须返回统一的 Response 包装类、必须包含参数校验注解、必须记录操作日志。
写技能描述时有一个技巧：步骤要足够具体，但不要过于死板。太具体了，AI 没有发挥空间，遇到稍微不同的场景就卡住了；太笼统了，AI 又会自由发挥，产出不稳定。我的经验是，把“必须遵守的硬性规范”写死，把“实现细节”留给 AI 自己决定。
4.3 在 STM32 等嵌入式场景中的使用
有人可能会好奇，superpowers 这种框架能不能用在嵌入式开发上，比如 STM32 项目。答案是能，但需要做一些适配。
嵌入式开发和 Web 开发的最大区别在于：硬件相关的代码很难通过单元测试来验证，而且对代码体积和运行效率有严格要求。所以在嵌入式场景下使用 superpowers，重点要放在“代码审查”和“规范检查”类技能上，而不是“自动生成完整功能”类技能。
比如你可以定义一个技能，让 AI 检查生成的 C 代码是否符合 MISRA 规范、是否有未初始化的变量、是否有潜在的数组越界。这类静态检查类的任务，AI 做起来比人快得多，而且不容易遗漏。
5. 踩坑记录：那些文档里不会写的实际问题
5.1 技能冲突与优先级问题
当你安装了多个技能包时，可能会遇到技能冲突的情况。比如两个技能都声称能处理“代码生成”任务，AI 在执行时不知道该用哪个。
这个问题的根源在于技能匹配机制。大多数框架是根据技能描述中的关键词来匹配的，如果关键词重叠，就会出现歧义。解决办法是在技能描述中明确写上“适用场景”和“不适用场景”，让匹配更精确。另外，一些框架支持给技能设置优先级，你可以把更常用的技能设为高优先级。
5.2 上下文窗口的限制与应对
Claude Code 和 Codex CLI 都有上下文窗口的限制，虽然现在有些版本支持 1M 上下文，但在处理大型项目时，仍然可能遇到“上下文不够用”的情况。
实际使用中，我的应对策略是：不要让 AI 一次性读取整个项目，而是按需读取。比如在执行“代码生成”技能时，只让它读取相关的接口定义和数据模型文件，而不是整个代码库。这样既能保证生成的代码和现有项目一致，又不会浪费上下文空间。
另外，可以善用“摘要”类技能。让 AI 先对项目结构做一个摘要，然后在后续任务中只传递摘要而不是完整代码，这样能大幅减少上下文占用。
5.3 网络与服务可用性相关的报错
在使用过程中，你可能会遇到类似note: claude code might not be available in your country. check supported co这样的提示。这通常是因为服务端对访问来源做了限制。遇到这种情况，需要检查你的网络配置是否符合服务的使用要求。
另一个常见问题是服务超时。当 AI 处理复杂任务时，响应时间可能会比较长，如果网络不稳定，就容易超时。建议在执行复杂技能时，确保网络环境稳定，并且不要同时运行多个占用带宽的任务。
5.4 技能更新与版本兼容
superpowers 的技能包是持续更新的，但更新后可能会和你的 CLI 工具版本不兼容。我就遇到过一次：更新技能包后，Claude Code 报错说技能描述文件的格式不支持。
避免这个问题的做法是：在更新技能包之前，先查看更新日志，确认它支持的 CLI 版本范围。如果版本不匹配，要么升级 CLI 工具，要么暂时不更新技能包。另外，建议在更新前备份现有的技能配置，万一出问题可以快速回滚。
6. 进阶技巧：让 superpowers 真正融入日常开发
6.1 把技能当成团队规范来维护
superpowers 的技能定义文件，本质上就是团队开发规范的代码化表达。与其把它当成一个工具配置，不如把它当成团队知识库的一部分来维护。
具体做法是：把技能文件纳入 Git 版本管理，每次团队规范调整时，同步更新技能文件。新成员加入时，只需要安装好 CLI 工具和技能包，就能按照团队规范来使用 AI 辅助开发，不需要额外的培训。
6.2 用技能链实现复杂工作流
单个技能能解决的问题有限，真正强大的是技能链。比如你可以定义一个“功能开发”技能链，包含：需求分析 → 接口设计 → 代码实现 → 测试编写 → 代码审查 → 文档生成。每个环节的输出自动传递给下一个环节，你只需要在关键节点做确认。
这种技能链的搭建需要一些前期投入，但一旦跑通，对于重复性的开发任务，效率提升是数量级的。
6.3 监控与优化技能执行效果
技能执行的效果不是一成不变的，随着项目演进和 AI 模型更新，同一个技能的表现可能会变化。建议定期回顾技能的执行日志，看看哪些环节经常出问题，然后针对性地调整技能描述。
比如你发现“代码生成”技能经常产出不符合命名规范的变量名，那就在技能描述里把命名规范写得更明确，甚至给出正反示例。这种持续优化能让技能越来越贴合你的实际需求。
6.4 与其他工具的集成思路
superpowers 不是孤立的，它可以和现有的开发工具链集成。比如你可以把技能执行嵌入到 CI 流程中，每次提交代码时自动触发“代码审查”技能，把审查结果作为 PR 评论发出来。或者把技能和 IDE 的插件系统结合，在编辑器里直接调用。
集成的关键在于找到合适的触发点和输出格式。触发点决定了技能什么时候执行，输出格式决定了结果怎么呈现给开发者。这两点想清楚了，集成方案就自然出来了。
7. 一些个人体会和后续可探索的方向
用了一段时间 superpowers 之后，我最大的感受是：AI 编程工具的价值不在于它能不能写出代码，而在于它能不能稳定地写出符合你要求的代码。superpowers 这套技能框架，本质上是在解决“稳定性”这个问题。它通过结构化的流程和明确的规范，把 AI 的随机性限制在一个可控的范围内。
当然，它也不是银弹。技能的定义和维护需要投入精力，而且不是所有任务都适合用技能来编排。对于那些一次性的、探索性的任务，直接用自然语言和 AI 对话可能更高效。技能框架更适合那些重复性的、有明确规范的任务。
后续我打算探索的方向有两个：一是把技能框架和代码审查流程更深度地结合，让 AI 在代码提交前就完成一轮自动审查；二是尝试把技能定义标准化，看看能不能在不同 AI 编程工具之间复用同一套技能描述。这两个方向如果跑通了，应该能进一步提升日常开发的效率。
