Superpowers技能框架：让AI编程助手稳定输出工程级代码

1. 从“superpowers”说起这套技能框架到底在解决什么问题第一次看到“superpowers”这个词很多人会以为是某个超级英雄题材的游戏或者插件合集。但如果你最近在折腾 Claude Code、Codex CLI 这类终端里的 AI 编程助手大概率已经在各种社区里刷到过它。简单来说superpowers 是一套面向 AI 编程代理的技能框架agentic skills framework也是一套围绕它建立起来的软件开发方法论。它要解决的核心痛点非常具体AI 编程助手本身很聪明但每次对话都是“失忆”的你不告诉它你的项目规范、代码风格、目录结构、测试习惯它就会按自己的默认套路来写出来的东西能跑但跟你的工程体系格格不入。superpowers 的思路是把这些“你希望 AI 一直记住并且一直遵守的东西”抽出来做成一个个可复用的技能模块然后在 Claude Code、Codex CLI 这类工具里按需加载。你可以把它理解成给 AI 助手装了一套“职业培训手册加操作规范”什么场景该调用什么技能、写代码前先看哪些约束、提交前跑哪些检查全都固化下来。它不是一个具体的库也不是某个语言的 SDK而是一层方法论加配置体系落在你的项目目录里跟着代码一起走。这套东西适合谁三类人最值得花时间研究。第一类是已经在用 Claude Code 或 Codex CLI 做日常开发但总觉得 AI 输出“差那么点意思”的工程师第二类是想把 AI 编程引入团队、但苦于无法统一输出质量的 Tech Lead第三类是刚接触 agentic 工具、想找一套现成规范照着抄的新手。它不要求你会写复杂的提示词工程也不要求你懂模型微调核心工作就是整理你的工程知识然后按框架约定组织起来。我自己的体会是superpowers 真正的价值不在于“让 AI 变强”而在于“让 AI 变稳”。模型能力是外部变量你控制不了但技能框架是你自己的资产写一次就能反复用换模型、换工具、换项目都能迁移。下面我会从设计思路、核心细节、实操落地、问题排查几个层面把我在实际项目里踩过的路完整讲一遍。2. 整体设计与思路拆解为什么是“技能”而不是“提示词”2.1 技能框架和普通提示词的本质区别很多人第一反应是这不就是写一段 system prompt 吗我直接把规范塞进对话开头不就行了。短期看确实能凑合但一旦项目变大、场景变多问题就暴露了。普通提示词是“一次性”的它跟着某一次对话走对话结束就没了而 superpowers 里的技能是“持久化”的它以文件形式存在项目里可以被版本控制、被复用、被组合。这是第一个本质区别提示词是会话级的技能是项目级的。第二个区别在于组织方式。一段长提示词是线性的所有规则堆在一起AI 读的时候没有优先级容易顾此失彼。而技能框架是模块化的每个技能负责一个明确的领域比如“代码风格”“测试规范”“提交信息格式”“依赖管理”。AI 在具体任务里只加载相关技能注意力更集中输出质量自然更稳定。这就像你给新员工培训不会把公司所有制度一次性念完而是按岗位、按场景分批给资料。第三个区别是可验证性。技能文件是纯文本你可以 review、可以 diff、可以写测试去校验它有没有被正确引用。提示词藏在对话历史里改了什么、什么时候改的根本追溯不了。对于团队协作来说这一点是决定性的。2.2 为什么选择 Claude Code 和 Codex CLI 作为主要载体superpowers 之所以和 Claude Code、Codex CLI 绑定得这么紧是因为这两类工具都支持在项目目录里读取本地文件作为上下文。Claude Code 有 CLAUDE.md 这类约定文件Codex CLI 也有自己的配置读取机制它们都允许你把项目级的指令放在仓库里而不是每次手动粘贴。这就给技能框架提供了落地的土壤。选这两个工具还有一层现实考虑它们都是终端优先的工作流天然贴近真实开发。你在终端里敲命令、跑测试、看 diffAI 助手就在同一个环境里能直接读文件、执行命令、看输出。技能框架里的很多规则比如“改完代码必须跑 lint”“提交前检查测试覆盖”在这种环境下是可以被真正执行的而不是停留在纸面上。相比之下纯聊天窗口里的 AI 助手你让它“记得跑测试”它只能口头答应实际做不做全看运气。提示如果你还没装 Claude Code 或 Codex CLI建议先把基础工具跑通再上技能框架。工具本身没跑顺框架只会放大混乱。2.3 框架的分层结构从“总纲”到“具体技能”我在实际项目里把 superpowers 的组织分成三层。最上面是总纲层通常是一个入口文件比如 CLAUDE.md 或者项目根目录的说明文件里面写清楚这个项目是干什么的、技术栈是什么、有哪些全局约束。这一层不涉及具体操作只给 AI 建立“世界观”。中间是技能层每个技能一个文件或一个目录比如skills/code-style.md、skills/testing.md、skills/git-workflow.md。每个技能内部结构尽量统一先说明这个技能解决什么问题再列出具体规则最后给正反例。统一结构的好处是 AI 读起来有预期你维护起来也方便。最下面是场景层也就是把技能和具体任务绑定。比如“新增一个 API 接口”这个场景需要加载 code-style、testing、api-convention 三个技能“修一个 bug”这个场景需要加载 debugging、testing 两个技能。场景层可以是一个简单的映射表也可以是一段说明文字告诉 AI 在什么情况下该看哪些技能。这种分层的好处是解耦。技能本身不关心什么时候被用场景只负责编排总纲只负责定调。任何一层要改都不会牵一发动全身。我见过有人把所有规则塞进一个巨大文件结果改一行要通读全文维护成本极高最后就没人愿意改了。3. 核心细节解析与实操要点技能文件到底怎么写3.1 一个合格技能文件的四段式结构写技能文件最容易犯的错是写成“愿望清单”——“代码要整洁”“命名要规范”“测试要覆盖”。这种话 AI 看了等于没看因为它不知道你的“整洁”和“规范”具体指什么。我总结下来一个能真正生效的技能文件应该包含四段适用场景、硬性规则、正例、反例。适用场景放在最前面用一两句话说明这个技能在什么时候生效。比如“当你需要新增或修改任何 Python 文件时遵循以下规则”。这句话的作用是给 AI 一个触发条件避免它在无关任务里乱套规则。硬性规则是核心必须具体到可执行。不要说“函数要短”要说“单个函数不超过 40 行超过就拆分”。不要说“命名要清晰”要说“变量用 snake_case类用 PascalCase常量全大写”。规则越具体AI 执行越稳定。我一般会把规则控制在 5 到 10 条太多 AI 记不住太少覆盖不全。正例和反例各给一到两个代码片段。正例展示“这样做是对的”反例展示“这样做是错的因为……”。反例特别重要因为 AI 对“不要做什么”的理解往往比“要做什么”更模糊给它一个具体的错误样本它能更快对齐你的预期。3.2 规则的具体化程度一个对比案例我拿“错误处理”这个技能举例展示一下模糊规则和具体规则的区别。模糊版本是这样的代码要有良好的错误处理不要吞掉异常要给出有意义的错误信息。这段话读起来没毛病但 AI 拿到之后基本会自由发挥有人写 try-catch 包一切有人直接抛原始异常风格完全不统一。具体版本我会这么写所有外部调用网络、文件、数据库必须包裹 try-catchcatch 块里必须记录日志日志包含操作名和关键参数禁止使用裸的except: pass对外抛出的异常必须是项目自定义的AppError子类并附带 error code。这样 AI 就知道边界在哪输出会稳定得多。再进一步我会在正例里给一段标准写法在反例里给一段“吞异常”的写法并标注问题所在。实测下来加了正反例之后AI 在错误处理上的输出一致性提升非常明显基本不需要我再手动改。3.3 技能之间的依赖和引用怎么处理项目大了之后技能之间会有依赖。比如 testing 技能可能依赖 code-style 技能里定义的命名规范git-workflow 技能可能依赖 testing 技能里定义的测试命令。如果每个技能都自包含会有大量重复如果互相引用又容易形成循环。我的做法是设一个基础技能层把最通用的规则放进去比如命名规范、目录结构、日志格式。其他技能可以引用基础层但基础层不引用任何其他技能。引用方式很简单在技能文件里写一句“本技能继承 base-convention 的命名规则”不需要复杂的机制。AI 读到这句话会自己去加载基础技能效果和显式 import 差不多。注意引用层级不要超过两层。基础层到具体技能一层就够了再深下去 AI 容易迷路维护的人也容易搞混。3.4 技能文件的存放位置和命名约定存放位置直接影响 AI 能不能找到。Claude Code 默认会读项目根目录的 CLAUDE.md所以我会在 CLAUDE.md 里写清楚技能目录在哪比如“所有技能文件位于.ai/skills/目录下”。Codex CLI 类似需要在它的配置里指定读取路径。命名上我建议用“领域-动作”的格式比如code-style.md、test-writing.md、git-commit.md。不要用中文文件名虽然技术上可行但在不同系统间同步容易出编码问题。也不要用太泛的名字比如rules.md、misc.md时间一长你自己都忘了里面写的什么。目录结构我一般是这样.ai/ skills/ base-convention.md code-style.md testing.md git-workflow.md api-convention.md scenarios/ new-feature.md bug-fix.md refactor.md.ai目录放在项目根目录跟.github、.vscode平级语义清晰也不会污染源码目录。4. 实操过程与核心环节实现从零搭起一套可用的技能框架4.1 环境准备Claude Code 与 Codex CLI 的基础配置在动手写技能之前先把工具跑通。Claude Code 的安装方式根据系统不同有差异Ubuntu 下一般是通过包管理器或者官方提供的安装脚本Windows 下建议用 WSL 环境避免路径和权限的坑。安装完之后在项目根目录运行一次确认它能正常读取文件、执行命令。如果遇到“unable to locate the codex cli binary or required runtime components”这类提示通常是运行环境没装全检查一下 Node 运行时和相关依赖是否到位。Codex CLI 的安装类似Windows 下同样推荐 WSL。装完之后用codex --version确认版本然后在项目里跑一个简单任务比如“读一下 README 并总结”看它能不能正常访问文件。这一步不要跳过工具本身有问题后面技能框架写得再好也白搭。VSCode 里配置 Claude Code 的话主要是确保终端环境和插件环境一致避免出现“终端里能用、插件里报错”的情况。我一般会先在终端里把所有流程跑通再考虑插件集成。4.2 第一步写总纲文件给 AI 建立项目世界观总纲文件是整个框架的入口我通常放在项目根目录命名成CLAUDE.md或者AGENTS.md。内容不需要长但要把关键信息说清楚。我的模板大概是这样# 项目总纲 ## 项目简介 这是一个基于 Python 的后端服务负责订单处理对外提供 REST API。 ## 技术栈 - 语言Python 3.11 - 框架FastAPI - 数据库PostgreSQL - 测试pytest ## 全局约束 - 所有代码必须通过 ruff 检查 - 提交前必须跑通 pytest - 技能文件位于 .ai/skills/ 目录 - 场景文件位于 .ai/scenarios/ 目录 ## 工作流程 1. 接到任务先读相关场景文件 2. 按场景加载对应技能 3. 改完代码跑 lint 和测试 4. 提交信息遵循 git-workflow 技能这个文件的作用是让 AI 一进项目就知道“我在哪、我要遵守什么”。实测下来有了总纲之后AI 在后续对话里跑偏的概率明显降低。4.3 第二步抽取你的第一条技能从代码风格开始第一条技能建议从代码风格入手因为它最通用、最容易验证。我以 Python 项目为例写一个code-style.md# 代码风格技能 ## 适用场景 新增或修改任何 Python 文件时生效。 ## 硬性规则 1. 缩进用 4 空格禁止 Tab 2. 行宽不超过 100 字符 3. 函数名和变量名用 snake_case 4. 类名用 PascalCase 5. 常量全大写单词间下划线分隔 6. 单个函数不超过 40 行 7. 导入顺序标准库、第三方库、本地模块三组之间空一行 8. 禁止使用通配符导入from x import * ## 正例 python import os from typing import Optional from fastapi import FastAPI from app.models import Order MAX_RETRY_COUNT 3 def calculate_total_price(order: Order) - float: ...反例from app.models import * # 禁止通配符导入 def CalcTotal(Order): # 命名不符合规范 ...写完这条技能后在总纲里引用它然后跑一个真实任务测试。比如让 AI 新增一个函数看它是否遵守了命名和行宽规则。如果没遵守说明规则写得还不够具体回去补细节。 ### 4.4 第三步建立场景映射让技能按需加载 技能写好了接下来要解决“什么时候用哪个技能”的问题。我在 .ai/scenarios/ 下建几个常见场景文件。以“新增功能”为例 markdown # 场景新增功能 ## 触发条件 用户要求新增一个 API 接口、一个业务函数或一个模块。 ## 加载技能 1. code-style必选 2. testing必选 3. api-convention如果涉及 API ## 执行步骤 1. 先读现有代码理解项目结构 2. 按 code-style 写实现 3. 按 testing 写单元测试 4. 跑 lint 和测试 5. 按 git-workflow 提交场景文件不需要复杂关键是让 AI 知道“这个任务该看哪些资料、按什么顺序做”。我一般会建四到五个场景新增功能、修 bug、重构、写文档、依赖升级。覆盖日常开发八成以上的情况。4.5 第四步参数与规则的量化让约束可执行很多规则之所以失效是因为没有量化。我在实操里会把能数字化的全部数字化。比如测试覆盖率不写“要有足够测试”写“核心模块覆盖率不低于 80%工具模块不低于 60%”。比如提交信息不写“写清楚”写“格式为 type(scope): descriptiontype 限定为 feat/fix/refactor/docs/test/chore”。量化的好处是可验证。AI 写完代码你可以让它自己对照规则检查一遍不符合就改。我甚至会在技能里加一段“自检清单”让 AI 在提交前逐条核对。实测下来加了自检清单之后返工率下降很明显。提示量化规则不要一次定太死先定一个宽松版本跑一段时间再收紧。一上来就要求 90% 覆盖率AI 和你都会崩溃。4.6 第五步把技能框架纳入版本控制技能文件是项目资产必须进 Git。我会把.ai/目录完整提交并且在 PR 模板里加一条“如果修改了技能文件请说明原因”。这样技能框架的演进就有迹可循新人入职也能通过读技能文件快速理解项目规范。另外技能文件的修改建议单独提交不要和业务代码混在一起。混在一起的话review 的人容易忽略技能变更时间一长就没人知道规则什么时候改的、为什么改。5. 常见问题与排查技巧实录我踩过的那些坑5.1 技能写了但 AI 不遵守怎么排查这是最常见的问题。排查思路分三步。第一步确认技能文件真的被加载了。可以在对话里直接问 AI“你现在加载了哪些技能文件”看它的回答是否包含你写的文件。如果没加载检查总纲里的路径配置对不对文件名有没有拼错。第二步确认规则是否具体。如果 AI 加载了但没遵守大概率是规则太模糊。把规则改写成可执行的形式加上正反例再测一次。我遇到过“日志要详细”这种规则AI 完全自由发挥改成“日志必须包含 request_id、user_id、操作名三个字段”之后立刻就稳定了。第三步确认规则之间没有冲突。如果两个技能对同一件事有不同要求AI 会随机选一个。比如 code-style 说函数不超过 40 行另一个技能说复杂逻辑可以放宽到 60 行AI 就懵了。解决办法是设一个优先级或者在总纲里明确“冲突时以 code-style 为准”。5.2 技能文件越写越多怎么控制规模我一开始也犯过这个错什么都想写进技能最后搞了二十多个文件AI 加载慢我自己也维护不动。后来我定了一个原则只写那些“AI 默认做不对、且反复出现”的规则。一次性的事情不写AI 本来就能做对的事情不写只写那些你每次都要手动纠正的点。按这个原则筛下来真正必要的技能通常不超过八个。剩下的可以合并或者删掉。技能框架的价值在于精不在于多。5.3 换模型或换工具之后技能框架还能用吗能用但要做适配。技能文件本身是纯文本跟模型无关换模型不影响。但不同工具读取技能的方式不一样Claude Code 读 CLAUDE.mdCodex CLI 有自己的配置入口换工具的时候需要在总纲里调整路径说明。我的做法是把技能内容本身和工具配置分离。技能文件放在.ai/skills/工具相关的配置放在各自的入口文件里入口文件只负责“告诉工具去哪读技能”。这样换工具的时候只需要改入口文件技能内容一行都不用动。5.4 常见问题速查表问题现象可能原因排查方法解决方式AI 不遵守技能规则技能未加载问 AI 加载了哪些技能检查总纲路径配置AI 部分遵守部分不遵守规则太模糊检查规则是否可执行改写为具体规则加正反例AI 行为前后矛盾技能间冲突对比相关技能规则设优先级或合并技能技能加载慢技能文件过多统计技能数量合并或删除非必要技能换工具后失效入口配置未更新检查工具入口文件更新路径说明提交信息格式乱规则未量化检查 git 技能明确 type 和格式模板5.5 几个容易被忽略的细节第一个细节是技能文件的编码。统一用 UTF-8不要用系统默认编码否则在不同机器上可能乱码。第二个细节是换行符Windows 和 Linux 混用的时候容易出问题建议在项目里配.gitattributes统一成 LF。第三个细节是技能文件的更新频率我一般一个月 review 一次把过时的规则删掉把新踩的坑补进去。还有一个坑是“技能膨胀”。有人觉得技能越多越专业其实相反。技能多了之后AI 的注意力被分散反而容易漏掉关键规则。我现在的做法是每个技能不超过 10 条规则超过就拆成两个技能但总数控制在八个以内。注意技能框架不是写完就完事的它需要跟着项目一起演进。项目变了技能不变框架就会变成负担。6. 技能框架的扩展玩法从个人到团队6.1 个人项目里的轻量用法如果你只是自己写点小项目不需要搞太复杂。一个总纲文件加两三个技能就够了。我自己的 side project 就只有一个CLAUDE.md里面写了技术栈、代码风格、测试要求三块跑起来完全够用。关键是养成习惯每次发现 AI 犯同样的错就把它补进技能文件而不是每次手动纠正。这种“边用边补”的方式比一开始就设计一套完美框架要实际得多。框架是长出来的不是设计出来的。6.2 团队协作里的技能治理团队用的话技能文件就成了协作规范的一部分。我建议指定一个人负责维护其他人提 PR 修改。修改的时候要写清楚“为什么改”因为技能规则背后往往有具体的踩坑经历不写清楚的话后人容易误删。另外团队里最好定期同步一次技能变更比如在周会上花五分钟过一下这周改了什么规则。不然规则悄悄变了大家的 AI 输出风格也跟着变但没人知道为什么。6.3 技能框架和 CI 的结合技能框架里的很多规则其实可以在 CI 里强制执行。比如代码风格用 ruff 检查测试覆盖率用 pytest-cov 检查提交信息用 commitlint 检查。这样 AI 写的东西在提交前就被机器卡一道比靠 AI 自觉要可靠得多。我的做法是技能文件里写规则CI 里配对应的检查工具两边保持一致。AI 在本地跑的时候按技能规则来提交到 CI 再被机器验一遍。双保险下来输出质量非常稳定。6.4 后续可以扩展的方向技能框架跑顺之后可以往几个方向扩展。一是把技能和具体工具链绑定比如技能里直接写“用 ruff 格式化”“用 pytest 跑测试”让 AI 直接调用命令。二是做技能模板库把通用技能抽出来新项目直接复制。三是把技能和代码审查结合让 AI 在 review 的时候按技能规则逐条检查。这些扩展都不需要改框架本身只是在现有结构上加东西。这也是分层设计的好处核心稳定外围灵活。我个人在实际操作中的体会是superpowers 这类技能框架最大的价值是把你脑子里那些“默认的工程常识”显性化。以前这些常识只存在于老员工的习惯里新人来了靠口口相传现在它们变成了文件AI 能读新人能看团队能 review。这件事本身比“让 AI 写代码更快”要有意义得多。最后再分享一个小技巧每次 AI 输出让你不满意的时候别急着改代码先想想“这条规则我写进技能了吗”。写进去了下次就不会再犯没写那就补上。坚持一个月你会发现需要手动纠正的次数越来越少。