superpowers技能框架：AI编程代理的工程化实践指南

1. 从“superpowers”说起：这套技能框架到底在解决什么问题

第一次看到“superpowers”这个词，很多人会以为是某个超级英雄题材的游戏或者插件。但如果你最近在折腾 Claude Code、Codex CLI 这类终端里的 AI 编程助手，大概率已经在各种社区里刷到过它。简单来说，superpowers 是一套面向 AI 编程代理的技能框架（agentic skills framework），也是一套软件开发方法论。它做的事情，是把“让 AI 帮你写代码”这件事，从随缘聊天式的提问，变成一套有章法、可复用、可积累的工程流程。

我自己是从去年开始重度使用 Claude Code 和 Codex CLI 的，一开始也是那种“打开终端，丢一句话，等它吐代码”的用法。用久了就发现一个很现实的问题：同样的模型，同样的工具，为什么有的人能让它一口气把一个模块从设计到测试全部跑通，而我这边总是改了三行又改回去？后来才慢慢意识到，差距不在模型本身，而在于你有没有给它一套结构化的技能体系。superpowers 就是干这个的——它把常见的开发动作拆成一个个可调用的“技能”，让 AI 代理知道在什么阶段该做什么、按什么顺序做、做完怎么验证。

这套框架的核心价值，我觉得可以归纳成三点。第一是流程固化，把需求澄清、方案设计、编码实现、测试验证、代码审查这些环节变成明确的步骤，而不是让模型自由发挥。第二是技能复用，一次调好的技能可以反复用在不同项目上，不用每次从零开始调教。第三是可观测性，每一步做了什么、为什么这么做，都有迹可循，出问题的时候能定位到具体环节，而不是面对一坨生成的代码发呆。

适合谁来参考这套东西？我的判断是：如果你只是偶尔用 AI 补全几行代码，那暂时用不上；但如果你已经把 Claude Code 或 Codex CLI 当成日常开发的主力工具，每天要处理多个任务、多个项目，那 superpowers 这套思路值得认真研究。它不挑语言、不挑框架，前端后端、脚本工具、数据处理都能套进去。下面我就按自己的理解，把这套框架拆开讲清楚，包括它背后的设计逻辑、具体怎么落地、以及我在实操中踩过的坑。

2. 核心设计思路拆解：为什么要把技能“框架化”

2.1 从“提示词工程”到“技能工程”的转变

早期大家用 AI 编程，拼的是提示词写得好不好。你写一段详细的描述，模型给你一段代码，不满意就再改描述。这种方式在单次任务上还行，但一旦任务变复杂，比如“帮我重构这个模块并补上单元测试”，提示词就会变得又长又乱，而且每次都要重新写一遍。superpowers 的思路是把这种一次性的提示词，升级成可持久化、可组合的技能单元。

打个比方，提示词工程像是每次做饭都现查菜谱，而技能工程像是你把自己拿手的几十道菜写成标准操作卡，需要的时候直接抽一张出来用。每张卡片上写清楚了这道菜需要什么食材、几步做完、火候怎么控制、出锅前怎么尝味道。对应到 AI 编程上，一个技能可能包含：触发条件、输入参数、执行步骤、验证标准、常见失败模式。这样模型在执行的时候，不是靠“猜”，而是靠“按卡片办事”。

这个转变带来的直接好处是稳定性。我实测下来，同一个重构任务，用自由提示词的方式，十次里大概有三次会跑偏，比如改动了不该改的文件、漏掉了边界条件。而用技能框架约束之后，跑偏的概率明显下降，因为每一步都有明确的检查点。当然，这不意味着模型变聪明了，而是你把它的发挥空间收窄到了正确的轨道上。

2.2 技能分层：原子技能、组合技能与工作流

superpowers 里的技能不是平铺的一堆卡片，而是有层次的。我把它理解成三层结构。最底层是原子技能，比如“读取文件内容”“搜索代码库中的符号”“运行单个测试用例”“格式化代码”。这些动作足够小，小到几乎没有歧义，模型执行起来很稳。中间层是组合技能，比如“为新功能添加测试”“修复一个失败的测试”“重构一个函数并保持行为不变”。这些技能由多个原子技能按顺序编排而成，解决的是有一定复杂度的具体任务。最上层是工作流，比如“从需求到合并请求的完整流程”“线上问题排查与修复流程”。工作流把多个组合技能串起来，形成端到端的开发闭环。

为什么要分层？因为不同层级的复用粒度不一样。原子技能几乎每个项目都能用，组合技能在同类任务里复用，工作流则适合团队统一规范。如果你把所有东西都塞进一个大提示词里，复用性就很差，改一个细节要动全身。分层之后，你可以单独优化某一层，比如发现“运行测试”这个原子技能经常因为环境变量缺失而失败，那就只改这一个技能，上层不受影响。

2.3 与 Claude Code、Codex CLI 的配合逻辑

superpowers 本身不是某个工具的专属插件，它更像是一套方法论和技能库，可以挂载在不同的 AI 编程代理上。目前社区里讨论最多的载体就是 Claude Code 和 Codex CLI。这两个工具的共同点是：都能在终端里直接操作文件系统、执行命令、读取项目上下文。区别在于 Claude Code 更偏向交互式的会话体验，Codex CLI 更偏向命令行批处理风格。

把 superpowers 套上去之后，实际发生的变化是：你不再直接对模型说“帮我改这个”，而是先让代理加载对应的技能，然后按技能定义的步骤走。比如在 Claude Code 里，你可以把技能定义成项目内的配置文件或者提示模板，代理在开始任务前先读取这些定义。在 Codex CLI 里，则可以通过命令参数或者项目根目录的约定文件来注入技能上下文。具体怎么挂载，下一章会展开讲。这里先记住一个原则：技能定义要放在项目里，跟着代码走，而不是散落在个人的聊天记录里。这样换工具、换机器、换协作者，技能都能延续。

3. 核心细节解析与实操要点：技能到底怎么写

3.1 一个合格技能定义的五个要素

我参考社区里的实践，加上自己反复调整，总结出一个技能定义至少要说清楚五件事。第一是触发条件：什么情况下该用这个技能。比如“当用户要求新增一个 API 端点时”或者“当测试套件出现失败用例时”。触发条件写得越具体，代理越不容易在不该用的时候乱用。第二是输入：执行这个技能需要哪些信息，比如文件路径、函数名、需求描述、相关配置。输入要明确类型和来源，避免代理自己去猜。

第三是步骤：按顺序列出要执行的动作。步骤要细到代理能直接照做，比如“第一步，在 routes 目录下新建文件；第二步，定义处理函数；第三步，注册路由；第四步，补充测试”。第四是验证标准：怎么判断这个技能执行成功了。可以是测试通过、lint 无报错、接口返回符合预期。第五是失败处理：如果某一步失败了怎么办，是回滚、重试，还是停下来询问。这五个要素齐了，一个技能才算完整。缺了验证标准，代理就不知道什么时候该停；缺了失败处理，一出错就卡死。

3.2 技能描述的粒度控制：太粗和太细都是坑

写技能最容易犯的错是粒度失控。我一开始写过一个“实现用户登录功能”的技能，步骤只有三行：设计数据库表、写后端接口、写前端页面。结果代理执行的时候，数据库表字段全靠猜，接口参数和前端对不上，最后返工重来。这就是太粗，粗到代理只能自由发挥，而自由发挥就意味着不可控。

后来我又走向另一个极端，写了一个“创建用户表”的技能，步骤细到“打开编辑器、输入 CREATE TABLE、检查分号”。这就太细了，细到技能本身比任务还长，而且换个数据库就得重写。我的经验是：技能的粒度应该对齐“一个可独立验证的交付物”。比如“新增一个带测试的 API 端点”就是一个合适的粒度，它有一个明确的产出（端点可用且测试通过），又不会细到绑定具体实现细节。判断标准很简单：如果这个技能执行完，你能拿着产出物去跟别人演示，那粒度就差不多了。

3.3 把项目约定写进技能，而不是靠记忆

每个项目都有自己的约定：目录结构、命名规范、错误处理方式、日志格式、测试框架。这些约定如果只存在于老成员的脑子里，新人和 AI 代理都会反复踩坑。superpowers 的一个核心用法，就是把这些约定显式写进技能定义。比如在技能里写明“所有 API 响应统一使用 { code, data, message } 结构”“数据库查询必须走 repository 层，不允许在 controller 里直接写 SQL”“新增文件必须同步更新 index 导出”。

这样做的好处是，代理每次执行相关任务时都会读到这些约定，不需要你反复提醒。我自己的项目里，把这些约定集中放在一个skills/conventions目录下，每个技能文件开头引用相关的约定文件。实测下来，代码风格的一致性明显提升，code review 的时候少了很多“这里怎么又不一样”的扯皮。而且新人接手项目时，读一遍技能定义就能快速了解项目规矩，比翻文档快得多。

注意：约定要写“是什么”和“为什么”，不要只写“必须这样做”。代理理解了原因，遇到约定没覆盖的边缘情况时，才更可能做出合理判断。

4. 实操过程与核心环节实现：从零搭一套可用的技能体系

4.1 环境准备：Claude Code 与 Codex CLI 的基础配置

在讲技能落地之前，先把工具环境理顺。Claude Code 的安装方式根据系统不同有差异，Mac 和 Ubuntu 上通常通过包管理器或者官方提供的安装脚本完成，Windows 上则要注意 64 位兼容性问题，社区里反馈过一些安装失败的情况，遇到时优先检查系统版本和依赖。安装完成后，第一次启动需要处理账号和订阅相关的配置，如果提示组织未开放访问权限，需要确认当前账号的订阅状态是否覆盖了该工具的使用范围。

Codex CLI 的安装依赖 Node 环境，国内网络下npm install拉包慢是常见问题，可以配置镜像源来加速。安装完成后，常用的命令包括/compact用来压缩上下文、/model用来切换模型、/resume用来恢复之前的会话。这些命令在长任务里特别有用，尤其是上下文快满的时候，先 compact 再继续，能避免代理“忘事”。卸载或删除 Codex CLI 时，除了卸载包本身，还要清理配置目录下的缓存和会话记录，否则重装后可能残留旧配置导致行为异常。

如果你习惯在 VS Code 里工作，可以装对应的 Claude Code 插件，把终端里的能力接进编辑器。配置的时候重点看两处：一是模型来源，二是工作目录。模型来源决定了代理用哪个模型跑，工作目录决定了它能访问哪些文件。这两处配错，后面技能写得再好也白搭。另外，有些场景下会用到第三方 API 或者本地模型，接入时注意接口格式和鉴权方式要和工具要求对齐，否则会出现连不上或者返回格式解析失败的问题。

4.2 技能目录结构设计：让代理一眼看懂

环境就绪后，下一步是在项目里规划技能目录。我目前用的结构是这样的：项目根目录下建一个skills文件夹，里面按类别分子目录，比如skills/atomic放原子技能，skills/composite放组合技能，skills/workflows放工作流，skills/conventions放项目约定。每个技能是一个独立的 Markdown 文件，文件名用动词开头的短横线命名，比如add-api-endpoint.md、fix-failing-test.md。

每个技能文件内部，我固定用几个小节来组织：## 触发条件、## 输入、## 步骤、## 验证、## 失败处理。这样格式统一，代理解析起来稳定，人读起来也清爽。文件开头可以加一行简短的摘要，说明这个技能解决什么问题，方便快速检索。如果技能之间有依赖，比如组合技能引用了原子技能，就在步骤里直接写“执行skills/atomic/run-single-test.md”，形成引用关系。

这个结构的好处是可发现性强。代理在开始任务前，可以先扫描skills目录，根据任务描述匹配相关技能。你也可以在项目根目录放一个SKILLS.md作为索引，列出所有技能和一句话说明。我试过把技能散落在各个地方，结果就是自己都忘了写过哪些，更别说让代理去用了。集中管理之后，维护成本低了很多。

4.3 编写第一个组合技能：以“新增带测试的 API 端点”为例

光说结构太抽象，直接看一个我实际在用的组合技能。假设项目是 Node.js 的 Express 应用，要新增一个查询用户列表的端点。技能文件大概长这样：

## 触发条件 用户要求新增一个 API 端点，且该端点需要返回数据列表。 ## 输入 - 端点路径，例如 GET /api/users - 返回字段列表 - 是否需要分页 ## 步骤 1. 在 routes 目录下新建或修改对应路由文件 2. 在 controller 层实现处理函数，调用 service 层获取数据 3. 在 service 层实现业务逻辑，通过 repository 层查询数据库 4. 定义返回结构，遵循 conventions/api-response.md 5. 在 tests 目录下新增测试文件，覆盖正常返回和空列表两种情况 6. 运行测试，确认通过 7. 运行 lint，确认无报错 ## 验证 - 测试全部通过 - lint 无 error - 手动请求端点返回结构符合约定 ## 失败处理 - 测试失败：定位失败用例，修复后重跑，不允许跳过 - lint 报错：按项目规范修复，不允许 disable 规则 - 数据库查询报错：检查 repository 层实现和表结构

这个技能写完之后，我让代理执行了大概二十次类似任务，成功率比之前自由发挥高出一大截。关键在于步骤里明确了分层（route/controller/service/repository），代理不会把 SQL 写到 controller 里；验证标准明确，代理知道什么时候算完成；失败处理明确，不会一遇到报错就停下来问“怎么办”。

4.4 参数选择与上下文管理：别让技能把上下文撑爆

技能写多了，另一个问题就来了：上下文不够用。Claude Code 和 Codex CLI 都有上下文窗口限制，如果一次加载太多技能文件，代理还没开始干活，上下文就满了。我的做法是按需加载：先加载一个轻量的技能索引，代理根据任务匹配到具体技能后，再加载那个技能的完整定义。组合技能引用原子技能时，也只在真正执行到那一步才加载。

另外，技能文件本身要控制长度。一个技能超过两百行，就说明粒度可能太粗了，考虑拆分。描述步骤时用短句，不要写大段解释。项目约定如果很长，拆成多个小文件，按主题引用。我实测下来，单个技能文件控制在五十到一百行之间，加载和执行都比较顺畅。如果发现代理开始“忘记”前面的步骤，大概率是上下文被挤占了，这时候用/compact压缩一下，或者把不相关的技能从当前会话里移除。

提示：技能文件里不要放敏感信息，比如密钥、内部地址、个人数据。这些应该放在环境变量或者独立的配置里，技能只引用变量名。

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

5.1 代理不按技能步骤走怎么办

这是最常见的问题。表现是：你明明写了步骤一二三四，代理却跳着做，或者自己加戏。原因通常有三个。第一，触发条件写得太模糊，代理觉得当前任务不完全匹配，就按自己的理解来了。解决办法是把触发条件写具体，最好带上例子。第二，步骤之间有歧义，比如“处理数据”这种描述，代理不知道具体怎么处理。解决办法是把每步的动作和产出写清楚。第三，技能没有被正确加载，代理根本没读到你的技能定义。这时候检查一下技能文件路径和加载方式，确认代理能访问到。

我遇到过一次，技能里写了“运行测试”，但没写用什么命令。代理试了npm test、yarn test、jest好几个，最后选了一个项目里根本不存在的脚本，自然失败了。后来我在技能里直接写明“运行npm run test:unit”，问题就没了。所以能写具体的就不要写笼统，这是减少代理自由发挥的最有效手段。

5.2 技能执行到一半失败，如何优雅恢复

长任务执行到一半失败，如果从头再来，浪费时间和上下文。我的做法是在技能里定义检查点。比如一个组合技能有七个步骤，我在第三步和第五步后面各设一个检查点，记录当前进度和已完成的产出。失败恢复时，代理可以从最近的检查点继续，而不是从第一步重来。实现方式可以是在项目里维护一个临时的进度文件，或者利用工具本身的会话恢复能力。

Codex CLI 的/resume命令就是干这个的，可以恢复之前的会话继续跑。Claude Code 里则可以通过会话历史或者手动指定从哪一步继续。关键是要让代理知道“哪些已经做完了，不要重复做”。我通常会在技能失败处理里写一句：“如果失败发生在第 N 步之后，先检查前 N 步的产出是否存在且有效，有效则从第 N+1 步继续。”这样代理恢复的时候有据可依。

5.3 多技能冲突与优先级处理

当项目里技能多了，难免出现冲突。比如一个技能说“所有新文件放在 src 目录”，另一个技能说“测试文件放在 tests 目录”，如果任务同时涉及两者，代理可能犯迷糊。解决办法是明确优先级和适用范围。我在技能索引里给每个技能标注适用范围，比如“适用于后端代码”“适用于测试相关任务”。代理匹配任务时，先按适用范围筛选，再按优先级排序。

另外，项目约定（conventions）的优先级应该高于具体技能。也就是说，如果技能步骤和项目约定冲突，以约定为准。我会在技能文件开头写一句“本技能执行时需遵守 conventions 目录下的所有约定”。这样代理在执行具体步骤前，会先读约定，避免写出违反项目规范的代码。实测下来，这个优先级规则能解决大部分冲突场景。

5.4 常见问题速查表

这张表是我自己踩坑之后整理的，基本覆盖了日常使用中八成以上的问题。遇到新问题的时候，先对照这张表排查，大部分情况能快速定位。

6. 把技能体系用起来的几个实操心得

技能体系搭好只是第一步，真正让它产生价值，还得在日常工作里用起来。我自己的习惯是：每接一个新任务，先花一分钟判断它属于哪类技能，然后让代理加载对应技能再开工。这个动作看起来多了一步，但省去了后面反复纠偏的时间，整体是赚的。尤其是那种重复性高的任务，比如新增 CRUD 接口、修复同类 bug、补充测试，技能用熟了之后效率提升非常明显。

另一个心得是技能要持续迭代。我每个月会回顾一下过去一个月里哪些技能经常失败、哪些步骤经常被跳过，然后针对性优化。技能不是写完就完事的文档，而是活的工具，跟着项目一起演进。有时候项目结构调整了，技能里的路径和命令也要同步更新，否则代理会按旧路径操作，报一堆找不到文件的错。

还有一点，不要追求一次写完美。我见过有人想把所有技能都设计得滴水不漏再开始用，结果拖了很久也没落地。我的建议是先写三五个最常用的技能，用起来，在实战中发现问题再改。技能体系的完善是靠一次次实际任务喂出来的，不是靠纸上推演。我最早的那批技能现在回头看写得很粗糙，但正是它们让我跑通了流程，才有了后面持续优化的基础。

最后分享一个我最近在试的扩展方向：把技能和项目的 CI 流程打通。比如代理执行完一个技能后，自动触发对应的 CI 检查，检查结果反过来作为技能验证标准的一部分。这样技能的成功与否不再依赖人工判断，而是有客观的流水线结果背书。这个方向还在摸索，等跑顺了再单独整理一篇。