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的安装同样走npmnpm install -g openai/codex-cli但这里有个很多人吐槽的点在国内网络环境下npm安装Codex CLI可能会非常慢甚至卡住不动。我的经验是换用国内镜像源或者用pnpm代替npm速度会好很多。如果还是不行可以考虑手动下载release包来安装。注意安装过程中如果遇到权限报错Linux和macOS下需要在命令前加sudoWindows下需要用管理员权限打开终端。另外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代码风格检查变更文件列表通过/不通过问题列表阻断后续流程run-tests运行单元测试项目根目录测试报告阻断回滚impact-analysis分析变更影响范围git diff受影响模块列表仅警告gen-summary生成变更摘要以上所有输出Markdown格式摘要仅警告这个表格看起来简单但实际配置的时候有几个细节需要注意。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-filterACM | 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的典型报错与解决在实际使用中有几个报错出现的频率特别高我整理成了一张速查表报错信息可能原因解决方法organization has disabled claude subscription access组织管理员关闭了Claude Code权限联系管理员开通或改用API key方式认证claude code might not be available in your country地区限制检查官方支持的地区列表或使用第三方API接入与64位版本的Windows不兼容系统版本问题确认系统为64位Win10以上或改用WSLnpm install codex-cli 卡住不动网络问题换国内镜像源或用pnpm代替npm技能触发后无响应配置文件格式错误用JSON validator检查配置文件确认trigger名称匹配测试超时被killtimeout设置过短根据项目实际测试耗时调整timeout值除了这些具体的报错还有一个比较隐蔽的问题技能之间的执行顺序有时候会乱掉。特别是在你同时配置了多个触发条件相似的技能时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显存才能跑得比较流畅。如果你用的是MacM系列芯片的统一内存架构在这方面有优势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正式启用。这个习惯帮我避免了好几次因为配置错误导致的意外文件修改。
