1. 从“superpowers”说起：一个让 AI 编码助手真正长出“工程肌肉”的技能框架
第一次看到 “superpowers” 这个词，是在一个开发者社群里有人贴了一张截图：同一个需求，普通对话式让 AI 写代码，和挂载了 superpowers 技能框架之后再让 AI 写代码，产出的东西完全是两个物种。前者给你一段能跑但不敢上线的脚本，后者给你一套带测试、带边界处理、带文档注释、甚至带回滚方案的完整模块。这个反差让我决定认真研究一下这套东西到底是什么。
superpowers 本质上是一套agentic skills framework，翻译过来就是“智能体技能框架”。它不是某个具体的软件，也不是一个可以直接双击安装的 App，而是一套组织 AI 编码助手工作方式的软件工程方法论。你可以把它理解成给 AI 助手装上了一本“老工程师的操作手册”——告诉它在接到任务之后，应该先做什么、再做什么、什么情况下必须停下来确认、什么情况下必须写测试、什么情况下必须拆解任务而不是一口气写完。
它主要服务于两类工具：Claude Code和Codex CLI。这两个都是目前主流的终端级 AI 编码助手，前者由 Anthropic 推出，后者由 OpenAI 推出。它们都能在命令行里直接读写你的项目文件、执行终端命令、跑测试、提交代码。而 superpowers 做的事情，就是给这些能力套上一层“工程纪律”，让 AI 不再是一个只会写代码的实习生，而更像一个懂流程、懂规范、懂取舍的资深工程师。
这篇文章适合谁看？如果你已经在用 Claude Code 或 Codex CLI，但总觉得产出质量不稳定、经常需要反复纠正、或者不敢让 AI 碰核心模块，那 superpowers 这套思路值得你花时间研究。如果你还没开始用这两个工具，那这篇文章也会顺带把安装、配置、常见坑讲清楚，让你能直接上手。接下来我会从设计思路、核心机制、实操流程、常见问题几个维度，把这套框架拆开讲透。
2. 为什么需要一套“技能框架”：AI 编码助手的能力边界与工程缺口
2.1 裸用 AI 编码助手的三个典型翻车场景
先说清楚问题，才能理解 superpowers 的价值。我自己的项目里，裸用 Claude Code 或 Codex CLI 时，翻车基本集中在三个地方。
第一个是任务粒度失控。你让它“加一个用户登录功能”，它可能一口气给你写出来路由、控制器、数据库迁移、前端表单、样式、测试，全部塞在一个回复里。看起来效率很高，但问题是：中间任何一步假设错了，后面全部要返工。而且它不会主动问你“你是要 JWT 还是 Session”“密码哈希用 bcrypt 还是 argon2”“要不要加 rate limiting”。它默认按最常见的方式做，但最常见不等于你项目需要。
第二个是测试与验证缺失。AI 写代码很快，但它经常不写测试，或者写了测试也是糊弄——只测 happy path，不测边界条件。你让它“写个函数解析日期”，它给你一个new Date(str)，你问它“如果 str 是空字符串呢”“如果是 13 月呢”“如果是时区偏移呢”，它才补上。这种被动补漏的方式，在核心模块上非常危险。
第三个是上下文遗忘与风格漂移。长对话里，AI 会忘记你前面定的规范。比如你一开始说“这个项目用 2 空格缩进、单引号、不用分号”，聊到第 20 轮，它又开始用 4 空格、双引号、分号。你纠正一次，它改一次，下次又忘。这不是模型笨，而是对话上下文太长之后，早期指令的权重被稀释了。
2.2 superpowers 的核心思路：把工程纪律外置成可复用技能
superpowers 的解法很直接：不依赖 AI 的“自觉”，而是把工程纪律写成显式的、可复用的技能定义。这些技能定义放在项目里的特定目录下，AI 每次开工前先读这些技能，然后按技能里写的流程走。
打个比方：裸用 AI 助手，就像你雇了一个很聪明但没上过班的应届生，你得每次口头交代“记得写测试”“记得拆任务”“记得问我关键决策”。而 superpowers 相当于给这个应届生发了一本《员工手册》，里面写清楚了“接到需求先做任务拆解”“涉及数据库变更必须先出迁移方案”“核心逻辑必须配单元测试”“不确定的决策必须列选项让负责人选”。他每次开工前翻一遍手册，按流程走，你就不用反复口头交代了。
这套框架的关键在于技能是可组合、可继承、可覆盖的。你可以定义一套团队通用的基础技能，然后针对不同项目类型（比如 Web 后端、数据管道、CLI 工具）定义不同的技能包。AI 在具体项目里工作时，会加载对应的技能包，按里面的流程执行。
2.3 和普通 Prompt 模板的本质区别
有人可能会说：这不就是 Prompt 模板吗？我写一段“你是一个资深工程师，请先拆解任务再写代码”不就行了？
区别在于三点。第一，持久化与自动加载。Prompt 模板你得每次手动贴，或者放在系统提示里但容易被后续对话冲淡。superpowers 的技能是放在项目文件里的，AI 每次通过工具读取，不依赖对话记忆。第二，结构化与可执行。普通 Prompt 是自然语言描述，AI 理解成什么样看运气。superpowers 的技能定义更接近“流程规范”，有明确的触发条件、步骤、检查点，AI 执行时偏差更小。第三，可版本控制与团队共享。技能文件放在 Git 里，团队所有人共用同一套，新人入职直接继承，不会因为某个人忘了交代而漏掉关键步骤。
我自己的体会是：普通 Prompt 模板像是给 AI 贴了一张便签，superpowers 像是给 AI 装了一套工作流引擎。前者靠提醒，后者靠机制。
3. 核心机制拆解：superpowers 到底怎么让 AI 按工程流程走
3.1 技能定义的结构：触发条件、执行步骤、检查点
superpowers 的技能定义通常包含三个核心部分。第一部分是触发条件，也就是“什么情况下该用这个技能”。比如“当用户要求新增功能时”“当涉及数据库 schema 变更时”“当需要重构现有代码时”。触发条件写得越具体，AI 判断越准。
第二部分是执行步骤，也就是“按什么顺序做什么”。比如一个“新增功能”技能可能写：第一步，复述需求并列出不确定点；第二步，拆解成子任务并标注依赖关系；第三步，对每个子任务给出实现方案概要；第四步，等用户确认后再写代码；第五步，写代码同时写测试；第六步，跑测试并报告结果。
第三部分是检查点，也就是“什么情况下必须停下来”。比如“涉及删除文件必须确认”“涉及修改公共 API 必须确认”“测试未通过不得继续下一步”。检查点是防止 AI 自作主张的关键机制。
3.2 技能加载与优先级：项目级覆盖全局级
实际使用中，技能通常分两层：全局技能和项目级技能。全局技能放在用户主目录下的配置目录里，对所有项目生效；项目级技能放在项目根目录的特定文件夹里，只对该项目生效。加载时，项目级技能会覆盖同名的全局技能。
这个设计很实用。比如你全局技能里写“测试框架用 Jest”，但某个老项目用的是 Mocha，你就在项目级技能里覆盖这一条，不用改全局配置。又比如你全局技能里写“提交信息用英文”，但某个项目要求中文，同样在项目级覆盖。
优先级规则一般是：项目级 > 全局级 > 内置默认。内置默认是框架自带的一套基础技能，保证你什么都不配也能用。我建议新手先直接用内置默认跑一遍，感受一下流程，然后再根据自己的习惯定制。
3.3 与 Claude Code / Codex CLI 的集成方式
superpowers 和这两个工具的集成方式略有不同，但核心逻辑一致：都是通过工具的文件读取能力，让 AI 在开工前读取技能文件。
在 Claude Code 里，通常是在项目根目录放一个技能目录，然后在对话开始时让 AI 读取。Claude Code 支持通过CLAUDE.md文件定义项目级指令，你可以把技能索引写在这里，AI 每次启动会自动读取。更细的技能文件放在子目录里，AI 按需读取。
在 Codex CLI 里，类似地通过项目配置文件定义指令，技能文件放在指定目录。Codex CLI 的命令体系里有/compact（压缩对话历史）、/model（切换模型）、/resume（恢复会话）等，这些命令和技能框架配合使用，可以在长任务里保持流程不中断。
注意：技能文件不要写得太长。单个技能文件建议控制在 200 行以内，太长 AI 读取后理解成本高，反而容易漏掉关键步骤。如果一个技能超过 200 行，考虑拆成多个子技能。
4. 从零上手实操：安装、配置、跑通第一个技能流程
4.1 Claude Code 的安装与基础配置
先说 Claude Code 的安装。在 macOS 或 Linux 上，最省事的方式是通过 npm 全局安装。前提是你机器上已经有 Node.js，建议版本 18 以上。命令是：
npm install -g @anthropic-ai/claude-code装完之后，在终端输入claude就能启动。第一次启动会引导你登录账号。如果你所在的环境无法直接登录，也可以配置第三方 API 接入，具体方式后面讲。
Windows 用户要注意：Claude Code 官方对原生 Windows 的支持有限，常见做法是在 WSL2 里安装，或者用 Git Bash 配合。如果你在 Windows 上遇到“与 64 位版本不兼容”之类的报错，大概率是 Node 版本或终端环境问题，换到 WSL2 里基本能解决。
Ubuntu 上的安装和 macOS 类似，npm 全局装完即可。如果 npm 安装很慢，可以先换源：
npm config set registry https://registry.npmmirror.com然后再执行安装命令，速度会明显提升。
4.2 Codex CLI 的安装与常见卡点
Codex CLI 的安装同样走 npm：
npm install -g @openai/codex装完之后输入codex启动。Codex CLI 的命令体系里，常用的有/compact用来压缩对话历史（长任务里很有用，防止上下文爆炸）、/model用来切换模型、/resume用来恢复之前的会话。如果你要删除 Codex CLI，用npm uninstall -g @openai/codex即可。
国内用户装 Codex CLI 最常见的卡点是 npm 下载慢。除了换源，还可以用--verbose看具体卡在哪个包，有时候是某个二进制依赖下载超时，手动设置对应的镜像环境变量能解决。
4.3 配置 superpowers 技能目录
安装完工具之后，开始配置技能目录。以 Claude Code 为例，在项目根目录创建如下结构：
项目根目录/ CLAUDE.md .claude/ skills/ new-feature.md refactor.md bugfix.mdCLAUDE.md里写技能索引和全局指令，.claude/skills/下放具体技能文件。CLAUDE.md的内容大致如下：
# 项目指令 ## 技能加载 开工前先读取 .claude/skills/ 下的相关技能文件。 新增功能读 new-feature.md，重构读 refactor.md，修 bug 读 bugfix.md。 ## 全局规范 - 缩进 2 空格，单引号，不用分号 - 所有新增函数必须有单元测试 - 涉及数据库变更必须先出迁移方案 - 不确定的决策列选项让用户选，不要自作主张技能文件new-feature.md的内容示例：
# 新增功能技能 ## 触发条件 用户要求新增功能、新增接口、新增模块时。 ## 执行步骤 1. 复述需求，列出所有不确定点，等用户确认。 2. 拆解成子任务，标注依赖关系，输出任务列表。 3. 对每个子任务给出实现方案概要，等用户确认。 4. 按依赖顺序实现，每个子任务完成后跑测试。 5. 全部完成后输出变更摘要和测试报告。 ## 检查点 - 涉及删除文件必须确认 - 涉及修改公共 API 必须确认 - 测试未通过不得进入下一子任务Codex CLI 的配置类似，只是索引文件换成 Codex 对应的项目配置文件，技能目录路径按 Codex 的约定来。核心逻辑一样：让 AI 开工前先读技能。
4.4 跑通第一个流程：用技能框架做一个真实小需求
配置好之后，找个真实小需求试跑。比如“给现有用户列表接口加一个按注册时间排序的参数”。启动 Claude Code，输入需求。AI 读取new-feature.md后，应该先复述需求并列出不确定点，比如“排序方向是升序还是降序”“默认行为是什么”“是否需要分页配合”。你确认后，它拆解任务、给方案、等确认、再实现、跑测试。
我第一次跑的时候，AI 确实按流程走了，但在“列出不确定点”这一步只列了两个，漏了“排序字段为空时怎么处理”。这说明技能文件里“列出所有不确定点”这个表述还不够强。后来我改成“列出至少 3 个不确定点，包括边界条件、默认行为、错误处理”，覆盖度明显提升。这就是技能框架的好处：流程不对，改技能文件就行，不用每次口头纠正。
5. 进阶玩法：多模型接入、团队协作与技能定制
5.1 接入第三方模型与本地模型
Claude Code 和 Codex CLI 默认用官方模型，但都支持接入第三方 API 或本地模型。常见做法是通过环境变量或配置文件指定 API 端点和密钥。比如你想用 DeepSeek、Qwen、GLM 等模型，可以在配置里改 base URL 和 model 名称。
本地模型方面，如果你用 LM Studio 跑本地模型，它提供一个兼容 OpenAI 格式的本地端点。把 Claude Code 或 Codex CLI 的 API 端点指向http://localhost:1234/v1（LM Studio 默认端口），模型名填你加载的模型，就能让 AI 助手调用本地模型。好处是数据不出本机、不消耗 API 额度；代价是本地模型能力通常弱于云端大模型，复杂任务上表现会打折扣。
提示：接入第三方或本地模型时，先跑一个简单任务验证连通性，再上复杂任务。常见问题是端点格式不兼容、模型名写错、流式输出不支持，这些在简单任务里就能暴露。
5.2 团队协作：技能文件的版本管理与共享
技能文件放 Git 里，团队共用。建议的做法是：基础技能放一个独立的仓库，各项目通过 submodule 或复制的方式引入。项目特有的技能覆盖放在项目自己的技能目录里。
这样新人入职，clone 项目后技能自动就位，不用口头交代规范。老人改规范，改技能文件提交，所有人下次开工自动生效。比写 Wiki 靠谱，因为 Wiki 没人看，技能文件 AI 每次必读。
我自己的团队里，技能文件还承担了“代码评审清单”的作用。评审时如果发现某类问题反复出现，就把对应的检查项加进技能文件，让 AI 下次开工就规避。相当于把评审经验沉淀成了自动化流程。
5.3 定制技能：从“通用流程”到“项目专属流程”
内置技能是通用的，但每个项目有自己的特殊性。比如数据管道项目，可能需要“任何 schema 变更必须同时更新数据字典”“任何新指标必须定义口径和计算逻辑”。这些就可以写成项目专属技能。
定制技能的关键是具体。不要写“注意数据质量”，要写“新增字段必须标注是否可空、默认值、取值范围”。不要写“写好测试”，要写“每个公开函数至少 3 个测试用例：正常输入、边界输入、异常输入”。越具体，AI 执行越到位。
6. 常见问题与排查技巧实录
6.1 安装与启动类问题速查
| 问题现象 | 可能原因 | 排查方向 |
|---|---|---|
| npm 安装极慢或超时 | 默认源在国外 | 换国内镜像源后重试 |
| 启动报 64 位不兼容 | Windows 原生环境限制 | 改用 WSL2 或 Git Bash |
| 登录提示组织禁用订阅 | 账号权限或地区限制 | 检查账号状态，或改用 API 接入 |
| 启动后无响应 | Node 版本过低 | 升级到 Node 18 以上 |
| 命令找不到 | 全局 bin 目录不在 PATH | 检查 npm 全局路径并加入 PATH |
6.2 技能不生效或流程走偏的排查
技能不生效，最常见的原因是 AI 没读到技能文件。排查步骤：第一，确认技能文件路径和索引文件里写的一致；第二，确认索引文件本身被 AI 读取了（可以在对话里直接问“你读到了哪些技能文件”）；第三，确认技能文件的触发条件描述和当前任务匹配。
流程走偏，通常是技能文件写得太模糊。比如“拆解任务”没写拆到什么粒度，AI 可能只拆两层就开写。改成“拆解到每个子任务可在 30 分钟内完成，且每个子任务有明确的验收标准”，效果会好很多。
6.3 长任务上下文管理技巧
长任务里，对话历史会越来越长，AI 容易忘早期指令。Claude Code 和 Codex CLI 都提供了压缩对话历史的机制。Codex CLI 的/compact命令就是干这个的。Claude Code 里可以通过总结当前进度、开新会话、把关键上下文写进技能文件或项目文档来管理。
我自己的做法是：每完成一个子任务，让 AI 输出一段“当前进度摘要”，然后开新会话，把摘要贴进去继续。这样上下文始终清爽，AI 不容易漂移。
6.4 独家避坑心得
第一条，技能文件先少后多。一开始别写十几条技能，先写最核心的三条：任务拆解、测试要求、检查点。跑顺了再逐步加。技能太多，AI 读取和理解成本高，反而容易漏。
第二条，检查点要硬。写“建议确认”没用，AI 可能不确认就往下走。写“必须确认，未确认不得继续”，效果完全不同。措辞上要用强制语气。
第三条，定期回顾技能文件。项目在变，技能文件也要跟着变。我一般每个月回顾一次，把最近踩的坑补进去，把过时的条目删掉。技能文件不是写完就完事，是活的。
7. 我对这套框架的真实体会
用了一段时间之后，我最大的感受是：superpowers 这类技能框架，解决的不是“AI 会不会写代码”的问题，而是“AI 按不按你的规矩写代码”的问题。前者靠模型能力，后者靠流程设计。模型能力你控制不了，流程设计你完全可控。
另一个体会是，这套东西对团队协作的价值大于对个人开发者的价值。个人开发者可能觉得“我自己记得就行”，但团队里人多、项目多、时间跨度长，靠人记必然漏。把规矩写进技能文件，让 AI 每次执行，比开十次会强调都管用。
最后分享一个小技巧：如果你不确定某个技能该怎么写，可以先手动跑一遍任务，把你实际做的每一步记下来，然后整理成技能文件。你手动怎么做，就让 AI 怎么做。这比凭空想“AI 应该怎么工作”靠谱得多。
