1. 从“superpowers”说起：一个让AI编程助手真正长出“超能力”的框架

第一次看到“superpowers”这个词，是在一个开发者社群里有人贴了一张截图：终端里一个AI编程助手正在自动拆解任务、调用工具、跑测试、改代码，最后还自己写了一份变更说明。底下有人评论说“这玩意儿装上superpowers之后完全变了个样”。我当时的第一反应是——又是一个营销概念吧？但后来自己动手折腾了几轮，才发现这个东西确实有点东西。

superpowers本质上是一个agentic skills framework，翻译过来就是“智能体技能框架”。它不是某个具体的软件，也不是一个可以直接双击安装的App，而是一套软件开发的元方法论——它定义了AI编程助手（比如Claude Code、Codex CLI这类工具）应该如何组织自己的行为、如何调用外部能力、如何在复杂任务中保持上下文连贯。你可以把它理解成给AI助手装了一套“行为准则+工具箱”，让它在写代码这件事上从“能聊几句”变成“能干活”。

为什么这个东西最近突然火起来了？因为Claude Code和Codex CLI这两个工具的普及，让大量开发者第一次真正在日常工作中用上了AI编程助手。但用着用着大家就发现一个问题：默认状态下的AI助手，你问它一句它答一句，让它改个函数它改得挺好，但你要是让它“把这个项目的登录模块重构一下，顺便把测试补上，再更新一下文档”，它就开始犯迷糊了——要么漏掉步骤，要么上下文丢失，要么改着改着就跑偏了。superpowers要解决的就是这个问题：通过一套结构化的技能定义和任务编排机制，让AI助手在面对复杂开发任务时能够像一个有经验的工程师那样有条不紊地推进工作。

这篇文章适合谁看？如果你已经在用Claude Code或Codex CLI，但总觉得“差点意思”，那这篇内容能帮你理解怎么通过superpowers的思路把工具用出真正的生产力。如果你还没开始用这些工具，也没关系，我会在讲superpowers的同时把相关的基础操作一并带过，保证你能跟上。全文会围绕superpowers的核心理念、落地方式、与Claude Code/Codex CLI的配合、实操步骤、常见坑点来展开，尽量做到你看完就能上手试。

2. superpowers到底解决了什么问题：AI编程助手的“能力天花板”在哪里

2.1 默认AI助手的三个致命短板

在深入superpowers之前，有必要先搞清楚一个前提：为什么默认状态下的AI编程助手不够用？我自己的使用体验加上和不少开发者的交流，总结下来主要是三个问题。

第一个是上下文断裂。当你让AI助手处理一个跨多个文件的任务时，它往往只能看到你当前打开的那个文件，或者你手动粘贴给它的那几段代码。一旦任务涉及到十几个文件的联动修改，它就开始“失忆”——改完A文件忘了B文件的接口定义，改完B文件又忘了C文件里还有一处调用需要同步更新。这不是模型能力不够，而是工具层面的上下文管理机制没有跟上。

第二个是任务拆解能力弱。你给它一个模糊的需求，比如“优化一下这个模块的性能”，它可能会直接给你一段优化后的代码，但它不会先去分析瓶颈在哪里、不会先跑一遍profiling、不会考虑修改后对下游的影响。换句话说，它缺少一个“先规划再执行”的思维框架。

第三个是工具调用碎片化。AI助手可以调用终端、可以读写文件、可以跑测试，但这些能力是散落的，没有一个统一的编排层来协调。比如你想让它“改完代码后自动跑测试，测试失败就回滚，测试通过就提交”，默认状态下你得一步步手动指挥，它自己不会把这个流程串起来。

2.2 superpowers的核心思路：把“技能”变成可组合的积木

superpowers的解法很巧妙：它不试图去改模型本身，而是在模型和任务之间加了一层技能抽象层。每一个“技能”（skill）就是一个独立的能力单元，比如“读取文件”、“运行测试”、“分析依赖关系”、“生成变更说明”等等。这些技能可以被单独定义、单独测试、单独复用，然后通过一个编排引擎按照任务需要组合起来。

这个思路其实借鉴了软件工程里“微服务”和“管道模式”的思想。你不再写一个巨大的、什么都干的函数，而是把每个能力拆成小的、职责单一的服务，然后通过编排层把它们串起来。superpowers做的事情就是把这个模式搬到了AI助手的任务执行上。

提示：理解这一点很关键——superpowers不是让AI变聪明了，而是让AI的“工作方式”变得更有序了。模型本身的推理能力没有变化，变化的是它被组织起来解决问题的方式。

2.3 为什么是现在：Claude Code和Codex CLI的成熟让这一切成为可能

superpowers这个概念能落地，离不开两个基础设施的成熟：Claude Code和Codex CLI。这两个工具提供了AI助手与本地开发环境交互的标准接口——读写文件、执行终端命令、调用外部API等等。没有这些接口，superpowers的技能定义就无处施展。

Claude Code是Anthropic推出的终端级AI编程助手，它可以直接在你的项目目录里运行，读取文件、执行命令、修改代码。Codex CLI则是OpenAI阵营的对应工具，功能类似但生态略有不同。两者都支持通过配置文件来扩展行为，这就给superpowers这样的框架留出了接入空间。

我自己的主力工具是Claude Code，所以后面的实操部分会以它为主来展开，但Codex CLI的逻辑是相通的，理解了其中一个，另一个上手就是几分钟的事。

3. 把superpowers跑起来：从环境准备到第一个技能定义

3.1 基础环境搭建：Claude Code和Codex CLI的安装

在折腾superpowers之前，你得先把基础的AI编程助手装好。这一步看起来简单，但实际操作中坑不少，我把自己踩过的和社群里常见的问题都整理一下。

Claude Code的安装，官方推荐的方式是通过npm全局安装。前提是你机器上已经有Node.js环境，建议版本在18以上。安装命令很简洁：

npm install -g @anthropic-ai/claude-code

装完之后在终端输入claude就能启动。第一次启动会引导你完成账号认证，这里有个常见问题：如果你所在的组织禁用了Claude Code的订阅访问，你会看到一条提示说“your organization has disabled claude subscription access for claude code”。遇到这种情况，要么找管理员开通权限，要么考虑通过第三方API的方式接入其他模型。

Codex CLI的安装同样走npm：

npm install -g @openai/codex-cli

但这里有个很多人吐槽的点：在国内网络环境下，npm安装Codex CLI可能会非常慢，甚至卡住不动。我的经验是换用国内镜像源，或者用pnpm代替npm，速度会好很多。如果还是不行，可以考虑手动下载release包来安装。

注意：安装过程中如果遇到权限报错，Linux和macOS下需要在命令前加sudo，Windows下需要用管理员权限打开终端。另外，Windows用户要注意Claude Code目前对32位系统不兼容，必须是64位Windows 10以上。

3.2 让Claude Code用上本地模型或其他模型

这是很多人关心的问题：Claude Code能不能不登录官方账号，直接用本地模型或者其他第三方模型？答案是——可以，但需要一些配置。

核心思路是通过环境变量或者配置文件，把Claude Code的API端点指向你自己的模型服务。比如你在本地用LM Studio跑了一个模型，它默认会在http://localhost:1234提供一个兼容OpenAI格式的API。你可以在Claude Code的配置里把base URL改过去，然后把API key设成任意值（本地模型通常不校验key）。

具体操作上，Claude Code支持通过~/.claude/config.json或者环境变量来覆盖默认配置。你需要设置的主要是三项：ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY、以及模型名称。如果你用的是DeepSeek、Qwen、GLM这些国内模型，它们大多也提供了兼容OpenAI的API接口，配置逻辑是一样的。

这里有一个实操心得：不是所有模型都能很好地支持Claude Code的工具调用协议。Claude Code依赖模型具备function calling能力，如果模型本身不支持或者支持得不好，你会看到它无法正确调用终端命令或读写文件。我试过几个本地模型，目前表现比较稳定的是Qwen系列的中等规模版本，太小的模型（7B以下）基本没法用，太大的模型（70B以上）对硬件要求又太高。折中下来，14B到32B这个区间的模型是比较务实的选择。

3.3 superpowers的接入方式：配置文件与技能注册

superpowers本身不是一个需要“安装”的软件包，它更像是一套约定和配置的集合。你需要在Claude Code或Codex CLI的配置目录下创建一个skills定义文件，通常是一个JSON或YAML格式的文件，里面描述了你希望AI助手具备哪些技能、每个技能的触发条件是什么、执行逻辑是什么。

一个最简单的技能定义大概长这样：

{ "skills": [ { "name": "run-tests", "description": "在代码修改后自动运行项目测试套件", "trigger": "after-code-change", "command": "npm test", "on_failure": "rollback" }, { "name": "update-docs", "description": "根据代码变更自动更新相关文档", "trigger": "after-tests-pass", "command": "npm run docs:generate" } ] }

这个配置的意思是：每当AI助手修改了代码，就自动触发run-tests技能跑测试；如果测试通过，再触发update-docs技能更新文档；如果测试失败，则执行回滚操作。这就是superpowers的基本工作方式——用声明式的配置来编排AI助手的行为序列。

提示：技能定义的粒度很关键。太粗了不够灵活，太细了配置起来又很繁琐。我的经验是按“一个完整的操作单元”来划分，比如“跑测试”是一个技能，“提交代码”是一个技能，但“读取文件”这种太底层的操作就不需要单独定义，因为AI助手本身就能做。

4. 实操：用superpowers思路搭建一个自动化代码审查流程

4.1 场景定义与任务拆解

光讲概念没意思，我们直接来一个完整的实操案例。假设你是一个团队的技术负责人，你希望AI助手能够在每次代码提交前自动完成以下工作：检查代码风格是否符合规范、运行单元测试、分析变更影响范围、生成变更摘要。这四件事如果手动做，每次至少花十几分钟，用superpowers的思路可以把它变成一个自动化的流水线。

首先要把这个任务拆解成独立的技能单元。按照superpowers的框架，每个技能应该满足三个条件：职责单一、输入输出明确、可以独立验证。拆解结果如下：

这个表格看起来简单，但实际配置的时候有几个细节需要注意。lint-check的失败处理设为“阻断后续流程”是因为代码风格问题必须在测试之前解决，否则测试跑出来的结果可能被风格问题干扰。impact-analysis设为“仅警告”是因为影响范围分析本身有一定的不确定性，不应该因为它阻断了整个流程。

4.2 技能配置文件的编写与调试

接下来把这些技能写成superpowers能识别的配置文件。我以Claude Code为例，配置文件放在项目根目录的.claude/skills.json下：

{ "version": "1.0", "skills": [ { "name": "lint-check", "description": "对变更文件执行ESLint检查", "trigger": "pre-commit", "command": "npx eslint $(git diff --cached --name-only --diff-filter=ACM | grep -E '\\.(js|ts|jsx|tsx)$')", "on_failure": "block", "timeout": 60 }, { "name": "run-tests", "description": "运行项目单元测试", "trigger": "after:lint-check", "command": "npm test -- --passWithNoTests", "on_failure": "rollback", "timeout": 300 }, { "name": "impact-analysis", "description": "分析本次变更影响的模块范围", "trigger": "after:run-tests", "command": "npx madge --changed --warning", "on_failure": "warn", "timeout": 120 }, { "name": "gen-summary", "description": "生成变更摘要文档", "trigger": "after:impact-analysis", "command": "node scripts/gen-summary.js", "on_failure": "warn", "timeout": 30 } ] }

写这个配置文件的时候有几个坑我踩过。第一个是trigger的写法，after:lint-check这种链式触发需要确保前一个技能的名称完全匹配，大小写和连字符都不能错。第二个是timeout的设置，测试类的技能超时时间要给足，我一开始设了120秒，结果在一个大项目上跑测试跑了3分钟还没完，直接被kill了。后来改成300秒才稳定。第三个是命令中的shell变量展开，$(git diff ...)这种写法在Claude Code的执行环境里是支持的，但如果你用的是Codex CLI，可能需要改成先执行一个脚本文件的方式。

4.3 运行效果与调优记录

配置好之后，实际跑一遍看看效果。我在一个中等规模的TypeScript项目上测试了这个流程，项目大概有200多个源文件，测试用例300多个。第一次跑的时候，lint-check花了8秒，run-tests花了95秒，impact-analysis花了22秒，gen-summary花了3秒，整个流程大概2分钟出头。对于一个提交前的自动化检查来说，这个时间是可以接受的。

但第一次跑也暴露了几个问题。一个是impact-analysis用的madge工具在分析循环依赖时会报一堆warning，导致输出信息很乱。后来我加了一个过滤脚本，只保留和本次变更直接相关的模块。另一个是gen-summary生成的摘要格式不太理想，它把所有信息都堆在一起了，后来我改了一下脚本，按“变更文件-测试结果-影响范围”三个板块来组织输出，可读性好了很多。

调优之后又跑了五六次，整体稳定性不错。唯一需要注意的是，如果你的项目测试套件里有集成测试或者端到端测试，最好把它们排除在这个流程之外，因为那些测试跑起来太慢了，放在提交前检查里会严重拖慢开发节奏。我的做法是在npm test后面加--testPathIgnorePatterns参数，把e2e目录排除掉。

5. 常见问题与排查技巧实录

5.1 Claude Code和Codex CLI的典型报错与解决

在实际使用中，有几个报错出现的频率特别高，我整理成了一张速查表：

除了这些具体的报错，还有一个比较隐蔽的问题：技能之间的执行顺序有时候会乱掉。特别是在你同时配置了多个触发条件相似的技能时，Claude Code可能会按照不确定的顺序执行它们。我的解决办法是尽量用显式的链式触发（after:xxx）来定义顺序，而不是依赖默认的触发时机。

5.2 模型选择与性能调优的经验

如果你用的是第三方模型或者本地模型来驱动Claude Code，模型的选择直接决定了superpowers能不能跑起来。我试过的组合里，表现最好的是Claude官方的Sonnet系列，工具调用准确率最高，但成本也最高。国内模型中，DeepSeek V3和Qwen Max在function calling上的表现比较稳定，GLM-4也还可以，但偶尔会出现调用格式错误。

本地模型方面，我用LM Studio跑过Qwen2.5-14B和Qwen2.5-32B。14B的版本在简单任务上能用，但一旦技能链超过三个步骤，它就开始丢失上下文。32B的版本明显好很多，但需要至少24GB显存才能跑得比较流畅。如果你用的是Mac，M系列芯片的统一内存架构在这方面有优势，32GB内存的MacBook Pro跑32B模型是可行的。

提示：不管用什么模型，都建议在正式使用前先用一个简单的技能链测试一下。比如定义一个“读取文件-修改文件-写回文件”的三步技能，看看模型能不能完整走完。如果这个都跑不通，后面的复杂流程就不用试了。

5.3 技能定义的粒度控制与维护策略

superpowers用久了之后，技能配置文件会越来越长。我一开始什么都想定义成技能，结果配置文件膨胀到几百行，维护起来非常痛苦。后来总结了一个原则：只有需要被复用的、或者需要被自动触发的操作才定义成技能。一次性的操作直接在对话里让AI助手做就行了，没必要写成配置。

另外，技能定义最好和项目代码一起做版本管理。我见过有人把技能配置放在全局目录下，结果换个项目就冲突了。正确的做法是在每个项目的根目录下放一份独立的技能配置，这样不同项目可以有完全不同的技能组合，互不干扰。

还有一个维护上的小技巧：给每个技能加一个version字段。当你修改了某个技能的执行逻辑时，把版本号加一。这样在排查问题时可以快速确认当前跑的是哪个版本的技能定义，避免“改了配置但没生效”这种低级问题。

6. 从工具到方法论：superpowers给开发流程带来的真正改变

6.1 不只是自动化：重新思考人与AI的分工边界

用superpowers搭了几套流程之后，我最大的感受不是“效率提升了多少”，而是我对AI助手的能力边界有了更清晰的认识。以前我总觉得AI要么什么都能干，要么什么都干不好，但实际用下来发现，它在“有明确规则和明确输入输出的任务”上表现非常好，在“需要模糊判断和创造性决策的任务”上还是得人来把关。

superpowers的价值就在于它帮你把这两类任务分开了。你把那些规则明确、步骤固定的工作定义成技能，交给AI自动执行；把那些需要判断和决策的部分留给自己。这种分工方式比“让AI全自动”或者“完全手动”都要高效。

6.2 团队协作场景下的superpowers实践

在团队里推广superpowers的时候，有一个经验值得分享：不要一上来就搞大而全的技能库。我一开始兴致勃勃地定义了二十多个技能，结果团队成员根本记不住哪个技能是干什么的，用了几次就放弃了。后来我改成从三个最基础的技能开始——代码格式化、单元测试、变更摘要——让大家先用起来，等习惯了再逐步增加。

另外，技能定义最好由团队里对AI工具最熟悉的那个人来维护，其他人只管用。如果每个人都去改配置文件，很容易出现冲突和混乱。我们现在的做法是技能配置放在一个独立的repo里，通过CI流程同步到各个项目，这样既能统一管理，又不会影响各项目的独立性。

6.3 后续可以扩展的方向

superpowers这套框架目前还在快速演进中，我观察到几个比较有潜力的扩展方向。一个是技能的市场化共享——就像npm包一样，开发者可以把自己写的技能发布出来，其他人直接引用。另一个是技能的自适应触发——不再依赖固定的触发条件，而是让AI根据当前上下文自动判断该调用哪个技能。还有一个是跨工具的技能复用——同一套技能定义既能在Claude Code里跑，也能在Codex CLI里跑，甚至能在其他AI编程工具里跑。

我自己最近在尝试的一个方向是把superpowers和代码审查流程结合得更深一些。不只是跑lint和测试，而是让AI助手在审查代码时能够参考历史提交记录、关联的issue、以及团队内部的编码规范文档，给出更有针对性的审查意见。这个方向目前还在实验阶段，等跑通了再单独写一篇来分享。

最后分享一个我在配置技能时的小技巧：给每个技能加一个dry_run模式。在正式启用之前，先用dry_run跑一遍，看看AI助手会怎么执行、会输出什么结果。确认没问题了再关掉dry_run正式启用。这个习惯帮我避免了好几次因为配置错误导致的意外文件修改。