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 这套东西大半年下来，最大的感受是：它逼着我把脑子里模糊的"项目规矩"写清楚。以前很多约定是"大家都知道"的隐性知识，写技能文件的时候才发现，原来大家对"大家都知道"的理解并不一致。这个过程本身就是一次团队规范的梳理，价值不亚于代理输出质量的提升。

另一个体会是，不要追求一步到位。我一开始想写一套覆盖所有场景的完美技能，结果写了三天还没写完，最后放弃。后来改成"遇到问题就补一条规则"，慢慢积累，反而更实用。技能框架是长出来的，不是设计出来的。

最后分享一个小技巧：给技能文件写一个"反例"章节，列出代理常犯的错误。代理看到反例，比看到正面规则更容易理解边界在哪里。这个技巧是我从代码评审的经验里迁移过来的，效果出奇地好。