1. 拆解 superpowers它到底想解决什么问题第一次看到 “superpowers” 这个词加上旁边跟着的 agentic skills framework、software development methodology、Claude Code、Codex CLI 这几个关键词我大概能猜到它想干什么。它不是某个具体的库也不是一个能直接npm install就完事的工具而是一套围绕 AI 编程助手构建的技能框架和协作方法论。说白了它想回答一个很现实的问题当 Claude Code、Codex CLI 这类终端里的 AI 编程代理越来越能干的时候我们怎么把它们的“能力”组织起来让它们像一支训练有素的工程团队而不是一个只会单点输出的聊天机器人。我接触 Claude Code 和 Codex CLI 有一段时间了最开始的新鲜感过去之后最大的痛点就暴露出来每次开一个新会话它就像失忆一样你得重新交代项目背景、代码规范、目录结构、测试命令。你让它改一个函数它可能顺手把旁边三个文件也动了理由是“顺手优化”。这不是模型不行而是缺少一层技能封装和流程约束。superpowers 这类框架的价值就在于把这层约束和封装标准化让 AI 代理在明确的技能边界内工作。所以这篇文章适合谁看如果你已经在用 Claude Code 或者 Codex CLI但总觉得“它很强但用起来累”那这套思路对你直接有用。如果你还没上手只是想搞清楚这些终端 AI 编程工具到底怎么落地我也会把安装、配置、模型接入这些基础环节讲清楚因为 superpowers 这类框架是建立在它们之上的。核心关键词 superpowers、agentic skills framework、software development methodology 会贯穿全文我不会只讲概念而是把每一步为什么这么做、参数怎么定、坑在哪里都摊开说。2. 核心设计思路为什么是“技能框架”而不是“提示词合集”2.1 从提示词工程到技能工程的转变很多人对 AI 编程助手的理解还停留在“写好提示词”的阶段。你写一段详细的 prompt告诉它要做什么、不要做什么然后祈祷它听话。这个方法在单次任务里有效但一旦任务变复杂、会话变长提示词就会被稀释、被遗忘。superpowers 背后的 agentic skills framework 思路是把“提示词”升级成“技能”——每个技能是一个有明确输入、输出、边界和验证方式的独立单元。我举个实际例子。假设你要让 AI 帮你写一个数据库迁移脚本。提示词思路是“请帮我写一个迁移脚本注意不要删数据要加事务要兼容旧版本。”技能思路是定义一个database-migration技能它包含触发条件用户提到迁移、schema 变更、执行步骤先读现有 schema、生成 diff、写迁移文件、跑测试、约束禁止 DROP 操作、必须包事务、验证迁移后跑一遍回滚测试。这两者的差别就像“口头交代任务”和“给员工一份标准作业程序”。为什么这种转变重要因为 AI 代理的上下文窗口是有限的而技能可以被索引、被复用、被组合。你不需要每次都在 prompt 里重复所有约束框架会在合适的时机把对应的技能加载进来。这就是 software development methodology 在 AI 时代的延伸——不是给人看的文档而是给代理执行的规范。2.2 技能框架的三个核心层次我把 superpowers 这类框架拆成三个层次来理解这样你在自己搭建或者选型的时候心里有数。第一层是技能定义层。每个技能要写清楚名称、描述、触发场景、前置条件、执行步骤、输出格式、失败处理。这一层的关键是“可判定”也就是说代理能根据当前上下文判断该不该用这个技能。描述写得太模糊代理就不知道该不该触发写得太死又会漏掉合理的场景。第二层是编排层。多个技能之间怎么协作谁先谁后什么时候需要人工确认这一层解决的是“代理自己决定下一步”的问题。比如一个code-review技能执行完之后如果发现问题应该自动触发fix-issue技能还是先停下来问人编排策略直接决定了代理是“自主干活”还是“频繁打断你”。第三层是执行与反馈层。技能真正跑起来的时候怎么调用工具、怎么读文件、怎么跑命令、怎么把结果反馈给模型。这一层跟具体的工具链强相关Claude Code 和 Codex CLI 在这一层的实现方式就不一样。Claude Code 更偏向在终端里直接操作文件系统和执行命令Codex CLI 则在命令组织和会话管理上有自己的风格。注意技能定义不是越细越好。我见过有人把每个函数都写成一个技能结果代理在触发时疯狂纠结该用哪个。技能粒度应该对齐“一个完整的工程动作”比如“新增一个 API 端点”而不是“写一个函数”。2.3 为什么这套思路在终端代理上特别成立终端里的 AI 编程代理和网页版聊天机器人有一个本质区别它能直接操作你的工作目录。这意味着它的每一个动作都有真实后果——改错文件、跑错命令、覆盖配置。superpowers 这类框架在终端环境里特别有价值因为它给代理装上了“护栏”和“检查点”。网页版聊天机器人说错话你复制粘贴的时候还能自己判断。终端代理直接rm一个文件你可能要花半小时从 git 里捞回来。所以技能框架里的约束和验证步骤在终端环境里不是锦上添花而是必需品。这也是为什么 superpowers 会和 Claude Code、Codex CLI 这些工具一起被讨论——它们共同构成了“能干活但需要管住”的 AI 编程工作流。3. 环境准备把 Claude Code 和 Codex CLI 跑起来3.1 Claude Code 的安装与基础配置Claude Code 的安装方式取决于你的操作系统。macOS 和 Linux 上官方推荐的方式是通过包管理器或者直接下载二进制。Ubuntu 用户要注意某些版本对 64 位兼容性有要求如果你在 Windows 上遇到“与 64 位版本不兼容”的提示通常是因为系统架构或者运行环境的问题换用 WSL 或者直接在 Linux 环境下操作会顺畅很多。安装完成之后第一件事是确认版本和基本命令可用claude --version claude --help如果这两条命令能正常输出说明基础环境没问题。接下来是配置模型接入。Claude Code 默认走官方订阅但很多人会遇到“your organization has disabled claude subscription access”这类提示或者所在地区不支持。这时候就需要考虑接入第三方 API 或者本地模型。我实测下来用 cc switch 这类工具来切换模型源是比较省心的做法。它支持接入 DeepSeek、Qwen、GLM 等模型配置方式通常是设置环境变量或者修改配置文件。以接入本地 LM Studio 为例你需要先在 LM Studio 里启动一个兼容 OpenAI 接口的服务然后在 Claude Code 的配置里把 base URL 指向本地地址比如http://localhost:1234/v1再填上对应的模型名称。export ANTHROPIC_BASE_URLhttp://localhost:1234/v1 export ANTHROPIC_API_KEYlm-studio提示本地模型的能力和云端模型有差距尤其是在复杂代码推理上。如果你的任务涉及大量跨文件重构建议还是用能力更强的模型本地模型更适合做代码补全、简单重构和隐私敏感的场景。3.2 Codex CLI 的安装与常用命令Codex CLI 是另一个终端 AI 编程工具它的命令风格和 Claude Code 有区别。安装方式同样取决于平台装完之后你需要熟悉几个核心命令。根据热词里提到的/compact、/model、/resume这几个是日常使用频率最高的。/model用来切换当前会话使用的模型。不同模型在代码生成、推理深度、响应速度上差异明显你可以根据任务类型来选。/compact用来压缩会话历史当对话变长、上下文快满的时候用它把前面的内容摘要化腾出空间给新任务。/resume用来恢复之前的会话这个在中断之后继续干活时特别有用。删除 Codex CLI 的指令通常是卸载命令具体取决于你的安装方式。如果是通过包管理器装的用对应的 remove 命令如果是手动下载的二进制直接删掉文件并清理 PATH 里的引用即可。3.3 VS Code 里的集成配置很多人不习惯纯终端操作那 VS Code 插件是个好选择。Claude Code for VS Code 插件装完之后你可以在编辑器里直接调用代理同时保留文件树、diff 视图这些可视化能力。配置的关键点在于插件需要知道你的模型接入方式——是走官方订阅还是第三方 API。如果你在 VS Code 里遇到连接问题先检查插件的配置项是否和终端环境一致。有时候终端里配好了环境变量但 VS Code 启动时没有继承就会导致插件连不上。解决办法是在 VS Code 的设置里显式填入 base URL 和 API key或者从终端启动 VS Code 让它继承环境变量。4. 把 superpowers 思路落地技能定义与编排实操4.1 定义一个最小可用技能光说概念没意思我直接给你一个可以抄的技能定义模板。假设我们要定义一个add-api-endpoint技能用于在现有项目里新增一个 REST 接口。name: add-api-endpoint description: 在现有 Web 项目中新增一个 REST API 端点包含路由、控制器、服务层和测试 triggers: - 用户要求新增接口 - 用户要求添加路由 - 用户提到 endpoint、API、route preconditions: - 项目使用标准的分层结构 - 存在路由注册文件 steps: - 读取现有路由文件确认注册方式 - 在控制器目录创建新控制器 - 在服务层创建对应服务 - 在路由文件注册新端点 - 生成对应的单元测试 - 运行测试并确认通过 constraints: - 不修改现有端点的行为 - 不引入新的第三方依赖除非明确要求 - 所有新增代码必须符合项目现有风格 output: - 新增文件列表 - 修改文件列表 - 测试运行结果 failure_handling: - 如果测试失败回滚所有改动并报告原因 - 如果路由注册方式不明确停下来询问这个模板的关键在于preconditions和constraints。前置条件让代理知道“什么情况下这个技能才适用”约束让代理知道“什么不能做”。没有这两块代理就会自由发挥而自由发挥在工程场景里往往意味着灾难。4.2 技能编排让代理自己决定下一步单个技能跑通之后下一步是编排。编排的核心问题是一个技能执行完之后怎么决定下一个动作。我常用的策略是“验证驱动”——每个技能都必须有明确的验证步骤验证通过才继续验证失败就进入修复或者上报流程。举个例子add-api-endpoint技能跑完测试之后如果测试通过可以自动触发update-documentation技能把新端点写进 API 文档。如果测试失败则触发debug-failure技能让代理先分析失败原因再决定是自动修复还是交给人处理。这种编排方式的好处是代理不会在“要不要继续”这个问题上浪费你的时间。它按照预设的规则往前走只在真正需要决策的时候才停下来。我实测下来合理的编排能把人工干预频率降低一半以上。4.3 技能库的组织方式当你有十几个甚至几十个技能的时候怎么组织它们就变得重要了。我的做法是按“领域 动作”两层分类。领域比如frontend、backend、database、devops动作比如create、modify、review、debug。这样代理在触发时可以先定位领域再选择动作减少误触发。目录结构大概长这样skills/ backend/ add-api-endpoint.yaml modify-service.yaml review-controller.yaml database/ create-migration.yaml review-schema.yaml frontend/ add-component.yaml review-accessibility.yaml每个技能文件保持独立方便版本管理和复用。如果你在团队里推广这套东西还可以给每个技能加上owner和last_reviewed字段确保技能不会过期。5. 实操中的常见问题与排查技巧5.1 代理不触发技能怎么办这是最常见的问题。你定义了一个技能但代理在该用的时候没用。原因通常有三个触发条件写得太窄、技能描述和当前上下文不匹配、或者代理的上下文里根本没有加载到这个技能。排查顺序是这样的先看技能描述里用的词和用户实际说的话是否对得上。用户说“加个接口”你的触发词里只有“新增端点”那代理可能就匹配不上。解决办法是把触发词写得更口语化、更全面。然后检查技能是否被正确加载——有些框架需要显式注册技能不是放在目录里就自动生效。5.2 代理触发了错误的技能比不触发更麻烦的是触发错了。比如你让它改一个前端组件它却触发了数据库迁移技能。这通常是技能描述之间的边界不清晰导致的。解决办法是在技能描述里明确写出“不适用场景”或者在编排层加一个优先级机制让更具体的技能优先于更通用的技能。5.3 技能执行到一半卡住有时候代理执行到某个步骤就停住了既不继续也不报错。这种情况多半是某个步骤的输入不明确代理在“等你说清楚”。解决办法是在技能定义里给每个步骤加上明确的输入来源比如“从路由文件读取注册方式”而不是“了解路由注册方式”。后者太模糊代理不知道去哪了解。5.4 常见问题速查表问题现象可能原因排查动作解决方向技能不触发触发词不匹配对比用户表述和触发词扩充触发词加入口语化表达触发错误技能技能边界模糊检查技能描述重叠度明确不适用场景加优先级执行中途卡住步骤输入不明确检查步骤的输入来源给每步指定明确的数据来源测试反复失败约束条件不足检查 constraints 字段补充禁止操作和验证要求会话上下文溢出历史太长用 /compact 压缩定期压缩拆分长任务提示技能定义写完不是终点。我建议每跑通一个新任务就回头看看技能定义有没有需要补充的约束或触发词。技能库是养出来的不是一次写好的。6. 从工具到方法论superpowers 给开发流程带来的变化6.1 开发者的角色转变用了这套东西一段时间之后我最大的感受是我的角色从“写代码的人”变成了“定义规则的人”。以前我花大量时间在具体实现上现在我花更多时间在思考“这个任务应该由哪些技能组成”“每个技能的边界在哪里”“什么情况下需要人工介入”。这不是偷懒而是把精力从重复劳动转移到了流程设计上。这种转变对个人开发者来说可能感觉不明显但对团队协作影响很大。当技能库成为团队共享资产的时候新人上手项目的速度会快很多——他不需要读完所有代码只需要理解技能库里的规范就知道这个项目是怎么运转的。6.2 技能库的维护成本说实话维护技能库是有成本的。你需要定期 review 技能定义确保它们和项目实际结构一致。项目重构之后原来的技能可能就失效了。我的做法是把技能库纳入版本控制每次项目结构变更时同步更新相关技能。这听起来像额外工作但比起每次让代理重新学习项目结构长期来看是省时间的。6.3 什么场景不适合这套方法不是所有项目都适合上技能框架。如果你只是偶尔用 AI 写几个小脚本或者项目结构极不稳定、每天都在变那定义技能的成本可能高于收益。技能框架最适合的是项目结构相对稳定、有明确的工程规范、AI 代理使用频率高的场景。判断标准很简单——如果你发现自己反复在 prompt 里交代同样的背景信息那就是该把它技能化的时候了。7. 模型接入的实操细节与选择建议7.1 第三方 API 接入的注意事项接入第三方 API 的时候最容易踩的坑是接口兼容性。Claude Code 和 Codex CLI 对接口格式有特定要求不是所有标称“兼容 OpenAI”的服务都能直接对接。你需要确认服务支持的工具调用格式、流式响应方式、以及 token 计算方式是否和客户端预期一致。另一个坑是速率限制。第三方服务通常有更严格的 QPS 限制代理在快速连续调用工具的时候容易触发限流。解决办法是在配置里调低并发数或者选择支持更高并发的服务。7.2 本地模型的实际表现本地模型在隐私和成本上有优势但在代码任务上的表现需要合理预期。我实测下来本地模型在单文件补全、简单重构、注释生成这些任务上够用但涉及跨文件推理、复杂 bug 定位、架构设计的时候和云端模型的差距就出来了。如果你的工作流里这类复杂任务占比高本地模型更适合作为补充而不是主力。7.3 模型切换的时机不同任务用不同模型这是很实际的策略。快速迭代、写测试、改样式这类任务用响应快的模型架构设计、复杂重构、疑难 bug用推理能力强的模型。cc switch 这类工具的价值就在于让切换成本足够低你不需要改配置文件、重启服务一条命令就能换。8. 我踩过的坑和最后分享的几个技巧第一个坑是技能定义写得太理想化。我一开始把每个步骤都写得非常细结果代理执行的时候频繁卡在“这一步的输入格式不对”上。后来我学乖了步骤描述保持“做什么”的粒度具体“怎么做”留给代理自己判断。技能定义是约束边界不是写死实现。第二个坑是忽略验证步骤。早期我定义的技能很多没有验证环节代理干完活就说完成了结果一跑测试全是红的。现在我强制每个技能必须有验证步骤而且验证必须是可执行的命令不是“检查一下是否正确”这种模糊表述。第三个技巧是关于会话管理的。长任务一定要拆成多个会话每个会话聚焦一个技能或者一组相关技能。会话太长不仅会触发上下文限制还会让代理的注意力分散。用/compact压缩历史是个好习惯但更好的做法是从一开始就把任务拆小。最后一个技巧技能库要定期“断舍离”。用不上的技能、过期的技能、边界模糊的技能该删就删。技能库不是越大越好而是越精准越好。一个触发准确、约束清晰的技能比十个模棱两可的技能有价值得多。