1. 拆解 superpowers它到底想解决什么问题第一次看到 “superpowers” 这个词加上旁边跟着的 agentic skills framework、software development methodology、Claude Code、Codex CLI 这几个关键词我大概花了不到十秒就判断出这不是一个普通的工具库。它更像是一套给 AI 编程助手“立规矩”的方法论框架核心目标是把 Claude Code、Codex CLI 这类终端里的智能体从“能聊几句代码”变成“能按工程规范干活”的角色。我最早接触这类东西是在去年帮一个朋友调试他的自动化脚本仓库。他当时用 Claude Code 做代码审查结果每次输出的格式都不一样有时候给建议有时候直接改文件有时候又只给一段解释。问题不在于模型能力不够而在于没有一套稳定的“行为契约”去约束它。superpowers 要解决的正是这个痛点它定义了一套技能框架让智能体在不同任务场景下知道该用什么工具、按什么流程走、输出成什么格式。这套框架适合谁如果你只是偶尔用 Claude Code 问几个语法问题那暂时不需要它。但如果你已经把 Claude Code 或 Codex CLI 接入了日常开发流程比如让它跑测试、改 bug、生成文档、做代码审查那你迟早会遇到“同一个指令每次结果不一样”的问题。superpowers 就是给这类场景准备的。它不挑模型Claude Code 能用Codex CLI 也能用甚至你通过第三方 API 接入其他模型只要接口兼容这套技能框架照样跑得起来。我下面会从设计思路、核心机制、实操配置、常见坑四个方向展开尽量把我在实际项目里踩过的弯路和总结出来的技巧都写清楚。文章里提到的具体命令和配置你可以直接抄作业但建议先理解背后的逻辑再动手不然出了问题排查起来会很痛苦。2. 核心设计思路为什么是“技能框架”而不是“提示词模板”2.1 从提示词工程到技能契约的转变很多人第一次听到 agentic skills framework 会下意识觉得“不就是写几个提示词吗”。我一开始也这么想直到我在一个真实项目里同时维护了二十多个提示词模板才发现问题所在。提示词模板是静态的你写一段话告诉模型“你要做代码审查”模型每次的理解都会有偏差。而技能框架是动态的它把每个任务拆成“触发条件、执行步骤、输出格式、异常处理”四个部分模型在执行时不是读一段描述而是加载一个结构化的技能定义。superpowers 的设计逻辑大概是这样它把软件开发中常见的动作抽象成一个个“技能”比如“审查代码变更”“生成单元测试”“重构函数”“解释报错”。每个技能都有明确的输入输出契约。当你对 Claude Code 说“帮我看看这个 PR”时框架会先匹配到“代码审查”这个技能然后按照技能定义里的步骤去执行而不是让模型自由发挥。这个转变带来的最大好处是可预测性。我实测下来同一个技能在 Claude Code 和 Codex CLI 上的输出结构基本一致差异只在模型本身的推理能力上。这对于团队协作特别重要因为你可以把技能定义当成团队规范的一部分新人接手时不需要重新学习“怎么跟 AI 说话”只需要知道有哪些技能可用。2.2 为什么选择终端智能体作为载体Claude Code 和 Codex CLI 这类终端工具本质上是一个“带文件系统和命令执行能力的对话界面”。它们比纯聊天窗口多了几个关键能力读写本地文件、执行 shell 命令、访问项目上下文。superpowers 选择在这类工具上落地而不是做一个独立的 GUI 应用原因很实际。第一终端工具天然贴近开发者的工作流。你不需要切换窗口不需要复制粘贴代码直接在项目目录里启动 Claude Code它就能看到整个仓库的结构。第二终端工具的执行能力让技能框架有了“手脚”。一个代码审查技能不只是输出一段文字它可以直接运行测试、检查 lint、对比 git diff然后把结果整合成一份报告。第三终端工具的配置可以版本化。你的技能定义、模型配置、项目上下文都可以放在仓库里团队共享这比每个人在自己电脑上配一套提示词要可靠得多。我试过在 VS Code 里通过插件调用 Claude Code也试过在 Ubuntu 终端里直接跑 Codex CLI体验上的差异主要在于上下文获取的便利性。VS Code 插件能自动把当前打开的文件和选中代码传给模型而终端工具需要你手动指定文件路径。但终端工具的优势在于可脚本化你可以把 superpowers 的技能调用写进 CI 流程让它在每次提交时自动跑一遍代码审查。2.3 框架的边界它不做什么这里要泼一盆冷水。superpowers 不是万能的它不负责模型推理能力的提升也不提供额外的算力。它做的事情是“约束”和“编排”把模型的能力引导到正确的方向上。如果你的模型本身在代码理解上就很弱那再好的技能框架也救不了。另外它不解决账号和网络问题。热词里提到的“claude code 注册账号和不注册有啥不同”“your organization has disabled claude subscription access”这些属于账号权限和地区可用性的范畴跟 superpowers 框架本身没有直接关系。框架只关心“模型接口能不能调通”至于你怎么拿到这个接口需要你自己解决。还有一个常见的误解是把它当成“自动化编程工具”。它确实能自动执行一些步骤但核心还是“辅助”不是“替代”。你仍然需要审查它的输出仍然需要对最终代码负责。我在实际使用中会把它的输出当成一个“高级草稿”而不是最终答案。3. 核心机制拆解技能定义、触发与执行链路3.1 技能定义的结构与编写要点一个 superpowers 技能定义通常包含几个关键字段技能名称、触发条件、前置检查、执行步骤、输出格式、失败处理。我用一个“生成单元测试”的技能来举例说明。技能名称要短且明确比如generate-unit-test。触发条件可以是一组关键词或正则表达式当用户的指令匹配到这些模式时框架就加载对应的技能。前置检查用来确认环境是否满足比如“项目根目录存在 package.json”或“目标文件有对应的测试目录”。执行步骤是核心通常是一组有序的操作比如“读取目标文件”“分析导出函数”“生成测试用例”“写入测试文件”“运行测试并报告结果”。输出格式定义最终返回给用户的内容结构比如“先列出生成的测试文件路径再展示测试运行结果最后给出覆盖率变化”。失败处理则规定当某一步骤出错时该怎么办比如“如果测试运行失败保留生成的测试文件并提示用户手动检查”。我踩过的一个坑是触发条件写得太宽泛。有一次我把“测试”这个词作为触发条件结果用户说“帮我测试一下这个接口”时框架错误地加载了单元测试生成技能而不是接口测试技能。后来我把触发条件改成更具体的模式比如“生成单元测试”“写测试用例”“补充测试覆盖”问题就解决了。注意技能定义的触发条件尽量用“动词名词”的组合避免单独使用名词否则很容易误触发。3.2 技能匹配与优先级机制当多个技能都可能匹配用户的指令时框架需要一个优先级机制来决定加载哪个。superpowers 通常采用“精确匹配优先、长匹配优先、显式指定优先”三条规则。精确匹配优先是指如果用户的指令完全等于某个技能的触发词那这个技能优先。长匹配优先是指如果两个技能的触发条件都能匹配匹配长度更长的那个优先。显式指定优先是指用户可以在指令里直接写技能名称比如“用 generate-unit-test 技能处理这个文件”这样框架会跳过自动匹配直接加载指定技能。这个机制在实际使用中很重要。比如你同时有“代码审查”和“安全审查”两个技能用户说“帮我审查这段代码的安全性”如果没有优先级机制框架可能随机选一个。有了长匹配优先“安全审查”的触发条件更长就会被选中。我在配置技能时会把最常用的技能放在前面但优先级规则本身不依赖顺序而是依赖匹配质量。这一点设计得比较合理避免了“谁先注册谁优先”的混乱。3.3 执行链路从指令到结果的完整流程一次完整的技能执行链路大概经过这几个阶段指令解析、技能匹配、上下文加载、步骤执行、结果汇总、输出格式化。指令解析阶段框架会把用户的自然语言指令拆成“意图”和“参数”。比如“帮我给 src/utils/date.js 生成单元测试”会被解析成意图“生成单元测试”和参数“src/utils/date.js”。技能匹配阶段根据意图找到对应技能。上下文加载阶段会读取项目配置、目标文件内容、相关依赖信息。步骤执行阶段按照技能定义逐步操作每一步都可能调用模型、执行命令或读写文件。结果汇总阶段把各步骤的输出整合起来。输出格式化阶段按照技能定义的格式返回给用户。这个链路里最容易出问题的是上下文加载。如果项目结构复杂或者目标文件依赖了其他模块框架需要决定加载多少上下文。加载太少模型理解不充分加载太多可能超出模型的上下文窗口。我在实际配置时会为每个技能设置一个“上下文预算”比如“最多读取目标文件及其直接依赖总 token 数不超过 8000”。这个预算需要根据你使用的模型来调整Claude Code 的上下文窗口比较大可以放宽一些Codex CLI 相对小一点需要更精细地控制。4. 实操配置从零搭建一套可用的技能框架4.1 环境准备与工具安装先确认你的基础环境。我用的是 Ubuntu 22.04macOS 上也可以Windows 需要 WSL 或者直接用桌面版。Claude Code 的安装方式根据平台不同有差异官方文档里有详细说明我这里只强调几个容易出问题的点。安装 Claude Code 之前确保 Node.js 版本在 18 以上。我遇到过因为 Node 版本太低导致安装脚本报错的情况升级到 20 LTS 之后就正常了。另外如果你在公司网络环境下可能需要配置代理才能访问外部资源这个具体怎么配取决于你的网络环境我不展开。Codex CLI 的安装相对简单但要注意它的命令和 Claude Code 有区别。热词里有人问“codex cli 命令哪些 /compact /model /resume”这些是 Codex CLI 的内置命令用来压缩上下文、切换模型、恢复会话。Claude Code 也有类似的命令但名称可能不同。建议安装完成后先跑一遍--help看看当前版本支持哪些命令。VS Code 的配置是另一个常见问题。如果你用 VS Code 接入 Claude Code需要安装对应的插件然后在设置里配置模型接口。我试过在 VS Code 里同时配 Claude Code 和 Codex CLI发现两者的配置项会互相干扰后来改成用不同的工作区分别配置问题就解决了。提示安装完成后先用一个简单的项目测试一下确认模型能正常读取文件和执行命令再开始配置技能框架。不然出了问题你分不清是安装问题还是技能配置问题。4.2 技能目录结构与文件组织superpowers 的技能定义通常放在项目根目录下的.superpowers/skills/目录里每个技能一个文件格式可以是 YAML 或 JSON。我倾向于用 YAML因为可读性更好写注释也方便。目录结构大概是这样.superpowers/ skills/ generate-unit-test.yaml review-code.yaml explain-error.yaml refactor-function.yaml config.yaml context/ project-summary.mdconfig.yaml里放全局配置比如默认模型、上下文预算、日志级别。context/目录放项目相关的上下文文件比如项目概述、架构说明、编码规范。这些文件会在技能执行时被加载帮助模型理解项目背景。我建议把.superpowers/目录纳入版本控制这样团队里每个人用的都是同一套技能定义。但要注意不要把敏感信息写进去比如 API key、数据库密码。这些应该通过环境变量传入而不是硬编码在配置文件里。4.3 编写第一个技能以代码审查为例我从最简单的代码审查技能开始。这个技能的目标是当用户要求审查代码时框架读取 git diff分析变更内容输出一份结构化的审查报告。技能定义大概长这样name: review-code triggers: - 审查代码 - review code - 看看这个改动 preconditions: - git repository exists steps: - action: run_command command: git diff --staged description: 获取暂存区的变更 - action: analyze prompt: 分析以下代码变更指出潜在问题、改进建议和风险点 - action: format_output template: review-report output: format: markdown sections: - 变更概述 - 问题列表 - 改进建议 - 风险提示 failure: - condition: no staged changes message: 暂存区没有变更请先 git add这个定义里triggers是触发条件preconditions是前置检查steps是执行步骤output是输出格式failure是失败处理。实际运行时框架会先检查是否在 git 仓库里然后执行git diff --staged获取变更把变更内容传给模型分析最后按照模板格式化输出。我实测下来这个技能在 Claude Code 和 Codex CLI 上都能跑但输出质量有差异。Claude Code 的分析更细致能指出一些边界情况Codex CLI 的输出更简洁适合快速浏览。你可以根据团队需求选择默认模型。4.4 模型接入与切换策略热词里提到“使用 cc switch 接入 deepseek v4, qwen, glm 等模型”这涉及到多模型切换的需求。superpowers 框架本身不限制模型只要接口兼容就行。你可以在config.yaml里配置多个模型然后为每个技能指定默认模型。我的策略是代码审查和重构用 Claude Code因为它的推理能力更强单元测试生成和文档生成用 Codex CLI因为它的输出更结构化如果遇到成本敏感的场景切换到第三方 API 接入的模型。切换模型时要注意上下文窗口的差异。Claude Code 的上下文窗口比较大可以加载更多项目上下文第三方模型的窗口可能小一些需要精简上下文。我在config.yaml里为每个模型单独设置了context_budget框架会根据当前使用的模型自动调整加载的上下文量。注意切换模型后建议先跑一遍回归测试确认技能输出格式没有变化。不同模型对同一提示词的理解可能有偏差尤其是输出格式的遵循程度。5. 常见问题与排查技巧实录5.1 技能不触发或误触发这是最常见的问题。技能不触发通常是因为触发条件写得太窄或者用户的指令表述和触发词不匹配。我遇到过一次用户说“帮我看看这段代码有没有问题”但我的触发词里只有“审查代码”和“review code”没有覆盖“看看有没有问题”这种口语化表达。后来我在触发词里加了一些同义表达问题就解决了。误触发则是相反的情况触发条件太宽泛。比如把“测试”作为触发词结果用户说“这个功能测试过了吗”也会触发单元测试生成技能。解决办法是让触发词更具体或者增加前置检查来过滤不匹配的场景。排查技巧打开框架的调试日志看看每次指令匹配到了哪个技能匹配分数是多少。如果匹配分数低于阈值说明触发条件需要调整。5.2 上下文加载失败或超限上下文加载失败通常是因为文件路径不对或者项目结构太复杂导致框架找不到目标文件。我建议在技能定义里明确指定上下文加载的范围比如“只加载目标文件及其直接依赖”避免框架盲目扫描整个项目。上下文超限是另一个问题。当加载的内容超过模型的上下文窗口时框架可能会截断内容或者报错。解决办法是设置context_budget并在技能定义里指定优先级比如“优先加载目标文件其次加载相关测试文件最后加载项目概述”。我踩过的一个坑是项目里有一个巨大的package-lock.json文件框架在加载上下文时把它也读进去了直接撑爆了上下文窗口。后来我在配置里加了排除规则把这类文件过滤掉。5.3 输出格式不一致不同模型对输出格式的遵循程度不一样。Claude Code 通常能很好地按照模板输出Codex CLI 有时候会自由发挥。解决办法是在技能定义里把输出格式写得更具体比如“用 Markdown 表格展示问题列表每行包含文件路径、行号、问题描述、严重程度”。如果格式还是不稳定可以在执行步骤里加一个“格式校验”步骤检查输出是否符合模板要求不符合就重新生成。这个步骤会增加一些 token 消耗但对于需要严格格式的场景是值得的。5.4 命令执行权限与安全问题Claude Code 和 Codex CLI 都能执行终端命令这带来了便利也带来了风险。我在配置技能时遵循一个原则只允许执行只读命令比如git diff、cat、ls禁止执行写操作命令比如rm、mv、git push。如果某个技能确实需要写操作我会在技能定义里明确标注并在执行前要求用户确认。另外命令执行的环境变量要控制好。不要把包含敏感信息的变量传给模型比如数据库连接串、API key。我见过有人在技能定义里直接写了export API_KEYxxx这是非常危险的做法。5.5 常见问题速查表问题现象可能原因排查方法解决措施技能不触发触发词不匹配查看调试日志的匹配分数增加同义触发词技能误触发触发条件太宽泛检查匹配到的技能名称收窄触发条件或加前置检查上下文加载失败文件路径错误检查目标文件是否存在修正路径或调整加载范围上下文超限加载了无关大文件查看加载的文件列表设置排除规则和上下文预算输出格式不一致模型遵循度差异对比不同模型的输出细化格式定义或加校验步骤命令执行报错权限不足或命令不存在手动执行相同命令检查权限和命令路径模型接口超时网络问题或接口限流查看错误日志重试或切换模型6. 进阶技巧让技能框架真正融入开发流程6.1 与 CI 流程集成把 superpowers 的技能调用写进 CI 流程可以在每次提交时自动跑代码审查和单元测试生成。我用的是 GitHub Actions在 workflow 里加一个步骤调用 Claude Code 执行review-code技能把输出保存成 artifact。这个做法的好处是审查结果有记录可以追溯团队成员不需要本地配置环境CI 里统一跑可以设置质量门禁比如审查发现严重问题就阻断合并。但要注意 CI 环境的资源限制。Claude Code 在 CI 里跑需要模型接口可用如果接口不稳定会导致 CI 失败。我的做法是设置重试机制并且把审查结果作为“建议”而不是“阻断条件”避免因为模型问题影响正常开发。6.2 技能版本管理与团队协作技能定义应该像代码一样管理。每次修改技能定义都要提交到版本控制并且写清楚修改原因。我建议给技能定义加一个版本号比如version: 1.2.0这样出问题时可以快速回滚。团队协作时不同成员可能对同一个技能有不同的需求。我的做法是核心技能由团队统一维护放在主分支个人定制技能放在自己的分支通过配置切换。这样既保证了团队规范的一致性又保留了个人的灵活性。6.3 性能优化减少 token 消耗和响应时间技能框架跑起来后token 消耗和响应时间是两个需要关注的指标。我通过几个手段来优化。第一精简上下文。只加载必要的信息不要把整个项目都塞给模型。第二缓存常用结果。比如项目概述、编码规范这些不常变的内容可以缓存起来不用每次都重新加载。第三并行执行独立步骤。比如代码审查里“检查 lint”和“分析变更”可以并行不用串行等待。第四设置合理的超时时间。避免某个步骤卡住导致整个技能执行失败。我实测下来优化之后单次代码审查的 token 消耗降低了大概四成响应时间从平均 45 秒降到 20 秒左右。这个提升在频繁使用的场景下感受很明显。6.4 扩展方向自定义技能与领域适配superpowers 的框架是开放的你可以根据自己的领域需求扩展技能。比如做数据科学的可以加“生成数据探索报告”技能做前端的可以加“检查组件可访问性”技能做后端的可以加“分析接口性能瓶颈”技能。扩展技能的关键是定义好输入输出契约。输入要明确需要哪些文件或参数输出要明确格式和内容范围。我建议先从一个小技能开始跑通之后再逐步增加复杂度。不要一上来就写一个“全能技能”那样很难调试和维护。我在实际项目里还试过把技能框架和飞书机器人结合通过飞书发送指令框架在服务器上执行技能然后把结果返回飞书。这个方案适合团队协作场景但需要额外处理消息格式和权限控制复杂度比本地使用高不少。7. 我个人在实际操作中的几点体会这套东西我用了大概半年最大的感受是技能框架的价值不在于“让 AI 更聪明”而在于“让 AI 更稳定”。模型本身的能力你控制不了但你可以控制它接收什么指令、按什么流程走、输出什么格式。superpowers 做的就是这件事。另一个体会是不要追求一步到位。我一开始想写一个覆盖所有场景的“超级技能”结果调试了两周都没跑通。后来拆成一个个小技能每个只做一件事反而很快就用起来了。现在我的技能库里有十几个小技能每个都很简单但组合起来能覆盖大部分日常开发场景。最后分享一个小技巧给每个技能加一个“示例输出”。在技能定义里放一段期望的输出样例模型在生成时会参考这个样例格式稳定性会明显提升。这个技巧是我从一位做提示词工程的朋友那里学来的实测有效。如果你也在用 Claude Code 或 Codex CLI 做日常开发建议花一个下午把 superpowers 的技能框架搭起来。前期投入的时间后面会以“不用反复调整提示词”的方式还给你。