1. 拆解 superpowers：它到底想解决什么问题

第一次看到 “superpowers” 这个词，加上旁边跟着的 agentic skills framework、software development methodology、Claude Code、Codex CLI 这几个关键词，我大概花了不到十秒就判断出这不是一个普通的工具库。它更像是一套给 AI 编程助手“立规矩”的方法论框架，核心目标是把 Claude Code、Codex CLI 这类终端里的智能体，从“能聊几句代码”变成“能按工程规范干活”的角色。

我最早接触这类东西是在去年帮一个朋友调试他的自动化脚本仓库。他当时用 Claude Code 做代码审查，结果每次输出的格式都不一样，有时候给建议，有时候直接改文件，有时候又只给一段解释。问题不在于模型能力不够，而在于没有一套稳定的“行为契约”去约束它。superpowers 要解决的正是这个痛点：它定义了一套技能框架，让智能体在不同任务场景下知道该用什么工具、按什么流程走、输出成什么格式。

这套框架适合谁？如果你只是偶尔用 Claude Code 问几个语法问题，那暂时不需要它。但如果你已经把 Claude Code 或 Codex CLI 接入了日常开发流程，比如让它跑测试、改 bug、生成文档、做代码审查，那你迟早会遇到“同一个指令每次结果不一样”的问题。superpowers 就是给这类场景准备的。它不挑模型，Claude Code 能用，Codex CLI 也能用，甚至你通过第三方 API 接入其他模型，只要接口兼容，这套技能框架照样跑得起来。

我下面会从设计思路、核心机制、实操配置、常见坑四个方向展开，尽量把我在实际项目里踩过的弯路和总结出来的技巧都写清楚。文章里提到的具体命令和配置，你可以直接抄作业，但建议先理解背后的逻辑再动手，不然出了问题排查起来会很痛苦。

2. 核心设计思路：为什么是“技能框架”而不是“提示词模板”

2.1 从提示词工程到技能契约的转变

很多人第一次听到 agentic skills framework 会下意识觉得“不就是写几个提示词吗”。我一开始也这么想，直到我在一个真实项目里同时维护了二十多个提示词模板，才发现问题所在。提示词模板是静态的，你写一段话告诉模型“你要做代码审查”，模型每次的理解都会有偏差。而技能框架是动态的，它把每个任务拆成“触发条件、执行步骤、输出格式、异常处理”四个部分，模型在执行时不是读一段描述，而是加载一个结构化的技能定义。

superpowers 的设计逻辑大概是这样：它把软件开发中常见的动作抽象成一个个“技能”，比如“审查代码变更”“生成单元测试”“重构函数”“解释报错”。每个技能都有明确的输入输出契约。当你对 Claude Code 说“帮我看看这个 PR”时，框架会先匹配到“代码审查”这个技能，然后按照技能定义里的步骤去执行，而不是让模型自由发挥。

这个转变带来的最大好处是可预测性。我实测下来，同一个技能在 Claude Code 和 Codex CLI 上的输出结构基本一致，差异只在模型本身的推理能力上。这对于团队协作特别重要，因为你可以把技能定义当成团队规范的一部分，新人接手时不需要重新学习“怎么跟 AI 说话”，只需要知道有哪些技能可用。

2.2 为什么选择终端智能体作为载体

Claude Code 和 Codex CLI 这类终端工具，本质上是一个“带文件系统和命令执行能力的对话界面”。它们比纯聊天窗口多了几个关键能力：读写本地文件、执行 shell 命令、访问项目上下文。superpowers 选择在这类工具上落地，而不是做一个独立的 GUI 应用，原因很实际。

第一，终端工具天然贴近开发者的工作流。你不需要切换窗口，不需要复制粘贴代码，直接在项目目录里启动 Claude Code，它就能看到整个仓库的结构。第二，终端工具的执行能力让技能框架有了“手脚”。一个代码审查技能不只是输出一段文字，它可以直接运行测试、检查 lint、对比 git diff，然后把结果整合成一份报告。第三，终端工具的配置可以版本化。你的技能定义、模型配置、项目上下文都可以放在仓库里，团队共享，这比每个人在自己电脑上配一套提示词要可靠得多。

我试过在 VS Code 里通过插件调用 Claude Code，也试过在 Ubuntu 终端里直接跑 Codex CLI，体验上的差异主要在于上下文获取的便利性。VS Code 插件能自动把当前打开的文件和选中代码传给模型，而终端工具需要你手动指定文件路径。但终端工具的优势在于可脚本化，你可以把 superpowers 的技能调用写进 CI 流程，让它在每次提交时自动跑一遍代码审查。

2.3 框架的边界：它不做什么

这里要泼一盆冷水。superpowers 不是万能的，它不负责模型推理能力的提升，也不提供额外的算力。它做的事情是“约束”和“编排”，把模型的能力引导到正确的方向上。如果你的模型本身在代码理解上就很弱，那再好的技能框架也救不了。

另外，它不解决账号和网络问题。热词里提到的“claude code 注册账号和不注册有啥不同”“your organization has disabled claude subscription access”这些，属于账号权限和地区可用性的范畴，跟 superpowers 框架本身没有直接关系。框架只关心“模型接口能不能调通”，至于你怎么拿到这个接口，需要你自己解决。

还有一个常见的误解是把它当成“自动化编程工具”。它确实能自动执行一些步骤，但核心还是“辅助”，不是“替代”。你仍然需要审查它的输出，仍然需要对最终代码负责。我在实际使用中会把它的输出当成一个“高级草稿”，而不是最终答案。

3. 核心机制拆解：技能定义、触发与执行链路

3.1 技能定义的结构与编写要点

一个 superpowers 技能定义通常包含几个关键字段：技能名称、触发条件、前置检查、执行步骤、输出格式、失败处理。我用一个“生成单元测试”的技能来举例说明。

技能名称要短且明确，比如generate-unit-test。触发条件可以是一组关键词或正则表达式，当用户的指令匹配到这些模式时，框架就加载对应的技能。前置检查用来确认环境是否满足，比如“项目根目录存在 package.json”或“目标文件有对应的测试目录”。执行步骤是核心，通常是一组有序的操作，比如“读取目标文件”“分析导出函数”“生成测试用例”“写入测试文件”“运行测试并报告结果”。输出格式定义最终返回给用户的内容结构，比如“先列出生成的测试文件路径，再展示测试运行结果，最后给出覆盖率变化”。失败处理则规定当某一步骤出错时该怎么办，比如“如果测试运行失败，保留生成的测试文件并提示用户手动检查”。

我踩过的一个坑是触发条件写得太宽泛。有一次我把“测试”这个词作为触发条件，结果用户说“帮我测试一下这个接口”时，框架错误地加载了单元测试生成技能，而不是接口测试技能。后来我把触发条件改成更具体的模式，比如“生成单元测试”“写测试用例”“补充测试覆盖”，问题就解决了。

注意：技能定义的触发条件尽量用“动词+名词”的组合，避免单独使用名词，否则很容易误触发。

3.2 技能匹配与优先级机制

当多个技能都可能匹配用户的指令时，框架需要一个优先级机制来决定加载哪个。superpowers 通常采用“精确匹配优先、长匹配优先、显式指定优先”三条规则。

精确匹配优先是指，如果用户的指令完全等于某个技能的触发词，那这个技能优先。长匹配优先是指，如果两个技能的触发条件都能匹配，匹配长度更长的那个优先。显式指定优先是指，用户可以在指令里直接写技能名称，比如“用 generate-unit-test 技能处理这个文件”，这样框架会跳过自动匹配，直接加载指定技能。

这个机制在实际使用中很重要。比如你同时有“代码审查”和“安全审查”两个技能，用户说“帮我审查这段代码的安全性”，如果没有优先级机制，框架可能随机选一个。有了长匹配优先，“安全审查”的触发条件更长，就会被选中。

我在配置技能时会把最常用的技能放在前面，但优先级规则本身不依赖顺序，而是依赖匹配质量。这一点设计得比较合理，避免了“谁先注册谁优先”的混乱。

3.3 执行链路：从指令到结果的完整流程

一次完整的技能执行链路大概经过这几个阶段：指令解析、技能匹配、上下文加载、步骤执行、结果汇总、输出格式化。

指令解析阶段，框架会把用户的自然语言指令拆成“意图”和“参数”。比如“帮我给 src/utils/date.js 生成单元测试”会被解析成意图“生成单元测试”和参数“src/utils/date.js”。技能匹配阶段根据意图找到对应技能。上下文加载阶段会读取项目配置、目标文件内容、相关依赖信息。步骤执行阶段按照技能定义逐步操作，每一步都可能调用模型、执行命令或读写文件。结果汇总阶段把各步骤的输出整合起来。输出格式化阶段按照技能定义的格式返回给用户。

这个链路里最容易出问题的是上下文加载。如果项目结构复杂，或者目标文件依赖了其他模块，框架需要决定加载多少上下文。加载太少，模型理解不充分；加载太多，可能超出模型的上下文窗口。我在实际配置时会为每个技能设置一个“上下文预算”，比如“最多读取目标文件及其直接依赖，总 token 数不超过 8000”。这个预算需要根据你使用的模型来调整，Claude Code 的上下文窗口比较大，可以放宽一些，Codex CLI 相对小一点，需要更精细地控制。

4. 实操配置：从零搭建一套可用的技能框架

4.1 环境准备与工具安装

先确认你的基础环境。我用的是 Ubuntu 22.04，macOS 上也可以，Windows 需要 WSL 或者直接用桌面版。Claude Code 的安装方式根据平台不同有差异，官方文档里有详细说明，我这里只强调几个容易出问题的点。

安装 Claude Code 之前，确保 Node.js 版本在 18 以上。我遇到过因为 Node 版本太低导致安装脚本报错的情况，升级到 20 LTS 之后就正常了。另外，如果你在公司网络环境下，可能需要配置代理才能访问外部资源，这个具体怎么配取决于你的网络环境，我不展开。

Codex CLI 的安装相对简单，但要注意它的命令和 Claude Code 有区别。热词里有人问“codex cli 命令哪些 /compact /model /resume”，这些是 Codex CLI 的内置命令，用来压缩上下文、切换模型、恢复会话。Claude Code 也有类似的命令，但名称可能不同。建议安装完成后先跑一遍--help看看当前版本支持哪些命令。

VS Code 的配置是另一个常见问题。如果你用 VS Code 接入 Claude Code，需要安装对应的插件，然后在设置里配置模型接口。我试过在 VS Code 里同时配 Claude Code 和 Codex CLI，发现两者的配置项会互相干扰，后来改成用不同的工作区分别配置，问题就解决了。

提示：安装完成后先用一个简单的项目测试一下，确认模型能正常读取文件和执行命令，再开始配置技能框架。不然出了问题你分不清是安装问题还是技能配置问题。

4.2 技能目录结构与文件组织

superpowers 的技能定义通常放在项目根目录下的.superpowers/skills/目录里，每个技能一个文件，格式可以是 YAML 或 JSON。我倾向于用 YAML，因为可读性更好，写注释也方便。

目录结构大概是这样：

.superpowers/ skills/ generate-unit-test.yaml review-code.yaml explain-error.yaml refactor-function.yaml config.yaml context/ project-summary.md

config.yaml里放全局配置，比如默认模型、上下文预算、日志级别。context/目录放项目相关的上下文文件，比如项目概述、架构说明、编码规范。这些文件会在技能执行时被加载，帮助模型理解项目背景。

我建议把.superpowers/目录纳入版本控制，这样团队里每个人用的都是同一套技能定义。但要注意不要把敏感信息写进去，比如 API key、数据库密码。这些应该通过环境变量传入，而不是硬编码在配置文件里。

4.3 编写第一个技能：以代码审查为例

我从最简单的代码审查技能开始。这个技能的目标是：当用户要求审查代码时，框架读取 git diff，分析变更内容，输出一份结构化的审查报告。

技能定义大概长这样：

name: review-code triggers: - "审查代码" - "review code" - "看看这个改动" preconditions: - "git repository exists" steps: - action: run_command command: "git diff --staged" description: "获取暂存区的变更" - action: analyze prompt: "分析以下代码变更，指出潜在问题、改进建议和风险点" - action: format_output template: "review-report" output: format: markdown sections: - "变更概述" - "问题列表" - "改进建议" - "风险提示" failure: - condition: "no staged changes" message: "暂存区没有变更，请先 git add"

这个定义里，triggers是触发条件，preconditions是前置检查，steps是执行步骤，output是输出格式，failure是失败处理。实际运行时，框架会先检查是否在 git 仓库里，然后执行git diff --staged获取变更，把变更内容传给模型分析，最后按照模板格式化输出。

我实测下来，这个技能在 Claude Code 和 Codex CLI 上都能跑，但输出质量有差异。Claude Code 的分析更细致，能指出一些边界情况；Codex CLI 的输出更简洁，适合快速浏览。你可以根据团队需求选择默认模型。

4.4 模型接入与切换策略

热词里提到“使用 cc switch 接入 deepseek v4, qwen, glm 等模型”，这涉及到多模型切换的需求。superpowers 框架本身不限制模型，只要接口兼容就行。你可以在config.yaml里配置多个模型，然后为每个技能指定默认模型。

我的策略是：代码审查和重构用 Claude Code，因为它的推理能力更强；单元测试生成和文档生成用 Codex CLI，因为它的输出更结构化；如果遇到成本敏感的场景，切换到第三方 API 接入的模型。

切换模型时要注意上下文窗口的差异。Claude Code 的上下文窗口比较大，可以加载更多项目上下文；第三方模型的窗口可能小一些，需要精简上下文。我在config.yaml里为每个模型单独设置了context_budget，框架会根据当前使用的模型自动调整加载的上下文量。

注意：切换模型后建议先跑一遍回归测试，确认技能输出格式没有变化。不同模型对同一提示词的理解可能有偏差，尤其是输出格式的遵循程度。

5. 常见问题与排查技巧实录

5.1 技能不触发或误触发

这是最常见的问题。技能不触发通常是因为触发条件写得太窄，或者用户的指令表述和触发词不匹配。我遇到过一次，用户说“帮我看看这段代码有没有问题”，但我的触发词里只有“审查代码”和“review code”，没有覆盖“看看有没有问题”这种口语化表达。后来我在触发词里加了一些同义表达，问题就解决了。

误触发则是相反的情况，触发条件太宽泛。比如把“测试”作为触发词，结果用户说“这个功能测试过了吗”也会触发单元测试生成技能。解决办法是让触发词更具体，或者增加前置检查来过滤不匹配的场景。

排查技巧：打开框架的调试日志，看看每次指令匹配到了哪个技能，匹配分数是多少。如果匹配分数低于阈值，说明触发条件需要调整。

5.2 上下文加载失败或超限

上下文加载失败通常是因为文件路径不对，或者项目结构太复杂导致框架找不到目标文件。我建议在技能定义里明确指定上下文加载的范围，比如“只加载目标文件及其直接依赖”，避免框架盲目扫描整个项目。

上下文超限是另一个问题。当加载的内容超过模型的上下文窗口时，框架可能会截断内容或者报错。解决办法是设置context_budget，并在技能定义里指定优先级，比如“优先加载目标文件，其次加载相关测试文件，最后加载项目概述”。

我踩过的一个坑是：项目里有一个巨大的package-lock.json文件，框架在加载上下文时把它也读进去了，直接撑爆了上下文窗口。后来我在配置里加了排除规则，把这类文件过滤掉。

5.3 输出格式不一致

不同模型对输出格式的遵循程度不一样。Claude Code 通常能很好地按照模板输出，Codex CLI 有时候会自由发挥。解决办法是在技能定义里把输出格式写得更具体，比如“用 Markdown 表格展示问题列表，每行包含文件路径、行号、问题描述、严重程度”。

如果格式还是不稳定，可以在执行步骤里加一个“格式校验”步骤，检查输出是否符合模板要求，不符合就重新生成。这个步骤会增加一些 token 消耗，但对于需要严格格式的场景是值得的。

5.4 命令执行权限与安全问题

Claude Code 和 Codex CLI 都能执行终端命令，这带来了便利也带来了风险。我在配置技能时遵循一个原则：只允许执行只读命令，比如git diff、cat、ls，禁止执行写操作命令，比如rm、mv、git push。如果某个技能确实需要写操作，我会在技能定义里明确标注，并在执行前要求用户确认。

另外，命令执行的环境变量要控制好。不要把包含敏感信息的变量传给模型，比如数据库连接串、API key。我见过有人在技能定义里直接写了export API_KEY=xxx，这是非常危险的做法。

5.5 常见问题速查表

6. 进阶技巧：让技能框架真正融入开发流程

6.1 与 CI 流程集成

把 superpowers 的技能调用写进 CI 流程，可以在每次提交时自动跑代码审查和单元测试生成。我用的是 GitHub Actions，在 workflow 里加一个步骤，调用 Claude Code 执行review-code技能，把输出保存成 artifact。

这个做法的好处是：审查结果有记录，可以追溯；团队成员不需要本地配置环境，CI 里统一跑；可以设置质量门禁，比如审查发现严重问题就阻断合并。

但要注意 CI 环境的资源限制。Claude Code 在 CI 里跑需要模型接口可用，如果接口不稳定，会导致 CI 失败。我的做法是设置重试机制，并且把审查结果作为“建议”而不是“阻断条件”，避免因为模型问题影响正常开发。

6.2 技能版本管理与团队协作

技能定义应该像代码一样管理。每次修改技能定义，都要提交到版本控制，并且写清楚修改原因。我建议给技能定义加一个版本号，比如version: 1.2.0，这样出问题时可以快速回滚。

团队协作时，不同成员可能对同一个技能有不同的需求。我的做法是：核心技能由团队统一维护，放在主分支；个人定制技能放在自己的分支，通过配置切换。这样既保证了团队规范的一致性，又保留了个人的灵活性。

6.3 性能优化：减少 token 消耗和响应时间

技能框架跑起来后，token 消耗和响应时间是两个需要关注的指标。我通过几个手段来优化。

第一，精简上下文。只加载必要的信息，不要把整个项目都塞给模型。第二，缓存常用结果。比如项目概述、编码规范这些不常变的内容，可以缓存起来，不用每次都重新加载。第三，并行执行独立步骤。比如代码审查里，“检查 lint”和“分析变更”可以并行，不用串行等待。第四，设置合理的超时时间。避免某个步骤卡住导致整个技能执行失败。

我实测下来，优化之后单次代码审查的 token 消耗降低了大概四成，响应时间从平均 45 秒降到 20 秒左右。这个提升在频繁使用的场景下感受很明显。

6.4 扩展方向：自定义技能与领域适配

superpowers 的框架是开放的，你可以根据自己的领域需求扩展技能。比如做数据科学的，可以加“生成数据探索报告”技能；做前端的，可以加“检查组件可访问性”技能；做后端的，可以加“分析接口性能瓶颈”技能。

扩展技能的关键是定义好输入输出契约。输入要明确需要哪些文件或参数，输出要明确格式和内容范围。我建议先从一个小技能开始，跑通之后再逐步增加复杂度。不要一上来就写一个“全能技能”，那样很难调试和维护。

我在实际项目里还试过把技能框架和飞书机器人结合，通过飞书发送指令，框架在服务器上执行技能，然后把结果返回飞书。这个方案适合团队协作场景，但需要额外处理消息格式和权限控制，复杂度比本地使用高不少。

7. 我个人在实际操作中的几点体会

这套东西我用了大概半年，最大的感受是：技能框架的价值不在于“让 AI 更聪明”，而在于“让 AI 更稳定”。模型本身的能力你控制不了，但你可以控制它接收什么指令、按什么流程走、输出什么格式。superpowers 做的就是这件事。

另一个体会是，不要追求一步到位。我一开始想写一个覆盖所有场景的“超级技能”，结果调试了两周都没跑通。后来拆成一个个小技能，每个只做一件事，反而很快就用起来了。现在我的技能库里有十几个小技能，每个都很简单，但组合起来能覆盖大部分日常开发场景。

最后分享一个小技巧：给每个技能加一个“示例输出”。在技能定义里放一段期望的输出样例，模型在生成时会参考这个样例，格式稳定性会明显提升。这个技巧是我从一位做提示词工程的朋友那里学来的，实测有效。

如果你也在用 Claude Code 或 Codex CLI 做日常开发，建议花一个下午把 superpowers 的技能框架搭起来。前期投入的时间，后面会以“不用反复调整提示词”的方式还给你。