superpowers技能框架：让Claude Code与Codex CLI编码代理更懂项目规范

1. 从superpowers说起这套技能框架到底在解决什么问题第一次看到superpowers这个词很多人会以为是某个超级英雄题材的游戏或者娱乐项目。但如果你最近在开发者社区里泡过尤其是关注 Claude Code、Codex CLI 这类终端智能编码工具的圈子就会发现这个词出现的频率越来越高。它指的其实是一套面向智能编码代理的技能框架英文叫 agentic skills framework核心思路是把软件开发方法论拆解成一个个可复用、可组合的技能单元让编码代理在执行任务时能够按需调用而不是每次都从零开始理解你的意图。我最初接触这套东西的时候心态是有点怀疑的。毕竟市面上各种框架方法论太多了大部分最后都沦为 PPT 上的概念。但实际用下来superpowers 解决的是一个非常具体的痛点当你用 Claude Code 或者 Codex CLI 处理复杂项目时代理很容易在长对话中丢失上下文或者对项目约定一无所知导致生成的代码风格不统一、目录结构混乱、测试覆盖缺失。superpowers 通过预定义的技能描述文件把这个项目应该怎么做事固化下来代理每次启动都能读取这些约定相当于给代理装了一套项目规范说明书。这套框架适合谁我的判断是三类人一是已经在用 Claude Code 或 Codex CLI 做日常开发的工程师想让代理输出更稳定二是团队里负责搭建开发规范的技术负责人想把团队约定沉淀成代理可读的格式三是对 agentic 开发流程感兴趣、想了解智能编码工具底层运作机制的学习者。哪怕你只是刚装好 Claude Code 的新手理解 superpowers 的设计思路也能帮你更好地组织自己的提示词和工作流。需要提前说明的是superpowers 本身不是一个独立的软件它更像是一套约定和文件组织方式依附于 Claude Code、Codex CLI 这类支持技能加载的代理工具运行。所以讨论 superpowers必然要连带讨论这些工具的安装、配置和技能加载机制。下面我会从设计思路、核心细节、实操流程、问题排查几个层面把这套东西拆开讲清楚。2. 核心设计思路拆解为什么是技能而不是提示词2.1 从提示词工程到技能框架的演进逻辑早期用 Claude Code 或者 Codex CLI 的人习惯把所有要求写在一段长长的提示词里项目用什么语言、目录怎么组织、测试怎么写、提交信息什么格式。这种做法在单次任务里还行但一旦任务变多、对话变长提示词就会被稀释代理开始忘记之前的约定。我自己就踩过这个坑一个项目里前面说了用四空格缩进聊到第十轮的时候代理突然给我返回两空格缩进的代码气得我当场重开对话。superpowers 的思路是把这些约定从一次性提示词变成持久化技能文件。每个技能文件描述一件事比如如何写这个项目的单元测试如何组织 API 路由如何处理数据库迁移。代理在执行任务前会先扫描技能目录把相关技能加载进上下文。这样做的好处有三个第一约定持久化不依赖对话历史第二技能可组合不同任务加载不同技能避免上下文污染第三技能可复用同一个技能文件可以跨项目、跨团队共享。这个设计背后的核心洞察是智能编码代理的能力瓶颈往往不在模型本身而在它不知道你的项目规矩。模型再强如果你不告诉它项目用 pnpm 而不是 npm、用 vitest 而不是 jest它就会按自己的默认习惯来。superpowers 本质上是把项目规矩这件事工程化了。2.2 技能文件的组织方式与加载机制从常见实践来看superpowers 的技能文件通常放在项目根目录下的特定文件夹里比如.claude/skills/或者类似的约定路径。每个技能是一个独立的 Markdown 文件或者结构化描述文件包含技能名称、触发条件、具体指令几部分。触发条件决定了代理在什么场景下加载这个技能具体指令则是给代理的行为规范。我见过的一种典型组织方式是这样的技能文件按领域分类testing.md管测试、api-design.md管接口设计、git-workflow.md管提交规范。每个文件开头用一段简短的描述说明这个技能解决什么问题然后是具体的规则条目。代理在接到任务时会根据任务描述匹配相关技能把匹配到的技能内容注入上下文。这里有个关键细节技能文件不是越长越好。我一开始图省事把所有规范塞进一个大文件结果代理加载后上下文被占满反而影响了正常推理。后来改成每个技能控制在几百字以内只写最关键的规则效果明显好转。这跟写函数是一个道理单一职责、短小精悍比大而全的模块更好维护。2.3 与 Claude Code、Codex CLI 的协作关系superpowers 要发挥作用离不开宿主工具的支持。Claude Code 和 Codex CLI 都提供了技能加载或者类似的项目上下文注入机制。Claude Code 通过项目根目录的配置文件读取项目约定Codex CLI 也有自己的配置方式。superpowers 可以理解为在这两者之上的一层方法论封装它规定了技能应该怎么写、怎么组织、怎么被代理消费。实际使用中我倾向于把 superpowers 当成一套写作规范而不是软件。它告诉你技能文件应该包含哪些要素、用什么语气写、如何避免歧义。至于具体用 Claude Code 还是 Codex CLI 来加载取决于你手头的工具链。两者在技能加载的细节上有差异但核心思路是相通的让代理在动手之前先读懂你的项目规矩。3. 核心细节解析与实操要点3.1 技能文件到底该写什么内容边界与颗粒度写技能文件最容易犯的错是把它写成项目文档。项目文档是给人看的技能文件是给代理看的两者的信息密度和表达方式完全不同。给人看的文档可以有大段背景介绍、架构图、历史沿革给代理看的技能文件必须是指令式的、无歧义的、可执行的。我的经验是一个合格的技能文件应该回答三个问题这个技能在什么情况下被触发触发后代理必须遵守哪些硬性规则有哪些常见的错误做法需要避免比如一个关于数据库迁移的技能触发条件是当任务涉及修改数据库 schema 时硬性规则包括迁移文件必须放在 migrations 目录每个迁移必须包含 up 和 down 两个方向迁移文件名必须带时间戳前缀常见错误包括不要直接修改已有迁移文件不要在迁移里写业务逻辑。颗粒度方面我建议按一个技能解决一类问题来切分。太粗会导致技能文件臃肿太细会导致技能数量爆炸、维护困难。一个实用的判断标准是如果一个技能文件超过 500 字还没写完说明它该拆了如果两个技能文件有超过一半的内容重复说明它们该合并了。3.2 触发条件的写法让代理准确匹配任务触发条件是技能框架里最容易被忽视、却最影响效果的部分。写得太宽泛代理会在不相关的任务里加载技能浪费上下文写得太窄代理又会在该加载的时候漏掉。我踩过的坑是一开始触发条件写得很模糊比如涉及代码修改时结果代理几乎每个任务都加载这个技能上下文里塞满了用不上的规则。后来我改成用更具体的场景描述比如当任务涉及新增或修改 HTTP 接口时当任务涉及数据库 schema 变更时当任务涉及前端组件新增时。这样代理能更精准地判断该不该加载。另一个技巧是在触发条件里列出关键词比如接口、路由、endpoint、API这些词出现时触发接口设计技能。代理的匹配机制通常对关键词比较敏感明确列出关键词能显著提升匹配准确率。提示触发条件不要写成自然语言长句尽量用场景 关键词的紧凑格式代理解析起来更稳定。3.3 规则条目的表达避免歧义的三条原则技能文件里的规则条目直接决定代理的行为。我总结了三条表达原则实测下来能大幅减少代理理解偏差的情况。第一条是用肯定句少用否定句。代理对必须做什么的执行力明显强于不要做什么。与其写不要用 var不如写声明变量一律使用 const需要重新赋值时使用 let。否定句容易让代理在规避的同时引入新的问题。第二条是给例子不给形容词。写代码风格要清晰这种话等于没写代理不知道什么叫清晰。写函数名使用动词开头的驼峰命名如 getUserById、createOrder就具体得多。例子是最好的规范。第三条是规则之间不要冲突。如果两个技能文件对同一件事给出了不同规则代理会陷入困惑输出变得不稳定。我建议在项目里维护一份规则总表新增技能前先检查有没有和已有规则冲突。3.4 技能文件的版本管理与团队协作技能文件既然是项目约定的一部分就应该跟代码一起纳入版本管理。我见过一些团队把技能文件放在个人目录下结果每个人用的规范都不一样代理输出自然五花八门。正确做法是把技能目录提交到仓库团队成员共享同一套技能。团队协作时技能文件的修改应该走代码评审流程。一个新技能或者一条新规则的加入可能影响所有成员的代理行为值得像改代码一样认真对待。我所在的团队就规定技能文件的修改必须至少一人 review涉及核心规范的修改需要两人 review。这条规矩帮我们避免了好几次某个人随手改了规则导致全组代理行为突变的事故。4. 实操过程与核心环节实现4.1 环境准备Claude Code 与 Codex CLI 的安装要点要让 superpowers 跑起来第一步是把宿主工具装好。Claude Code 的安装方式根据操作系统不同有差异。在 Ubuntu 或者类似的 Linux 环境下通常通过包管理器或者官方提供的安装脚本完成在 Windows 上可以通过 WSL 环境安装也可以使用桌面版。安装完成后用claude --version之类的命令验证是否成功。Codex CLI 的安装类似官方提供了多种安装途径。Windows 用户如果遇到 unable to locate the codex cli binary or required runtime components 这类报错通常是运行时组件缺失或者环境变量没配好。我的排查顺序是先确认 Node.js 或者对应的运行时是否安装、版本是否满足要求再确认安装路径是否加入了 PATH最后检查是否有权限问题。注意安装过程中如果遇到网络相关的报错优先检查本地网络环境和包管理器的镜像配置不要盲目重装。安装完成后建议先跑一个最简单的任务验证工具能正常工作比如让它读一个文件、改一行代码。确认基础功能没问题再进入 superpowers 的配置环节。这一步看似多余但能帮你把工具本身的问题和技能配置的问题分开后面排查起来省事很多。4.2 技能目录的初始化与第一个技能文件环境就绪后在项目根目录创建技能目录。具体路径取决于你用的工具Claude Code 常见的约定是.claude/skills/Codex CLI 有自己的约定路径。创建目录后写第一个技能文件。我建议从最简单的开始比如一个项目概览技能描述项目用什么语言、什么框架、目录结构大概什么样。第一个技能文件的内容可以这样组织开头一段说明这个技能的作用然后是几条硬性规则最后是几个常见错误。写完后启动代理给它一个简单任务观察它是否加载了这个技能、是否遵守了规则。如果代理没有加载检查触发条件是不是写得太窄如果加载了但没遵守检查规则条目是不是有歧义。这个写一个、测一个的节奏很重要。一次性写十个技能文件然后一起测出了问题很难定位是哪个文件的问题。我自己的做法是每加一个技能就跑一次验证任务确认没问题再加下一个。4.3 技能加载验证怎么确认代理真的读到了验证技能是否被加载有几种方法。最直接的是在任务里问代理你现在加载了哪些技能大部分工具会如实回答。另一种方法是观察代理的行为如果它开始遵守你写的规则说明技能生效了如果它还是按默认习惯来说明技能没被加载或者被忽略了。我还用过一种埋点技巧在技能文件里写一条非常具体的规则比如所有新建的 Python 文件必须在文件头加一行注释# project: myapp。然后让代理新建一个文件看它有没有加这行注释。加了说明技能生效没加说明有问题。这种可观测的规则比抽象的代码风格要统一更容易验证。如果发现技能没生效排查顺序是先确认技能文件路径对不对再确认文件格式是否符合工具要求然后确认触发条件是否匹配当前任务最后确认技能内容有没有语法错误。这四步走下来大部分加载问题都能定位。4.4 一个完整的技能应用实例从任务到输出假设我们要让代理完成一个新增用户注册接口的任务。没有 superpowers 的情况下代理可能会自己决定用什么框架、什么目录结构、什么命名风格输出质量全看运气。有了 superpowers 之后流程变成这样代理接到任务扫描技能目录匹配到接口设计技能和数据库操作技能。加载接口设计技能后它知道接口要放在src/api/目录下路由命名用 kebab-case请求体要经过校验层。加载数据库操作技能后它知道要写迁移文件、迁移文件放migrations/目录、文件名带时间戳。然后代理开始动手生成的代码自然符合项目规范。这个流程里代理的自由度被约束在合理范围内它仍然可以决定具体的实现细节但项目级的约定被技能文件固定下来。这就是 superpowers 的核心价值——约束该约束的放开该放开的。5. 常见问题与排查技巧实录5.1 技能不生效的典型原因速查现象可能原因排查方法代理完全没提到技能技能目录路径错误对照工具文档确认约定路径代理提到技能但没遵守规则条目有歧义把规则改成指令式、带例子部分任务加载、部分不加载触发条件太窄补充关键词和场景描述加载后输出反而变差技能文件太长拆分技能控制单文件长度多个技能规则冲突规则未统一管理建立规则总表定期检查这张表是我自己踩坑总结出来的覆盖了八成以上的技能失效场景。遇到问题先对照这张表排查比盲目改文件高效得多。5.2 代理忘记规则的几种情况代理忘记规则通常不是真的忘了而是上下文被其他信息挤占了。长对话里早期的技能内容可能被后续的对话历史覆盖。解决办法有两个一是把关键规则写得更靠前、更醒目二是在长任务里定期提醒代理重新加载技能。另一种情况是规则本身太抽象代理记住了但不知道怎么执行。比如代码要健壮这种规则代理记住了也没用。改成所有外部输入必须经过校验校验失败返回 400 状态码就具体多了。规则的可执行性比规则的完整性更重要。5.3 跨工具使用的兼容性问题同一个项目可能有人用 Claude Code有人用 Codex CLI。两者的技能加载机制有差异直接共用一套技能文件可能出问题。我的做法是把技能内容写成工具无关的格式然后用一层薄薄的适配配置把技能目录映射到各自工具期望的路径。这样技能内容只需要维护一份适配层各自处理。如果团队里工具不统一建议在项目文档里明确说明技能文件的结构和加载方式让每个人都能正确配置自己的工具。工具差异带来的问题本质上是配置问题不是技能设计问题分开处理就好。5.4 技能维护的长期策略技能文件不是写完就完事了它需要跟着项目一起演进。我的经验是每个月回顾一次技能目录看看有没有过时的规则、有没有重复的技能、有没有该新增的场景。回顾的时候问自己三个问题过去一个月代理在哪些任务上表现不好这些任务有没有对应的技能现有技能里有没有互相矛盾的规则另一个实用技巧是给技能文件加最后更新日期和负责人字段。这样过一段时间回头看能快速判断哪些技能可能已经过时该找谁确认。技能框架的价值在于持续维护一次性投入然后放着不管效果会随时间衰减。6. 我个人的一些实操体会用 superpowers 这套东西大半年下来最大的感受是它逼着我把脑子里模糊的项目规矩写清楚。以前很多约定是大家都知道的隐性知识写技能文件的时候才发现原来大家对大家都知道的理解并不一致。这个过程本身就是一次团队规范的梳理价值不亚于代理输出质量的提升。另一个体会是不要追求一步到位。我一开始想写一套覆盖所有场景的完美技能结果写了三天还没写完最后放弃。后来改成遇到问题就补一条规则慢慢积累反而更实用。技能框架是长出来的不是设计出来的。最后分享一个小技巧给技能文件写一个反例章节列出代理常犯的错误。代理看到反例比看到正面规则更容易理解边界在哪里。这个技巧是我从代码评审的经验里迁移过来的效果出奇地好。