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

第一次看到"superpowers"这个标题，很多人会以为是某个超级英雄题材的项目，或者是一个泛泛的口号式命名。但结合 agentic skills framework、software development methodology、Claude Code、Codex CLI 这几个关键词来看，它指向的其实是一个非常具体的东西：一套围绕 AI 编程代理（agentic coding）构建的技能框架与方法论。

说白了，superpowers 想解决的问题是：当 Claude Code、Codex CLI 这类命令行 AI 编程工具已经能读写文件、执行终端命令、跑测试的时候，为什么大多数人还是用不好它们？答案往往不在模型本身，而在于使用者没有一套结构化的"技能"体系——不知道该在什么场景下让代理做什么、怎么拆解任务、怎么验证结果、怎么把一次成功的操作沉淀成可复用的流程。

superpowers 就是冲着这个痛点来的。它把"如何指挥一个 AI 代理完成软件开发任务"这件事，拆成了一系列可命名、可组合、可复用的技能单元（skills），再配上一套方法论，让代理的行为从"随机发挥"变成"按套路出牌"。这套东西适合谁？适合已经在用 Claude Code 或 Codex CLI、但感觉效率忽高忽低的人；也适合刚接触 agentic 编程、想少走弯路的新手；还适合团队里想把 AI 辅助开发流程标准化的技术负责人。

需要说明的是，superpowers 本身不是一个能独立运行的软件，它更像是一层"行为规范 + 技能库"，依附在 Claude Code、Codex CLI 这类宿主工具之上。理解这一点很关键，因为后面所有的安装、配置、使用，都是围绕"如何让宿主工具加载并执行这套技能"展开的。

2. 为什么裸用 Claude Code 会让人又爱又恨

2.1 代理能力强，但"自由发挥"是双刃剑

Claude Code 这类工具最吸引人的地方，是它能直接在你的项目目录里读文件、改代码、跑命令。你一句"帮我修复这个 bug"，它真的会去翻代码、定位问题、改完再跑一遍测试。这种体验第一次用会非常震撼。

但用久了问题就来了。同一个需求，你今天让它做，它可能先写测试再改代码；明天让它做，它可能直接改代码然后忘了跑测试。任务稍微复杂一点，它就容易"跑偏"——改了一堆不该改的文件，或者在一个死胡同里反复尝试。这不是模型不行，而是缺少一个稳定的行为框架来约束它的工作方式。

2.2 技能缺失导致的典型翻车场景

我整理了几个在没有技能框架时最常遇到的翻车场景，这些也是 superpowers 想要重点解决的：

这些问题的共同点是：它们都不是靠"换个更强的模型"能解决的，而是靠流程和约束解决的。superpowers 的价值恰恰在这里——它把资深工程师脑子里的"工作习惯"显式化，变成代理可以遵循的技能。

2.3 方法论层面的缺失才是真瓶颈

很多人把注意力全放在"用哪个模型""API 怎么接"上，却忽略了更上层的东西：你让代理干活的方式，决定了产出质量的上限。一个清晰的技能框架，能让中等模型产出稳定可靠的结果；而一个混乱的指挥方式，再强的模型也会被你带沟里。superpowers 的核心主张就是这个——先把方法论立起来，工具只是执行层。

3. superpowers 的技能框架是怎么组织的

3.1 技能（skill）作为最小复用单元

superpowers 把每一个可复用的工作模式定义为一个 skill。一个 skill 通常包含几个要素：触发条件（什么情况下用这个技能）、执行步骤（具体怎么做）、验证标准（怎么算做完了）、注意事项（容易踩的坑）。

举个具体的例子，"修复 bug"这个技能可能长这样：触发条件是"用户报告了一个可复现的缺陷"；执行步骤是"先写一个能复现 bug 的测试 → 确认测试失败 → 定位根因 → 最小化修改 → 确认测试通过 → 检查是否影响其他功能"；验证标准是"复现测试从红变绿，且全量测试无回归"；注意事项是"不要顺手重构无关代码"。

这种结构的好处是，它把"经验"变成了"可传递的资产"。新人不需要自己摸索三年，直接照着技能走就行。

3.2 技能之间的组合与编排

单个技能解决单点问题，但真实开发任务是连续的。superpowers 的框架允许你把技能串起来：比如"理解需求 → 拆解任务 → 逐个实现 → 集成验证 → 收尾清理"这样一条链。每个环节调用对应的技能，前一个环节的产出作为后一个环节的输入。

这里有个关键设计：技能之间要有明确的交接物。比如"拆解任务"技能的输出是一份任务清单，"逐个实现"技能就消费这份清单。这样即使中间代理的上下文被压缩了，也能靠交接物把流程接上。这一点在长任务里特别重要，后面讲实操时会再展开。

3.3 框架与宿主工具的边界

必须说清楚：superpowers 不负责"怎么调用模型""怎么连 API"，那是 Claude Code、Codex CLI 这些宿主工具的活。superpowers 负责的是"代理拿到任务后应该怎么工作"。所以它的落地方式通常是：把技能定义成宿主工具能读取的配置文件或提示词模板，让宿主在启动或执行任务时加载。

理解这个边界，你就不会纠结"superpowers 能不能替代 Claude Code"这种问题了——它俩是互补的，一个是大脑的工作方法，一个是手脚的执行能力。

4. 在 Claude Code 与 Codex CLI 上落地这套框架

4.1 环境准备：先把宿主工具跑起来

在谈 superpowers 之前，宿主工具得先能用。Claude Code 和 Codex CLI 的安装方式各有讲究，这里说几个实操中容易卡住的点。

Claude Code 的安装，官方推荐用 npm 全局安装。Node 版本建议 18 以上，低了会在安装或运行时各种报错。如果你在国内网络环境下遇到下载慢的问题，可以配置 npm 镜像源，这个属于常规操作，能显著提速。安装完成后第一次运行需要完成账号相关的初始化流程，按提示走即可。

Codex CLI 的安装同样是 npm 路线，但很多人反馈"node 安装 codex cli 很慢"，这基本是网络问题，换镜像源或者用更稳定的网络环境就能解决。安装完可以用codex --version验证。

提示：安装类问题九成是 Node 版本和网络源的问题，先排查这两个，别急着怀疑工具本身。

4.2 让宿主加载技能：配置的三种思路

把 superpowers 的技能框架接入宿主工具，常见有三种思路，各有适用场景：

第一种是项目级配置文件。在项目根目录放一个约定好的配置文件（比如 CLAUDE.md 或类似的说明文件），把技能定义和调用规则写进去。宿主工具在项目内工作时会自动读取。这种方式适合团队协作，配置跟着代码走。

第二种是全局提示词模板。把技能框架写进宿主的全局配置里，所有项目共享。适合个人开发者，一次配置到处生效。

第三种是按需注入。不常驻加载，而是在具体任务开始时，把相关技能作为上下文喂给代理。这种方式最灵活，但需要你自己管理"什么时候注入什么技能"。

我的建议是：个人用第二种起步，团队用第一种，等熟练了再玩第三种。

4.3 一个最小可用的技能配置示例

下面给一个简化的技能配置骨架，展示它大概长什么样。注意这是基于常见实践的合理构造，不是某个官方文件的逐字复制：

# 工作技能框架 ## 技能：最小改动修复 触发：修复缺陷类任务 步骤： 1. 先写复现测试，确认失败 2. 定位根因，记录证据 3. 只改必要代码 4. 跑测试确认通过 5. 检查回归 禁止：重构无关代码、修改无关文件 ## 技能：任务拆解 触发：需求描述超过三句话 步骤： 1. 列出所有子任务 2. 标注依赖关系 3. 输出可勾选清单

这种配置的核心是把"禁止"和"必须"写清楚。代理对明确的约束响应很好，模糊的期望则容易被忽略。

4.4 验证框架是否生效

配置完别急着上大任务，先用一个小任务验证。比如故意让它修一个简单 bug，观察它是否按"先写测试"的流程走。如果它跳过了测试直接改代码，说明技能没被正确加载，回去检查配置文件的位置和格式。这个验证步骤能帮你省下大量"以为配好了其实没生效"的调试时间。

5. 把技能框架用进真实开发流程

5.1 需求理解阶段：先对齐再动手

真实开发里，最大的浪费是"做错了方向"。superpowers 框架在需求阶段的核心技能是复述与确认：让代理先用自己的话把需求复述一遍，列出它理解的边界和不确定点，等你确认后再动手。

这个动作看起来多余，但实测能挡掉大量返工。代理理解偏了，你在它动手前就能发现，而不是等它改完一堆文件才反应过来。

5.2 任务拆解与进度追踪

复杂任务一定要拆。框架里的拆解技能会要求代理输出一份带勾选框的任务清单，每完成一项就标记。这样做有两个好处：一是你能随时看到进度，二是代理在长任务中不容易"忘记"自己做到哪了。

进度追踪还有个隐藏价值：当任务中断（比如你关掉终端第二天再来），你可以把清单重新喂给代理，它就能接着干，不用从头解释。

5.3 实现与自检的闭环

实现阶段的核心是"小步快跑 + 每步自检"。框架会要求代理每完成一个子任务就跑一次相关测试，而不是全部写完再统一测。这样一旦出问题，定位范围小，修复成本低。

自检的标准要写死在技能里，比如"测试全绿才算完成""新增代码要有对应测试""不能引入新的警告"。标准越具体，代理的执行越稳定。

5.4 收尾：清理与沉淀

任务做完不等于结束。收尾技能包括：清理临时文件、检查是否有调试代码残留、更新相关文档、把这次任务中可复用的经验沉淀成新技能。最后这一步是 superpowers 框架的精髓——让每一次开发都让框架本身变得更强。

6. 实操中踩过的坑与应对

6.1 技能加载了但代理不遵守

最常见的问题是配置文件写了，代理却当没看见。原因通常有三个：文件位置不对（宿主没读到）、格式不符合宿主的解析规则、或者技能描述太抽象代理抓不住重点。排查顺序就是从这三条走。我的经验是，把技能写成"命令式"而不是"描述式"——写"必须先写测试"而不是"建议考虑测试"，遵守率会明显提升。

6.2 长任务上下文被压缩后失忆

长任务跑到一半，宿主工具可能会压缩上下文，代理就"忘了"之前的约定。应对办法是把关键约束和当前进度外化成文件，而不是只放在对话里。代理每次需要时重新读文件，就不怕上下文丢失了。这也是为什么前面强调"交接物"的重要性。

6.3 技能太多反而拖慢速度

技能不是越多越好。我一开始恨不得把所有经验都写成技能，结果代理每次启动要读一大堆，反而变慢，还容易抓错重点。后来精简到"高频 + 高价值"的十几个核心技能，效果反而更好。技能库要像工具箱，不是仓库。

6.4 危险操作的前置确认

涉及删除文件、覆盖数据、执行破坏性命令的操作，一定要在技能里加"前置确认"。让代理在执行前明确列出它要做什么、影响哪些文件，等你点头再动手。这个习惯帮我挡过好几次误删。

7. 关于模型接入与工具链的一些经验

7.1 本地模型与第三方 API 的取舍

不少人想用本地模型或第三方 API 来驱动 Claude Code 这类工具，动机通常是成本或可用性。这里的技术路径通常是：通过兼容层把本地模型（比如用 LM Studio 起的服务）或第三方 API 包装成宿主能识别的接口。

需要提醒的是，模型能力和技能框架是乘法关系，不是加法。一个较弱的模型配上好的技能框架，能产出及格线以上的结果；但指望弱模型靠框架逆天改命也不现实。选模型时先明确你的任务复杂度，简单任务本地小模型够用，复杂重构还是得上强模型。

7.2 命令速查：那些高频操作

Claude Code 和 Codex CLI 都有一批高频命令，熟练之后效率差别很大。比如会话管理类的命令（恢复上次会话、切换模型、压缩上下文），这些在长任务里几乎天天用。建议花半小时把官方文档里的命令列表过一遍，把常用的记下来。具体命令名各工具不同，以你所用版本的官方文档为准。

7.3 编辑器集成：让工作流更顺

把 Claude Code 接进 VS Code 这类编辑器，能省掉大量在终端和编辑器之间切换的时间。配置的核心是让编辑器能调用宿主工具，并把结果展示在编辑器里。配置过程中最容易出问题的是路径和环境变量——编辑器启动的进程可能读不到你终端里的环境配置，遇到"命令找不到"先查这个。

8. 我对这套框架的真实看法

用了一段时间之后，我最大的感受是：superpowers 这类技能框架的价值，不在于它让 AI 变聪明了，而在于它逼着使用者把"怎么干活"这件事想清楚。很多时候我们觉得 AI 不好用，其实是我们自己没想清楚要它怎么干。

另一个体会是，框架要"活"。别指望一次配好就一劳永逸，真实项目里你会不断发现新的坑、新的模式，把这些及时沉淀成技能，框架才会越用越顺手。我现在的习惯是每完成一个稍复杂的任务，就花五分钟想想"这次有什么值得固化成技能的"，积少成多，效果很明显。

最后分享一个小技巧：刚开始别追求大而全的框架，先挑三五个你最高频、最痛的任务写成技能，用顺了再扩。框架是长出来的，不是设计出来的。