1. 从superpowers这个词说起它到底指什么第一次看到superpowers这个标题加上agentic skills framework和software development methodology这两个关键词我脑子里第一反应是这大概率不是某个具体软件的名字而是一套围绕 AI 编程助手构建的能力增强体系。事实也确实如此。在 Claude Code、Codex CLI 这类终端里的 AI 编程工具越来越普及之后社区里逐渐形成了一个共识——光靠模型本身的能力是不够的真正拉开差距的是你给它配了什么样的技能包、用了什么样的工作流、以及怎么把零散的工具串成一套可复用的方法论。superpowers 就是在这个背景下被反复提起的一个概念。它不是一个能双击安装的 exe也不是一个 pip install 就能搞定的库而更像是一套围绕 agentic skills 组织起来的开发范式把 AI 编程助手当成一个可以持续长技能的搭档通过结构化的技能定义、清晰的上下文管理、以及标准化的调用流程让它在真实项目里稳定输出而不是每次都要你从头解释一遍需求。我接触这套东西的起点其实很朴素。当时我在用 Claude Code 处理一个中型项目代码量不算大但模块之间的依赖关系比较绕。用了一段时间之后发现一个问题每次新开一个会话它对我项目的理解都归零我得重新告诉它目录结构、技术栈、命名习惯、哪些文件不能动。这种重复劳动累积起来非常消耗耐心。后来我开始琢磨能不能把这些项目常识沉淀成一套固定的技能描述让 AI 每次都能快速进入状态。顺着这个思路往下挖就摸到了 superpowers 这类框架的设计逻辑。所以这篇文章我想聊的不是superpowers 是什么官方定义而是作为一个实际使用者我是怎么理解并落地这套 agentic skills 方法论的。内容包括为什么需要它、核心机制怎么运转、在 Claude Code 和 Codex CLI 上分别怎么配置、踩过哪些坑、以及怎么把它变成你自己项目里真正能用的东西。适合已经上手过 AI 编程工具、但觉得用起来还是不够顺手的开发者也适合刚接触 Claude Code、想少走弯路的新手。2. 为什么裸用 AI 编程助手迟早会撞墙2.1 上下文窗口不是无限记忆它更像短期工作台很多人对 AI 编程助手有个误解觉得它记得住整个项目。实际上无论是 Claude Code 还是 Codex CLI它们的工作方式都是把当前相关的文件内容、对话历史、系统提示拼成一个上下文窗口送进模型。这个窗口是有上限的而且会话一关记忆就散了。我举个具体的例子。之前我让 Claude Code 帮我重构一个工具函数它改完之后我又让它去改调用这个函数的另一个模块。结果它在新一轮对话里对刚才那个函数的签名已经记不清了给出的调用方式还是旧的。这不是模型笨而是上下文管理的问题——它没有把刚才的改动当成一个需要持久化的技能状态。superpowers 这类框架要解决的第一件事就是把易失的对话记忆转化成可复用的技能资产。你可以理解为与其每次口头交代不如写一份操作手册放在项目里AI 每次开工前先读手册。2.2 技能定义缺失导致的三种典型翻车在没有技能框架的情况下我总结出三种高频翻车场景几乎每个重度用户都遇到过风格漂移第一次让它写代码用了 4 空格缩进第二次变成 2 空格第三次又混用了 tab。因为每次会话它都在猜你的偏好。边界失控你只想让它改一个文件它顺手把隔壁两个文件也优化了理由是顺手发现的。这在没有明确约束时非常常见。流程断裂一个任务需要先读需求→再写测试→再实现→最后跑验证但裸用的时候它经常跳步直接上来就写实现测试和验证全靠你事后补。这三种问题的根因是同一个AI 缺少一个稳定的、跨会话的行为契约。superpowers 的价值就在于提供这个契约的载体。2.3 agentic skills 和普通 prompt 的本质区别这里要澄清一个容易混淆的点。很多人觉得我写个详细的 prompt 不就行了但 prompt 和 skill 是两回事。维度普通 PromptAgentic Skill生命周期单次会话跨会话持久触发方式手动粘贴按条件自动加载内容粒度针对具体任务针对一类能力可组合性低容易冲突高可分层叠加维护成本每次重写一次定义持续迭代打个比方prompt 像是你每次点外卖时在备注里写不要香菜、少辣、多加醋skill 像是你给这家店建了个我的口味档案以后下单自动生效。前者是临时的后者是资产。理解了这层区别你就能明白为什么社区里那么多人强调要安装 superpowers——他们真正想要的是把自己的开发习惯沉淀成一套 AI 能读懂、能执行的技能体系。3. superpowers 框架的运转机制拆解3.1 技能是怎么被加载进 AI 的superpowers 的核心机制我理解下来可以概括成一句话用结构化的文件描述技能让 AI 在合适的时机自动读取并遵循。具体来说它通常依赖几个关键要素技能清单文件一个总入口告诉 AI 本项目有哪些技能可用类似目录。单个技能定义每个技能是一个独立文件包含触发条件、执行步骤、注意事项、示例。加载规则定义什么情况下加载哪个技能比如涉及数据库操作时加载 db-skill。在 Claude Code 里这套东西通常通过项目根目录的配置文件比如 CLAUDE.md 或类似的约定文件来承载。Codex CLI 也有自己的配置约定。框架本身不强制你用某种格式但会给出推荐结构。我自己的做法是把技能分成三层——项目层这个项目特有的规范、技术栈层比如 React 或 Python 的通用约定、个人层我自己的编码偏好。加载时按优先级叠加项目层覆盖技术栈层技术栈层覆盖个人层。这样既保证了通用性又不会让某个项目的特殊要求被淹没。3.2 触发条件设计让技能该出现时才出现技能定义里最关键、也最容易写砸的部分是触发条件。写得太宽AI 动不动就加载一堆无关技能上下文被塞满写得太窄该用的时候用不上。我踩过的坑是这样的一开始我把触发条件写成当用户提到测试时加载测试技能。结果有一次我只是随口说了句这个测试环境有点慢它就把整套测试技能加载进来了然后开始给我讲测试最佳实践完全跑偏。后来我改成更精确的条件比如当任务涉及新增或修改测试文件时加载并且加上仅在明确要求编写测试时激活。这样误触发率大幅下降。一个实用的经验是触发条件要基于动作而不是话题。话题太宽泛动作更具体。比如重构函数是动作代码质量是话题前者适合做触发条件。3.3 技能之间的依赖与冲突处理当技能多起来之后冲突是必然的。比如极简风格技能要求函数不超过 20 行性能优化技能又要求把循环展开——这俩放一起就打架。superpowers 框架一般会提供优先级机制但更靠谱的做法是在定义阶段就避免冲突。我的处理原则有三条单一职责一个技能只干一件事不要写全能技能。显式声明依赖如果技能 B 依赖技能 A 的产出就在 B 里写清楚前置条件A 已执行。冲突时人工裁决对于无法自动调和的冲突让 AI 停下来问你而不是自己拍板。提示技能数量不是越多越好。我实测下来一个项目维护 8 到 15 个核心技能是比较舒服的区间超过 20 个之后加载和冲突管理的成本会明显上升。3.4 为什么这套机制对长期项目特别有价值短期脚本用不用技能框架差别不大但项目一旦超过两周价值就显现出来了。因为长期项目里你会反复回到同一类任务加接口、写迁移、补测试、改配置。每次都要重新交代一遍累积的时间成本非常可观。我做过一个粗略统计在一个持续三个月的项目里引入技能框架之前我平均每天要花 15 到 20 分钟在向 AI 解释项目背景上引入之后这个时间降到了 3 到 5 分钟。省下来的时间不算惊天动地但胜在稳定——不用每次都靠临场发挥。4. 在 Claude Code 上落地 superpowers 的完整路径4.1 环境准备先把 Claude Code 本身跑通在谈技能框架之前得先确保 Claude Code 能正常工作。这一步看似基础但新手卡在这里的比例相当高。安装方式根据系统不同有差异。macOS 和 Ubuntu 上通常通过包管理器或官方脚本安装Windows 用户要注意 64 位兼容性问题——社区里反馈过与 64 位版本不兼容的情况遇到这种一般需要检查运行环境或改用 WSL。安装完成后第一件事是验证基础功能# 检查版本确认安装成功 claude --version # 进入项目目录后启动 cd your-project claude启动后如果提示your organization has disabled claude subscription access之类的信息通常是账号权限或订阅状态的问题需要去账号设置里确认。另外有些地区会提示might not be available in your country这属于服务可用性范围问题按官方支持列表确认即可。VS Code 用户可以直接装 Claude Code 的官方插件配置好之后在编辑器里就能调用省去切换终端的麻烦。插件配置的核心是填对可执行文件路径和默认工作目录这两项填错是最常见的装了但用不了原因。4.2 项目级技能目录的组织方式Claude Code 跑通之后就可以开始搭技能体系了。我的目录结构是这样的project-root/ ├── CLAUDE.md # 主入口技能清单和全局规则 ├── .claude/ │ └── skills/ │ ├── coding-style.md # 编码风格技能 │ ├── testing.md # 测试技能 │ ├── db-migration.md # 数据库迁移技能 │ └── api-design.md # 接口设计技能 └── src/CLAUDE.md是总纲内容不需要很长但要把有哪些技能、什么时候用说清楚。我一般会写三段项目概述、技能索引、全局禁忌。技能文件本身我遵循一个固定模板# 技能名称 ## 触发条件 什么情况下加载 ## 执行步骤 1. 2. 3. 分步说明 ## 注意事项 容易出错的地方 ## 示例 一个正例必要时加一个反例这个模板的好处是结构稳定AI 读起来不容易漏项。我试过用自由格式写技能结果 AI 经常只执行了步骤、忽略了注意事项导致同样的坑反复踩。4.3 把编码习惯翻译成技能描述的技巧这一步是很多人觉得难的地方我知道自己的习惯但不知道怎么写成 AI 能懂的描述。我的经验是用如果……就……的句式把隐性习惯显性化。举几个我实际写过的例子如果新增函数就在函数上方写一行注释说明用途不写参数说明。如果修改已有函数签名就同步搜索所有调用点并更新。如果遇到不确定的业务逻辑就停下来问我不要自己假设。注意这些描述都是可判定的——AI 能明确知道做了没有。反面例子是代码要优雅这种AI 没法判定等于没写。还有一个技巧把你 code review 时最常提的意见收集起来每一条都翻译成一个技能条目。这些意见往往就是你最在意的规范比凭空想更靠谱。4.4 验证技能是否真的生效写完技能不代表就生效了。我一般用三个测试来验证正向测试给一个明确触发条件的任务看它是否加载了对应技能。反向测试给一个不该触发的任务看它是否误加载。冲突测试同时给两个可能冲突的任务看它是否停下来询问。如果正向测试失败通常是触发条件写得太隐晦反向测试失败是条件太宽冲突测试失败说明缺少优先级声明。这三种失败我都遇到过逐个调条件就能解决。注意技能生效不是一次性的项目演进过程中要定期回顾。我一般每两周花十分钟过一遍技能文件把过时的删掉、把新踩的坑补进去。5. Codex CLI 上的差异化配置与命令实操5.1 Codex CLI 和 Claude Code 的定位差异虽然两者都是终端里的 AI 编程助手但用下来感觉定位不太一样。Claude Code 更偏向深度协作适合长时间、多轮次的任务Codex CLI 更偏向快速执行适合单点任务和脚本化调用。这个差异直接影响了技能框架的落地方式。在 Claude Code 上我可以写很详细的技能描述因为它有耐心读完在 Codex CLI 上技能描述要更精简否则容易被截断或忽略。我的做法是同一套技能维护两个版本。详细版给 Claude Code精简版给 Codex CLI。精简版只保留触发条件和核心步骤注意事项压缩成一句话。5.2 常用命令的实战用法Codex CLI 的命令体系是日常高频使用的部分几个关键命令值得单独说/compact压缩当前上下文。当对话变长、响应变慢时用它能把历史对话浓缩成摘要释放上下文空间。我一般在完成一个子任务、准备开始下一个时用。/model切换模型。不同任务用不同模型是常见做法比如复杂重构用强模型简单格式化用快模型。/resume恢复之前的会话。这个在中断后继续工作时特别有用不用重新交代背景。删除指令这块社区里常问怎么删除 Codex CLI 指令。实际上命令本身是内置的不能删但你可以通过配置文件禁用某些行为或者用别名覆盖。我一般不改内置命令而是通过技能层去约束行为。5.3 在 Codex CLI 里挂载技能的最小可行方案Codex CLI 没有 Claude Code 那么成熟的技能目录约定但可以用一个变通方案把技能写成项目根目录的说明文件在每次会话开始时用一条命令让它读取。具体操作是在项目根放一个AGENTS.md或类似文件内容就是精简版技能清单。启动会话后第一件事请先读取项目根目录的 AGENTS.md了解本项目的开发规范然后再开始任务。这一句话就能把技能体系注入进去。虽然不如自动加载优雅但胜在简单可靠不依赖特定版本的功能支持。我实测下来这个方案在中小型项目里完全够用。唯一要注意的是每次新会话都要记得说这句话容易忘。我的解决办法是把它写进 shell 别名启动 Codex CLI 时自动带上。5.4 两个工具混用时的技能同步问题我现在的日常是两个工具混用复杂任务用 Claude Code快速任务用 Codex CLI。这就带来一个同步问题——技能更新了两边都得改。我的处理方式是单一数据源技能内容只维护一份放在一个中立目录里然后用脚本生成两个工具各自的格式。脚本很简单就是读源文件、按模板输出。这样改一次两边都更新不会出现Claude Code 知道但 Codex CLI 不知道的情况。如果你不想写脚本退而求其次的做法是把技能源文件放在项目根两个工具都直接读它只是加载方式不同。这样至少内容是一致的。6. 那些文档不会告诉你的踩坑记录6.1 技能写太细反而拖慢响应我一开始犯的错是事无巨细。一个编码风格技能写了 800 多字涵盖了缩进、命名、注释、异常处理、日志格式等十几个方面。结果每次加载这个技能AI 的响应都明显变慢而且经常顾此失彼——记住了缩进忘了命名。后来我把它拆成三个独立技能格式规范、命名规范、错误处理规范。每个 200 字左右按需加载。响应速度回来了执行准确率也上去了。这个教训的核心是技能粒度要匹配任务粒度。一个任务通常只涉及一两个维度没必要把整个规范体系都塞进去。6.2 触发条件里的隐形歧义有个坑我踩了很久才发现。我写过一个技能触发条件是当涉及用户输入时加载。本意是处理表单验证相关的任务。结果有一次我在讨论用户故事user story它把这个技能加载了然后开始给我讲输入校验完全跑偏。问题出在用户输入这个词有歧义。后来我改成当任务涉及表单字段校验或请求参数处理时加载歧义就消除了。这件事让我意识到自然语言写触发条件一定要假设 AI 会从最宽泛的角度理解。宁可写长一点、具体一点也不要留模糊空间。6.3 技能版本管理被忽视的后果技能文件也是代码也需要版本管理。我早期没在意这点结果有一次改了个技能导致之前能跑的任务全挂了想回滚却发现没记录改了什么。现在我强制自己做两件事技能文件纳入 git 管理每次修改在文件头写一行变更说明。看起来麻烦但真出问题时能救命。另外技能和代码的版本要对应。如果项目代码大改比如换了框架旧技能可能就不适用了。我一般在大版本升级时同步审查一遍所有技能。6.4 多人协作时技能冲突的真实案例团队里每个人都有自己的习惯技能文件如果各写各的冲突会很严重。我遇到过最典型的一次A 同事的技能要求所有函数必须写完整类型注解B 同事的技能要求简单函数省略类型注解保持简洁。AI 每次写函数都在两个要求之间反复横跳。解决办法是建立技能评审机制个人技能可以私有但项目级技能必须经过团队确认。我们定了个简单规则——项目级技能文件改动需要至少一人 review避免个人偏好直接污染团队规范。这个机制运行下来效果不错技能文件逐渐变成了团队共识的载体而不是某个人的偏好集合。7. 把 superpowers 变成你自己的东西7.1 从照搬到定制的过渡网上能找到不少现成的技能模板直接拿来用当然可以但用一段时间后你会发现别人的技能解决的是别人的问题。真正好用的技能体系一定是从你自己的痛点里长出来的。我的过渡路径是这样的先照搬一套基础模板跑两周记录下每次它没按我想的做的时刻把这些时刻转化成技能条目。三个月下来我的技能文件里原创内容占了七成以上剩下的三成是通用规范。这个过程没法跳过。你不可能一开始就知道自己需要什么技能只有用起来、撞了墙才知道该补哪块。7.2 判断一个技能该不该保留的标准技能攒多了要清理。我用的判断标准有三条最近一个月触发过吗没触发过的要么删掉要么说明触发条件写错了。触发后真的有用吗有些技能触发了但没产生实际影响属于存在感技能该删。和其他技能重复吗功能重叠的技能要合并否则会互相干扰。按这三条清理一轮我的技能数量从 30 多个精简到了 12 个但实际效果反而更好了。7.3 技能体系的长期演进思路技能体系不是一次搭好就完事的它会随着项目和你自己的成长而演进。我观察到的演进规律是从约束行为逐渐转向沉淀判断。早期技能主要是约束比如必须这样写不能那样做。后期技能更多是判断比如遇到 X 情况时优先考虑 Y 方案因为 Z。后者更难写但价值更高因为它传递的是经验而不是规则。我现在正在做的就是把一些反复出现的决策场景写成判断型技能。比如当接口需要兼容旧版本时优先用适配层而不是改原接口因为改动面更小。这类技能写起来费劲但一旦写好AI 的表现会有质的提升。7.4 一个可复用的技能模板最后分享一个我用了很久的技能模板你可以直接拿去改# [技能名称] 变更记录YYYY-MM-DD 初版 ## 触发条件 当任务涉及 [具体动作] 时加载。 ## 前置检查 - [ ] 确认 [某条件] - [ ] 确认 [某条件] ## 执行步骤 1. [第一步动词开头] 2. [第二步] 3. [第三步] ## 禁止事项 - 不要 [某行为] - 不要 [某行为] ## 示例 输入[某场景] 输出[期望结果]这个模板的关键在于前置检查和禁止事项两块。前者防止 AI 在条件不满足时硬上后者防止它越界。我试过删掉这两块结果技能的执行质量明显下降。技能写完之后别急着大规模用。先在一个小任务上试观察它的实际表现再决定要不要推广。我踩过技能写得很漂亮但实际不好用的坑就是因为跳过了小范围验证这一步。这套东西说到底核心不是工具本身而是你愿不愿意花时间把自己的经验结构化。工具会更新命令会变化但把隐性知识显性化这件事的价值是长期的。我在实际操作中的体会是技能体系搭起来的前两周最痛苦之后就是复利——你投入的每一分钟都会在后续无数次的 AI 协作里被还回来。