★ FEATURED ARTICLE 1. 从“superpowers”说起这套 agentic skills framework 到底在解决什么问题第一次看到 “superpowers” 这个词是在几个做 AI 编程工具链的朋友群里。有人甩了一句“想要安装 superpowers”底下立刻有人接“你是说 Claude Code 那套还是 Codex CLI 那套”。我当时就意识到这已经不是某个单一工具的名字而是一整套围绕agentic skills framework和software development methodology长出来的实践体系。先把话说清楚superpowers 不是某个能一键下载的软件包它更像是一套“给 AI 编程代理装上技能树”的方法论框架。核心思路是把一个通用的大模型代理比如 Claude Code、Codex CLI 这类命令行代理工具通过结构化的技能定义、上下文注入和工具编排变成能稳定完成特定开发任务的“专业选手”。它解决的问题很具体——通用代理什么都懂一点但落到真实项目里经常犯低级错误、忘记上下文、乱改文件、跑偏需求。superpowers 就是用来治这些毛病的。这套东西适合谁如果你已经在用 Claude Code 或者 Codex CLI但总觉得“它有时候很聪明有时候又像个傻子”那这套框架就是给你准备的。如果你还没入门只是想搞清楚 claude code 安装、codex cli 安装这些基础问题那也建议先了解 superpowers 的设计思路因为它会直接影响你后面怎么配置工具、怎么组织项目、怎么调用本地模型。我自己的判断是2024 年之后AI 编程工具的竞争已经从“模型谁更强”转向“代理框架谁更稳”。superpowers 代表的正是后一种思路——不追求模型本身多神而是通过工程化的技能编排让普通模型也能干出专业活。这也是为什么热搜里同时出现 claude code、codex cli、agentic skills framework 这些词它们本来就是一条链上的东西。2. 核心设计思路拆解为什么是“技能框架”而不是“提示词合集”2.1 从提示词工程到技能工程的范式转移早期大家用 AI 写代码基本就是写一段提示词把需求丢进去等结果。这种做法在简单任务上还行一旦项目超过几百行、涉及多个文件、需要跑测试、需要遵守团队规范就彻底崩了。原因很简单提示词是“一次性”的而软件开发是“持续性”的。superpowers 的第一个关键设计就是把“提示词”升级成“技能”。技能不是一段话而是一个有结构、有触发条件、有执行步骤、有验证标准的单元。举个例子普通提示词可能是“帮我写一个 React 组件”而一个技能定义会包含什么时候触发这个技能比如检测到 .tsx 文件、需要哪些上下文项目用的 UI 库、状态管理方案、执行步骤先读现有组件风格、再生成、再跑 lint、验证标准类型检查通过、无 ESLint 报错。这种设计背后的逻辑是把隐性知识显性化。一个资深工程师写组件时脑子里有一整套检查清单superpowers 就是把这套清单变成代理能执行的技能。这也是 agentic skills framework 这个词的真正含义——不是让代理更聪明而是让代理更守规矩。2.2 技能分层原子技能、组合技能与工作流在实际落地中superpowers 的技能通常分三层。最底层是原子技能比如“读取文件”“运行测试”“格式化代码”这些是代理的基础动作。中间层是组合技能比如“实现一个 API 端点”它会调用读文件、写代码、跑测试等多个原子技能。最上层是工作流比如“完成一个 feature 分支”它会串联需求分析、编码、测试、提交等多个组合技能。这种分层的好处是可复用、可调试。如果某个环节出问题你能快速定位是原子技能配置错了还是组合逻辑有问题。我见过太多团队把所有逻辑塞在一个巨大的提示词里结果代理一跑偏就完全没法排查。superpowers 的分层设计本质上是把软件工程的模块化思想搬到了代理编排上。2.3 与 Claude Code、Codex CLI 的关系Claude Code 和 Codex CLI 是这套框架的“运行宿主”。superpowers 本身不绑定某个具体工具但它的技能定义需要宿主提供几个能力文件系统访问、终端命令执行、上下文管理、模型调用。Claude Code 在这几点上做得比较完整尤其是它的项目级上下文管理和终端命令执行能力天然适合承载技能框架。Codex CLI 则更偏向轻量级命令行交互适合快速任务。这也是为什么热搜里 claude code 使用、codex cli 命令哪些 /compact /model /resume 这些词会同时出现。用户在实际操作中会发现不同宿主对技能的支持程度不一样配置方式也不一样。比如 Claude Code 的 /compact 命令用来压缩上下文这在长会话中非常关键因为技能执行会消耗大量 token不压缩很快就会超出窗口。3. 环境准备与工具安装从零把宿主跑起来3.1 Claude Code 安装的几条路径与选择逻辑claude code 安装这件事看起来简单实际上坑不少。官方提供了几种方式npm 全局安装、桌面版安装包、VS Code 插件。我的建议是如果你主要做命令行开发优先用 npm 安装如果你习惯图形界面再考虑桌面版。npm 安装的命令大致是npm install -g anthropic-ai/claude-code装完之后用claude命令启动。这里有个常见问题mac 安装 claude code 和 ubuntu 安装 claude code 的权限处理不一样。mac 上如果遇到权限报错通常是因为 npm 全局目录没有写权限可以用sudo或者改 npm prefix。ubuntu 上则要注意 Node 版本建议用 nvm 管理避免系统自带 Node 版本太老。注意安装过程中如果提示 “claude code might not be available in your country”这通常是网络或账号区域问题不是安装本身的问题。先确认你的账号状态和网络环境再排查安装步骤。3.2 Codex CLI 安装与常用命令速查Codex CLI 的安装相对轻量通常也是通过 npm 或直接下载二进制。装完之后你需要熟悉几个核心命令这些在热搜里也被反复提到命令作用使用场景/compact压缩当前会话上下文长会话 token 快满时/model切换或查看当前模型需要在不同模型间对比时/resume恢复之前的会话中断后继续任务/help查看所有可用命令刚上手时删除 codex cli 指令这个需求通常出现在你想清理环境或者重装的时候。如果是 npm 安装的用npm uninstall -g对应包名即可。但要注意卸载不会自动清理配置文件和缓存这些通常在用户目录下的隐藏文件夹里需要手动删。3.3 VS Code 配置 Claude Code 的实操细节vscode 配置 claude code 是很多人的首选因为能在编辑器里直接调用。安装 claude code for vs code 插件后需要在设置里配置 API 密钥或者登录账号。这里有个关键点插件模式和命令行模式的上下文是分开的插件里配置的项目路径、模型选择不会自动同步到终端。如果你要用 vscode 接入 claude code 并调用本地模型比如通过 LM Studio 跑本地模型需要在插件设置里把 API endpoint 指向本地服务地址。claude code 调用 lmstudio 的本地模型这个场景核心是确认 LM Studio 的本地服务器开启了 OpenAI 兼容接口然后在 Claude Code 的配置里把 base URL 改成http://localhost:1234/v1这类地址。提示本地模型的能力和云端模型差距明显用它跑 superpowers 这类技能框架时建议先从简单技能开始不要一上来就上复杂工作流。4. 技能框架的落地从配置到第一个可运行技能4.1 技能定义文件的结构与编写要点superpowers 的技能通常以结构化文件形式存在可能是 YAML、JSON 或者特定格式的 Markdown。一个典型的技能定义包含几个部分元信息名称、版本、描述、触发条件什么情况下激活、上下文需求需要读取哪些文件或变量、执行步骤具体做什么、验证标准怎么算成功。编写技能时最容易犯的错误是“步骤太粗”。比如写“实现登录功能”代理根本不知道从哪下手。正确的做法是拆到可执行粒度先读现有路由文件、再检查是否已有认证中间件、再生成控制器、再写测试、再跑测试。每一步都要明确输入和输出。另一个要点是验证标准必须可自动检查。如果你写“代码质量好”代理没法判断。但如果你写“通过 ESLint 且测试覆盖率不低于 80%”代理就能跑命令验证。这是技能框架和普通提示词的本质区别。4.2 上下文注入让代理真正“懂”你的项目技能执行效果好不好很大程度上取决于上下文注入是否到位。superpowers 通常会在技能触发时自动注入几类上下文项目结构、相关文件内容、团队规范、历史提交记录。这些信息不是一股脑塞进去而是按需加载。我自己的经验是上下文注入要遵循“最小必要”原则。注入太多token 消耗快代理还容易分心注入太少代理又容易瞎猜。一个实用的做法是在技能定义里明确写“需要读取哪些文件”而不是让代理自己去探索。比如实现 API 端点时明确指定读取路由文件、控制器目录、测试目录代理就不会乱翻整个项目。4.3 第一个可运行技能以“新增一个 REST 端点”为例假设我们要写一个技能让代理在现有项目里新增一个 REST 端点。技能定义大致如下name: add-rest-endpoint trigger: 用户要求新增 API 端点 context: - 读取 routes/ 目录下所有文件 - 读取 controllers/ 目录下同类控制器 - 读取 tests/ 目录下同类测试 steps: - 分析现有路由命名规范 - 生成路由注册代码 - 生成控制器方法 - 生成对应测试 - 运行测试并检查通过 validation: - 测试全部通过 - 无 lint 错误这个技能跑起来后代理会按步骤执行每步都有明确产出。如果测试失败它会回到生成代码那一步重新调整而不是直接放弃。这就是技能框架的价值——它给了代理一个“纠错循环”。5. 模型接入与第三方 API 的实战配置5.1 使用 cc switch 接入 DeepSeek、Qwen、GLM 等模型cc switch 这类工具的作用是帮你在不同模型提供商之间快速切换。使用 cc switch 接入 deepseek v4、qwen、glm 等模型核心是配置好每个提供商的 API endpoint 和密钥然后通过 switch 命令切换当前使用的模型。配置时要注意几点不同模型的上下文窗口不一样切换后要相应调整 /compact 的触发阈值不同模型对技能定义格式的兼容性也有差异有些模型对结构化指令遵循得更好有些则容易忽略细节。我的建议是先用简单技能测试每个模型的遵循度再决定用哪个跑复杂工作流。5.2 第三方 API 使用技巧与常见坑第三方 API 使用技巧里最关键的是错误处理和重试策略。很多第三方 API 在高峰期会返回 429 或 503如果代理没有重试机制技能执行就会中断。在 superpowers 的技能定义里可以加一层重试逻辑比如失败后等待几秒再试最多重试三次。另一个坑是计费和配额。第三方 API 通常按 token 计费技能框架跑起来 token 消耗比普通对话大得多。建议在配置里加上用量监控避免月底账单爆炸。我自己的做法是给每个技能设置 token 上限超过就暂停并提示。5.3 本地模型与云端模型的取舍claude code 调用 lmstudio 的本地模型适合对数据隐私要求高、或者想省成本的场景。但本地模型在复杂技能上的表现目前和云端模型还有差距。我的建议是混合使用简单任务、格式化、文件读取用本地模型复杂推理、代码生成、测试修复用云端模型。这种混合模式需要在技能定义里做路由比如根据任务类型选择模型。superpowers 框架本身支持这种路由配置但需要你手动定义规则。规则不用太复杂先按任务复杂度分两档就行。6. 常见问题与排查技巧实录6.1 安装与登录类问题速查问题现象可能原因解决思路安装后命令找不到全局路径未加入 PATH检查 npm prefix 和 shell 配置登录失败账号区域或网络问题确认账号状态检查网络桌面版安装包报错系统版本不兼容确认系统要求换命令行版与 64 位 Windows 不兼容安装包架构不匹配下载对应架构版本claude code 注册账号和不注册有啥不同这个问题很多人问。简单说注册账号后能用云端模型和同步功能不注册只能用本地配置的模型功能受限。如果你只是本地测试不注册也能跑但长期用还是建议注册。6.2 技能执行跑偏的排查思路技能跑偏通常有三个原因上下文注入不对、技能定义太模糊、模型遵循度不够。排查时先看上下文确认代理读到的文件是不是你期望的再看技能定义步骤是不是够具体最后换模型测试看是不是模型本身的问题。我踩过的一个坑是技能定义里写了“参考现有代码风格”但没指定参考哪个文件结果代理参考了一个完全不相关的旧文件生成了一堆过时写法。后来改成明确指定参考文件路径问题就解决了。6.3 上下文管理与 /compact 的使用时机长会话跑技能框架token 消耗非常快。 /compact 命令的作用是压缩上下文把历史对话摘要化释放 token 空间。使用时机很关键不要等到快满了才压缩那样可能已经丢失关键信息也不要在技能执行中途压缩那样会打断执行流。我的经验是每完成一个组合技能就压缩一次这样既保留了关键结果又释放了空间。压缩后要检查摘要是否准确有时候压缩会丢掉一些细节需要手动补回来。7. 把 superpowers 用成习惯一些个人体会这套东西刚上手时确实有点重配置多、概念多、要记的命令也多。但我用下来最大的感受是一旦跑通第一个技能后面就是复制粘贴加微调。真正花时间的不是写技能定义而是想清楚“这个任务到底该怎么拆”。拆得越细代理执行越稳。另一个体会是不要追求一步到位。我见过有人一上来就想让代理自动完成整个 feature结果各种报错最后放弃。正确的做法是从最小技能开始比如“格式化一个文件”跑通了再加复杂度。superpowers 的威力不在于单个技能多强而在于技能之间能组合、能复用、能积累。最后分享一个小技巧给每个技能写一个“失败案例”注释记录这个技能在什么情况下会失败、怎么修复。这些注释积累多了就是你自己的一套排查手册比任何官方文档都实用。
阅读完成 · 觉得有帮助？
深度解析：线程模型、异常排查与阻塞陷阱)
