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

第一次看到 “superpowers” 这个词，很多人会以为是某个超级英雄题材的游戏或者娱乐项目。但如果你最近在关注 AI 辅助编程这个圈子，尤其是在 Claude Code、Codex CLI 这些工具的社区里泡过，就会发现这个词出现的频率越来越高。它其实是一个agentic skills framework，翻译过来就是“智能体技能框架”。说白了，它想做的事情，是给 AI 编程助手装上一套可复用、可组合、可迭代的“技能包”，让 AI 不再只是被动地回答问题，而是能像一个有经验的工程师那样，主动规划、执行、验证、修正。

我最初接触这个概念的时候，心里是有点怀疑的。因为市面上关于 AI 编程的工具已经够多了，Claude Code、Codex CLI、各种 VS Code 插件，每一个都在说自己是“革命性”的。但真正用下来你会发现，大部分工具的能力边界非常依赖你给的提示词质量。你问得好，它就答得好；你问得模糊，它就给你一堆看起来正确但跑不通的代码。superpowers 这个框架的切入点不一样，它不是在模型层面做文章，而是在工作流层面做文章。它把软件开发过程中那些反复出现的动作——比如需求拆解、方案设计、代码生成、测试验证、错误修复——抽象成一个个独立的“技能”，然后让 AI 根据当前任务自动调用合适的技能组合。

这就好比一个刚入行的程序员，你让他直接写一个完整的电商系统，他大概率会懵。但如果你给他一套标准作业流程：先画 ER 图，再定接口，再写单元测试，最后实现业务逻辑，他就能一步步做下来。superpowers 做的就是把这套流程固化下来，变成 AI 可以理解和执行的技能模块。它的核心价值不在于让 AI 变得更聪明，而在于让 AI 的工作方式变得更可控、可预期、可复现。

适合谁来研究这个框架？我觉得有三类人最应该关注。第一类是已经在用 Claude Code 或 Codex CLI 做日常开发的工程师，你肯定遇到过 AI 写着写着就跑偏的情况，superpowers 能帮你把这种跑偏的概率降下来。第二类是想把 AI 编程引入团队协作的技术负责人，你需要的不只是“能写代码的 AI”，而是“能按照团队规范写代码的 AI”。第三类是对 agentic workflow 感兴趣的产品经理或创业者，你想知道 AI 智能体的能力边界到底在哪里，这个框架会给你很多启发。

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

2.1 从提示词工程到技能工程的范式转移

过去两年，大家用 AI 编程的主要方式就是写提示词。你打开 Claude Code 或者 Codex CLI，输入一段描述，等它生成代码，然后复制粘贴到项目里跑。跑不通就改提示词，再试一次。这种方式在简单任务上没问题，但一旦任务复杂度上来，比如要改一个涉及五六个文件的 bug，或者要新增一个跨模块的功能，提示词就会变得极其冗长且脆弱。你稍微改一个词，输出结果可能就完全不一样。

superpowers 的设计者显然意识到了这个问题。他们把“技能”定义为一个有明确输入输出、有前置条件、有验证标准的独立单元。举个例子，“生成数据库迁移脚本”是一个技能，它的输入是数据模型定义，输出是 SQL 文件，前置条件是数据库连接可用，验证标准是脚本能成功执行且不破坏现有数据。当你需要做数据库变更时，AI 不是直接开始写 SQL，而是先调用这个技能，按照既定流程走一遍。

这种设计的好处是显而易见的。首先，可组合性大大增强。一个复杂的任务可以被拆解成多个技能的串联，每个技能只负责一小块，出了问题也容易定位。其次，可复用性提高。同一个技能可以在不同项目、不同语言、不同框架中重复使用，不需要每次都重新写提示词。最后，可验证性有了保障。每个技能都有自己的验证标准，AI 执行完一个技能后可以自动检查是否通过，不通过就重试或者上报，而不是把一堆未经验证的代码直接丢给你。

2.2 技能的生命周期管理

一个技能从创建到废弃，superpowers 定义了一套完整的生命周期。创建阶段，你需要明确这个技能解决什么问题、输入输出是什么、依赖哪些工具或环境。执行阶段，AI 会根据当前上下文判断是否应该调用这个技能，以及如何调用。验证阶段，技能执行完毕后会自动运行预设的检查逻辑，比如语法检查、单元测试、类型检查等。反馈阶段，如果验证不通过，AI 会根据错误信息决定是重试、修改技能参数，还是上报给人类处理。迭代阶段，你可以根据实际使用情况不断优化技能的定义和实现。

这套生命周期管理听起来有点重，但实际用起来你会发现它解决了一个很痛的问题：AI 编程的不可解释性。以前 AI 给你一段代码，你问它为什么这么写，它只能给你一个模糊的解释。现在有了技能框架，你可以清楚地看到 AI 调用了哪些技能、每个技能的输入输出是什么、验证结果如何。这对于调试和审计来说，价值巨大。

2.3 与 Claude Code、Codex CLI 的集成逻辑

superpowers 并不是一个独立的 IDE 或者编辑器，它更像是一个中间层，架在 AI 模型和开发工具之间。Claude Code 和 Codex CLI 是它目前最主流的两个宿主环境。在 Claude Code 里，superpowers 通过自定义指令和钩子函数来注入技能逻辑。在 Codex CLI 里，它通过命令别名和脚本包装来实现类似的效果。

为什么选择这两个工具作为主要集成对象？我的理解是，Claude Code 和 Codex CLI 都提供了比较开放的扩展接口，允许第三方框架介入它们的执行流程。而且这两个工具的用户群体高度重合，都是那些对 AI 编程接受度高、愿意折腾新工具的开发者和技术团队。superpowers 借助这两个工具的生态，可以快速触达目标用户，而不需要自己从头搭建一套完整的开发环境。

注意：superpowers 的技能定义文件通常放在项目根目录的.superpowers文件夹下，这个文件夹需要纳入版本控制，但其中的缓存和日志文件应该加入.gitignore。我见过有人把整个文件夹都提交上去，结果每次运行都产生大量无意义的 diff。

3. 核心细节解析：技能定义、执行引擎与验证机制

3.1 技能定义文件的编写规范

一个标准的 superpowers 技能定义文件通常包含以下几个部分：元信息、输入模式、输出模式、执行步骤、验证规则。元信息包括技能名称、版本号、作者、描述等。输入模式定义了技能需要哪些参数，每个参数的类型、是否必填、默认值是什么。输出模式定义了技能执行后会返回什么结果。执行步骤是技能的核心逻辑，通常是一系列有序的操作指令。验证规则定义了如何判断技能执行成功。

我拿一个实际例子来说明。假设你要定义一个“生成 RESTful API 端点”的技能。元信息里写清楚这个技能叫generate-rest-endpoint，版本1.0.0，描述是“根据数据模型自动生成 CRUD 接口”。输入模式里定义model_name是字符串必填，fields是数组必填，framework是枚举可选，默认值是express。输出模式里定义返回一个包含路由文件路径和测试文件路径的对象。执行步骤里写清楚先读取模型定义，再生成路由代码，再生成控制器代码，最后生成测试文件。验证规则里写清楚要检查生成的文件是否存在、语法是否正确、测试是否通过。

这套规范看起来繁琐，但写多了之后你会发现它其实是在帮你理清思路。很多时候我们觉得一个任务很简单，但真正动手写技能定义的时候才发现，原来有这么多细节没有考虑到。这种“被迫的严谨”对于提高代码质量是有好处的。

3.2 执行引擎的调度策略

superpowers 的执行引擎负责决定在什么时机调用哪个技能。它维护了一个技能注册表，记录了所有可用技能的名称、输入输出模式和依赖关系。当 AI 接收到一个任务时，执行引擎会先对任务进行解析，提取出关键意图和约束条件，然后在注册表中查找匹配的技能。

调度策略主要有三种模式。顺序模式是最简单的，技能按照预定义的顺序依次执行，前一个的输出作为后一个的输入。条件模式会根据运行时状态动态选择技能，比如如果检测到项目使用 TypeScript，就调用 TypeScript 版本的代码生成技能，否则调用 JavaScript 版本。循环模式用于需要反复迭代的场景，比如“生成代码 -> 运行测试 -> 修复错误”这个循环，直到测试全部通过或者达到最大重试次数。

我实测下来，条件模式和循环模式的组合是最实用的。比如在做一个全栈项目的时候，前端代码生成和后端代码生成可以并行执行，但数据库迁移必须在两者之前完成。执行引擎会自动识别这种依赖关系，安排合理的执行顺序。这比我自己手动协调各个步骤要省心得多。

3.3 验证机制的层次化设计

验证是 superpowers 最让我放心的一块。它把验证分成了三个层次：语法层、逻辑层、业务层。语法层验证是最基础的，检查生成的代码是否符合语言规范，比如括号是否匹配、变量是否声明、类型是否一致。逻辑层验证检查代码的行为是否符合预期，比如函数返回值是否正确、边界条件是否处理、异常是否捕获。业务层验证检查代码是否满足实际业务需求，比如接口返回的数据结构是否正确、权限控制是否到位、性能指标是否达标。

这三个层次的验证不是孤立的，而是层层递进的。语法层不通过，后面的验证就不用做了。逻辑层不通过，业务层验证也没有意义。这种设计避免了无效验证带来的资源浪费。而且每个层次的验证都可以配置为“阻断”或“警告”模式。阻断模式下，验证不通过会直接终止技能执行；警告模式下，验证不通过只会记录日志，继续执行后续步骤。

提示：业务层验证通常需要你提供额外的测试数据或 mock 服务。我建议在项目初期就把这些测试基础设施搭好，否则后期补起来会很痛苦。尤其是涉及到第三方 API 调用的场景，没有 mock 服务的话，验证会变得非常不稳定。

4. 实操过程：从零搭建一个 superpowers 工作流

4.1 环境准备与基础配置

在开始之前，你需要确保本地已经安装了 Node.js 18 以上版本，以及 npm 或 yarn。superpowers 本身是一个 npm 包，可以通过npm install -g superpowers-cli全局安装。安装完成后，运行superpowers init会在当前目录下生成一个.superpowers文件夹，里面包含默认的技能定义和配置文件。

接下来需要配置宿主环境。如果你用的是 Claude Code，需要在 Claude Code 的设置里添加 superpowers 作为自定义指令源。具体操作是打开 Claude Code 的配置文件，找到customInstructions字段，把.superpowers/instructions.md的路径填进去。如果你用的是 Codex CLI，需要在.codexrc文件里添加superpowers作为插件，并指定技能目录的路径。

配置完成后，运行superpowers doctor可以检查环境是否正常。这个命令会检查 Node.js 版本、依赖包完整性、宿主环境配置、技能定义语法等。如果有问题，它会给出具体的修复建议。我建议每次更新 superpowers 版本后都跑一遍这个命令，避免因为版本不兼容导致的各种奇怪问题。

4.2 定义你的第一个技能：从需求到实现

假设我们要定义一个“生成 React 组件”的技能。首先在.superpowers/skills目录下创建一个新文件generate-react-component.yaml。文件内容大致如下：

name: generate-react-component version: 1.0.0 description: 根据组件名称和属性定义生成 React 函数组件 inputs: - name: componentName type: string required: true - name: props type: array required: false default: [] - name: styleType type: enum values: [css, scss, styled-components] default: css outputs: - name: componentPath type: string - name: testPath type: string steps: - action: generate-file template: react-component params: name: "{{componentName}}" props: "{{props}}" style: "{{styleType}}" - action: generate-file template: react-test params: name: "{{componentName}}" validation: - type: syntax command: "npx tsc --noEmit {{componentPath}}" - type: logic command: "npx jest {{testPath}}"

这个技能定义里，inputs部分声明了三个参数：组件名称必填，属性列表可选默认为空数组，样式类型可选默认为 css。steps部分定义了两个步骤：先生成组件文件，再生成测试文件。validation部分定义了两层验证：先用 TypeScript 编译器检查语法，再用 Jest 运行测试。

写完之后，运行superpowers validate generate-react-component可以检查技能定义是否符合规范。如果通过，这个技能就注册成功了。之后在 Claude Code 或 Codex CLI 里，当你输入类似“帮我生成一个 UserCard 组件”的指令时，执行引擎就会自动匹配到这个技能并调用它。

4.3 技能组合实战：搭建一个完整的 CRUD 模块

单个技能只能解决单一问题，真正体现 superpowers 价值的是技能组合。我们来做一个完整的 CRUD 模块，涉及数据库模型、API 路由、前端页面三个部分。首先定义三个基础技能：generate-db-model、generate-api-route、generate-frontend-page。然后在.superpowers/workflows目录下创建一个工作流文件crud-module.yaml：

name: crud-module description: 生成一个完整的 CRUD 模块 steps: - skill: generate-db-model inputs: modelName: "{{moduleName}}" fields: "{{fields}}" - skill: generate-api-route inputs: modelName: "{{moduleName}}" basePath: "/api/{{moduleName | lower}}" dependsOn: generate-db-model - skill: generate-frontend-page inputs: modelName: "{{moduleName}}" apiBase: "/api/{{moduleName | lower}}" dependsOn: generate-api-route validation: - type: integration command: "npm run test:integration"

这个工作流定义了三个步骤，每个步骤调用一个技能，并且通过dependsOn声明了依赖关系。执行引擎会按照依赖顺序依次执行，前一个技能的输出会自动传递给后一个技能作为输入。最后运行集成测试来验证整个模块是否正常工作。

我实测下来，用这种方式生成一个 CRUD 模块，从定义技能到跑通测试，大概需要 20 到 30 分钟。如果手动写的话，即使是有经验的工程师，至少也要半天时间。而且手动写容易遗漏一些细节，比如参数校验、错误处理、分页逻辑等，技能框架会把这些都考虑进去。

4.4 与本地模型和第三方 API 的对接

有些团队出于成本或隐私考虑，不想直接用云端模型，而是希望接入本地部署的模型。superpowers 支持通过配置modelProvider来切换模型来源。你可以在.superpowers/config.yaml里指定provider: lmstudio，然后配置baseUrl和modelName。这样执行引擎在调用技能时，就会把请求转发到本地模型服务。

对接第三方 API 也是类似的操作。比如你想用某个国产大模型的 API，只需要在配置里添加对应的provider和apiKey即可。superpowers 内置了几个主流提供商的适配器，如果没有你需要的，也可以自己写一个适配器插件。适配器需要实现generate和validate两个方法，分别负责调用模型和验证结果。

注意：使用本地模型时，技能定义里的验证命令需要根据本地模型的能力做调整。有些本地模型在代码生成方面表现不错，但在复杂逻辑推理上可能不如云端模型。我建议先用简单技能测试一下本地模型的表现，再决定是否把复杂技能也迁移过去。

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

5.1 技能匹配失败怎么办

这是最常见的问题。你输入一个指令，执行引擎告诉你“没有找到匹配的技能”。原因通常有三种：技能名称拼写错误、技能定义文件格式有误、技能注册表没有刷新。排查步骤是先用superpowers list查看当前已注册的技能列表，确认目标技能是否存在。如果存在但匹配不上，检查技能定义里的inputs和outputs是否与你的指令语义匹配。如果不存在，检查技能文件是否放在了正确的目录下，以及文件扩展名是否为.yaml或.yml。

还有一种情况是技能存在但优先级不够高。superpowers 允许同一个功能定义多个技能，执行引擎会根据匹配度打分，选择分数最高的那个。如果你新定义的技能总是被旧技能覆盖，可以在技能定义里加上priority: high来提升优先级。

5.2 验证不通过的典型场景

验证不通过的原因五花八门，我整理了一个速查表：

我踩过最坑的一次是验证命令里用了相对路径，结果在执行引擎的工作目录下找不到文件。后来改成绝对路径就解决了。所以写验证命令的时候，尽量用绝对路径或者基于项目根目录的路径，避免因为工作目录变化导致的问题。

5.3 技能执行结果不稳定的处理

有时候同一个技能，同样的输入，两次执行的结果却不一样。这种情况通常是因为模型本身的随机性导致的。superpowers 提供了temperature和seed两个参数来控制生成的随机性。把temperature设低一点，比如 0.2，生成结果会稳定很多。如果模型支持seed参数，固定 seed 值可以保证每次生成完全一致的结果。

另一个导致不稳定的原因是技能定义里的步骤顺序不固定。比如你用了并行执行，但某些步骤之间有隐式的依赖关系，没有显式声明。这种情况下，执行引擎可能会以不同的顺序调度步骤，导致结果不一致。解决办法是把所有依赖关系都显式声明出来，不要依赖隐式约定。

5.4 性能优化与资源控制

当技能数量多了之后，执行引擎的调度开销会变得明显。我实测下来，技能数量超过 50 个之后，每次调度的耗时从几十毫秒增加到了几百毫秒。优化方法有几个：一是把不常用的技能归档，减少注册表大小；二是给技能定义加上tags，执行引擎可以根据标签快速过滤；三是把一些简单的技能合并成复合技能，减少调度次数。

资源控制方面，主要是限制并发执行的技能数量。默认情况下，执行引擎会尽可能并行执行没有依赖关系的技能。但如果你的机器资源有限，或者某些技能本身就很吃资源，可以在配置里设置maxConcurrency来限制并发数。我一般设成 CPU 核心数的一半，这样既能利用多核性能，又不会把机器跑满。

6. 技能框架的扩展与团队协作

6.1 自定义技能模板的编写技巧

superpowers 内置了一批常用技能模板，但实际项目中你肯定需要写自己的模板。写模板的时候有几个技巧可以分享。第一，模板变量命名要语义化。不要用var1、var2这种名字，用componentName、apiBasePath这种一看就懂的名字。第二，模板里要包含注释。生成的代码里带上注释，说明这段代码是自动生成的，以及生成时用的参数是什么。这样后期维护的时候，一眼就能看出哪些代码是 AI 生成的，哪些是人工写的。

第三，模板要支持条件渲染。比如根据styleType参数决定生成 CSS 文件还是 SCSS 文件。superpowers 的模板引擎支持简单的条件语法，类似{{#if styleType === 'scss'}}这样的写法。第四，模板要预留扩展点。生成的代码里留一些 TODO 注释或者空函数，方便开发者后续填充业务逻辑。不要试图让模板生成 100% 完整的代码，那样模板会变得极其复杂且难以维护。

6.2 团队技能库的版本管理与共享

团队协作场景下，技能库的版本管理是个绕不开的问题。我的做法是每个项目单独维护一个.superpowers文件夹，但把通用的技能抽出来放到一个独立的 npm 包里，通过superpowers install命令安装。这样不同项目可以共享同一套基础技能，同时又保留项目特有的技能。

版本管理方面，技能定义文件里必须写清楚version字段。每次修改技能定义，都要递增版本号。执行引擎在调用技能时，会记录使用的技能版本，方便追溯问题。如果某个技能的新版本出了问题，可以快速回滚到旧版本。我建议在 CI 流程里加上技能定义的校验步骤，确保提交的技能定义符合规范，避免因为格式错误导致执行失败。

6.3 技能效果评估与持续改进

技能写出来只是第一步，持续改进才是关键。我一般会记录每个技能的执行成功率、平均耗时、验证通过率等指标。执行成功率低的技能，要么是定义有问题，要么是模型能力不够。平均耗时长的技能，可能是步骤太复杂，需要拆分。验证通过率低的技能，说明验证规则可能太严格或者太宽松，需要调整。

这些指标可以通过 superpowers 的日志功能收集。每次技能执行都会生成一条日志，包含技能名称、输入参数、执行结果、耗时等信息。你可以写个简单的脚本分析这些日志，生成周报或者月报。我团队里就有一个小面板，每天自动刷新技能健康度，哪个技能出问题了，一眼就能看到。

7. 我个人的一些实操体会

用 superpowers 这段时间，最大的感受是它改变了我对 AI 编程的预期。以前我总希望 AI 能一次性给我完美的代码，后来发现这不现实。现在我把 AI 当成一个执行力很强但需要明确指令的初级工程师，superpowers 就是给这个工程师的作业指导书。指导书写得越清楚，工程师干得越好。

另一个体会是，技能定义本身就是一个很好的文档。以前项目里的开发规范写在 Wiki 里，没人看。现在把规范写成技能定义，AI 执行的时候必须遵守，不遵守就验证不通过。这比写一百遍“请遵循代码规范”都管用。

最后分享一个小技巧：刚开始用的时候，不要试图定义太多技能。先从最常用的三五个场景开始，把这三个五个技能打磨好，再逐步扩展。我见过有人一上来就定义了上百个技能，结果大部分都没用上，反而增加了维护负担。技能框架的价值在于质量，不在于数量。