1. 从“superpowers”说起这套 agentic skills framework 到底在解决什么问题第一次看到 “superpowers” 这个词是在几个做 AI 编程工具链的朋友群里。有人甩了个链接配文是“这玩意儿把 Claude Code 和 Codex CLI 的玩法又往上抬了一层”。点进去看完之后我大概理解了它想干的事把零散的、靠个人经验堆出来的 AI 辅助开发流程抽象成一套可复用、可组合、可迁移的 agentic skills framework。说白了就是给“让 AI 帮你写代码”这件事定一套软件开发的章法。很多人对 Claude Code、Codex CLI 这类工具的理解还停留在“终端里能对话的 AI”。但真正用过一段时间就会发现问题从来不是模型够不够聪明而是你怎么组织任务、怎么约束输出、怎么让多个步骤串起来不跑偏。superpowers 这套框架的核心价值就是回答这个问题。它不绑定某一个具体模型也不绑定某一个 CLI而是一套方法论加配套的 skill 组织方式让你在 Claude Code、Codex CLI 甚至本地模型上都能跑出一致的工作流。这篇文章适合三类人看。第一类是已经在用 Claude Code 或 Codex CLI但总觉得“用得不顺手、每次都要重新解释需求”的开发者第二类是刚接触 agentic 开发想搞清楚 skills framework 到底是个什么概念的入门者第三类是在团队里想推动 AI 辅助开发规范化需要一套可落地方法论的技术负责人。我会从框架设计思路讲到具体实操包括 Claude Code 的安装配置、Codex CLI 的命令体系、本地模型接入、常见报错排查尽量把踩过的坑都摊开说。需要先说明一点superpowers 本身是一个偏方法论和 skill 编排的框架它不是一个装完就完事的软件。理解这一点很关键否则你会一直在找“superpowers 安装包”而找不到。它的落地依赖 Claude Code、Codex CLI 这类执行载体框架负责的是“怎么组织”载体负责的是“怎么执行”。2. 框架整体设计与思路拆解2.1 为什么需要 agentic skills framework传统的 AI 辅助编程基本是“一问一答”模式你描述需求模型给代码你复制粘贴出问题再问。这个模式在简单任务上没问题但一旦任务变复杂比如“重构一个模块并补全测试”就会暴露三个致命问题。第一个问题是上下文漂移。多轮对话之后模型会逐渐忘记最初的约束条件你前面说的“不要引入新依赖”到第十轮可能就被它抛到脑后了。第二个问题是步骤不可复用。你这次调教出一套好用的提示词流程下次换个项目又得从头来。第三个问题是质量不可控。同一个需求今天问和明天问输出质量可能差很多因为没有固定的检查环节。superpowers 这套 agentic skills framework 的设计出发点就是把这三点逐个击破。它把开发任务拆成一个个skill技能单元每个 skill 有明确的输入、输出和约束。多个 skill 可以组合成一条workflow工作流工作流里的每一步都有校验点。这样一来上下文被切分成可控的块步骤被固化下来可以复用质量也有了检查机制。我个人的理解是这套思路借鉴了软件工程里“关注点分离”和“流水线”的经典思想只不过把执行者从人换成了 AI agent。你不再是对着一个万能助手喊话而是在指挥一支各司其职的小队。2.2 核心概念skill、workflow 与 agent 的关系要理解 superpowers得先把三个核心概念理清楚不然看文档会一头雾水。Skill是最小执行单元。一个 skill 通常对应一件具体的事比如“读取指定文件并总结结构”“根据接口定义生成类型声明”“对改动做静态检查”。每个 skill 会定义它需要什么输入、产出什么结果、在什么条件下算成功。你可以把它类比成一个函数有明确的签名和职责。Workflow是 skill 的编排。它定义了多个 skill 按什么顺序执行、哪些可以并行、哪一步失败要回滚。比如一个“新增 API 端点”的 workflow可能是先读现有路由结构 → 生成 handler 骨架 → 补全类型 → 写测试 → 跑 lint。workflow 是这套框架真正产生价值的地方因为它把“老手的经验”固化成了可执行的流程。Agent是执行载体。Claude Code、Codex CLI 这些工具扮演的就是 agent 的角色它们负责实际调用模型、执行终端命令、读写文件。superpowers 不关心你用哪个 agent它关心的是 skill 和 workflow 怎么定义。这也是为什么它能同时适配 Claude Code 和 Codex CLI——框架层和执行层是解耦的。三者关系可以用一句话概括agent 提供能力skill 封装能力workflow 组织能力。理解了这层后面所有的配置和操作都会顺很多。2.3 为什么选择 Claude Code 和 Codex CLI 作为主要载体市面上能跑 agentic workflow 的工具不少但 superpowers 社区里讨论最多的还是 Claude Code 和 Codex CLI。这不是偶然。Claude Code 的优势在于终端原生和文件系统操作能力强。它直接在终端里跑能读写项目文件、执行命令、看 git 状态这些能力对 workflow 落地至关重要。而且它的 skill 机制相对开放你可以用自然语言描述复杂的多步任务它会自己规划执行路径。对于需要频繁和代码库交互的场景Claude Code 的体验是目前比较顺的。Codex CLI 的优势在于命令体系清晰和可脚本化程度高。它的/compact、/model、/resume这些命令让会话管理变得很可控。特别是/compact能在上下文快满的时候压缩历史这对长 workflow 特别有用。另外 Codex CLI 对本地模型的支持相对友好想接 LM Studio 跑本地模型的话配置起来比 Claude Code 省事。两者不是二选一的关系。我的实际做法是探索性、需要大量文件操作的任务用 Claude Code流程固定、需要反复执行的任务用 Codex CLI。superpowers 的 skill 定义是通用的换载体不用重写。3. 核心细节解析与实操要点3.1 Claude Code 安装配置全流程Claude Code 的安装不同系统差别不小我按平台分开说顺便把常见的坑标出来。macOS 安装相对最省心。官方推荐的方式是通过包管理器安装装完之后在终端直接敲命令就能启动。需要注意的是第一次启动会引导你登录账号如果你所在的环境访问受限可能会遇到提示说服务在当前地区不可用。这种情况通常和账号注册地、网络环境有关建议先确认账号状态是否正常。Ubuntu 安装要稍微注意权限问题。如果你用普通用户安装可能会在全局命令链接那一步失败需要加 sudo 或者配置用户级的 bin 目录。我一般建议直接用用户级安装避免污染系统环境。装完之后记得把对应的 bin 目录加到 PATH 里不然会提示 command not found。Windows 安装是坑最多的。最常见的一个报错是提示与 64 位版本不兼容这通常是因为装到了 32 位的运行环境里或者系统缺少必要的运行库。解决办法是确认系统架构、装对应版本必要时用 WSL 来跑。说实话Windows 上跑这类终端工具WSL 的体验比原生好太多我强烈建议 Windows 用户直接上 WSL。安装完成后验证是否成功很简单敲一下版本命令能正常输出版本号就说明装好了。如果报错先看错误信息里提到的路径和权限八成问题出在这两处。提示安装过程中如果遇到账号相关的限制提示先别急着反复重装多半不是安装本身的问题而是账号或环境配置的问题重装解决不了。3.2 VS Code 接入 Claude Code 的配置要点很多人不习惯纯终端操作想在 VS Code 里用 Claude Code。这条路是通的但配置有几个关键点。首先是插件安装。在 VS Code 的扩展市场里搜对应的插件装完之后需要配置。配置的核心是告诉插件 Claude Code 的可执行文件在哪、用哪个模型、工作目录是什么。这几项配错任何一项插件都会连不上。其次是工作目录的设置。这一点特别容易被忽略。如果你不指定工作目录插件可能会用 VS Code 当前打开的文件夹也可能用默认目录导致 AI 读不到你想要的代码。我的习惯是每个项目单独配一个工作目录避免跨项目串味。再就是模型选择。VS Code 插件里可以指定用哪个模型如果你接了第三方 API 或者本地模型这里要填对。填错的话表现是能连上但回复很慢或者报错。实测下来VS Code 插件的体验和终端版有差异。终端版在文件操作和命令执行上更直接插件版在代码补全和行内建议上更顺手。我的建议是两个都装按场景切换写代码时用插件跑 workflow 时用终端。3.3 Codex CLI 命令体系与常用操作Codex CLI 的命令体系是它的一大亮点几个核心命令必须掌握。/compact是我用得最多的。当会话历史变长、上下文快满的时候用它来压缩。压缩之后模型会保留关键信息丢掉冗余对话这样能继续在同一个会话里干活不用重开。对于长 workflow这个命令能救命。/model用来切换模型。同一个会话里你可能想让不同步骤用不同模型——简单任务用快模型复杂推理用强模型。这个命令让切换变得很轻量。/resume用来恢复之前的会话。有时候你关掉终端去干别的回来想接着之前的进度用它就能把上下文捞回来。这个功能对多天推进的项目特别实用。除了这几个还有一些辅助命令比如查看当前状态、清理会话等。建议花十分钟把命令列表过一遍知道有哪些能力用的时候才不会抓瞎。删除 Codex CLI 的指令也要知道。如果你要卸载或者清理配置得找到对应的配置目录手动删掉相关文件。不同系统配置目录位置不一样macOS 和 Linux 通常在用户主目录下的隐藏文件夹里Windows 在 AppData 里。删之前建议备份免得误删了重要配置。3.4 本地模型接入以 LM Studio 为例想省钱或者想数据不出本地接本地模型是个好选择。以 LM Studio 为例说下流程。第一步是在 LM Studio 里加载模型并启动本地服务。启动后它会给你一个本地地址通常是 localhost 加一个端口。这个地址就是后面要填的 API 端点。第二步是在 Claude Code 或 Codex CLI 里配置这个端点。你需要把 API base URL 指向本地地址模型名填 LM Studio 里加载的那个模型的名字。有些工具还需要你填一个 API key本地模型随便填个占位符就行。第三步是测试连通性。发一个简单请求看能不能正常返回。如果连不上先检查 LM Studio 的服务是不是真的在跑再看端口有没有被占用最后看防火墙有没有拦。这里有个经验本地模型的上下文窗口通常比云端小跑长 workflow 容易爆。所以接本地模型时workflow 要设计得更精简或者多用/compact压缩。另外本地模型的指令遵循能力参差不齐skill 的约束要写得更明确别指望它自己领会。3.5 第三方 API 接入技巧除了官方和本地模型接第三方 API 也是常见需求。比如用 CC Switch 这类工具把请求转发到 DeepSeek、Qwen、GLM 等模型上。接入的核心是端点、密钥、模型名三件套。端点填第三方服务提供的地址密钥填你申请到的模型名填对方支持的模型标识。三样都对上基本就能通。但有几个坑要注意。第一是格式兼容性不同服务商的 API 格式可能有细微差异有的工具能自动适配有的需要你手动调。第二是速率限制第三方服务通常有 QPS 或 token 限制workflow 跑太快会被限流建议在 skill 里加适当的重试和退避。第三是模型能力差异同一个 prompt 在不同模型上效果可能差很多skill 里的约束要针对目标模型调优。我的做法是先用一个最小 workflow 测通链路确认能正常调用再逐步加复杂度。一上来就跑完整 workflow出问题很难定位是配置问题还是模型问题。4. 实操过程与核心环节实现4.1 从零搭建一个最小可用 workflow光说概念没用我带你搭一个最小 workflow跑通之后你就理解整套机制了。假设我们要做一个“给现有函数补测试”的 workflow。它包含三个 skill第一个 skill 读取目标文件识别出没有测试覆盖的函数第二个 skill 针对每个函数生成测试用例第三个 skill 运行测试并报告结果。第一步定义 skill 的输入输出。第一个 skill 输入是文件路径输出是函数列表。第二个 skill 输入是单个函数输出是测试代码。第三个 skill 输入是测试文件输出是运行结果。每个 skill 的职责单一这样出问题容易定位。第二步在 Claude Code 里描述这个 workflow。你可以用自然语言把三个步骤串起来明确每步的约束比如“生成的测试要覆盖边界条件”“不要修改原函数”。Claude Code 会按你的描述规划执行。第三步跑一遍看结果。第一次跑大概率不完美可能测试生成得不全或者运行报错。这时候不要急着改 workflow先看是哪一步出的问题。如果是生成质量不行调整第二个 skill 的约束如果是运行环境问题检查测试框架配置。第四步把跑通的 workflow 固化下来。把 skill 定义和编排逻辑存成文件下次直接复用。这就是 superpowers 框架的价值——一次调优长期复用。4.2 参数选择与上下文管理workflow 跑得好不好上下文管理占一半功劳。这里说几个关键参数。上下文窗口大小决定了你一次能塞多少信息。云端模型通常窗口大本地模型窗口小。设计 workflow 时要估算每一步大概消耗多少 token。一个粗略的经验是读一个中等大小的源文件大概几千 token生成测试又是几千跑几轮就上万了。窗口不够就得靠/compact或者拆分 workflow。温度参数影响输出的随机性。生成代码时温度别太高不然会冒出奇怪的写法做头脑风暴时可以调高一点。不同工具设置温度的方式不一样有的在配置文件里有的在命令参数里。最大输出长度要设合理。设太短生成的代码被截断设太长浪费 token 还可能跑偏。一般按任务复杂度设简单任务几千复杂任务上万。我踩过的一个坑是没控制好上下文导致 workflow 跑到一半模型开始胡言乱语。后来学乖了在每个 skill 之间加一个检查点确认上一步输出合理再继续不合理就压缩或者重来。4.3 让 AI 直接执行终端命令的注意事项Claude Code 和 Codex CLI 都能直接执行终端命令这个能力很强大但也很危险。强大的地方在于workflow 可以真正闭环。比如生成代码之后直接跑测试、跑 lint、跑构建不用你手动复制命令。这让自动化程度大幅提升。危险的地方在于AI 可能执行你不想执行的命令。比如它可能误删文件、误改配置、跑一个耗时很长的任务。所以权限控制必须做好。我的做法是分三级。第一级是只读操作随便跑。第二级是写操作但限定在项目目录内允许但要有日志。第三级是系统级操作比如装包、改全局配置必须手动确认。Claude Code 和 Codex CLI 都支持某种形式的确认机制一定要开启。另外在 workflow 里执行命令要加超时。有些命令可能卡住没有超时的话整个 workflow 就挂那了。设个合理的超时超了就跳过或者报错别让它无限等。4.4 飞书等协作工具与 workflow 的衔接团队协作场景下把 workflow 和飞书这类工具连起来能省不少事。思路是这样的workflow 跑完之后把结果推送到飞书群或者文档里。比如代码审查 workflow 跑完把发现的问题整理成消息发到群里或者测试 workflow 跑完把报告写进飞书文档。实现方式通常是调用飞书的开放接口。你需要在飞书那边创建一个应用拿到凭证然后在 workflow 的最后一步加一个 skill负责把结果格式化并发送。这一步的关键是结果格式化要让消息在飞书里读起来清晰别一股脑把原始输出扔过去。我实际用下来这个衔接对团队效率提升明显。以前代码审查结果要人工整理转发现在自动就推送到位了。但要注意别推送太频繁不然会变成骚扰。建议按需触发或者做每日汇总。5. 常见问题与排查技巧实录5.1 安装与登录类问题速查问题现象可能原因排查方向提示当前地区不可用账号或环境配置问题确认账号状态检查环境配置提示与 64 位系统不兼容装错架构版本或缺运行库确认系统架构补装运行库考虑 WSLcommand not foundPATH 没配好检查 bin 目录是否加入 PATH登录后仍提示未授权凭证过期或缓存问题清理缓存重新登录插件连不上终端可执行文件路径配错检查插件配置里的路径这张表是我自己踩坑总结的基本覆盖了安装阶段八成的问题。遇到报错先对号入座能省很多瞎折腾的时间。5.2 模型调用与响应异常排查模型调用出问题表现通常是连不上、响应慢、输出乱、中途断。连不上先查网络和端点配置。响应慢先看是不是模型太大或者上下文太长。输出乱通常是 prompt 或温度的问题。中途断多半是上下文超限或者超时。我遇到过一个比较隐蔽的问题第三方 API 返回格式和工具预期不一致导致解析失败。表现是能连上但一直报错。解决办法是抓一下原始返回对比工具文档里说的格式看差在哪。有时候是字段名不一样有时候是嵌套结构不同改配置或者加一层转换就行。还有一个常见问题是模型不遵循 skill 约束。这在小模型上特别明显。解决办法是把约束写得更硬用明确的祈使句别用“建议”“最好”这种软词。必要时在 skill 里加校验步骤输出不符合就重来。5.3 上下文超限与性能优化上下文超限是长 workflow 的头号杀手。症状是跑到一半模型开始重复、遗忘或者报错。应对手段有几个。最直接的是/compact压缩。其次是拆分 workflow把一个大流程拆成几个小流程每个跑完存结果下一个读结果继续。再就是精简 skill 的输入别把整个文件都塞进去只给相关片段。性能优化方面并行化是个好思路。workflow 里没有依赖关系的 skill 可以并行跑省时间。比如同时生成多个模块的测试没必要串行。但并行要注意资源竞争别同时写同一个文件。另外缓存中间结果能省很多重复计算。比如读文件解析出的结构存下来给后续 skill 用别每次都重新读。5.4 独家避坑经验说几个文档里不会写、但实际很要命的坑。第一个坑别在 workflow 里跑交互式命令。有些命令会等你输入AI 不知道要输入什么就卡住了。跑之前确认命令是非交互的或者用参数跳过交互。第二个坑文件路径用绝对路径。相对路径在不同工作目录下会解析成不同结果AI 很容易搞混。统一用绝对路径省心。第三个坑git 状态要干净再跑 workflow。如果工作区有未提交的改动AI 改完文件之后你分不清哪些是它改的、哪些是你之前改的。跑之前先 commit 或者 stash。第四个坑别让 AI 碰敏感文件。比如密钥文件、生产配置在 workflow 里明确排除。一旦被误改后果可能很严重。第五个坑定期备份 skill 定义。调好的 workflow 是资产丢了要重来。存到 git 里或者至少定期导出。6. 框架的延展玩法与个人体会superpowers 这套 agentic skills framework 真正有意思的地方是它能延展出很多玩法。比如你可以把常用的代码审查规则做成 skill 库团队共享。新人提交代码自动跑一遍审查 workflow把常见问题挡在人工审查之前。再比如你可以把部署流程做成 workflow从构建到测试到发布一条龙减少手动操作出错。我还见过有人把 remotion 这类视频生成工具接进 workflow用 AI 生成脚本、生成素材、渲染视频整个流程自动化。这说明这套框架的边界不限于写代码任何有明确步骤的任务都能往里套。我个人的体会是这套框架最大的价值不是省了多少时间而是把经验沉淀下来了。以前老手的开发习惯只存在脑子里现在能写成 skill 和 workflow让整个团队受益。新人上手快老人也不用反复解释。当然它也不是银弹。workflow 设计得好不好直接决定效果。设计得糙还不如手动干。所以前期投入时间打磨 skill 是值得的别指望随便写写就能跑出好结果。最后分享一个小技巧从最小的 workflow 开始跑通了再加复杂度。我见过太多人一上来就想搭个大而全的流程结果处处报错最后放弃。先用两三个 skill 跑通一个简单任务建立信心再逐步扩展。这个节奏最稳。另外社区里关于 Claude Code 和 Codex CLI 的讨论一直在更新命令和配置可能会变。遇到问题先查官方文档再看社区讨论别死磕过时的教程。工具在进化用法也得跟着更新。