1. 从superpowers这个词说起它到底指什么第一次看到superpowers这个词很多人会以为是某个超级英雄题材的游戏或者影视项目。但在当前的技术语境下它指的是一套围绕 AI 编程助手构建的智能体技能框架agentic skills framework。简单说它做的事情是把一套结构化的软件开发方法论注入到 Claude Code、Codex CLI 这类命令行 AI 编程工具里让它们不再只是你问一句它答一句的聊天机器人而是能按照固定流程、带着明确角色分工去完成开发任务的虚拟团队。我最初接触这个概念的时候心里是犯嘀咕的。因为市面上号称提升 AI 编程效率的东西太多了大多数本质上就是几段提示词模板换个壳子就出来卖。但 superpowers 不太一样的地方在于它强调的是一套可复用的技能skills体系而不是零散的提示词。每个 skill 对应一种具体的开发能力——比如需求拆解、代码审查、测试编写、重构规划——并且这些 skill 可以被组合、被调用、被复用。这就引出了一个核心问题为什么我们需要这样一套框架答案其实很朴素。你直接跟 Claude Code 说帮我写个登录功能它确实能写出来但写出来的东西质量参差不齐因为它没有固定的工作流。它不知道你的项目规范、不知道你团队的代码风格、不知道你希望先写测试还是先写实现。superpowers 要解决的就是把这个不确定性降下来用一套方法论把 AI 的行为约束在可控范围内。适合读这篇内容的人我大致分三类第一类是用过 Claude Code 或 Codex CLI但觉得输出质量不稳定、想找一套系统方法的人第二类是刚接触 agentic 编程工具想搞清楚技能框架到底是怎么回事的新手第三类是在团队里推动 AI 辅助开发需要一套可落地、可复制的流程的工程师。不管你是哪一类接下来的内容都会从概念到实操把 superpowers 这套东西拆开讲清楚。需要提前说明的是superpowers 本身不是一个独立的软件它更像是一套方法论 技能定义的集合需要依附在 Claude Code、Codex CLI 这类宿主工具上运行。所以理解它的前提是先理解这些宿主工具是怎么工作的。2. 宿主工具先搞明白Claude Code 与 Codex CLI 的定位差异在深入 superpowers 之前有必要先把它的两个主要宿主工具讲清楚。因为很多人卡在第一步——工具都没装明白谈技能框架就是空中楼阁。2.1 Claude Code 是什么它和普通 IDE 插件有什么不同Claude Code 是 Anthropic 推出的命令行 AI 编程工具。它和 VS Code 里那种侧边栏聊天的插件有本质区别Claude Code 运行在终端里能直接读写你本地的文件、执行终端命令、跑测试、看 git 状态。换句话说它是一个有手有脚的智能体而不只是一个会说话的对话框。这个区别非常关键。普通插件你问它这个 bug 怎么修它给你一段建议代码你还得自己复制粘贴。Claude Code 你问同样的问题它会自己去读相关文件、定位问题、改代码、跑测试验证然后把结果告诉你。这种能动手的能力正是 superpowers 这类技能框架能发挥作用的基础——因为技能框架本质上是在指挥一个能干活的人而不是在给一个只会说话的人提建议。安装 Claude Code 的常见方式是通过 npm 全局安装命令大致是npm install -g anthropic-ai/claude-code装完之后在项目目录下运行claude就能进入交互界面。这里有个新手常踩的坑一定要在项目根目录下启动而不是随便找个文件夹。因为 Claude Code 会以当前目录为工作区来理解你的项目结构如果你在错误的目录启动它读到的上下文就是错的后面所有的技能调用都会跑偏。另外关于登录和账号网上经常能看到某地区不可用之类的提示。这个属于账号和地区策略问题我这里不展开只提醒一点如果你在配置过程中遇到账号相关的报错优先去官方文档确认当前的账号要求不要轻信网上那些来路不明的绕过方案那些东西既不安全也不稳定。2.2 Codex CLI 的安装与常用命令速查Codex CLI 是另一条技术路线上的命令行编程助手。它的定位和 Claude Code 类似都是终端里的 AI 编程智能体但在具体实现和命令体系上有自己的特点。安装 Codex CLI 通常也是走包管理器装完之后你会用到几个高频命令。我把最常用的几个整理成表格方便对照命令作用使用场景/compact压缩当前对话上下文对话太长、token 快满时使用/model切换当前使用的模型需要在不同能力的模型间切换时/resume恢复之前的会话中断后想接着上次的进度继续这几个命令看起来简单但用得好不好差别很大。比如/compact很多人不知道它的价值。AI 编程工具都有一个上下文窗口限制对话越长早期的重要信息就越容易被挤出去。当你发现 AI 开始忘记前面说过的项目规范时与其重新解释一遍不如主动用/compact把上下文压缩一下保留关键信息、丢弃冗余内容。这个操作在长时间开发任务里几乎是必备的。至于删除 Codex CLI 的指令一般就是对应的包管理器卸载命令比如 npm 装的用npm uninstall -g加包名。这里不展开具体包名因为不同版本可能不一样建议以你安装时用的包名为准。2.3 在 VS Code 里接入命令行工具的正确姿势很多人习惯在 VS Code 里工作所以会问能不能在 VS Code 里直接用 Claude Code 或 Codex CLI答案是能但要理解它的工作方式。最直接的方式是打开 VS Code 的集成终端在里面运行命令行工具。这样你既能享受 VS Code 的编辑器体验又能用上命令行智能体的能力。VS Code 的集成终端本质上就是一个真实的终端所以命令行工具在里面跑和在系统终端里跑没有区别。还有一种方式是通过 VS Code 的插件市场找对应的官方插件。但这里要提醒一句插件和命令行工具是两套东西插件通常是图形化封装功能上可能比命令行版本少一些。如果你追求完整能力命令行版本仍然是首选。配置插件的时候重点看它连接的是哪个模型、走的是哪个 API 端点这些配置项决定了它能不能正常工作。提示无论用哪种方式接入都要确保你的工作目录是项目根目录。这是后面所有技能框架能正常工作的前提。3. superpowers 的核心技能skills体系是怎么组织的把宿主工具搞明白之后就可以进入正题了。superpowers 最核心的概念就是技能理解技能体系是理解整套框架的钥匙。3.1 一个 skill 到底包含哪些东西很多人以为 skill 就是一段提示词其实不是。一个完整的 skill 通常包含几个部分触发条件什么时候该用这个技能、角色设定用这个技能时 AI 扮演什么角色、工作流程分几步做、每步做什么、输出规范产出物长什么样、检查清单做完之后怎么验证。举个例子一个代码审查技能它的触发条件可能是当用户提交了一段新代码或要求审查某个文件时角色设定是你是一名有十年经验的资深工程师注重可读性和边界情况工作流程可能是先通读代码理解意图再逐段检查逻辑最后按严重程度列出问题输出规范是按阻塞、建议、可选三级分类检查清单是是否覆盖了空值、并发、错误处理等常见风险点。你看这样一套东西下来AI 的行为就被约束得非常具体了。它不再是随便给点建议而是按照一个资深工程师的思维路径去工作。这就是技能框架相比裸提示词的核心优势——结构化和可复用。3.2 技能之间如何组合与调用单个技能已经很有用了但 superpowers 真正的威力在于技能的组合。一个完整的开发任务往往需要多个技能接力完成。我拿一个真实场景来说明。假设你要给现有项目加一个用户导出数据的功能。用 superpowers 的思路整个流程可能是这样的需求拆解技能先把导出数据这个模糊需求拆成具体的功能点——导出哪些字段、什么格式、要不要权限控制、大数据量怎么处理。方案设计技能基于拆解结果设计技术方案——用流式导出还是全量加载、文件格式选 CSV 还是 Excel、接口怎么设计。测试先行技能先写测试用例覆盖正常流程和边界情况。实现技能按方案写代码边写边跑测试。代码审查技能实现完成后用审查技能过一遍找问题。文档技能最后补上接口文档和使用说明。这六个技能串起来就是一个完整的开发工作流。每个技能各司其职输出交给下一个技能作为输入。这种流水线式的组织方式让 AI 的工作变得可预测、可检查。3.3 为什么方法论比提示词更重要这里我想多说一句关于方法论的思考。市面上大量所谓的AI 编程技巧本质上是提示词的堆砌——你要这样问你要加这句话。这些技巧短期有效但不可持续因为模型在变、工具在变今天好用的提示词明天可能就失效了。而 superpowers 走的是另一条路它沉淀的是软件开发方法论。需求怎么拆、测试怎么写、代码怎么审这些是几十年软件工程积累下来的东西不会因为模型换代就失效。技能框架只是把这些方法论翻译成 AI 能执行的格式。所以哪怕将来换了模型、换了工具这套方法论依然成立你只需要重新做一次翻译。这也是我为什么觉得 superpowers 值得认真研究的原因。它不是在教你怎么问 AI而是在教你怎么用 AI 做工程。这两者的层次完全不一样。4. 把 superpowers 引入你的工作流从零到跑通概念讲完了接下来是实操。这一部分我会尽量给出可复现的步骤同时说明每一步为什么这么做。4.1 引入前的环境准备清单在引入任何技能框架之前先把基础环境理清楚。我列一个清单你可以对照检查宿主工具已安装并能正常运行Claude Code 或 Codex CLI 至少有一个能跑起来能正常读写文件、执行命令。项目目录结构清晰技能框架需要理解你的项目如果目录一团乱麻AI 也很难工作。至少保证源码、测试、配置分开放。版本控制已就位git 一定要用起来。因为 AI 会改你的代码有 git 你才能随时回滚。这是保命的。基础规范文档存在哪怕只是一个简单的 README写清楚项目是干什么的、用什么技术栈、代码风格是什么。这些会成为技能框架的重要上下文。这四点里我认为版本控制是最容易被忽视但最重要的。我见过有人直接让 AI 在没提交的工作区里大改代码结果改崩了想回滚都回不去。养成让 AI 动手前先 commit的习惯能省掉无数麻烦。4.2 技能文件的组织方式与目录约定技能框架要能被宿主工具识别通常需要放在约定的目录下。常见的做法是在项目根目录建一个专门的文件夹比如.skills/或者skills/把每个技能写成一个独立的文件Markdown 或 YAML 格式都有。目录结构大致长这样项目根目录/ ├── .skills/ │ ├── requirement-breakdown.md │ ├── code-review.md │ ├── test-first.md │ └── ... ├── src/ ├── tests/ └── README.md每个技能文件里按前面说的结构写清楚触发条件、角色、流程、输出规范、检查清单。文件名要见名知意因为宿主工具在调用技能时往往是通过文件名或文件内的标识来匹配的。这里有个实操心得技能不要写得太长。我一开始恨不得把每个技能写成一篇论文结果发现 AI 在执行时反而抓不住重点。后来我把每个技能控制在几百字以内只保留最关键的流程和约束效果反而更好。技能是操作手册不是百科全书。4.3 让宿主工具识别并调用技能技能文件写好了怎么让 Claude Code 或 Codex CLI 用起来通常有两种方式。第一种是显式调用你在对话里直接说用代码审查技能看一下这个文件宿主工具会去技能目录里找对应的技能并加载。这种方式适合你想精确控制用哪个技能的场景。第二种是隐式触发技能文件里定义了触发条件宿主工具根据当前任务自动匹配。比如你贴了一段代码说帮我看看有没有问题它可能自动触发代码审查技能。这种方式更省心但对技能定义的准确性要求更高。实际使用中我建议前期用显式调用后期再逐步过渡到隐式触发。因为前期你对技能的效果还没把握显式调用能让你清楚地看到这个技能到底做了什么。等某个技能你用得顺手了、验证过效果了再让它自动触发。注意不同宿主工具对技能的识别机制不完全一样。Claude Code 和 Codex CLI 在加载技能的方式上可能有差异具体以你所用工具的文档为准。如果技能没被识别先检查目录位置和文件格式是否符合要求。4.4 跑通第一个技能以代码审查为例理论说再多不如跑一遍。我拿代码审查这个技能作为第一个跑通的对象因为它最容易看到效果。先写一个简单的技能文件内容大致是当用户要求审查代码时你扮演资深工程师按逻辑正确性、边界情况、可读性、性能、安全五个维度逐项检查输出时按阻塞问题、改进建议、可选优化三级分类每条问题要指出具体行号和修改建议。写完之后找一段你项目里真实的代码让宿主工具用这个技能审查。你会看到它的输出和平时随便问问完全不一样——它会系统性地过一遍五个维度而不是想到哪说到哪。跑通之后你可以对比一下用技能审查和不用技能审查输出的质量差多少。我自己的体验是用了结构化技能之后AI 找出的问题数量大概能翻一倍而且分类清晰直接就能拿去改。这个对比会让你对技能框架的价值有直观感受。5. 实战中绕不开的那些坑任何工具在实际用起来之后都会暴露出一堆文档里不会写的问题。这一部分我把自己踩过的、以及社区里高频出现的坑整理出来希望能帮你少走弯路。5.1 上下文丢失AI 为什么忘了前面说的话这是最高频的问题。你明明在前面告诉过 AI 项目用什么框架、代码风格是什么聊到一半它突然开始用另一套风格写代码。原因就是上下文窗口被占满了早期的信息被挤出去了。解决办法有几个层次。最基础的是主动使用/compact这类压缩命令把上下文精简一下。进阶一点的做法是把项目规范写进技能文件或专门的上下文文件里这样每次调用技能时都会重新加载不依赖对话历史。最彻底的做法是把长任务拆成多个短会话每个会话聚焦一个子任务做完就结束不拖泥带水。我个人的习惯是单个会话不超过一个完整的功能点。做完一个功能就开新会话把上一个会话的产出代码、文档作为新会话的输入。这样上下文永远是干净的AI 的表现也最稳定。5.2 技能冲突多个技能同时触发怎么办当你积累了一定数量的技能后可能会遇到多个技能同时被触发的情况。比如你让 AI重构这段代码并加测试重构技能和测试技能可能都想接管。处理原则是明确优先级。在技能定义里可以标注优先级或者在调用时显式指定先做 A 再做 B。更简单的办法是把复合任务拆开一次只让一个技能工作。虽然多几步操作但结果更可控。我踩过的一个坑是两个技能对同一个文件的输出格式要求不一样结果 AI 在两者之间反复横跳输出了一堆自相矛盾的内容。后来我学乖了同一时间只激活一个技能需要多个技能就串行执行一个做完再做下一个。5.3 输出质量不稳定问题往往出在技能定义上有时候你会发现同一个技能这次用效果好下次用效果差。排除模型本身的波动大概率是技能定义有问题。常见的定义问题有三类。一是流程太模糊比如只写仔细检查代码没写具体检查什么AI 就只能自由发挥。二是约束太死把每一步都规定得死死的AI 遇到稍微不同的情况就不知道怎么处理。三是缺少示例纯文字描述流程不如给一两个输入输出的例子来得直观。我的经验是技能定义要在框架和留白之间找平衡。关键的流程步骤和输出格式要写死具体的实现细节留给 AI 判断。同时每个技能最好配一两个示例让 AI 知道好的输出长什么样。5.4 本地模型接入什么时候值得折腾有些朋友出于成本或隐私考虑想用本地模型跑 Claude Code 或 Codex CLI。这个方向是可行的但要看场景。本地模型的优势是数据不出本地、没有调用费用。劣势是能力通常比云端大模型弱一截尤其是在复杂推理和长上下文处理上。所以我的建议是简单任务、重复性任务可以用本地模型复杂的设计和审查任务还是用能力更强的模型。接入本地模型通常需要配置 API 端点把宿主工具指向本地服务。配置的时候重点确认三件事端点地址对不对、模型名称匹配不匹配、上下文长度够不够。这三样任何一个不对都会导致工具报错或者表现异常。6. 把技能框架用出复利一些进阶思路跑通基础流程之后如果你想让这套东西产生更大的价值可以往几个方向深挖。6.1 沉淀团队规范为可复用技能个人用技能框架收益是线性的团队用技能框架收益是指数的。因为团队可以把代码规范、审查标准、发布流程这些沉淀成技能让每个成员调用的 AI 都遵循同一套标准。比如你们团队规定所有接口必须有参数校验和错误码那就写一个接口开发技能把这条规定固化进去。以后任何人用这个技能开发接口AI 都会自动加上校验和错误码。久而久之团队的代码质量下限就被抬高了。这件事的价值在于它把隐性知识变成了显性资产。以前这些规范靠口口相传新人来了要很久才能摸清楚现在写进技能里AI 会替你把规范执行到位。6.2 用技能串联起完整的开发闭环单个技能解决单点问题技能串联解决流程问题。你可以设计一条从需求到上线的完整技能链需求拆解 → 方案设计 → 测试编写 → 代码实现 → 代码审查 → 文档生成 → 发布检查。这条链跑通之后一个功能从想法到可提交中间的大部分环节都有 AI 参与而且每个环节都有明确的质量标准。人的角色从写代码变成定标准、做决策、把方向。当然这条链不是一天建成的。我的建议是从最痛的那个环节开始。哪个环节你最耗时、最容易出错就先给那个环节做技能。跑顺了再往前后延伸逐步把链条补全。6.3 技能库的维护与迭代节奏技能库不是写完就一劳永逸的。项目在变、团队在变、模型也在变技能需要定期回顾和更新。我给自己定的节奏是每完成一个较大的功能就回顾一次相关技能。看看这次用下来技能定义有没有需要补充的、有没有过时的约束、有没有可以简化的地方。这个回顾不用很正式花十分钟改改技能文件就行。另外技能库要保持精简。我见过有人攒了几十个技能结果自己都记不清哪个是哪个用的时候反而挑花眼。技能不在多在于每个都真正有用、真正被用起来。定期清理那些长期不用的技能让技能库保持高信噪比。7. 我个人的一些使用体会聊了这么多技术和流程最后说点更个人化的东西。我用这套技能框架有一段时间了最大的感受是它改变的不是我写代码的速度而是我思考问题的方式。以前我拿到一个需求脑子里是一团乱麻边写边想。现在我会先想这个任务该用哪几个技能、按什么顺序把问题结构化之后再动手。这个先想清楚再动手的习惯其实是技能框架倒逼出来的。另一个体会是不要指望技能框架能替代思考。它能把 AI 的行为约束得更规范但做什么、为什么做这些判断还是得人来定。技能框架是放大器它放大的是你已有的工程能力如果你本身对工程没有清晰的认识它放大出来的可能是一堆规范但无用的产出。还有一点别追求一步到位。我一开始想搭一套完美的技能体系结果卡在设计阶段迟迟不动手。后来我换了个思路先写一个最粗糙的技能跑起来用起来之后再迭代。事实证明这个思路对得多——技能是在使用中长出来的不是在设计里想出来的。如果你现在正准备开始我的建议就一句话挑一个你每天都在做的重复性任务给它写一个技能然后连续用一周。一周之后你自然就知道这套东西适不适合你、该怎么往下走了。
