1. 从“superpowers”这个词说起：它到底指什么
第一次看到“superpowers”这个标题，加上“agentic skills framework”“software development methodology”这几个关键词，我脑子里第一反应是：这不是某个具体工具的名字，而更像是一套给 AI 编程代理（agent）用的能力框架。后来结合 Claude Code、Codex CLI 这些热词一起看，方向就清楚了——它讨论的是怎么把 AI 代理从“会聊天的代码补全器”升级成“能自己规划、自己调工具、自己验证结果的开发搭档”。
说白了，大多数人用 AI 写代码，还停留在“我问一句、它答一句”的阶段。你贴一段报错，它给你一段修复建议；你描述一个函数，它吐出一段实现。这种方式的问题很明显：上下文一长就断片，多步骤任务要你手动拆解，工具调用全靠你复制粘贴。而 superpowers 这类框架想解决的，就是让代理具备持续规划、工具编排、自我纠错这三样“超能力”。
我自己的理解是，superpowers 不是某一个能npm install的包，而是一种方法论 + 技能编排层。它把开发任务拆成“感知—规划—执行—验证”的闭环，每个环节都对应可复用的技能模块（skills）。这跟传统脚本自动化的区别在于：脚本是死的，路径写死；代理是活的，能根据中间结果动态调整下一步。
适合谁来了解这块内容？三类人最该看：一是天天跟 Claude Code、Codex CLI 打交道的重度用户，想把手动操作变成半自动流水线；二是团队里负责搭内部开发工具的人，想搞清楚代理框架的边界在哪；三是单纯好奇“AI 代理到底能自主到什么程度”的技术爱好者。下面我会把框架拆开、把落地路径讲透，也会把我在配置和使用中踩过的坑一并交代。
2. 代理技能框架的底层逻辑：为什么不是简单的提示词堆叠
2.1 从“单轮问答”到“闭环代理”的范式转变
传统用法里，提示词工程的核心是“把话说清楚”。但代理框架的核心不是措辞，而是状态管理。一个能自主完成任务的代理，必须在多轮交互中维护三类状态：任务目标、当前进度、已获得的中间结果。没有状态管理，代理每轮都像失忆一样重新开始，多步骤任务必然崩。
superpowers 这类框架通常会把任务表示成一个有向的执行图，节点是技能（skill），边是数据流。比如“修复一个失败的测试”这个任务，会被拆成：读取测试输出 → 定位失败断言 → 检索相关源码 → 生成补丁 → 重新运行测试 → 判断是否通过。每个节点都是一个独立技能，可以单独调试、单独替换。
这种设计的好处是可观测。你不再面对一个黑盒，而是能看到代理卡在哪一步、哪一步的输出不对。我实测下来，调试代理最痛苦的就是“它说做完了但结果是错的”，有了执行图，你至少知道该去哪个节点查。
2.2 技能（skill）的粒度该怎么切
粒度是这套框架里最容易被忽视、却最影响成败的设计决策。切太细，代理要调用几十次工具才能完成一件事，延迟高、token 烧得快；切太粗，单个技能内部逻辑复杂，出错后难以定位。
我的经验是遵循**“单一职责 + 可独立验证”**原则。一个技能应该只做一件事，并且这件事的结果能被明确判断对错。比如“运行测试并解析结果”是一个合格技能，因为输出是结构化的通过/失败列表；“修复代码”就不是好技能，因为它太笼统，无法独立验证。
实际操作中，我会先列出任务涉及的所有原子操作，然后按“输入输出是否清晰”来合并。合并的标准是：如果两个操作之间没有需要人工判断的分支，就可以合成一个技能。这个判断标准很实用，能避免过度拆分。
2.3 工具编排：代理怎么知道该调哪个工具
代理调工具不是靠猜，而是靠工具描述 + 当前上下文做匹配。每个工具注册时都要提供清晰的用途说明、参数 schema、返回格式。代理在规划阶段会把这些描述和当前任务目标做语义匹配，选出候选工具。
这里有个坑：工具描述写得太模糊，代理会乱调。我见过有人把工具描述写成“处理文件相关操作”，结果代理在需要读文件时调了写文件的工具。正确做法是描述里明确写“读取指定路径的文本文件内容，返回字符串”，把动作、对象、返回类型都写清楚。
另一个经验是给工具加约束条件。比如“仅在文件存在时调用”“仅在测试失败后调用”，这些前置条件能大幅降低误调用率。框架一般支持在工具定义里声明 precondition，规划器会据此过滤候选集。
3. 把框架落到 Claude Code 和 Codex CLI 上的实操路径
3.1 环境准备：别急着装，先把依赖理清楚
热词里“claude code安装”“codex cli安装”出现频率极高，说明很多人卡在第一步。我的建议是先把运行环境理清楚，再动手装。
Claude Code 和 Codex CLI 都是命令行代理工具，对运行环境有基本要求。以 Ubuntu 为例，需要确认 Node.js 版本、包管理器、以及终端对交互式界面的支持。我遇到过在精简版系统上装完跑不起来的情况，排查半天发现是缺少某些基础库。
安装前建议做三件事：确认系统架构（64 位还是 ARM）、确认已有 Node 版本、确认磁盘空间。这三项看起来基础，但恰恰是报错最集中的地方。热词里那条“由于与64位版本的windows不兼容”就是典型的架构问题，装之前先看清楚。
提示：安装类问题九成出在环境不匹配，而不是安装命令本身。先把环境信息打印出来核对，比反复重装有效得多。
3.2 模型接入：本地模型和第三方 API 的取舍
“claude code 调用 lmstudio 的本地模型”“使用 cc switch 接入 deepseek、qwen、glm 等模型”这些热词说明大家很关心模型接入的灵活性。这里要讲清楚一个核心概念：代理框架和底层模型是解耦的。
代理框架负责规划、工具编排、状态管理，模型负责生成具体内容。理论上你可以把任何满足接口规范的模型接进来。本地模型（通过 LM Studio 之类工具暴露接口）的好处是数据不出本地、成本可控；第三方 API 的好处是能力强、上下文长。
我的实测结论是：复杂规划任务用强模型，简单执行任务用本地模型。规划阶段对推理能力要求高，本地小模型容易规划出错误路径；而执行阶段（比如按模板生成代码、解析输出）本地模型完全够用。这种混合策略能显著降低成本。
接入时要注意接口兼容性。不同模型的 API 格式有差异，框架一般提供适配层。配置时重点核对三样：接口地址、认证方式、请求/响应字段映射。这三样对不上，代理就跑不起来。
3.3 常用命令与工作流：/compact、/model、/resume 怎么用
热词里专门提到了“/compact /model /resume”这几个命令，说明它们是高频操作。我逐个说下使用场景。
/model用于切换当前会话使用的模型。当你在规划阶段用强模型、执行阶段想切到本地模型时，这个命令很关键。切换后上下文会保留，但要注意不同模型的上下文窗口大小不同，切换前最好确认当前对话长度没超。
/compact用于压缩上下文。代理跑久了，对话历史会越来越长，既占 token 又拖慢响应。compact 会把历史对话总结成精简版本，保留关键信息、丢弃冗余内容。我的经验是在完成一个子任务、准备开始下一个子任务时执行 compact，这样总结的边界清晰，不会把没完成的任务信息压掉。
/resume用于恢复之前的会话。代理任务中断（比如你关了终端）后，用这个命令能接着上次的进度继续。这里有个坑：resume 依赖会话持久化，如果框架没开启持久化，resume 会失败。配置时记得确认持久化目录可写。
3.4 编辑器集成：VS Code 里怎么用起来
“vscode配置claude code”“claude code for vs code”这类需求很集中。编辑器集成的价值在于减少上下文切换——不用在终端和编辑器之间来回跳。
配置的核心是让编辑器插件能调用到命令行代理。一般流程是：安装插件 → 配置代理路径 → 配置模型参数 → 测试连通性。测试连通性这步别跳过，我见过配置看起来都对但就是不通的情况，最后发现是路径里有空格没转义。
集成后最实用的功能是选中代码直接提问。选中一段代码，右键调用代理，让它解释、重构、找 bug。这比复制粘贴到终端高效得多。另一个实用功能是内联 diff 预览，代理生成的修改直接以 diff 形式展示，你逐块接受或拒绝。
4. 技能编排的实战设计：从任务拆解到结果验证
4.1 任务拆解的颗粒度控制
前面讲了技能粒度，这里讲任务拆解。一个复杂任务（比如“给现有项目加一个用户认证模块”）直接丢给代理，它大概率会跑偏。正确做法是先人工拆成几个阶段，每个阶段再让代理细化。
我的拆解模板是：调研 → 设计 → 实现 → 验证。调研阶段让代理读现有代码、找相关模块；设计阶段让它给出接口定义和数据结构；实现阶段按文件逐个生成；验证阶段跑测试、检查边界。
每个阶段之间设一个人工确认点。这不是不信任代理，而是控制风险。代理在调研阶段理解错了项目结构，后面全错。早点确认能省大量返工。
4.2 验证环节为什么必须独立成技能
很多代理框架的失败案例，根源都在“代理自己说自己做完了”。生成代码的代理和验证代码的代理如果是同一个上下文，它会倾向于认为自己的输出是对的。
解决办法是验证独立成技能，且用不同的判断依据。比如实现技能生成代码，验证技能不读代码，只读测试结果。测试通过就是通过，不通过就是不通过，跟代理“觉得”对不对无关。
更进一步，验证技能应该覆盖正向和反向两类用例。正向用例验证功能正确，反向用例验证错误处理。我见过代理生成的代码正向用例全过、反向用例全崩的情况，就是因为验证只覆盖了正向。
4.3 失败重试的策略设计
代理任务失败是常态，关键是重试策略。无脑重试会浪费资源，正确做法是分类处理。
| 失败类型 | 典型表现 | 处理策略 |
|---|---|---|
| 环境问题 | 命令找不到、权限不足 | 修复环境后重试，不重新规划 |
| 规划错误 | 路径选错、工具调错 | 回到规划阶段，补充约束后重规划 |
| 执行错误 | 代码语法错、逻辑错 | 局部重试，保留已成功的部分 |
| 验证失败 | 测试不通过 | 分析失败原因，针对性修复 |
这张表是我实际用下来总结的，能覆盖八成以上的失败场景。关键是不要把所有失败都当成同一种，分类之后处理效率高很多。
5. 那些文档里不会写的踩坑记录
5.1 上下文窗口的隐形天花板
代理跑长任务时，上下文会持续增长。很多人只关注模型标称的上下文窗口大小，忽略了实际可用窗口远小于标称值。因为系统提示、工具定义、历史对话都要占空间。
我的经验是：当对话轮次超过 20 轮，或者单次任务涉及文件超过 10 个，就要主动 compact。别等到报“上下文超限”才处理，那时候已经丢信息了。
另一个技巧是把大文件拆成片段处理。代理读一个几千行的文件，光读文件就占满上下文。正确做法是先让它读文件结构（函数列表、类定义），定位到相关片段后再读具体内容。
5.2 工具调用的权限陷阱
代理调工具时，权限问题很隐蔽。比如它要执行一个 shell 命令，但当前用户没权限，报错信息可能被代理理解成“命令不存在”，然后它换个命令继续试，越试越偏。
我的做法是在工具定义里明确声明所需权限，代理规划时会检查权限是否满足。不满足就提前报错，而不是执行到一半失败。这个改动看起来小，但能省很多排查时间。
还有一类坑是危险操作没有二次确认。代理删文件、改配置这类操作，一定要加确认环节。我一般会配置成“危险操作先输出计划，人工确认后再执行”。
5.3 模型切换导致的行为突变
用/model切换模型后，代理的行为风格可能突变。强模型倾向于详细规划，弱模型倾向于直接动手。切换后如果不调整提示词，代理可能做出不符合预期的行为。
我的经验是切换模型时同步调整系统提示。切到弱模型时，把提示写得更具体、约束更明确；切到强模型时，可以给更多自主空间。这个细节很少有人提，但实际影响很大。
5.4 会话恢复的边界条件
/resume不是万能的。如果会话中断时代理正在执行一个工具调用，恢复后这个调用可能处于“悬空”状态——代理不知道它成没成功。这时候直接继续，代理可能重复执行或跳过。
正确做法是恢复后先让代理汇报当前状态，确认哪些步骤已完成、哪些未完成，再决定下一步。我一般会加一句“请先总结当前进度，不要执行任何操作”，等它汇报完再继续。
6. 从单代理到多代理：能力扩展的下一步
6.1 什么时候需要多代理
单代理能搞定大部分任务，但遇到需要并行探索或需要不同视角的场景，多代理更合适。比如同时调研三个技术方案，单代理只能串行做，多代理可以并行。
判断标准很简单：如果任务能被拆成几个互不依赖的子任务，就适合多代理。如果子任务之间有强依赖，多代理反而增加协调成本。
6.2 代理间通信的设计要点
多代理的核心难点是通信。代理之间怎么传递信息、怎么避免冲突、怎么汇总结果，都需要设计。
我的做法是用共享状态 + 消息队列。共享状态存全局信息（任务目标、已完成步骤），消息队列传具体数据。每个代理只读写自己负责的部分，避免冲突。
汇总环节要设一个协调代理，负责收集各代理结果、判断是否冲突、生成最终输出。协调代理不干具体活，只做决策。
6.3 成本与收益的平衡
多代理不是越多越好。每个代理都要消耗 token、占用资源。我实测下来，两到三个代理是性价比最高的区间。再多，协调成本就超过并行收益了。
另一个经验是按任务阶段动态启停代理。调研阶段启三个代理并行探索，实现阶段只留一个代理串行执行。这样既享受并行收益，又不浪费资源。
7. 我个人的使用体会
这套框架用下来，最大的感受是：代理的能力上限不取决于模型，而取决于框架设计。同一个模型，在好的框架里能完成复杂任务，在差的框架里连简单任务都跑不通。所以花时间研究框架设计，比追新模型更划算。
另一个体会是别追求全自动。完全无人值守的代理听起来很美，实际风险很高。我的做法是设多个确认点，关键决策人工介入。这样既享受代理的效率，又控制风险。
最后分享一个小技巧：给代理写“操作日志”。让它每完成一步就记录“做了什么、结果是什么、下一步计划”。这个日志在排查问题时极其有用，比翻对话历史高效得多。日志格式不用复杂，纯文本就行，关键是坚持记。
这套东西还在快速演进，今天的最佳实践明天可能就过时了。但底层的思路——状态管理、技能编排、独立验证——这些不会变。把这几样吃透，换什么工具都能快速上手。
