1. 从superpowers这个词说起它到底指什么第一次看到superpowers这个标题加上agentic skills frameworksoftware development methodology这几个关键词我脑子里第一反应是这不是某个具体工具的名字而是一套给 AI 编程代理agent用的技能框架和方法论。换句话说它讨论的不是装哪个软件而是怎么让 AI 代理在真实软件开发流程里真正干活、干得靠谱。我接触过不少把 AI 塞进开发流程的团队绝大多数人卡在同一个地方模型能写代码片段但一旦让它独立完成一个完整任务——读需求、改多个文件、跑测试、修 bug、提交——就开始翻车。翻车的根因往往不是模型不够聪明而是缺少一套结构化的技能组织和执行方法论。superpowers 这类框架要解决的正是这个问题把一个会聊天的模型变成一个按流程办事的工程代理。所以这篇内容适合谁看三类人一是已经在用 Claude Code、Codex CLI 这类命令行代理工具但总觉得它没发挥出全部实力的开发者二是想给团队搭建 AI 辅助开发规范的技术负责人三是纯粹好奇agentic skills framework 到底是个啥的技术爱好者。我会从概念、原理、落地步骤、踩坑经验几个层面把它讲透尽量让你看完能直接上手而不是停留在听起来很厉害。需要先说明一点superpowers 本身是一个偏方法论和技能编排的概念它落地时会依附在具体的代理运行环境上比如 Claude Code 或 Codex CLI。所以讲 superpowers绕不开这两个工具但重点始终在技能框架怎么设计、怎么用。2. agentic skills framework 的核心逻辑把能力拆成可复用的技能单元2.1 为什么一个大模型不够非要拆成技能很多人对 AI 编程的想象是我描述需求模型一次性给我完整代码。实际用下来你会发现这种一锤子买卖在简单脚本上还行稍微复杂一点就崩。原因很朴素——上下文有限、任务越长越容易跑偏、错误会累积。agentic skills framework 的思路是把一个大任务拆成若干技能单元skill每个技能单元职责单一、输入输出明确。比如读取并理解项目结构是一个技能定位需要修改的文件是另一个技能执行测试并解析失败原因又是一个技能。代理在执行时按需调用这些技能而不是试图一口气吞下整个任务。这个思路其实和人类工程师的工作方式一致。你修一个 bug不会从头到尾只用一个修 bug的念头而是先复现、再定位、再改、再验证。每一步都是独立的心智动作。superpowers 做的事情就是把这套心智动作显式化、可复用化。2.2 技能单元的三个关键属性我总结下来一个合格的技能单元至少要有三个属性缺一个都会让框架变脆边界清晰这个技能只干一件事。如果描述里出现并且同时这类词通常说明该拆了。输入输出确定给它什么、它返回什么要能说清楚。模糊的接口会让代理在调用时反复试探浪费上下文。可组合技能之间能像积木一样拼起来。这是框架和一堆脚本的本质区别。举个具体例子。假设你要让代理完成给现有项目加一个日志模块这个任务拆解后可能是这样一条技能链技能单元输入输出项目结构扫描项目根目录目录树 关键文件清单依赖分析依赖清单文件已有日志相关依赖方案生成需求 现状候选实现方案代码修改选定方案变更后的文件测试验证变更文件测试结果这张表看起来简单但它是整个框架能跑起来的地基。没有这张表代理就是在凭感觉干活。2.3 方法论层面superpowers 强调的先规划后执行superpowers 作为一套 software development methodology最核心的一条原则我理解为代理必须先产出计划再执行计划且计划要可审查。这一点和很多人用 AI 的习惯相反。大多数人是边聊边改聊到哪算哪。这种方式在探索阶段没问题但在真实项目里风险很大——你根本不知道代理下一步要动哪个文件。superpowers 要求代理先把我打算怎么做写出来人确认或至少可见之后再动手。这个计划先行的机制带来两个好处一是可干预你可以在它动手前叫停错误方向二是可追溯出问题时能回看是哪一步的规划就错了。我在实际项目里最深的体会是让代理先写计划能省掉大量改到一半发现方向全错的返工。3. 落地载体Claude Code 与 Codex CLI 在框架里的角色3.1 为什么这两个工具会成为 superpowers 的常见宿主superpowers 是方法论方法论得有执行环境。目前社区里讨论最多的两个宿主是 Claude Code 和 Codex CLI原因很实际它们都是命令行形态、能直接操作文件系统和终端、支持自定义指令和技能扩展的代理工具。这三点恰好是 agentic skills framework 落地所必需的。命令行形态意味着代理能直接跑命令、读文件、看输出而不是只能生成文本让你复制粘贴。支持自定义指令意味着你可以把 superpowers 的技能单元写成它认识的配置。能操作文件系统意味着代码修改这个技能才真正成立。我个人的判断是选哪个宿主取决于你团队已有的工作流。如果你重度使用某个模型生态就选对应的工具如果追求灵活两个都装、按任务切换也很常见。下面分别说。3.2 Claude Code 的安装与基础配置要点Claude Code 的安装官方文档是最权威的来源我这里只讲几个文档里不显眼但实际很关键的点。安装方式通常有几种通过包管理器全局安装、通过桌面版安装包、或者作为编辑器插件使用。我建议新手先用命令行版本因为它最贴近 superpowers 需要的直接操作终端能力。安装完成后第一件事是确认它能正常调用终端命令——这是后面所有技能单元的基础。配置层面有几个容易忽略的细节工作目录代理默认在哪个目录下操作直接决定它能看到哪些文件。启动前一定要cd到项目根目录否则它扫描的是错误的位置。权限确认默认情况下代理执行某些操作前会请求确认。这在初期是好事能防止误操作但熟练后如果每个命令都确认会很烦可以按需调整策略。模型选择不同任务对模型能力要求不同。简单重构用轻量模型就够复杂架构设计再上强模型能省不少成本。提示安装过程中如果遇到当前地区不可用之类的提示属于工具本身的区域策略问题建议查阅官方文档了解支持范围不要轻信来路不明的第三方安装包。3.3 Codex CLI 的常用命令与技能编排Codex CLI 是另一个常被拿来和 superpowers 搭配的工具。它的命令体系里有几个高频指令值得记住因为它们直接对应技能编排里的控制流/compact压缩上下文。长任务里上下文会膨胀适时压缩能避免代理忘事或跑偏。/model切换模型。不同技能单元可以用不同模型这是框架灵活性的体现。/resume恢复之前的会话。任务中断后接着干不用从头再来。这几个命令看起来是工具细节但在 superpowers 的语境下它们是技能链能长时间稳定运行的保障。我踩过的坑是一个长任务跑到一半上下文塞满了无关信息代理开始胡言乱语。后来养成习惯每完成一个技能单元就/compact一次稳定性明显提升。3.4 两个工具的取舍一张对照表维度Claude CodeCodex CLI形态命令行 编辑器插件 桌面版命令行技能扩展支持自定义指令支持自定义指令终端操作原生支持原生支持上手难度中等中等适合场景深度集成到编辑器工作流纯命令行、脚本化编排这张表不是让你二选一而是帮你判断当前任务更适合哪个。我的实际做法是探索性、需要频繁看代码的任务用编辑器集成形态批量、脚本化的任务用纯命令行。4. 把 superpowers 真正跑起来从零搭建一套技能链4.1 第一步定义你的技能清单动手之前先别急着敲命令。拿出一张纸或者一个 Markdown 文件把你希望代理具备的技能列出来。这一步是 superpowers 落地的真正起点也是最容易被跳过的一步。列清单的方法回想你日常开发里重复性最高的动作。比如每次新需求都要先看现有代码怎么组织的每次改完都要跑一遍测试每次提交前要检查有没有漏改的引用。这些重复动作就是候选技能。我建议初期控制在 5 到 8 个技能太多会管不过来。列完之后给每个技能写一句话描述它的输入和输出。这一步做完你其实已经有了一套属于自己的 agentic skills framework 雏形。4.2 第二步把技能写成代理能读懂的指令技能清单是给人看的代理需要的是可执行的指令。这一步要把每个技能翻译成宿主工具能识别的配置或提示词。翻译时有个原则具体到可验证。不要说帮我优化代码要说扫描 src 目录下所有文件找出函数长度超过 50 行的列出文件路径和行号。前者代理只能猜后者代理能明确执行、你也能明确验证。我通常会为每个技能写三段触发条件什么时候用这个技能、执行步骤具体做什么、完成标准怎么算做完了。第三段最容易被忽略但它决定了代理会不会自我感觉良好地提前收工。4.3 第三步编排技能链处理技能之间的衔接单个技能能跑通之后真正的难点来了技能之间怎么衔接。比如代码修改技能产出的文件怎么传给测试验证技能中间如果测试失败怎么回到定位问题技能这就是 superpowers 作为 framework 的价值所在——它不只是技能集合还规定了技能之间的数据流和控制流。我的经验是衔接处最容易出问题因为代理在技能切换时可能丢失上下文。处理办法有两个一是显式传递每个技能的产出都落成文件或明确的数据结构下一个技能读它二是设置检查点在关键衔接处让代理停下来汇报人确认后再继续。前者适合自动化程度高的场景后者适合风险高的场景。4.4 第四步跑一个真实任务验证整条链技能链搭好后别用玩具任务测试直接上一个真实的小需求。我一般会挑那种我自己做大概半小时、但步骤清晰的任务比如给某个接口加参数校验。跑的过程中重点观察三件事代理在哪一步卡住、哪一步产出不符合预期、哪一步需要人工干预。这三个观察点就是你后续优化的方向。第一次跑大概率不完美这很正常superpowers 的框架本来就是迭代出来的不是一次设计到位的。5. 实测中那些文档不会告诉你的坑5.1 上下文膨胀长任务的隐形杀手这是我最想强调的一个坑。superpowers 的技能链往往比较长跑着跑着上下文就满了。表现是代理开始重复之前做过的事、忘记已经确认过的决策、或者干脆答非所问。根因是每个技能单元的输入输出都往上下文里塞累积起来非常快。解决办法前面提过——定期压缩。但更根本的办法是让技能产出落盘而不是全留在对话里。代理需要时去读文件而不是靠记忆。这一条改完长任务的稳定性会有质的提升。5.2 技能粒度过细或过粗都会翻车粒度太细代理会在技能之间频繁切换每次切换都有开销和上下文损耗整体效率反而低。粒度太粗又退回到一个大任务的老问题容易跑偏。怎么找平衡点我的经验法则是一个技能单元应该对应一个你能独立验证的产出。如果这个产出你没法单独检查对错说明粒度有问题。比如生成方案这个技能产出是一份方案文档你能读、能判断好坏这就是合适的粒度。5.3 代理自作主张改了你没让它改的文件这个坑很常见也很危险。代理在执行某个技能时可能顺手改了别的文件理由是我觉得这样更好。在真实项目里这可能导致意外破坏。防范办法是在技能指令里明确操作边界只允许修改哪些目录、哪些类型的文件。同时开启变更审查让代理在提交前把改动列出来。我现在的习惯是任何涉及文件修改的技能都要求代理先输出将要修改的文件清单我确认后才执行。5.4 模型切换带来的行为不一致用/model切换模型时你会发现同一个技能在不同模型下表现差异很大。有的模型更听话有的更有主见。这在技能编排里是个隐患——你按 A 模型调好的技能链换 B 模型可能就跑不通了。我的处理方式是关键技能固定模型不让它随意切换。探索性、容错高的技能可以用轻量模型涉及核心逻辑的技能固定用能力强的模型。这样整条链的行为更可预测。6. 让框架长期可用的几个工程化习惯6.1 把技能配置纳入版本管理技能配置本质上是代码应该和项目代码一起进版本库。好处是改动可追溯、团队可共享、出问题可回滚。我见过不少团队把技能配置散落在各人本地结果就是只有某个人能跑通这完全违背了框架的初衷。6.2 给每个技能写失败案例除了写技能怎么用我还会记录这个技能在什么情况下会失败。比如依赖分析技能在项目用了非标准依赖管理方式时会漏掉依赖。这些失败案例积累起来就是团队最宝贵的经验库比任何官方文档都实用。6.3 定期回顾技能链的实际效果框架搭好不是终点。我大概每个月会回顾一次哪些技能实际很少用考虑删掉、哪些技能经常需要人工干预考虑优化、有没有新的重复动作值得抽成技能。superpowers 这类方法论的生命力就在于持续迭代一次搭好就放着不管很快就会和实际工作脱节。6.4 团队协作时的技能共享约定如果多人用同一套框架需要约定技能命名规范、技能配置的存放位置、修改技能时的评审流程。这些约定看起来是管理问题但实际直接影响框架能不能在团队里活下来。我见过太多个人用得很爽、一推广就崩的案例根因都是缺少这些约定。7. 一些我自己的使用体会用 superpowers 这套思路做 AI 辅助开发有一段时间了最大的感受是它把用 AI从玄学变成了工程。以前用 AI 编程效果好坏很看运气同一个需求今天能跑通明天就翻车。现在有了技能框架至少知道问题出在哪个环节能针对性修。另一个体会是框架的价值不在于自动化程度多高而在于可控。我宁愿代理每一步都慢一点、多问我一句也不愿意它飞快地跑完然后给我一堆需要推倒重来的东西。superpowers 强调的计划先行、边界清晰、可审查本质上都是在换可控性。最后分享一个小技巧刚开始搭框架时别追求完美。先用三五个技能跑通一个真实小任务跑通了再慢慢加。我见过太多人一上来就设计一套完美框架结果卡在设计阶段迟迟不动手。框架是跑出来的不是设计出来的。先让它动起来剩下的边跑边调。