1. 从“superpowers”这个词说起它到底指什么第一次看到“superpowers”这个标题加上“agentic skills framework”“software development methodology”这几个关键词我脑子里第一反应是这不是某个具体软件的名字而更像是一套给 AI 编程代理agent用的能力框架。后来结合 Claude Code、Codex CLI 这些热词基本可以确认——它讨论的是“怎么让命令行里的 AI 代理真正具备超能力”也就是把零散的提示词、工具调用、上下文管理整合成一套可复用、可组合的技能体系。说白了大多数人用 Claude Code 或者 Codex CLI停留在“我问一句、它答一句、偶尔帮我改个文件”的阶段。这就像你手里有一把瑞士军刀但只会用它开瓶盖。而 superpowers 这套思路想解决的核心问题是如何把 AI 代理从“聊天机器人”升级成“能独立完成复杂工程任务的协作伙伴”。它涉及的不只是模型能力还包括技能的组织方式、上下文的注入策略、工具链的编排以及一套让代理“知道自己在干什么”的方法论。这篇文章适合三类人看第一类是想把 Claude Code、Codex CLI 真正用起来的开发者第二类是对 agentic skills framework 这个概念好奇、想知道它和普通 prompt engineering 有什么区别的技术人第三类是在团队里推动 AI 辅助开发、需要一套可落地方法论的负责人。我会从概念拆解讲到实操配置再讲到技能框架的设计思路尽量把“superpowers”这个词背后的东西讲透。需要先说明一点superpowers 本身并不是一个我能在官方渠道下载到的独立安装包它更像是一种围绕 AI 编程代理构建能力体系的方法论和工具集合。市面上流传的很多“安装 superpowers”的说法实际上指的是配置 Claude Code、Codex CLI 这类代理工具再配合一套技能定义文件让代理具备更强的任务执行能力。所以下文我会把重点放在“怎么搭出这套能力”上而不是纠结于某个具体安装命令。2. Claude Code 与 Codex CLI两条主流的代理落地路径2.1 为什么命令行代理比 IDE 插件更值得投入很多人第一次接触 AI 编程是从 VS Code 插件开始的比如 Claude Code for VS Code、Codex 的编辑器集成。这类插件的好处是上手快装完就能在侧边栏对话。但我实际用下来发现真正能释放代理能力的场景往往在命令行里。原因有三个。第一命令行代理能直接执行终端命令。你让它跑测试、装依赖、查日志它真的能动手而不是只给你一段建议代码。第二命令行环境天然适合脚本化和自动化你可以把代理嵌进 CI 流程、嵌进自定义脚本。第三命令行代理对项目上下文的读取更自由它能自己决定读哪些文件、跑哪些命令来收集信息而不是被动等你粘贴代码。Claude Code 和 Codex CLI 就是这条路线上的两个代表。Claude Code 是 Anthropic 推出的命令行代理工具Codex CLI 则是另一套思路相近的实现。它们都支持读取本地文件、执行命令、多轮任务规划。热词里出现的“claude code 如何直接执行终端命令”“codex cli 命令哪些 /compact /model /resume”说明大家最关心的就是这类代理的实操细节。2.2 Claude Code 的安装与首次配置要点关于 Claude Code 的安装热词里有一堆相关搜索“claude code 安装”“mac 安装 claude code”“ubuntu 安装 claude code”“claude code 下载安装”。我按自己的经验梳理一下关键点。在 macOS 或 Linux 上通常通过包管理器安装。安装完成后第一次运行会引导你完成账号认证。这里有个常见坑热词里出现了“your organization has disabled claude subscription access for claude code”和“note: claude code might not be available in your country”说明账号权限和地区可用性是两道门槛。如果你用的是团队账号可能被管理员限制了访问如果是个人账号也要确认当前区域是否在支持范围内。配置层面我建议第一次就把工作目录、默认模型、权限模式这几项理清楚。Claude Code 默认会在你当前所在的项目目录下工作所以一定要先 cd 到目标项目再启动否则它可能在一个空目录里瞎转。权限模式决定了它执行命令前是否需要你确认新手建议先用确认模式跑顺了再考虑放宽。2.3 Codex CLI 的定位差异与命令体系Codex CLI 和 Claude Code 在能力上高度重叠但使用手感有差异。热词里“codex cli 命令哪些 /compact /model /resume”直接点出了它的核心命令。我解释一下这几个命令的实际作用。/compact是用来压缩上下文的。代理跑久了对话历史会越来越长既占 token 又拖慢响应。/compact会把之前的对话总结成更短的摘要保留关键信息丢掉冗余部分。这个操作在长任务里非常关键我一般每完成一个阶段性目标就 compact 一次。/model用来切换底层模型。不同任务对模型的要求不一样简单重构用快模型复杂架构设计用强模型切换一下能省不少成本。/resume是恢复之前的会话。代理任务中断了、终端关了用这个命令能把上下文接回来不用从头再来。热词里还有“删除 codex cli 指令”这个我没找到特别权威的对应推测是指清理或卸载相关命令。我的建议是卸载前先确认没有正在运行的任务避免残留进程占用资源。2.4 两条路径的选型对照维度Claude CodeCodex CLI安装方式包管理器 / 官方脚本包管理器 / npm 类工具上下文压缩自动 手动/compact显式触发模型切换配置项 / 命令/model命令会话恢复支持/resume本地模型接入可通过第三方方案可通过第三方方案适合场景深度重构、长任务快速迭代、脚本化这张表不是绝对的实际选型还要看你团队已有的工具链。我的经验是如果你已经在用 Anthropic 的生态Claude Code 更顺手如果你更习惯 npm 系的工具管理Codex CLI 的集成成本更低。两者不必二选一我自己的机器上就都装着按任务类型切换。3. 让代理接入本地模型与第三方 API 的实操思路3.1 为什么要考虑本地模型热词里有一条很显眼“claude code 调用 lmstudio 的本地模型”。这说明很多人不满足于只用官方云端模型想把代理接到本地跑。动机无非几个数据不出本地、成本可控、离线可用、想用特定开源模型。LM Studio 是一个可以在本地加载和运行开源模型的工具它提供兼容 OpenAI 接口的本地服务。理论上只要代理工具支持自定义 API 端点就能把请求指向 LM Studio。但这里有个现实问题代理工具对模型的能力要求比较高尤其是工具调用function calling和长上下文理解。本地小模型在这些方面往往力不从心跑起来会出现“它不知道该调用哪个工具”“上下文一长就胡言乱语”的情况。我的建议是本地模型适合做轻量任务比如代码解释、简单补全、文档问答。真正复杂的多步任务还是交给能力更强的云端模型。把本地模型当成“日常小助手”把云端模型当成“攻坚主力”这个分工比较务实。3.2 第三方 API 接入的通用套路热词里“使用 cc switch 接入 deepseek v4, qwen, glm 等模型”“第三方 api 使用技巧”指向的是同一个需求把代理工具的请求转发到第三方模型服务。cc switch 这类工具的作用就是帮你管理多个模型供应商的配置一键切换。通用套路是这样的代理工具通常允许你配置 API base URL 和 API key。你把这些指向第三方服务商的端点填上对应的 key代理就会把请求发过去。听起来简单但实操中有几个坑。第一个坑是接口兼容性。不是所有第三方服务都完全兼容 OpenAI 或 Anthropic 的接口格式有些字段名、返回结构有差异会导致代理解析失败。第二个坑是工具调用支持。代理依赖工具调用来执行命令、读写文件如果第三方模型不支持或者支持得不完整代理就退化成普通聊天。第三个坑是速率和稳定性第三方服务的限流策略和官方不一样长任务跑到一半被限流会很尴尬。我的做法是接入新供应商前先用一个最小任务测试让它读一个文件、改一行代码、跑一条命令。三件事都能顺利完成才说明这个供应商可用。3.3 配置文件的组织方式不管是接本地模型还是第三方 API配置文件的组织都值得讲究。我习惯把不同供应商的配置分成独立文件用一个切换脚本或工具来激活。这样做的理由是避免配置互相污染。你手动改来改去很容易把 base URL 和 key 配错排查起来很痛苦。一个典型的配置结构大概是这样{ provider: third-party, baseUrl: https://api.example.com/v1, apiKey: your-key-here, model: target-model-name, maxTokens: 8192, temperature: 0.2 }temperature我一般设得比较低0.1 到 0.3 之间。代理任务需要的是稳定和准确不是创意发散。温度高了它可能给你编出不存在的命令。提示API key 千万不要硬编码在会提交到版本库的文件里。用环境变量或者本地未跟踪的配置文件这是基本的安全习惯。3.4 本地模型接入的实测体会我自己用 LM Studio 接过一次本地模型跑 Claude Code 类的任务体验是简单任务能跑复杂任务会崩。具体表现是让它解释一段代码没问题让它规划一个多文件重构它就开始绕圈子反复读同一个文件或者生成格式不对的工具调用。后来我调整了策略本地模型只用来做“预处理”比如先把项目结构总结一遍、把相关文件筛出来然后把筛选结果喂给云端模型做真正的任务规划。这样既利用了本地的隐私和成本优势又保证了核心任务的质量。这个组合思路我觉得比单纯追求“全本地”更实际。4. 技能框架agentic skills framework的设计逻辑4.1 技能不是提示词模板很多人把 agentic skills framework 理解成“一堆写好的提示词模板”这个理解偏了。提示词模板是静态的你填个空就完事。而技能框架里的“技能”是带有触发条件、执行步骤、工具依赖和验证标准的可组合单元。举个例子。一个“重构函数”的技能不只是“请帮我重构这个函数”这句话。它应该包含什么时候触发这个技能比如用户说“这个函数太长了”、执行前要收集什么信息函数所在文件、调用方、测试覆盖情况、执行中允许用哪些工具读文件、写文件、跑测试、执行后怎么验证测试是否通过、调用方是否受影响。这才叫一个完整的技能。superpowers 这个概念的价值就在于它试图把这种“完整技能”标准化让代理能像搭积木一样组合使用。4.2 技能的三层结构我总结下来一个可用的技能大致分三层。第一层是意图识别层。代理需要判断当前任务该用哪个技能。这层靠的是对用户输入和项目状态的综合理解。做得好的代理能根据你一句话就选对技能做得差的你得手动指定。第二层是执行编排层。技能内部有多个步骤代理要决定先做什么、后做什么、遇到分支怎么走。这层最考验代理的规划能力也是本地小模型最容易翻车的地方。第三层是工具调用层。具体到读哪个文件、跑哪条命令、怎么写回结果。这层相对机械但对准确性要求高一个路径写错就全盘皆输。三层里第一层和第三层相对容易做好第二层是真正的难点。这也是为什么我在前面强调复杂任务还是要用能力强的模型。4.3 技能定义文件的写法技能定义通常用结构化格式写YAML 或 JSON 都行。我倾向于 YAML可读性好。一个技能定义大概长这样name: refactor-function description: 当函数过长或职责过多时将其拆分为更小的函数 triggers: - 这个函数太长了 - 帮我重构这个函数 - 拆分这个函数 steps: - action: read_file target: {{current_file}} - action: analyze goal: 识别函数内的独立逻辑块 - action: propose_plan output: 拆分方案 - action: confirm condition: 方案涉及跨文件修改 - action: execute_refactor - action: run_tests on_failure: 回滚并报告这个定义里triggers是触发条件steps是执行步骤on_failure是失败处理。关键点是每一步都要有明确的动作和验证不能有“然后代理自己看着办”这种模糊表述。4.4 技能组合与冲突处理单个技能好写难的是多个技能组合时的冲突。比如你同时定义了“快速修复”和“彻底重构”两个技能用户说“这个 bug 修一下”代理该用哪个快速修复可能治标不治本彻底重构又太重。我的处理方式是给技能加优先级和适用条件。“快速修复”适用于生产环境紧急问题“彻底重构”适用于开发阶段的代码质量改进。代理根据当前上下文是不是生产分支、有没有测试覆盖来选择。如果实在判断不了就主动询问用户而不是自作主张。这一点很重要好的技能框架不是让代理替你做所有决定而是让它在该问的时候问该做的时候做。很多代理用起来让人不放心就是因为它在模糊地带乱猜。5. 上下文管理与长任务执行的关键技巧5.1 上下文窗口是稀缺资源代理跑长任务最大的敌人是上下文窗口。你让它重构一个模块它读了十几个文件对话历史几千行很快窗口就满了。满了之后要么报错要么开始遗忘早期信息行为变得不可预测。热词里“/compact”这个命令就是为解决这个问题设计的。但光靠 compact 不够还要在任务设计上做文章。我的经验是把大任务拆成小任务每个小任务独立完成、独立验证、独立压缩。不要指望代理一口气吃下一个大重构。5.2 用文件系统做外部记忆代理的上下文窗口有限但文件系统是无限的。我习惯让代理把中间结果写到文件里比如分析报告、重构计划、变更清单。这样即使上下文被压缩了关键信息还在磁盘上随时可以读回来。具体做法是在技能定义里加一步“写中间产物到.agent/目录”。这个目录加到.gitignore里不污染版本库。代理需要回顾时读这个目录就行比翻对话历史高效得多。5.3 长任务的检查点机制跑长任务时我会设置检查点。每完成一个阶段让代理输出一份简短的状态报告做了什么、当前在哪、下一步是什么、有没有阻塞。这份报告既是给我看的也是给代理自己看的——万一上下文丢了读这份报告就能恢复状态。检查点的频率我一般按任务复杂度定。简单任务一个检查点就够复杂任务每个子模块一个。太频繁会打断节奏太稀疏又起不到保护作用。5.4 失败恢复的实操代理任务失败是常态关键是怎么恢复。我的流程是先看它卡在哪一步再判断是上下文问题、工具问题还是模型能力问题。上下文问题就 compact 或重开工具问题就修配置模型能力问题就换模型。热词里“/resume”就是为恢复设计的。但 resume 只能恢复会话不能恢复“思路”。如果代理之前走错了方向resume 回来还是错的。所以我的习惯是发现方向错了就果断重开不要恋战。重开的成本往往比在错误方向上挣扎低得多。6. 团队协作与工程化落地的注意事项6.1 把代理配置纳入版本管理个人用代理配置放本地就行。团队用配置必须进版本库。但要注意API key 不能进版本库。我的做法是配置文件进库key 用环境变量注入再写一个模板文件说明需要哪些环境变量。这样新成员拉下代码照着模板配好 key就能用统一的代理配置。避免了“每个人配置不一样、行为不一致”的问题。6.2 技能库的共享与评审技能定义文件应该像代码一样评审。一个新技能加进来要有人 review 它的触发条件是否合理、步骤是否完整、失败处理是否到位。我见过团队里有人写了个技能触发条件写得太宽结果代理动不动就触发它把简单任务搞复杂。评审的重点是触发条件的精确性和失败处理的完备性。前者决定技能会不会被误触发后者决定出问题时能不能优雅降级。6.3 权限与安全边界代理能执行终端命令这是它的威力也是它的风险。团队落地时一定要划清权限边界。哪些命令允许自动执行哪些必须人工确认哪些绝对禁止都要有明确规定。我的建议是破坏性操作一律人工确认。删除文件、强制推送、修改生产配置这些操作代理可以提议但执行前必须过人的手。这不是不信任代理而是工程纪律。6.4 效果度量与迭代代理用得好不好不能凭感觉。我建议记录几个指标任务完成率、平均耗时、人工干预次数、失败原因分布。这些数据能告诉你技能框架哪里需要改进模型选型是否合理上下文策略是否有效。我自己的记录习惯是每周回顾一次失败案例看看是技能定义的问题还是模型能力的问题。前者改技能后者换模型或调整任务粒度。坚持几个月代理的可用性会有明显提升。7. 我踩过的几个坑和对应的解法7.1 代理在空目录里空转前面提过一次这里展开说。我第一次用 Claude Code 时忘了先 cd 到项目目录结果它在用户主目录下启动读了一堆无关文件还试图修改我的 shell 配置。幸好权限模式拦住了。解法很简单启动前确认工作目录。我现在养成了习惯启动代理前先pwd一下确认在正确的项目根目录。有些代理工具支持指定工作目录参数用那个更保险。7.2 上下文压缩后丢失关键约束有一次我让代理重构一个模块中途 compact 了一次结果它把“不要修改公共接口”这个约束给忘了改完之后调用方全挂了。解法是把关键约束写进技能定义或项目配置文件而不是只放在对话里。对话会被压缩配置文件不会。我现在会把“不可修改的接口”“必须通过的测试”“代码风格要求”这些写进一个AGENTS.md或类似的文件代理每次启动都会读。7.3 第三方模型不支持工具调用接第三方 API 时踩过这个坑。配置看起来都对但代理就是不执行命令只会输出文字。排查半天才发现那个第三方模型不支持 function calling。解法是接入前先确认模型能力。看文档、跑最小测试确认支持工具调用再正式用。不支持的就只能当聊天用别指望它执行任务。7.4 技能触发条件写得太宽团队里有人写了个“优化代码”的技能触发条件包含“优化”这个词。结果用户说“优化一下这个查询”代理触发了整个代码重构流程把简单问题搞复杂了。解法是触发条件要具体。“优化代码”太宽“优化这个 SQL 查询的性能”才够具体。写技能定义时多问自己一句这个条件会不会误触发7.5 长任务没有检查点导致全盘重来跑一个跨多文件的重构跑了半小时中途终端崩了上下文全丢只能从头再来。那次之后我就加了检查点机制。解法是阶段性落盘。每完成一个子任务把状态写到文件。终端崩了、会话断了读文件就能恢复。这个习惯救了我好几次。8. 关于 superpowers 这套思路的个人判断用了一段时间 Claude Code、Codex CLI也折腾过技能框架和本地模型接入我对 superpowers 这类思路的判断是方向对但落地还在早期。方向对是因为 AI 编程代理确实需要一套结构化的能力体系。光靠提示词能力上限很低而且不可复用、不可维护。技能框架把经验沉淀下来让代理的行为可预期、可迭代这是必经之路。落地早期是因为现在的工具链还很碎。配置格式不统一、技能定义没有标准、不同代理之间不兼容、本地模型能力参差。你想搭一套顺手的体系得自己填很多坑。我的建议是别追求一步到位。先从一两个高频任务开始写好技能定义跑顺了再扩展。上下文管理、检查点、失败恢复这些机制边用边加。等这套东西在你手里跑顺了再考虑团队推广。最后分享一个我自己的小习惯每次代理任务失败我都会花两分钟记一下失败原因和当时的配置。攒了几个月这份记录成了我调优技能框架最值钱的参考。工具会更新模型会换代但“什么情况下会出什么问题”这种经验是真正属于你自己的 superpowers。