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 的安装同样走 npmnpm 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/v1LM 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 全局路径并加入 PATH6.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 应该怎么工作”靠谱得多。
