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 步的产出是否存在且有效有效则从第 N1 步继续。”这样代理恢复的时候有据可依。5.3 多技能冲突与优先级处理当项目里技能多了难免出现冲突。比如一个技能说“所有新文件放在 src 目录”另一个技能说“测试文件放在 tests 目录”如果任务同时涉及两者代理可能犯迷糊。解决办法是明确优先级和适用范围。我在技能索引里给每个技能标注适用范围比如“适用于后端代码”“适用于测试相关任务”。代理匹配任务时先按适用范围筛选再按优先级排序。另外项目约定conventions的优先级应该高于具体技能。也就是说如果技能步骤和项目约定冲突以约定为准。我会在技能文件开头写一句“本技能执行时需遵守 conventions 目录下的所有约定”。这样代理在执行具体步骤前会先读约定避免写出违反项目规范的代码。实测下来这个优先级规则能解决大部分冲突场景。5.4 常见问题速查表问题现象可能原因排查方向解决建议代理跳过技能步骤触发条件模糊或技能未加载检查技能匹配逻辑和加载路径细化触发条件确认技能可被读取执行到一半卡住上下文不足或步骤有歧义查看上下文占用检查步骤描述压缩上下文把步骤写具体产出不符合项目规范约定未写进技能或优先级不清检查 conventions 引用在技能中显式引用约定并声明优先级测试反复失败验证标准不明确或环境问题检查测试命令和环境变量写明具体测试命令固定环境配置技能之间互相干扰适用范围重叠梳理技能索引和适用范围标注适用范围设定优先级恢复后重复劳动缺少检查点检查进度记录机制在关键步骤后设检查点恢复时先校验产出这张表是我自己踩坑之后整理的基本覆盖了日常使用中八成以上的问题。遇到新问题的时候先对照这张表排查大部分情况能快速定位。6. 把技能体系用起来的几个实操心得技能体系搭好只是第一步真正让它产生价值还得在日常工作里用起来。我自己的习惯是每接一个新任务先花一分钟判断它属于哪类技能然后让代理加载对应技能再开工。这个动作看起来多了一步但省去了后面反复纠偏的时间整体是赚的。尤其是那种重复性高的任务比如新增 CRUD 接口、修复同类 bug、补充测试技能用熟了之后效率提升非常明显。另一个心得是技能要持续迭代。我每个月会回顾一下过去一个月里哪些技能经常失败、哪些步骤经常被跳过然后针对性优化。技能不是写完就完事的文档而是活的工具跟着项目一起演进。有时候项目结构调整了技能里的路径和命令也要同步更新否则代理会按旧路径操作报一堆找不到文件的错。还有一点不要追求一次写完美。我见过有人想把所有技能都设计得滴水不漏再开始用结果拖了很久也没落地。我的建议是先写三五个最常用的技能用起来在实战中发现问题再改。技能体系的完善是靠一次次实际任务喂出来的不是靠纸上推演。我最早的那批技能现在回头看写得很粗糙但正是它们让我跑通了流程才有了后面持续优化的基础。最后分享一个我最近在试的扩展方向把技能和项目的 CI 流程打通。比如代理执行完一个技能后自动触发对应的 CI 检查检查结果反过来作为技能验证标准的一部分。这样技能的成功与否不再依赖人工判断而是有客观的流水线结果背书。这个方向还在摸索等跑顺了再单独整理一篇。