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.yamlname: 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 验证不通过的典型场景验证不通过的原因五花八门我整理了一个速查表问题现象可能原因解决方法语法验证失败生成的代码有语法错误检查模板文件确保变量替换后语法正确逻辑验证失败测试用例不通过查看测试输出定位具体失败的断言业务验证失败接口返回数据不符合预期检查 mock 数据是否与真实数据结构一致验证超时验证命令执行时间过长增加超时时间配置或优化验证命令验证环境缺失缺少必要的依赖或服务运行superpowers doctor检查环境我踩过最坑的一次是验证命令里用了相对路径结果在执行引擎的工作目录下找不到文件。后来改成绝对路径就解决了。所以写验证命令的时候尽量用绝对路径或者基于项目根目录的路径避免因为工作目录变化导致的问题。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 执行的时候必须遵守不遵守就验证不通过。这比写一百遍“请遵循代码规范”都管用。最后分享一个小技巧刚开始用的时候不要试图定义太多技能。先从最常用的三五个场景开始把这三个五个技能打磨好再逐步扩展。我见过有人一上来就定义了上百个技能结果大部分都没用上反而增加了维护负担。技能框架的价值在于质量不在于数量。
