如果你最近在 AI 编程工具链的圈子里逛几乎不可能避开 superpowers 这个词。它不是一个具体的编程框架也不是某家大厂的闭源黑科技而是一套围绕 Claude Code、Codex CLI 这类终端 AI 编码代理设计的“技能扩展集合”。说白了它把资深工程师脑子里那套方法论——需求澄清、系统化调试、根因分析、代码审查、边界测试——用结构化的技能文件固化下来让 AI 在动手之前先学会“怎么想”。我最早是因为被 Claude Code 反复“瞎改代码”搞烦了才去研究它的。明明模型能力很强但一遇到模糊需求或者线上 Bug它就容易直接开干改完不测、测完不验出了问题再回头补循环往复。superpowers 解决的就是这个核心问题模型本身不缺知识缺的是一套稳定的工作流程。装上之后AI 会像跟了几年的靠谱同事一样先问清需求再列计划改完之后自己补测试。这套东西适合谁如果你在用 CLI 形式的 AI 编程工具做日常开发尤其是被“AI 改完就崩”“AI 自作主张”折磨过的人非常值得试试。下面我把自己的安装、使用、踩坑过程完整过一遍。1. superpowers到底是什么一个带工程方法论的AI外挂1.1 先说说背景AI编码代理为什么会能力忽高忽低要理解 superpowers得先明白 Claude Code 这类工具的运行机制。它们本质上是通过 API 调用大模型在终端里读写文件、执行命令、观察输出形成一个“感知-行动-验证”的循环。模型本身有很强的知识储备但它的“工作纪律”完全取决于上下文里的提示词。这就带来一个尴尬的现实同一个模型在 A 的项目里表现得很专业到了 B 的项目里就可能像个刚入职的实习生。原因很简单——项目没有把“怎么干活”的标准告诉它。大多数人的用法是装好工具就直接丢需求AI 接到一个模糊指令后只能靠猜测补全细节猜测错了就返工返工次数一多代码质量自然崩。我见过太多类似的案例。比如让 AI “优化一下登录逻辑”它直接把整个 session 管理重写了让 AI “修一下这个 Bug”它修完主路径之后把异常路径的兜底逻辑删了。这些问题的共同点不是模型“笨”而是没有人在流程上约束它需求没有澄清改动没有计划测试没有覆盖验收没有标准。superpowers 的思路就是在这个环节下手。它不是给模型加知识而是给模型加“行为规范”——把资深工程师的工作方法论写成结构化的技能文件让 AI 在合适的场景主动调用按固定的步骤走完整个流程。模型还是那个模型但它的工作方式变了。1.2 技能文件机制SKILL.md 与 CLAUDE.md 的分工聊 superpowers 绕不开一个基础概念技能文件机制。Claude Code 系列工具支持一个叫“Agent Skills”的目录规范每个技能是一个独立的文件夹里面有一个 SKILL.md 文件作为入口文件头部用 YAML 格式写技能的元信息正文写具体的操作步骤。SKILL.md 的核心是description字段。模型在对话过程中会不断扫描技能目录里的描述信息当当前任务和某个技能的描述匹配时它就会自动加载这个技能按里面的步骤执行。这是一个“按需加载”的设计——平时技能只是索引不占上下文窗口只有真正用到时才把完整内容读进来。这里要分清两个容易混淆的文件CLAUDE.md 和 SKILL.md。CLAUDE.md 是项目级或者用户级的长期记忆告诉 AI 项目的背景、技术栈、常用命令、代码规范相当于入职手册SKILL.md 是某个具体工作流的操作标准相当于某个岗位的 SOP。打个比方CLAUDE.md 告诉你“我们团队用 Java 17、Maven、Spring Boot”SKILL.md 告诉你“遇到线上 Bug 时必须先复现、再假设、最后才改代码”。两者配合的方式是CLAUDE.md 负责让 AI“知道自己在哪”SKILL.md 负责让 AI“知道该怎么干”。superpowers 这套技能库就是围绕 SKILL.md 规范构建的因为它把大量工程实践沉淀成了标准化的技能文件所以可以被不同项目复用也能被个人二次修改。1.3 这套东西解决了我最头疼的三件事装了 superpowers 之后我最直观的感受是它的技能设计完全踩在我的痛点上了。第一件事是需求模糊。以前我给 AI 一句“帮我加个超时关闭功能”它可能直接就开始写代码最后写出来一个跟业务约束完全不符的东西。现在有了 brainstorming 技能AI 在动手前会连续追问场景细节、约束条件、验收标准把需求从一句话扩展成一份清晰的说明书。第二件事是改完不测。以前 AI 改完代码自己觉得逻辑通了就算完事根本不跑测试。现在有了 systematic-testing 技能它会在改动完成后主动设计测试用例覆盖正常路径、边界值、异常输入然后自己执行测试并汇报结果。这个过程说不上多智能但至少把“测试”这一步从可选变成了默认。第三件事是复盘缺失。以前 AI 修完一个 Bug 就结束了不追问根因也不防回归。现在有了 root-cause-analysis 和 code-review 技能它会沿着因果链往下挖搞清楚为什么会出现这个问题然后在相关位置补上防护逻辑。这个“多走一步”的习惯恰恰是很多初级工程师和 AI 默认状态下最缺的。说白了superpowers 给我的感觉不是“换了个更聪明的 AI”而是“把靠谱同事的工作习惯复制给了 AI”。这比单纯换更大参数的模型要实在得多。2. 安装与工具选型从零到跑通一个技能2.1 前置环境Claude Code 和 Codex CLI 怎么选superpowers 最早是围绕 Claude Code 设计的这套技能机制也是 Anthropic 的 Agent Skills 规范。如果你主力用的是 Claude Code安装起来最顺技能加载、上下文管理、文件读写都原生支持。Claude Code 目前可以通过 npm 安装装完在终端里输入claude就能进入交互界面。如果你用的是 OpenAI 的 Codex CLI情况稍微复杂一点。Codex 的配置文件是 AGENTS.md它本质上也支持类似的自定义指令机制但不像 Claude Code 那样有一套完整的技能目录规范。社区里有一些适配方案我在后面的常见问题部分会详细讲。我的建议是如果你只是想体验 superpowers先装 Claude Code如果团队已经统一用了 Codex那也别急着切换可以考虑把技能内容精简后移植到 AGENTS.md 里。另外一个容易踩的坑是版本问题。Claude Code 的迭代速度很快技能目录的默认路径在不同版本里可能不一样有的版本读~/.claude/skills/有的版本读项目目录下的.claude/skills/还有的版本要求在配置里手动声明技能目录。安装前先claude --version看一眼版本再去查对应版本的文档能省不少事。2.2 拉取技能库从 GitHub 克隆到本地安装 superpowers 本身很简单因为它不是需要编译的程序而是一堆 markdown 文件组成的技能目录。社区里最常见的做法是把整个仓库克隆到 Claude Code 默认读取的技能目录下。以我目前使用的版本为例命令大概是这样的# 把技能库克隆到用户级技能目录 git clone https://github.com/obra/superpowers.git ~/.claude/skills/superpowers克隆完之后你会看到技能库里包含了多个子目录每个子目录就是一个独立的技能比如 brainstorming、planning、systematic-testing、systematic-debugging 等。每个目录里都有一个 SKILL.md 文件这就是模型的“技能说明书”。如果你用的是项目级配置也可以把技能目录放在项目的.claude/skills/下。区别在于用户级目录对所有项目生效项目级目录只对当前项目生效。我的习惯是把通用的方法论类技能放在用户级把跟业务强相关的专属技能放在项目级这样既保证基础能力覆盖又避免脏技能污染其他项目。克隆完成后需要在 CLAUDE.md 里加一段引导语让模型知道技能库的存在。以用户级配置文件为例# ~/.claude/CLAUDE.md ## 技能使用 本项目环境已加载 superpowers 技能库。当你需要澄清需求、制定计划、排查问题、审查代码或设计测试时请优先从技能库中查找并加载对应技能严格按照技能中的步骤执行。这段引导语不需要写太详细因为技能的细节都在 SKILL.md 里。它起的作用是“钩子”——提醒模型在合适的时候主动去翻技能库而不是凭感觉自由发挥。2.3 快速验证让AI主动“发现”技能装完之后很多人会怀疑“到底装没装上”。有一个很简单的验证方法在 Claude Code 里随便说一句“我有一个需求但还没想清楚能不能帮我理一下”然后观察它的反应。如果它开始主动追问业务场景、用户人群、约束条件并且提到类似“我先用 brainstorming 技能帮你梳理”的话那就说明技能加载成功了。如果它完全没有反应还是直接问“请描述你的需求”那多半是技能没有被识别。这种时候可以先手动指定一下比如直接说“加载 brainstorming 技能然后按技能里的流程走”。手动加载成功说明技能文件本身没问题问题出在自动触发环节通常需要回去调整 CLAUDE.md 里的提示语或者检查 description 字段的表述是否足够精准。还有一种情况是模型版本太老不支持 Agent Skills 机制。遇到这种问题没什么好办法只能升级 Claude Code 或者换用支持技能机制的编码代理。我在测试中发现较新版本的模型对技能触发更敏感会自动读取多个技能的描述然后在合适的时机切入体验比旧版好很多。2.4 定制属于自己的技能包superpowers 给我最大的启发是技能不一定要用现成的完全可以自己写。技能机制本质上是“用 markdown 写操作手册”门槛低得惊人。我自己写过一个处理数据库慢查询的技能目录结构大概是这样的project/.claude/skills/slow-query-triage/ ├── SKILL.md └── examples/ └── slow-query-report.mdSKILL.md 的内容很简单YAML 头部加上正文步骤--- name: slow-query-triage description: 当用户反馈接口响应慢、数据库查询耗时异常、需要定位慢 SQL 时使用该技能。 --- # 慢查询排查流程 1. 获取慢查询日志或开启 profiling。 2. 提取执行计划定位全表扫描或索引失效。 3. 列出候选优化方案对比影响面。 4. 实施最小改动并用 EXPLAIN 前后对比验证。写完这个技能文件之后不需要任何额外配置模型就能在遇到慢查询相关问题时自动加载它。这种“低成本沉淀经验”的能力比技能本身更值钱。团队里任何一个成员踩过的坑都能通过这种方式固化成团队资产。3. 核心技能实操拆解方法论是怎么被工程化的3.1 Brainstorming从帮我做个功能到可执行方案我用的最多的技能是 brainstorming。它的定位是解决需求不清晰的问题。以前我会直接跟 AI 说“给订单加个超时关闭功能”然后等着它交代码。现在有了这个技能AI 在拿到需求后不会马上动笔而是进入一个澄清循环。这个技能的实际行为很像一次结构化的需求访谈。AI 会依次问几个关键问题这个功能的最终用户是谁触发条件是哪些能不能容忍误判已有的系统约束是什么哪些场景可以暂时不做每一个问题背后都有目的比如“最终用户是谁”是为了区分运营后台手动触发和 C 端用户自助操作这两种场景的设计方案完全不同。等需求澄清得差不多了AI 会输出一份方案对比通常以表格形式列出几种可选方案的优缺点、成本、风险然后给出推荐。比如“订单超时关闭”这个需求方案可以是定时任务批量扫描、延迟消息队列、或者在下单时设置 TTL 由存储层自动处理。不同方案的延迟精度、开发成本、运维复杂度差异很大如果没有前面的澄清环节AI 大概率只会给你一个默认实现。我个人的体会是brainstorming 技能的价值不在于把需求问得很细而在于让 AI 在动手前先建立“目标-约束-方案”的框架。它把这个框架变成了一个稳定的输出结构即使需求提得很糙最后也能拿到一个可以评审的东西。3.2 Systematic Debugging把排查过程变成固定流程调试 Bug 是另一个我忍了很久的痛点。以前让 AI 查 Bug它经常直接“我看到这段代码有问题改成这样”然后就没有然后了。万一改错了它还会换个地方继续猜。systematic-debugging 技能改变了这个局面它把调试拆成了六个步骤复现问题、收集信息、列出假设、设计最小验证、实施修复、回归验证。第一个步骤是复现。AI 会先要求你提供复现步骤或者自己构造一个最小复现用例。这一步卡死过很多人因为日志里报错一堆但说不清什么时候触发。如果复现不了AI 会引导你加日志、看监控、构造测试数据而不是雾里看花地猜。第二个步骤是收集信息包括报错栈、相关日志、输入数据、环境信息信息越全后面判断越准。真正让我觉得这个技能值回票价的是“列出假设”这一步。AI 会把可能的原因列成一张清单比如“缓存和数据源不一致”“并发下状态字段被覆盖”“异常路径把 session 清掉了”然后在清单上逐个验证而不是一上来就锁定一个原因。每个假设都要设计一个最小实验来验证这一步大幅降低了“修错方向”的概率。修复之后还有回归验证确保改动没有破坏其他逻辑。这套调试流程对模型的意义在于它把“找 Bug”这种发散型任务变成了一个有边界的收敛型任务。步骤是固定的每个步骤的产出也是固定的模型不需要在每次调试时重新发明流程。说实话这套方法我自己写代码的时候都不一定每次遵守但 AI 只要遵守了产出质量就明显高一截。3.3 Root Cause Analysis不止修Bug还要挖根因和 systematic-debugging 搭配使用的是 root-cause-analysis。调试技能解决的是“把眼前的 Bug 修好”根因分析技能解决的是“为什么这个 Bug 会出现在这里”。这个技能的底层逻辑是经典的五 Why 分析和因果链拆解但它被工程化成了一套可供模型执行的流程。实际执行时AI 会沿着一个问题往上追问。比如“订单状态变成了已支付但支付回调其实失败了”第一层原因可能是状态机被错误触发第二层可能是并发请求导致重复回调第三层可能是接口没有做幂等保护第四层可能是调用方重试机制设计不当。逐层往下挖最后得到的往往不是一行代码的问题而是某个设计决策的疏漏。这个技能最有价值的部分是最后的“防再发”建议。AI 会指出应该在系统的哪个位置增加防护是入口幂等、状态机校验还是监控告警。这些建议不一定都会实施但至少给了你一个排查清单。实际上我发现让 AI 做根因分析有一个附加好处它会比人更耐心地遍历因果链的每一个分支不会因为“看起来像这个原因”就草率结束。3.4 Code Review 与 Systematic Testing质量和回归的双保险如果说前面几个技能是“防患于未然”那 code-review 和 systematic-testing 就是“事后兜底”。code-review 技能的审查维度比较全面包括功能正确性、边界处理、性能隐患、安全风险、可维护性、依赖引入是否合理。AI 会把改动文件逐个过一遍按维度输出问题列表而不是简单地说一句“代码写得不错”。systematic-testing 技能则是对测试策略的规范。以前 AI 只会补一个“主路径成功”的测试用例现在它会按正常路径、边界值、异常输入、资源释放、并发影响这几个维度来设计用例。比如测一个文件上传接口正常路径是上传成功返回 URL边界值是空文件、超大文件异常输入是非法格式、文件名带特殊字符资源释放是连接和流是否关闭。这套维度对 Java 开发尤其适用因为 Java 项目里空指针、资源泄漏、并发问题都很常见。我用下来的感受是code-review 和 systematic-testing 这两个技能应该作为“默认开启”的流程而不是遇到问题才想起来用。它们能强制 AI 在交付前多走一步自检流程。如果你维护的是核心业务系统这一步几乎可以肉眼可见地减少回归 Bug 的数量。3.5 在Java项目里怎么用Maven/Gradle、JUnit与Spring场景superpowers 的技能设计跟语言无关但在 Java 项目里有一些特定的玩法值得单独说说。首先是构建工具Claude Code 在加载技能后会优先从 CLAUDE.md 里读取项目的构建命令所以配置里一定要写清楚是 Maven 还是 Gradle。这个细节很重要因为它决定了系统的调试技能要执行mvn test还是./gradlew test。其次是 JUnit 的测试风格。systematic-testing 技能在 Java 项目里的默认输出是 JUnit 5 的测试类它生成的测试代码依赖你项目里已有的测试基础。如果你的项目里连 Mockito 都没有我建议在 CLAUDE.md 里注明“如果需要 mock 依赖优先使用项目已有的测试工具”否则 AI 可能会自作主张引入一堆新的依赖反而增加维护成本。Spring Boot 场景下调试技能的用处尤其明显。当接口报错时AI 会先看 Controller、Service、Mapper 三层各自的日志再根据异常类型缩小范围。典型的排查链路是先确定是不是请求参数问题再看 Service 层事务是否回滚最后查数据库 SQL 和连接池状态。这个链路如果让 AI 自由发挥它可能直接跳到“改 SQL”这一步但有了系统化调试的流程约束它会按层级逐个排除。另外提一句 Java 特有的坑检查异常和受检异常的处理方式以及 Lombok 的使用约定。如果你的项目用了 Lombok而 CLAUDE.md 里没写AI 生成的代码可能会在编译期报一堆“找不到 getter/setter”的错误。这些项目约定都应该在配置文件里写清楚让技能在加载时能感知到。4. 实战记录用superpowers跑完一次Java服务重构4.1 需求澄清阶段从一句话需求到验收标准理论说多了有点干我拿最近一个真实需求完整跑了一遍流程。需求一句话“给订单服务加个超时关闭功能未支付的订单 30 分钟后自动关掉。”放在以前我会直接把这句话丢给 AI现在我用 brainstorming 技能先把需求揉碎。AI 在澄清阶段连续追问了三轮。第一轮问的是业务边界哪些订单状态算“未支付”部分支付算不算关闭之后用户还能不能重新下单第二轮问的是技术约束订单服务是 Spring Boot MySQL当前有没有现成的定时任务框架有没有消息队列可以用第三轮问的是运营需求关闭操作需不需要给用户发通知需不需要记录关闭原因这几轮问完我发现自己原以为很简单的需求其实包含三个隐藏点部分支付的订单不可关闭、关闭操作需要幂等、超时时间要支持配置。如果这些点没有提前澄清AI 直接写出来的代码大概率会在部分支付这个分支上出错。澄清结束后AI 输出了一份需求确认单包含功能范围、非功能要求、验收标准三个部分我问了三个问题之后这份文档直接变成了开发排期的依据。4.2 计划与拆解让AI按里程碑推进需求确认之后第二件事是让 AI 用 planning 技能拆解实施计划。我特别强调了一点不要一次性把所有代码写出来按里程碑推进每个里程碑结束都要编译验证。AI 把任务拆成了四个里程碑。M1 是数据库变更加状态字段迁移M2 是新增超时扫描任务的核心逻辑M3 是幂等控制和通知预留接口M4 是补测试和文档。每个里程碑下面又细分了若干步骤每步都标注了涉及的类和文件以及验证方式。这个拆解看起来不复杂但价值在于它把一个大需求变成了若干个可以独立验证的小步骤AI 每完成一个里程碑我都能在本地跑一次测试及时发现问题而不是最后一次性面对一大坨改动。计划阶段还有一个意想不到的收获AI 在拆解过程中自己提出扫描任务要考虑分页查询避免一次把大量过期订单加载进内存。这个建议如果在开发阶段直接让 AI 写代码它大概率会写一个全表扫描。有了计划阶段的约束它在实现时会主动考虑数据量级和批处理。4.3 开发与系统化测试单元测试、边界、异常进入开发阶段我让 AI 按照计划逐步实现并且在每个里程碑结束时调用 systematic-testing 技能。这个技能生成了三类测试用例把我想不到的边界全补上了。第一类是正常场景订单创建 30 分钟后未支付扫描任务把它改为已关闭。第二类是边界场景订单刚好在 30 分钟整触发这要求测试里对时间做可控处理不能直接等 30 分钟。AI 的做法是把超时判断逻辑抽成独立方法注入一个时间源测试时传入固定时间。第三类是异常场景订单已经被用户手动取消扫描任务再碰到它不能重复处理扫描任务跑了两次第二次不能产生重复的关闭记录。最让我满意的是 AI 没有只写单元测试还补了一个集成测试验证整个扫描流程从数据库查询到状态更新再到通知接口调用的链路是通的。虽然这个测试跑起来稍微慢一点但它在后续重构时成了最重要的回归保障。当然这个过程中也踩了一个 Java 特有的坑——时间比较用LocalDateTime时如果和数据库存储的timestamp比较时区不一致会导致差 8 小时的诡异问题。AI 在写代码时没有意识到这个点我补了一轮代码审查之后才修正。这也说明技能调用不是万能的人工审查仍然不可替代。4.4 事后审查与技能沉淀开发完成后我让 AI 调了一次 code-review 技能对全部改动做了一次全量审查。审查结果里有两条很有价值的发现。第一条是扫描任务没有做分布式锁处理如果生产环境同时部署多份实例会出现重复扫描的问题第二天是状态更新的 SQL 语句没有加条件更新极端情况下可能把已经关闭的订单又改回关闭状态虽然结果一致但会产生多余的行锁竞争。这两个问题在单机本地测试时根本不会暴露但一旦上线就是事故。我根据审查结果让 AI 补了分布式锁方案把更新 SQL 改成了带状态条件的更新语句然后重新跑了一遍全量测试。这轮审查让代码从“本地能跑”提升到了“生产可用”整个过程只多花了十几分钟。做完这次涉及的功能开发之后我还要做一个动作把踩到的坑沉淀成团队技能。我把“本地时间与数据库时区不一致导致差 8 小时”这个问题写成了一个自定义技能内容包括问题现象、排查路径、修复模板放进项目级技能目录。以后再有 AI 在这个项目里处理时间相关逻辑它就会自动加载这个技能避开我已经踩过的坑。5. 常见问题与排查技巧实录5.1 技能加载失败先从目录和命名排查我见过最多的问题是技能装上了但没生效。90% 的情况出在目录路径和文件名上。Claude Code 的技能目录有严格的规范目录名不能乱起SKILL.md 必须放在技能目录的根目录下。如果你的目录名和技能内部定义的 name 不一致模型可能识别不到。排错的顺序通常是这样先确认技能目录是否在模型当前生效的配置范围内是用户级还是项目级再确认 SKILL.md 的 YAML 头部格式是否正确name字段有没有写错最后在对话里直接手动指定技能名看能否强制加载。如果你手动指定能加载、自动触发不行问题基本出在description字段的表述上描述里的关键词和你的对话内容匹配不上模型自然不知道什么时候该用它。还有一个很容易忽略的问题技能目录不能嵌套在其他技能目录里。superpowers 整个仓库被一键克隆到 skills 目录下如果你把它当作一个子目录直接放在某个技能里面模型遍历时会因为层级太深而跳过。正确做法是把技能库解包让每个技能目录平铺在 skills 根目录下或者把整个技能库作为独立的一个技能处理。5.2 AI不主动调用技能需要给模型一个钩子如果你的 AI 明明知道技能库存在但就是不调用别急着怀疑技能没装好。这通常是因为 CLAUDE.md 里的提示语不够强。模型默认的行为模式是“最快路径完成任务”如果配置文件里只说“你有技能可以用”它大概率会认为“直接回答也行”于是就走捷径了。解决办法是给一个强指令明确什么场景下必须加载技能。我在 CLAUDE.md 里写的措辞是“当任务涉及需求澄清、计划制定、调试排错、代码审查或测试设计时必须先加载对应技能且不能跳过技能中的任何步骤”。这个措辞把“是否使用技能”从模型自由裁量变成了硬性规定触发率明显提高。如果你的项目里同时有多个技能我建议把触发最频繁的那几个技能写进 CLAUDE.md 的开头。因为模型对上下文中靠前的内容注意力更高越早看到提示越容易在后续对话里保持“使用技能”的状态。把一堆不常用的技能描述堆在配置文件尾部效果会差很多。5.3 上下文窗口不够用为技能瘦身和分层加载技能文件本身不占上下文空间因为 Agent Skills 的机制是“按需加载”。但一旦加载了某个技能它的完整内容就会进入上下文如果技能写得太长加上项目文件内容、对话历史很容易把上下文窗口挤爆。我一开始把整个 superpowers 技能库在 CLAUDE.md 里高亮推荐结果模型在做任何任务前都会扫描一遍所有技能上下文消耗反而变大。优化办法是“分层加载”。用户级目录里放少量全局必备技能项目级目录只放和当前项目相关的技能。我在重构项目期间只保留了 brainstorming、planning、systematic-debugging、systematic-testing 四个技能其他的一律从技能目录里暂时移走。这样模型在扫描时快速匹配到的技能数量有限上下文压力小触发也更快。另外一个实用技巧是精简 SKILL.md 正文。技能的价值在于“可执行步骤”那些背景介绍、原理阐述能省则省。我自己写技能时会刻意把步骤控制在 5 到 8 步每步一句话不做过多解释。如果你的技能文件超过 200 行大概率需要拆分把详细示例放到 references 目录下让模型按需读取而不是一次性加载全部。5.4 Codex CLI 用户怎么用AGENTS.md 适配方案很多用 Codex CLI 的朋友也想来一套 superpowers但不是所有技能机制都能直接照搬。Codex 的配置文件是 AGENTS.md它没有 Agent Skills 那样完整的目录规范但它支持在项目里放置多份 AGENTS.md 文件并且会按目录层级自动合并。基于这个机制我试过一种比较顺手的适配方式。做法是把 superpowers 里的核心技能分别转成独立的 AGENTS.md 片段放在项目目录下。比如把 systematic-debugging 的六个步骤写进debugging.agents.md然后在主 AGENTS.md 里用引用的方式引导模型按步骤执行。Codex 会读取这些文件在任务类型匹配时参考其中的步骤。实测下来它虽然没有 Claude Code 那种“按需加载”的精细度但至少能把方法论注入到模型的每一步操作里。如果你对细节不敏感也可以直接在主 AGENTS.md 里写一段“调试流程先复现、再假设、后修改、终回归”效果比完全没有强很多。不过要做好心理准备Codex 对长流程的遵循能力通常弱于 Claude Code步骤一多就容易“跳步”。我的建议是每个 AGENTS.md 片段只聚焦一个工作流步骤控制在五步以内。5.5 避坑清单速查表最后把我踩过的坑整理成一张速查表方便你对照排查。坑现象解决方式技能目录层级嵌套过深模型完全感知不到技能技能目录平铺在 skills 根目录下SKILL.md 里name与目录名不一致手动加载失败保持两者一致且用短横线命名CLAUDE.md 提示语太弱模型知道技能但不主动用改为强约束指令明确必须加载技能描述里缺乏匹配关键词任务来了但技能不触发描述里写清触发场景、同义词上下文窗口被技能撑爆响应明显变慢开始丢信息分层加载按需精简技能步骤本地时间与数据库时区不一致Java 时间比较出现 8 小时偏差统一时区配置测试注入固定时间源多实例部署没有分布式锁定时扫描任务重复执行在计划阶段就考虑并发部署自动触发的技能太多模型频繁切换技能产出不连贯项目级目录只保留必要技能这张表是我在实际使用中一点一点攒出来的。如果你在自己的项目里遇到类似现象按表格的顺序排查大多数问题都能在几分钟内定位。我个人在实际操作中的体会是superpowers 这套东西最大的价值不在于某个具体技能写得有多妙而在于它示范了“如何把人的工程经验结构化地喂给 AI”。以前我们教 AI 靠的是提示词里写一段话现在靠的是 SOP 式的技能文件前者是“告诉 AI 一个事实”后者是“教会 AI 一个流程”。安装一个现成的技能库只是第一步更值得做的是为自己的项目写一套专属技能把团队里每个人的经验都固化下来。这比反复写提示词要耐用得多也才是这套工具最值得投入精力的地方。