1. 从“superpowers”说起：这套 agentic skills framework 到底在解决什么问题
第一次看到 “superpowers” 这个词，很多人会以为是某个游戏模组或者某个超级英雄主题的插件。但如果你最近在折腾 Claude Code、Codex CLI 这类终端里的 AI 编程代理，大概率已经在各种社区里刷到过它。简单说，superpowers 是一套面向 AI 编程代理的 agentic skills framework，本质上是一套“技能包 + 工作方法论”的组合，它把软件开发过程中那些高频、重复、容易出错的环节，抽象成代理可以直接调用的技能单元，再配上一套约束代理行为的开发流程规范。
它要解决的问题其实很具体。你在用 Claude Code 或者 Codex CLI 的时候，有没有遇到过这种情况：你让它改一个功能，它上来就噼里啪啦写一堆代码，改完之后你一看，测试没跑、边界没考虑、原来的代码风格全被打乱，甚至把不该动的文件也顺手改了。这不是模型不够聪明，而是缺少一套稳定的“行为脚手架”。superpowers 干的事情，就是给这些代理装上这套脚手架，让它在动手之前先想清楚要做什么、按什么顺序做、做完之后怎么验证。
这套框架适合谁？我的判断是三类人。第一类是已经把 Claude Code 或 Codex CLI 当成日常开发工具，但总觉得输出质量忽高忽低的开发者；第二类是想把 AI 代理引入团队流程，但苦于没有统一规范可落地的技术负责人；第三类是对 agentic skills 这个概念感兴趣，想找一个真实可参考的框架来研究其设计思路的人。不管你用的是 Claude Code 还是 Codex CLI，甚至是在 VS Code 里通过插件调用，superpowers 的思路都是通用的，因为它约束的是“代理怎么干活”，而不是“代理跑在哪个壳里”。
需要提前说明的是，superpowers 本身不是一个可以双击安装的软件，它更像是一套约定和技能定义的集合。你需要在理解它的设计逻辑之后，把它落到你自己的代理配置里。这也是为什么很多人搜“想要安装 superpowers”却找不到一个标准安装包——它的“安装”过程，其实是把这套技能体系接入你的代理工作流。
2. 核心设计思路拆解：为什么是“技能”而不是“提示词”
2.1 从提示词工程到技能工程的关键转变
大部分人用 AI 编程代理的方式，是在对话框里写一段提示词，然后等结果。这种方式在单次任务上还行，但一旦任务变复杂，提示词就会越写越长，最后变成一篇小作文，代理反而抓不住重点。superpowers 的设计思路跳出了这个循环，它不追求“写一个完美的提示词”，而是把能力拆成一个个独立的、可组合的技能单元。
打个比方，提示词工程像是你每次做饭都从头口述一遍菜谱，而技能工程像是你提前把“切菜”“调酱汁”“控火候”这些动作练成肌肉记忆，做菜的时候直接调用就行。superpowers 里的每个 skill，就是这样一个肌肉记忆单元。比如“先写测试再写实现”是一个 skill，“改动前先读相关文件”是一个 skill，“完成后运行验证命令”也是一个 skill。这些 skill 单独看都很朴素，但组合起来就能形成一套稳定的开发行为。
这个转变背后的逻辑是：代理的不可靠，往往不是知识不足，而是行为顺序混乱。模型知道怎么写测试，但它不一定会在写实现之前先写测试。模型知道要读文件，但它可能只读了被直接修改的那个文件，忽略了依赖它的其他文件。superpowers 通过把正确的行为顺序固化成技能，让代理在执行任务时按部就班，而不是凭“感觉”发挥。
2.2 技能框架的三层结构：触发、执行、验证
拆开来看，superpowers 的技能框架大致可以分成三层。最上面一层是触发条件，也就是“什么时候该用这个技能”。比如当任务涉及修改已有函数时，触发“先读后写”技能；当任务涉及新增功能时，触发“测试先行”技能。触发条件的设计很关键，它决定了代理能不能在正确的时机想起正确的技能。
中间一层是执行步骤，也就是“这个技能具体怎么做”。这一步需要足够具体，具体到代理可以直接照着执行。比如“先读后写”技能的执行步骤可能是：第一步，定位目标函数所在文件；第二步，读取该文件完整内容；第三步，搜索该函数被哪些地方调用；第四步，确认修改影响范围后再动手。步骤越清晰，代理的执行偏差就越小。
最下面一层是验证标准，也就是“怎么判断这个技能执行到位了”。验证标准可以是运行测试、检查输出、对比修改前后的行为差异等。这一层最容易被忽略，但恰恰是最重要的。没有验证标准的技能，就像没有验收标准的施工，做完也不知道对不对。superpowers 强调每个技能都要有可验证的产出，这样代理才能形成“执行—验证—修正”的闭环。
2.3 为什么这套思路对 Claude Code 和 Codex CLI 都适用
Claude Code 和 Codex CLI 虽然底层模型和交互方式不同，但它们在“代理行为”这个层面面临的问题是相似的：都需要读文件、改代码、跑命令、验证结果。superpowers 的技能定义不依赖具体某个模型的 API，而是描述“代理应该做什么”，所以它天然具有跨工具的适应性。
我在实际使用中的体会是，Claude Code 在长上下文理解上比较强，适合处理需要通读多个文件的复杂任务；Codex CLI 在命令执行和快速迭代上比较顺手，适合处理边界清晰的局部修改。但不管用哪个，如果没有技能框架约束，都会出现“跳步”的问题。superpowers 的价值就在于，它提供了一套与工具无关的行为规范，你可以在 Claude Code 里用，也可以在 Codex CLI 里用，甚至可以在两者之间切换时保持行为一致。
3. 核心技能单元详解与实操要点
3.1 读改分离：为什么“先读后写”是最重要的基础技能
在所有技能里，如果只能保留一个，我会选“先读后写”。这个技能看起来简单到不值一提，但它是绝大多数代理翻车的根源。代理在没有充分读取上下文的情况下直接改代码，轻则改错位置，重则破坏依赖关系，而且这种错误往往在运行测试时才暴露，排查成本很高。
“先读后写”技能的执行要点有几个。第一，读取范围要覆盖直接目标和间接依赖。不能只读被修改的那个文件，还要读它引用的模块和引用它的模块。第二，读取时要关注代码风格和命名约定，这样改出来的代码才能和现有代码保持一致。第三，读取后要先输出一个修改计划，说明打算改哪些地方、为什么改、预期影响是什么，确认无误后再动手。
注意：很多代理在“先读后写”这一步会偷懒，只读文件的前几十行就下结论。实操中建议在技能定义里明确要求“读取完整文件”，如果文件过长，至少读取目标函数及其上下文各五十行。
我在用 Claude Code 处理一个中型项目时踩过一个坑：让它给一个工具函数加参数，它只读了那个函数本身，没注意到这个函数在另外三个文件里被以位置参数的方式调用。结果它加了参数之后，那三个调用点全部报错。后来我把“先读后写”技能加进去，要求它在修改函数签名前必须搜索所有调用点，这类问题就再没出现过。
3.2 测试先行：让代理自己给自己出考卷
“测试先行”是另一个高频技能。它的核心逻辑是：在写实现之前，先让代理写出验证这个实现的测试。这样做有两个好处。第一，测试写出来之后，代理对“什么算完成”有了明确标准，不会写着写着跑偏。第二，测试本身也是对需求的一次校验，如果测试写不出来，说明需求本身可能没想清楚。
执行这个技能时，要注意测试的粒度。对于新增功能，测试应该覆盖正常路径和至少一个边界情况。对于修改功能，测试应该先能复现修改前的行为，再验证修改后的行为。对于修复 bug，测试应该先能稳定复现 bug，再验证修复后 bug 消失。这个顺序不能乱，否则测试就失去了“考卷”的意义。
提示：如果项目本身没有测试框架，不要强行引入一个重型框架。可以用最简单的断言脚本代替，关键是让代理有一个可执行的验证手段，而不是追求测试覆盖率。
3.3 小步提交：把大任务拆成可验证的小步骤
代理处理大任务时最容易失控。你让它“重构用户模块”，它可能一口气改十几个文件，改完之后你根本不知道从哪里开始检查。superpowers 里的“小步提交”技能，就是要求代理把大任务拆成一系列小步骤，每个步骤都有独立的验证点，完成一步验证一步，验证通过再进入下一步。
拆步骤的原则是每个步骤的改动范围可控、验证方式明确。比如“重构用户模块”可以拆成：第一步，提取用户相关的常量；第二步，把用户校验逻辑抽成独立函数；第三步，替换所有调用点；第四步，删除旧代码。每一步做完都跑一次测试，确保没有引入回归。这样即使某一步出了问题，也能快速定位到具体步骤，而不是在一大堆改动里大海捞针。
这个技能在 Codex CLI 里尤其好用，因为 Codex CLI 的命令执行反馈很快，你可以让它每完成一步就运行一次测试命令，根据输出决定是否继续。我在处理一个遗留项目时用这种方式，把原本需要一次性改二十多个文件的任务拆成了七个小步骤，每一步都验证通过后再继续，最终一次性通过，没有出现反复调试的情况。
3.4 上下文管理：什么时候该压缩，什么时候该重开
Claude Code 和 Codex CLI 都有上下文长度的限制，任务做久了上下文会越来越长，代理的注意力也会被稀释。superpowers 里有一个容易被忽视但很实用的技能，就是上下文管理。它要求代理在上下文接近饱和时主动压缩，把已经完成的部分总结成简短记录，释放上下文空间给后续任务。
压缩的时机很关键。太早压缩会丢失细节，太晚压缩又来不及。我的经验是，当代理开始出现“忘记之前约定”或者“重复询问已经确认过的信息”时，就是该压缩的信号。压缩时要把已完成的工作、当前状态、待办事项、关键决策记录清楚，这样即使上下文被压缩，代理也能快速恢复状态。
如果任务已经完成了一个阶段，而下一个阶段和之前关联不大，更好的做法是重开一个会话，而不是在旧会话里继续。重开会话可以让代理轻装上阵，避免被之前的历史包袱拖累。我在用 Claude Code 做多阶段任务时，习惯在每个阶段结束后把关键结论记录下来，然后开新会话继续下一阶段，效果比一直在一个会话里硬撑要好得多。
4. 完整实操流程：从零接入 superpowers 思路
4.1 环境准备：Claude Code 与 Codex CLI 的基础配置
在接入 superpowers 思路之前，先把基础环境搭好。Claude Code 的安装方式根据平台不同略有差异，Mac 和 Ubuntu 下通常通过命令行工具安装，Windows 下需要注意 64 位兼容性问题。安装完成后，第一次运行需要完成账号注册和登录流程，如果遇到组织策略限制导致无法使用的情况，需要检查账号权限配置。
Codex CLI 的安装相对直接，通过包管理器安装后即可在终端调用。它的常用命令包括/compact用于压缩上下文、/model用于切换模型、/resume用于恢复会话。如果你需要在 VS Code 里使用，可以安装对应的插件，把 Claude Code 或 Codex CLI 接入编辑器工作流。对于想用本地模型的场景，可以通过配置把请求转发到本地推理服务，这样可以在不依赖外部服务的情况下使用代理能力。
注意：不同平台的安装细节和权限要求差异较大，建议先确认自己的操作系统版本和账号状态，再按官方文档逐步操作。遇到“当前地区不可用”之类的提示时，优先检查账号配置和网络环境是否符合要求。
4.2 技能定义落地：把 superpowers 思路写进你的代理配置
环境准备好之后，下一步是把 superpowers 的技能思路落到实际配置里。具体做法是：在你的项目根目录下创建一个技能定义文件，把常用的技能单元写进去，然后在每次启动代理时加载这个文件。技能定义不需要很复杂，关键是清晰描述触发条件、执行步骤和验证标准。
比如“先读后写”技能可以这样定义：触发条件是“任务涉及修改已有代码”，执行步骤是“读取目标文件完整内容、搜索所有调用点、输出修改计划”，验证标准是“修改计划经确认后再执行”。类似地，“测试先行”技能的触发条件是“任务涉及新增或修改功能”，执行步骤是“先写测试、运行测试确认失败、再写实现、运行测试确认通过”，验证标准是“测试从失败变为通过”。
这些定义写一次之后可以复用，不同项目之间只需要微调触发条件。我在多个项目里用同一套技能定义，发现代理的行为一致性明显提升，不再需要每次都在提示词里重复交代“先读再改”“记得跑测试”这些要求。
4.3 一次完整任务的全流程演示
假设现在有一个任务：给一个现有的工具函数增加参数校验。按照 superpowers 的思路，整个流程会这样走。
第一步，代理读取目标函数所在文件，搜索该函数的所有调用点，确认修改影响范围。第二步，代理输出修改计划，说明打算在哪里加校验、加什么校验、会影响哪些调用点。第三步，代理先写一个测试，验证不加校验时非法参数会导致什么问题。第四步，代理运行测试，确认测试失败。第五步，代理实现参数校验逻辑。第六步，代理再次运行测试，确认测试通过。第七步，代理检查修改后的代码风格是否与现有代码一致。第八步，代理总结本次修改内容，记录关键决策。
这个流程看起来步骤很多，但实际执行时代理可以连续完成，你只需要在关键节点确认即可。相比“直接改代码然后祈祷没问题”的方式，这套流程的返工率要低得多。我在实际项目里对比过，用技能框架约束的代理任务，一次通过率大概能从五成提升到八成以上，剩下的两成问题也能在早期步骤里被发现，而不是等到最后才暴露。
5. 常见问题与排查技巧实录
5.1 代理不按技能执行怎么办
这是最常见的问题。你明明定义了“先读后写”，代理还是直接动手改代码。原因通常有两个：一是技能定义没有被正确加载，二是技能定义的触发条件写得太模糊，代理没有识别出当前任务应该触发这个技能。
排查方法是先确认技能文件是否被读取，可以在任务开始时让代理复述当前可用的技能列表。如果技能已加载但没触发，就把触发条件写得更具体，比如把“涉及修改代码”改成“涉及修改任何已存在的函数或类”。触发条件越具体，代理越容易在正确时机想起来。
5.2 上下文压缩后代理“失忆”怎么处理
上下文压缩是必要的，但压缩后代理可能会忘记之前的关键决策。解决办法是在压缩时保留一份“状态摘要”，包含已完成工作、当前状态、待办事项和关键决策。这份摘要要放在上下文里显眼的位置，让代理在压缩后能第一时间看到。
如果压缩后代理还是出现失忆，可以考虑把状态摘要单独存成一个文件，每次任务开始时让代理先读这个文件。这样即使上下文完全重置，代理也能通过读文件恢复状态。我在处理长周期任务时用这个方法，效果比较稳定。
5.3 测试先行写不出测试怎么办
有时候代理会卡在“写测试”这一步，尤其是面对一些难以测试的代码时。这时候不要硬逼代理写测试，而是先让它分析“为什么这个代码难以测试”。通常分析下来会发现，难以测试的代码往往也是耦合过高的代码，这本身就是一个值得先处理的问题。
如果确实无法写自动化测试，可以退而求其次，让代理写一个手动验证步骤，明确说明“怎么操作、预期看到什么结果”。手动验证虽然不如自动化测试可靠，但至少给了代理一个明确的完成标准，比完全没有验证要好。
5.4 技能框架让任务变慢值得吗
短期看，技能框架确实会让单个任务的执行步骤变多，感觉变慢了。但把时间拉长看，返工和调试的时间大幅减少，整体效率是提升的。我自己的体感是，简单任务（改个变量名、加个日志）用不用框架差别不大，但复杂任务（跨文件重构、新增功能模块）用框架的收益非常明显。
提示：可以根据任务复杂度灵活调整技能启用范围。简单任务只启用“先读后写”，复杂任务启用全套技能。不必一刀切。
5.5 常见问题速查表
| 问题现象 | 可能原因 | 排查方向 | 解决建议 |
|---|---|---|---|
| 代理直接改代码不读上下文 | 技能未加载或触发条件模糊 | 检查技能文件加载状态 | 细化触发条件，任务开始时复述技能列表 |
| 压缩后忘记之前决策 | 状态摘要缺失或不显眼 | 检查压缩时是否保留摘要 | 单独存状态文件，任务开始时先读取 |
| 写不出测试 | 代码耦合过高或需求不清 | 分析代码可测试性 | 先解耦或改为手动验证步骤 |
| 任务执行变慢 | 技能启用范围过大 | 评估任务复杂度 | 简单任务只启用基础技能 |
| 代理重复询问已确认信息 | 上下文过长导致注意力稀释 | 检查上下文长度 | 及时压缩或重开会话 |
6. 工具选型与组合建议：Claude Code、Codex CLI 怎么搭
6.1 两个工具的能力边界与适用场景
Claude Code 和 Codex CLI 不是互斥关系，而是可以互补的。Claude Code 的优势在于长上下文理解和多文件协同，适合处理需要通读项目、理解复杂依赖关系的任务。Codex CLI 的优势在于命令执行和快速迭代，适合处理边界清晰、验证方式明确的局部任务。
我的组合方式是：用 Claude Code 做前期的方案设计和跨文件分析，把任务拆解清楚；然后用 Codex CLI 执行具体的代码修改和测试验证。这样既发挥了 Claude Code 的理解能力，又利用了 Codex CLI 的执行效率。两者之间通过技能定义文件共享同一套行为规范，保证行为一致。
6.2 本地模型接入的注意事项
如果你想把代理接到本地模型上，需要注意几点。第一，本地模型的上下文长度通常比云端模型短，技能定义要更精简，避免占用过多上下文。第二，本地模型的指令遵循能力可能弱一些，技能定义要更具体，减少模糊表述。第三，本地模型的推理速度受硬件影响较大，任务拆解要更细，避免单次任务过重。
在配置本地模型接入时，关键是确认接口兼容性和参数映射是否正确。不同本地推理服务的 API 格式可能有差异，需要根据实际情况调整配置。如果遇到调用失败，优先检查模型名称、接口地址和认证配置这三项。
6.3 第三方 API 使用的经验与边界
有些场景下会用到第三方 API 来接入不同的模型。使用第三方 API 时，要注意接口稳定性、响应格式兼容性和费用控制。建议在技能定义里加入“失败重试”和“降级处理”逻辑，当第三方 API 不可用时，代理能自动切换到备用方案，而不是直接卡死。
另外，第三方 API 的响应格式可能和官方接口有差异，需要在配置层做适配。我的做法是写一个简单的适配层，把不同来源的响应统一成代理能理解的格式，这样技能定义就不需要关心底层用的是哪个 API。
7. 我个人的实操体会与后续扩展方向
这套 superpowers 思路我用了一段时间，最大的感受是：代理的可靠性不取决于模型有多强，而取决于行为有多稳。同一个模型，加上技能框架约束之后，输出质量的波动明显变小。以前我需要反复检查代理的改动，现在大部分情况下只需要在关键节点确认一下就行。
如果要把这套思路继续扩展，我觉得有两个方向值得尝试。一个是技能的市场化，把常用的技能单元做成可分享的包，不同项目之间直接复用，减少重复定义的成本。另一个是技能的自动化触发，通过分析任务类型自动匹配应该启用的技能，而不是靠人工判断。这两个方向都能进一步降低使用门槛，让更多人享受到技能框架带来的稳定性提升。
最后分享一个小技巧：技能定义不要一次写太多，先从“先读后写”和“测试先行”这两个最基础的开始，用顺了再逐步增加。技能太多反而会让代理无所适从，少而精比多而杂更有效。
