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 想要重点解决的翻车场景具体表现根本原因任务边界模糊让它改 A 文件它顺手重构了 B、C 文件没有最小改动的约束技能验证缺失改完代码不跑测试就宣布完成没有完成前自检的强制流程上下文丢失长任务做到一半忘了最初目标没有任务分解与进度追踪机制重复劳动每次都要重新解释同样的规范缺少可复用的技能沉淀命令误用执行了危险的删除或覆盖操作没有危险操作的前置确认技能这些问题的共同点是它们都不是靠换个更强的模型能解决的而是靠流程和约束解决的。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 不好用其实是我们自己没想清楚要它怎么干。另一个体会是框架要活。别指望一次配好就一劳永逸真实项目里你会不断发现新的坑、新的模式把这些及时沉淀成技能框架才会越用越顺手。我现在的习惯是每完成一个稍复杂的任务就花五分钟想想这次有什么值得固化成技能的积少成多效果很明显。最后分享一个小技巧刚开始别追求大而全的框架先挑三五个你最高频、最痛的任务写成技能用顺了再扩。框架是长出来的不是设计出来的。
