最近一个月我基本把写代码的重活都交给了 AI 编程助手但在一次改老项目的时候翻了大车改一个工具函数AI 一口气动了七八个文件把两个原本正常的模块也顺手“优化”掉了最后git diff一看几百行改动里有一半是无辜的。后来我才意识到问题不在模型智商而在工作方法——AI 缺的不是聪明是章法。也就是在那段时间我接触到了superpowers这个技能包。它是一套专门给 AI 编程助手用的skills技能集装进 Claude Code、Codex CLI、Trae、WorkBuddy 这类工具之后AI 会按“先想清楚、再定计划、分步执行、随时检查、事后复盘”的流程干活。原先那种“问一句就埋头写几百行”的失控感一下就好多了。这篇文章我把从安装到使用的完整过程都记录下来给正在折腾 AI 编程工具、又被模型“自由发挥”折磨过的朋友一个可以直接抄作业的参考。1. superpowers 到底是什么为什么它能让 AI 编程不翻车1.1 模型够聪明但缺一套工程方法现在的代码大模型单看能力真的不差你让它写个排序、封装个请求库、补一段单元测试它都能给你有模有样的答案。可一旦把任务放大到“给一个完整功能做实现”问题就全冒出来了要么一口气改太多文件要么跳过测试直接写业务代码要么修完 A bug 把 B 模块踩坏。这背后其实是工程方法缺失。真实团队里写代码从来不是“想到哪写到哪”而是有需求评审、方案设计、任务拆解、编码规范、测试回归、代码评审这一整套流程。但你在对话框里问 AI 时它默认走的是一条最短路径理解你的话直接生成代码。你让它“改一下登录逻辑”它就可能把整个认证模块重写一遍。superpowers 的出发点就是把这个“工程方法缺失”补上。它把一套可执行的软件开发方法论做成了 AI 能主动调用的技能文件。工具检测到当前任务进入了某个阶段就会自动加载对应的技能引导模型按照固定流程走。说白了它给 AI 装上了一套“工作操作系统”。另一个关键点是它解决了上下文失控的问题。长任务里 AI 做着做着就忘了最初的目标superpowers 通过计划文件、进度检查、质量门禁这些机制让 AI 不管跑多远都能回到主线。我自己用下来的感受是装与不装AI 干活的差别就像“自由发挥的实习生”和“按规范执行的工程师”那么大。1.2 技能清单superpowers 内置了哪些能力superpowers 不是一个单一技能而是一组技能的集合。它对标的是真实研发团队里的各个角色动作我把核心技能整理成了下面的表格技能名称触发场景它做了什么brainstorming需求还没有完全明确时和用户来回讨论把目标、约束、痛点问清楚plan需求已经清晰要动工之前产出分步计划按优先级排列任务列出风险点execute计划确定后按计划逐步实现每完成一步都汇报进度test-driven development需要写新功能逻辑时先写失败测试再用最小代码让测试通过debugging测试报错或行为异常时定位根因先写回归测试再做修复quality gates每个阶段结束准备进入下一阶段时检查变更日志、linter、测试套件不达标就不放行retrograde一个任务整体完成后复盘哪里做得好、哪里浪费了时间沉淀经验file operations需要批量读写、移动、重命名文件时用受控的方式操作文件先列计划再执行terminal use需要运行命令、跑测试、装依赖时安全地执行终端命令并解读输出这些技能不是靠模型“想起来才用”而是通过SKILL.md文件里的触发规则自动关联。比如 AI 发现自己准备直接动手写代码而项目里还没有对应测试它就可能主动加载 TDD 技能先把失败测试写出来。这个设计逻辑我觉得很巧妙它没有强迫模型用一套固定话术而是把工程动作拆成独立模块需要哪个上哪个。所以你不需要学一套新的“提示词魔法”只要把技能集装好AI 会在合适的时机自己调用。2. 安装前先想清楚工具选型和环境准备2.1 基础环境准备在装 superpowers 之前有几个基础环境需要先确认。虽然不同 AI 编程工具要求略有差异但底层基本都跑在 Node.js 生态里所以第一步先把 Node.js 装好建议直接上 LTS 版本太老的版本会导致技能脚本跑不起来。然后是 Git。superpowers 的官方仓库在 GitHub 上日常更新很快用git clone拉代码是最省事的方式。如果你本机还装过 pnpm、Volta 这类工具那更好部分技能脚本里会调用这些命令提前把常用命令的环境变量配好后面能少踩很多坑。再一个容易被忽略的是操作系统的权限问题。技能文件通常要写到用户目录下的隐藏文件夹比如~/.claude/skills或~/.codex/skills。macOS 和 Linux 下如果目录权限不对工具会静默忽略技能你根本不知道哪里出了问题。建议安装前跑一遍echo $HOME确认当前用户有对用户目录的写权限。还有个小建议先做一次备份把你原来的~/.claude或~/.codex目录压缩一份放旁边。这个动作不花几分钟但万一装到一半把原有配置搞乱了可以马上回滚。这个习惯我踩了几次坑之后养成了确实省事。2.2 常用 AI 编程工具怎么选现在支持 skills 机制的 AI 编程工具有好几款不是每一款的装载方式都一样。我把体验过的几款工具放在一起对比工具skills 支持程度安装目录特点适合谁Claude Code原生支持首批适配~/.claude/skills/想完整体验技能流的人Codex CLIAgent 模式支持~/.codex/skills/或项目.codex/skills/习惯命令行和轻量操作的人Trae支持 skill配置路径不同各版本差异大需要在界面/文档确认偏好 IDE 图形界面的人WorkBuddy菜单式安装通过界面导入或复制到指定目录想少碰命令行的人我的建议是如果你还没深度绑定某一款工具优先选 Claude Code 体验完整度最高。如果你日常主力是 Codex CLI那直接在 Codex 里装也完全没问题它通过AGENTS.md加载技能的方式对爱折腾配置的人其实更友好。Trae 和 WorkBuddy 更偏“开箱即用”缺点是技能目录的位置不是那么直观。尤其是 Trae 的各个版本有的按项目目录识别有的读全局用户目录有时候找半天找不到。后面第 3 章我会专门讲它们和 Claude Code / Codex CLI 的安装差异。3. 实操把 superpowers 装进你的工具3.1 一键脚本安装最快的上手方式常规做法是直接从官方仓库克隆代码然后跑项目自带的一键安装脚本。打开终端依次执行git clone https://github.com/obra/superpowers.git cd superpowers ./install.sh脚本会检测你机器上装了哪些 AI 编程工具然后把技能文件复制到对应位置。我第一次跑这个脚本大概十几秒就结束了输出会明确告诉你“已安装到 Claude Code”还是“已安装到 Codex CLI”方便你复核。这个方式我推荐给第一次接触的人因为它省掉了手抄目录的麻烦。需要注意脚本运行完并不会帮你验证 AI 能不能读到技能所以装完了一定要自己打开工具做一次冒烟测试最简单的办法是直接问一句“你能用哪些 superpowers 技能”看它能不能列出技能清单。如果你的网络环境在拉取仓库时不太顺畅一个替代方案是用压缩包方式把仓库页面里的Download ZIP下载下来解压到任意目录后再手动执行安装脚本。这两种方式的最终效果没有本质差别。3.2 手动安装到 Claude Code / Codex CLI精确定位文件不想跑脚本或者脚本没覆盖到你的工具版本时手动安装也不复杂核心就是把 superpowers 的文件放到工具的 skills 目录下结构一定要保持为superpowers/SKILL.md这种形式。以 Claude Code 为例先建目录再复制mkdir -p ~/.claude/skills cp -r superpowers ~/.claude/skills/这里的~/.claude/skills是 Claude Code 扫描个人技能的位置。复制完以后可以检查一下文件结构ls ~/.claude/skills/superpowers/SKILL.md能输出路径就说明放对了。Codex CLI 的装法类似但它除了把技能放进~/.codex/skills/之外还有个更灵活的路子在~/.codex/AGENTS.md里写一行引用让 Codex 每次启动都主动去读 superpowers 的说明# 在开始任何编码任务前请先阅读 ~/.codex/skills/superpowers/SKILL.md这个写法的好处是技能不一定要复制到固定目录你可以把 superpowers 仓库放在自己熟悉的地方通过AGENTS.md指向它更新时直接git pull就行不用反复复制文件。我个人用的是这种“外部引用”方式版本更新特别省事。3.3 WorkBuddy 与 Trae 的安装差异WorkBuddy 走的是菜单式路径我用的版本是在设置里找到“技能”或“Skills”面板里面提供一个导入入口选择本地包含SKILL.md的目录就能加载。也有部分版本要求在项目的.workbuddy/skills下建目录你把 superpowers 整个文件夹丢进去再重启工具即可。Trae 的情况稍微复杂一点。不同版本对 skill 的识别位置不完全一致有的读用户级目录有的读项目级目录。我建议先查一下自己所用版本的官方文档确认路径然后把 superpowers 目录复制到对应位置重启工具再做一次技能识别检查。如果你安装时始终找不到技能最可靠的兜底办法是创建一个测试项目把 superpowers 放到项目的.trae/skills或类似目录下试一下项目级加载是否正常。这两类工具目前对 skills 的支持都在快速迭代装不上很多时候不是你的问题而是版本太旧。遇到这种情况优先更新工具本体再重新安装。4. 核心使用流程与实操要点4.1 启动一次完整开发从头脑风暴到计划装好之后真正的关键是用起来。很多人装完会发现 AI 还是没有按技能流程走原因很简单默认对话模式下模型并不会主动切换到技能模式。你需要在任务开始时明确唤起它。我常用的启动提示词是这样的请使用 superpowers 技能集。先进入 brainstorming 技能 和我确认清楚需求与约束再进入 plan 技能输出实施计划。 在没有明确计划之前不要写任何代码。这句话的核心是“计划之前不写代码”。AI 一旦接收到这个指令会先输出一组问题比如这个功能给谁用、输入输出边界是什么、有没有兼容性要求、现有代码里哪些模块会受影响。你要耐心做完这轮问答因为它是后续所有工作的地基。需求确认完AI 会调用 plan 技能产出实施计划。这个计划通常是分步骤的包含每步的目标、涉及文件、验证方式。我一般会要求它把计划写成一个 Markdown 文件存到项目里比如PLAN.md这样中途断线重连也能接着开会话不用从头再来。这里有个容易被忽略的点计划阶段一定要让 AI 明确写出“每步的完成标准”。只写“实现登录接口”是不够的要写“登录接口可调用且通过 2 个用例测试”这样执行阶段才能用质量门禁去卡每一步。4.2 执行阶段怎么盯住质量计划通过后AI 进入 execute 模式一步一个脚印地实现。这个阶段你要克制住“让它一口气全做完”的冲动用分步确认喂给 AI现在按计划执行第 1 步和第 2 步。每一步完成后 先跑相关测试和代码检查再向我汇报 diff 摘要。superpowers 里的 quality gates 会把检查动作制度化。按它的设计每完成一个阶段至少要过三道检查更新 CHANGELOG、运行 linter、跑测试套件。只要任何一项失败AI 就不能进入下一个阶段而是要先修复问题。实测下来的体验是这个闸门确实能拦住大多数“改完就忘测试”的情况。有一次我让它加一个配置解析功能前两步都正常到第三步时它想顺手重构一个无关的 util 函数结果被测试套件拦住了AI 自己在汇报里承认“重构与当前目标无关已回滚”。这种自律在没装技能之前很难想象。我还会额外要求它在每个阶段结束后输出一段完成摘要包含改动了哪些文件、测试通过情况、下一步计划。这个摘要不仅是给你看的更是让 AI 自己重新读一遍上下文避免迷失方向。相当于每次提交代码前的一次“强制复盘”。4.3 报错后的调试与复盘闭环真正开发时不可能一路绿灯报错才是常态。AI 编程工具最常见的毛病是一报错就开始瞎猜改一行试一次跟碰运气似的。superpowers 的 debugging 技能专门治这个。比如测试挂了你可以这样指示请使用 debugging 技能处理测试失败。 先根据报错信息定位根因再编写一个能复现该问题的回归测试 最后用最小改动修复代码并确保测试通过。debugging 技能会把流程固定为“复现 → 定位 → 修复 → 回归”。它强调先写回归测试再改代码这个顺序很重要没有回归测试的修复等于没有验收标准的修复你不知道自己到底成功没有。任务全部结束后还有最后一步复盘。superpowers 的 retrograde 技能会让 AI 回顾整个开发过程把“这次哪里做得好、哪里拖慢了进度、下次哪种命令和方式更高”写下来。这些经验会被追加进项目的AGENTS.md或用户级配置里久而久之AI 在这个项目上的表现会越来越贴合项目的实际习惯。我刚开始觉得复盘是走形式直到有一次复盘记录里留下“项目使用 pnpm不要用 npm 安装依赖”这条经验后后续 AI 装依赖就再也没有装错包管理器了我才意识到这个闭环的真正价值。5. 常见问题与排查技巧实录5.1 技能装不上、找不到的排查我身边的不少朋友在安装阶段就卡住了。最典型的表现是明明把目录复制到正确位置AI 还是说不知道 superpowers 是什么。这时候先别急着怪工具按下面的顺序排查第一确认目录名和SKILL.md的路径。很多人在 GitHub 上下载的是压缩包解压后目录名会带-main或-master后缀导致路径变成superpowers-main/SKILL.md工具就扫不到了。把目录名改成superpowers就能解决。第二确认工具的版本。Claude Code 和 Codex CLI 是在某一个版本开始才支持 skills 自动发现太老的版本根本不会扫描这些目录。升级到最新版再试。第三确认权限。技能目录如果权限不对工具会静默跳过。macOS 和 Linux 下可以执行chmod -R r ~/.claude/skills/superpowers然后再测试一次。第四确认工具的配置文件没有被覆盖。比如~/.codex/AGENTS.md里如果写了很长的自定义指令且与你加的 superpowers 引用有冲突技能可能会被模型“视而不见”。测试时建议先临时注释掉其他自定义指令只保留 superpowers 引用。5.2 技能装好但 AI 不听话的解法目录没问题、也确认版本很新但 AI 就是不用技能。这个问题比“装不上”更隐蔽。我遇到最多的情况是用户用的启动提示词太泛只说“请你帮我实现 xxx”并没有明确要求走 superpowers 流程。模型默认情况下不会主动去翻技能因为那会增加推理成本。解决方法是把启动提示词写得更“强制”一些比如在提示词里加上一句“在编写任何代码前先输出你将使用的 superpowers 技能名称并说明理由”。一旦 AI 必须在回答里交代技能选择它就很难跳过这个步骤。还有一种情况是项目级的AGENTS.md或CLAUDE.md里已经写出了一套完整的工作规范和 superpowers 的流程叠加后会互相干扰。我的建议是两者选其一作为主导一般新项目直接用 superpowers 就好把项目规范文件里的流程描述精简到最低限度。如果以上都试过了还是不行那就开启调试模式看工具在启动时是否输出了技能加载日志。Codex CLI 有--debug相关的参数Claude Code 可以用/status查看当前加载的上下文。日志没有提到技能文件问题大概率还是在路径或权限上。5.3 其他容易踩的坑速查坑现象解法Node.js 版本过低技能脚本运行报语法错误升级到 Node.js 20 LTS 或更高路径里有中文或空格技能脚本无法找到文件把 superpowers 放到纯英文无空格目录技能更新不及时AI 行为和新版本文档不一致定期git pull更新技能仓库多工具共享配置Claude 装好但 Codex 没生效检查各工具独立的 skills 目录计划文件被 AI 自己覆盖执行到一半 PLANNING 丢失要求 AI 每次修改计划前先 diff依赖管理器不一致自动装依赖时选错包管理器在 AGENTS.md 里写明项目用哪个这条速查表里的问题我基本都亲身踩过。尤其“路径里有空格”那条看起来是小问题技能脚本在找不到路径时会静默失败等你排查一圈才发现是目录名带了空格非常浪费时间。另外提醒一句如果你在一个项目里同时给多个编码工具用 superpowers建议在用户的全局配置文件里统一声明“本机编码技能统一使用 superpowers”让工具之间以同样的方式协作避免一个装了另一个没装导致行为不一致。5.4 我的使用体会与建议写到这儿说说我最直接的感受。superpowers 对我的最大改变不是多写了多少代码而是把我和 AI 协作的节奏从“散打”变成了“回合制”。每个阶段有目标、有检查、有交付物出问题知道在哪一步找原因而不是面对一团乱麻的 diff 无从下手。给初次尝试的人一个建议不要一上来就给 AI 丢完整的大项目。先选一个小功能比如给现有工具加一个命令行参数把“头脑风暴 → 计划 → 执行 → 测试 → 复盘”完整跑通一遍。流程顺手之后再逐步加大任务规模。刚开始多花在计划上的那几分钟到后期省下的返工时间往往是几倍甚至十几倍。