★ FEATURED ARTICLE 1. 从“superpowers”说起这套技能框架到底在解决什么问题第一次看到superpowers这个词是在一个做 AI 辅助开发的群里。有人甩了张截图终端里敲了一行命令然后 Claude Code 就像被“开了光”一样开始按一套固定流程拆需求、写方案、跑测试、做复盘。当时我的第一反应是这不就是把软件工程那套方法论硬塞进 AI 编程工具里吗后来自己上手折腾了两周才发现事情没那么简单。superpowers本质上是一套agentic skills framework翻译过来叫“智能体技能框架”。它不绑定某一个具体的 AI 编程工具而是通过一套结构化的技能定义让 Claude Code、Codex CLI 这类命令行 AI 助手能够按照预设的软件工程方法论去工作。你可以把它理解成给 AI 装了一本“操作手册”——不是教它写代码而是教它怎么像一个有经验的工程师那样思考和组织工作。这套东西解决的核心痛点很明确默认状态下的 AI 编程助手你问一句它答一句上下文一长就忘任务一复杂就乱。你让它改个 bug它可能顺手把旁边的功能重构了你让它加个接口它可能连测试都不写。superpowers通过技能skills的形式把“需求分析、方案设计、编码实现、测试验证、代码审查”这些环节固化下来让 AI 在每一步都有明确的输入、输出和质量标准。适合谁来参考三类人最值得花时间研究。第一类是日常用 Claude Code 或 Codex CLI 写代码的开发者尤其是那种已经过了“哇 AI 能写代码”的新鲜期、开始被 AI 的不可控性折磨的人。第二类是技术团队负责人想给团队定一套 AI 辅助开发的规范但又不想自己从零造轮子。第三类是对 agentic 工作流感兴趣的技术爱好者想看看当前开源社区是怎么把软件工程方法论“翻译”成 AI 能执行的技能定义的。我自己的使用场景比较典型一个中等规模的 TypeScript 项目后端 Node.js前端 React用 Claude Code 做日常开发。没上superpowers之前我每次都要在 prompt 里重复交代“先写测试”“别动无关文件”“改完跑一遍 lint”说多了自己都烦。上了之后这些约束变成了技能定义的一部分AI 自己会按流程走我只需要在关键节点做决策。这个体验差异后面会详细展开。2. 核心设计思路拆解为什么是“技能”而不是“提示词”2.1 技能框架与普通提示词的本质区别很多人第一次接触superpowers会把它当成一套“高级提示词模板”。这个理解不能说错但不够准确。普通提示词是你每次对话时临时写给 AI 的指令用完就散而superpowers里的技能是持久化、可组合、可版本管理的资产。我打个比方。普通提示词像是你每次做饭前口头告诉厨师“少放盐、多放葱”技能框架则是你给厨师一本菜谱菜谱里写清楚了每道菜的标准流程、用料比例、火候控制厨师照着做就行而且这本菜谱还能不断修订、增补新菜。具体到技术实现上一个 skill 通常包含几个部分触发条件什么情况下启用这个技能、输入要求需要哪些上下文信息、执行步骤按什么顺序做什么事、输出规范产出物长什么样、质量检查点怎么判断做完了、做对了。这套结构让 AI 的行为从“随机应变”变成“有章可循”。2.2 为什么选择 Claude Code 和 Codex CLI 作为主要载体superpowers目前最主要的两个落地载体是 Claude Code 和 Codex CLI。这个选择背后有很实际的考量。Claude Code 的优势在于它的工具调用能力和上下文管理。它原生支持读写文件、执行命令、搜索代码库这些能力是技能框架能跑起来的基础。你让一个只能聊天的 AI 去执行“先跑测试再改代码”的流程它做不到因为它没有执行测试的工具。Claude Code 有所以技能定义里的“执行步骤”才能真正落地。Codex CLI 则是另一个路数。它更轻量更偏向命令行原生体验适合那些不想离开终端、喜欢用管道和脚本串联工作流的开发者。superpowers在 Codex CLI 上的实现更多是利用它的非交互式执行能力把技能定义成可以在 CI/CD 流水线里调用的命令。我两个都试过。Claude Code 上的体验更“重”适合复杂的多步骤任务Codex CLI 上的体验更“轻”适合快速、重复性的检查类任务。选哪个取决于你的工作习惯和任务类型。2.3 软件工程方法论的“技能化”翻译superpowers最核心的价值在于它把软件工程里那些“老生常谈”的方法论翻译成了 AI 能执行的技能定义。这个翻译过程不是简单的文字转换而是需要解决几个关键问题。第一个问题是粒度。方法论说“要做代码审查”但代码审查具体查什么superpowers会把它拆成检查命名规范、检查错误处理、检查边界条件、检查测试覆盖、检查文档更新。每个检查项都有明确的判断标准AI 才能执行。第二个问题是顺序依赖。方法论说“先设计后编码”但 AI 怎么知道设计做完了superpowers通过产出物检查来解决设计阶段的产出是一份设计文档文档里必须包含接口定义、数据流图、异常处理策略缺一项就不算完成不能进入编码阶段。第三个问题是回退机制。如果编码阶段发现设计有问题怎么办superpowers允许技能定义里包含“回退到上一阶段”的指令而不是硬着头皮往下走。这个设计很关键因为 AI 很容易“将错就错”有了回退机制才能保证质量。2.4 技能组合与工作流编排单个技能解决单个问题但真实开发任务是多个问题的组合。superpowers支持技能的组合调用形成一个完整的工作流。比如一个“实现新功能”的工作流可能包含这些技能需求澄清技能、方案设计技能、测试先行技能、编码实现技能、代码审查技能、文档更新技能。每个技能有自己的触发条件和完成标准前一个技能完成后自动触发下一个。这个编排能力是superpowers区别于零散提示词的关键。它让 AI 的工作从“单点响应”变成“流程执行”从“你问我答”变成“任务驱动”。3. 安装与配置实操从零把环境跑起来3.1 Claude Code 的安装与基础配置先说 Claude Code 的安装。不同系统下的步骤略有差异我分别说一下我实际操作过的路径。在 macOS 或 Linux 上最直接的方式是通过 npm 全局安装。前提是你本地有 Node.js 环境建议版本在 18 以上。命令很简单npm install -g anthropic-ai/claude-code装完之后在终端输入claude就能启动。第一次启动会引导你做认证配置按提示走就行。Windows 上的情况稍微复杂一点。原生 Windows 终端对某些命令行工具的支持不够好我实测下来最稳的方案是用 WSL2。在 WSL2 的 Ubuntu 环境里安装步骤和 Linux 完全一致。如果你非要在 PowerShell 里跑也不是不行但可能会遇到路径分隔符、权限之类的小问题排查起来费时间。Ubuntu 上还有一个坑某些版本的 npm 默认安装路径不在 PATH 里。装完之后如果提示command not found检查一下~/.npm-global/bin或者/usr/local/bin是否在 PATH 中。这个不是 Claude Code 的问题是 npm 配置的问题但很多人第一次装会卡在这里。VSCode 里用 Claude Code 的话推荐装官方插件然后在 VSCode 的集成终端里启动。这样文件路径和编辑器上下文能自动同步体验比在外部终端好很多。3.2 Codex CLI 的安装与常见报错处理Codex CLI 的安装方式取决于你用的版本。开源社区维护的 Codex CLI 通常通过 npm 或直接下载二进制文件安装。npm 方式npm install -g openai/codex装完之后输入codex验证。如果报错unable to locate the codex cli binary or required runtime components大概率是两个原因一是 npm 全局 bin 目录没在 PATH 里二是缺少运行时依赖比如某些系统库。排查思路是这样的先which codex看看能不能找到可执行文件。找不到的话npm config get prefix看看全局安装路径然后手动把这个路径加到 PATH。找得到但运行报错的话用lddLinux或otool -LmacOS检查动态库依赖缺什么补什么。Windows 上装 Codex CLI同样推荐 WSL2。如果坚持用原生 Windows注意把终端换成 Windows Terminal并且确保 PowerShell 的执行策略允许运行脚本。codex cli如何更新这个问题也常被问到npm 安装的话npm update -g openai/codex就行二进制安装的话重新下载覆盖。3.3 superpowers 的安装与技能目录结构superpowers本身的安装取决于你用的是哪个发行版。社区里比较活跃的几个版本安装方式大同小异要么是通过包管理器装要么是手动把技能定义文件放到指定目录。手动安装的话核心是搞清楚技能目录的位置。Claude Code 默认会从几个位置加载技能项目根目录下的.claude/skills/、用户主目录下的.claude/skills/、以及通过环境变量指定的额外路径。superpowers的技能文件通常是一堆 Markdown 或 YAML 文件每个文件定义一个技能。我建议的做法是项目级技能放项目目录通用技能放用户目录。项目级的技能可以跟着代码库一起版本管理团队共享用户级的技能是你个人的工作习惯不跟项目走。这个分层策略后面会详细说。安装完成后验证是否生效的方法很简单启动 Claude Code输入一个触发技能的关键词看它是否按技能定义的流程响应。比如你装了一个“测试先行”技能输入“帮我加个函数”它应该先问你测试怎么写而不是直接给实现。3.4 验证安装与最小可用示例装完不验证等于没装。我习惯用一个最小示例来确认整套东西跑通了。找一个空目录初始化一个最简单的项目比如一个只有index.js的 Node 项目。然后启动 Claude Code输入“用 superpowers 的流程帮我给这个项目加一个加法函数”。如果技能框架生效你应该看到 AI 不是直接写代码而是先做需求澄清问你这个函数要不要处理非数字输入、再写测试、再实现、最后跑测试验证。整个过程有明确的阶段划分而不是一口气输出一堆代码。这个最小示例能帮你确认三件事技能是否被正确加载、工作流是否按预期编排、工具调用是否正常。任何一环出问题都能在这个简单场景里暴露出来比在复杂项目里排查容易得多。4. 核心技能解析与实操要点4.1 需求澄清技能把模糊需求变成可执行任务需求澄清是superpowers工作流的第一个环节也是最容易被忽视的环节。很多人用 AI 写代码上来就说“帮我做个登录功能”然后 AI 给了一堆代码结果发现跟自己想要的完全不一样。问题不在 AI在需求本身就没说清楚。superpowers的需求澄清技能核心是让 AI主动提问而不是被动执行。它会从几个维度去澄清功能边界做什么、不做什么、输入输出接收什么、产出什么、异常情况出错怎么办、性能要求响应时间、并发量、兼容性要求跟现有系统怎么对接。我实操下来的感受是这个环节能省掉后面大量的返工。有一次我让 AI 做一个“数据导出”功能它先问了我五个问题导出格式是 CSV 还是 JSON、数据量大概多大、要不要支持筛选、导出是同步还是异步、失败要不要重试。这五个问题问完实现方案基本就清晰了后面写代码一气呵成。注意需求澄清技能的关键是“问对问题”。如果 AI 问的问题太泛比如“你有什么要求”说明技能定义的质量不够需要补充更具体的提问模板。4.2 方案设计技能先画图纸再动工需求澄清完进入方案设计。这个技能要求 AI 产出一份设计文档而不是直接写代码。设计文档的内容包括模块划分、接口定义、数据结构、关键流程、异常处理策略、测试策略。为什么非要先设计因为 AI 的上下文是有限的直接写代码容易“只见树木不见森林”。先设计相当于先画一张地图后面写代码时随时可以对照地图不容易跑偏。我自己的经验是方案设计阶段最值得花时间的是接口定义。把函数签名、参数类型、返回值类型定清楚后面实现就是填空。如果接口没定好实现阶段改来改去测试也得跟着改效率反而低。设计文档的格式不用太正式Markdown 就行。关键是内容要具体不能写“设计一个合理的接口”而要写“接口接收 userId 和 dateRange返回一个包含 records 数组和 total 计数的对象records 里每条记录包含 id、timestamp、amount 三个字段”。4.3 测试先行技能让 AI 自己给自己出考卷测试先行是superpowers里我最喜欢的技能。它的逻辑很简单写实现之前先写测试测试通过了实现才算完成。这个技能的价值在于它给 AI 提供了一个自我验证的闭环。没有测试的时候AI 写完代码说“完成了”你也不知道对不对得自己跑一遍。有了测试AI 写完代码自己跑测试跑不过就继续改改到跑过为止。你拿到的是一个已经验证过的实现而不是一个“看起来对”的实现。实操中要注意的是测试的粒度。测试太粗覆盖不到边界情况测试太细维护成本高。我的经验是每个函数至少覆盖正常输入、边界输入空值、极值、异常输入类型错误、越界。这三类覆盖到了基本就够用了。还有一个坑AI 写的测试有时候会“迎合”实现就是实现怎么写它就怎么测失去了测试的意义。避免这个问题的方法是在技能定义里明确要求“测试用例必须基于需求文档而不是基于实现代码”。这样 AI 写测试时会参考需求而不是参考自己刚写的代码。4.4 代码审查技能AI 审 AI 的代码代码审查技能是让 AI 用“审查者”的视角重新看一遍自己写的代码。这个环节能发现很多实现阶段忽略的问题命名不一致、重复代码、错误处理缺失、注释过期、性能隐患。我实测下来AI 审查自己代码的效果比审查别人代码要差一些因为它有“作者偏见”。但即便如此还是能抓到不少问题。尤其是那些“写的时候觉得没问题、回头看才发现不对”的地方审查环节经常能发现。提高审查效果的一个技巧是让审查技能使用不同的提示词模板。实现阶段用的是“实现者”视角关注“怎么把功能做出来”审查阶段用的是“审查者”视角关注“这样做有没有问题”。视角切换了发现问题的概率就高了。审查技能的产出通常是一份问题清单每个问题标注严重程度阻塞、重要、建议和修改建议。AI 根据这份清单决定是直接修改还是回退到设计阶段。这个决策逻辑也要在技能定义里写清楚否则 AI 容易“自作主张”。4.5 技能组合与工作流编排实战单个技能用熟了之后就可以玩组合了。superpowers的工作流编排本质上是把多个技能串成一条流水线。我常用的一个工作流是这样的需求澄清 → 方案设计 → 测试先行 → 编码实现 → 代码审查 → 文档更新。每个环节的产出物是下一个环节的输入任何一个环节不通过就回退。这个工作流跑一个中等复杂度的功能比如一个带分页和筛选的列表接口大概需要 15 到 20 轮对话。听起来不少但考虑到它把需求、设计、实现、测试、审查全包了而且每步都有产出物实际效率比我自己从头写要高。编排的时候要注意技能之间的衔接。比如需求澄清的产出是一份需求文档方案设计技能要能读取这份文档作为输入。这要求技能定义里明确写清楚“输入来源”和“输出格式”否则 AI 在切换技能时会丢失上下文。5. 常见问题与排查技巧实录5.1 安装类问题速查问题现象可能原因排查方法解决方案command not found全局 bin 目录不在 PATHnpm config get prefix把输出路径加入 PATHunable to locate codex cli binary二进制未安装或路径错误which codex重新安装或手动指定路径认证失败凭证过期或配置错误检查配置文件重新执行认证流程技能不生效技能目录位置错误检查.claude/skills/移动到正确目录权限报错文件权限不足ls -la查看权限chmod调整权限这张表是我踩坑之后整理的基本覆盖了 90% 的安装问题。其中“技能不生效”是最常见的多数情况是技能文件放错了目录或者文件格式不对比如 YAML 缩进错了。5.2 技能加载失败的排查思路技能加载失败的表现是AI 不按技能定义的流程走还是老样子一问一答。排查步骤分三层。第一层确认技能文件存在且格式正确。Markdown 文件检查标题层级YAML 文件检查缩进和语法。我遇到过好几次是 YAML 里用了 Tab 而不是空格导致解析失败。第二层确认技能目录被正确加载。Claude Code 启动时会在日志里输出加载了哪些技能如果日志里没有你的技能说明目录配置有问题。检查环境变量和配置文件里的路径设置。第三层确认技能触发条件匹配。有些技能定义了特定的触发关键词如果你的输入不包含这些关键词技能不会被激活。这个设计是为了避免技能“过度触发”但有时候也会导致“该触发的时候没触发”。解决办法是在技能定义里放宽触发条件或者手动指定使用某个技能。5.3 工作流中断与上下文丢失的处理工作流跑到一半中断是另一个高频问题。表现是 AI 突然“忘了”之前的设计开始自由发挥。原因通常是上下文窗口满了早期的对话被截断了。处理这个问题有两个思路。一是控制单个技能的上下文消耗把大段的代码和文档放到外部文件里技能定义里只引用文件路径不把内容全塞进对话。二是在关键节点做检查点把当前状态需求文档、设计文档、测试结果保存到文件里中断后可以从检查点恢复。我自己的做法是每个技能完成后让 AI 把产出物写入一个固定的文件比如.superpowers/state/current-design.md。下一个技能启动时先读这个文件而不是依赖对话历史。这样即使对话被截断工作流也能继续。5.4 技能冲突与优先级问题装了多个技能之后可能会遇到技能冲突两个技能都想处理同一个输入或者一个技能的产出被另一个技能覆盖。解决冲突的核心是优先级定义。在技能定义里可以指定优先级数值数值高的先执行。或者用更明确的触发条件让每个技能只在自己擅长的场景下激活。我遇到过一个典型冲突一个“快速修复”技能和一个“完整流程”技能都响应“修 bug”这个输入。快速修复直接改代码完整流程走需求澄清到代码审查。两个同时触发就乱了。解决办法是给它们不同的触发词比如“快速修一下”触发前者“按流程修”触发后者。5.5 性能优化与资源占用控制superpowers跑起来之后资源占用主要来自两个方面AI 的推理调用和本地工具的执行。推理调用是主要开销尤其是工作流长的时候一轮下来可能几十次调用。优化思路有几个。一是合并技能把一些简单的、经常连续出现的技能合并成一个减少切换开销。二是缓存中间结果需求文档、设计文档这些产出物缓存起来避免重复生成。三是按需加载技能不是所有技能都需要常驻用不到的技能不加载减少启动时的解析开销。实测下来一个中等复杂度的工作流优化前跑一轮大概 3 到 5 分钟优化后能压到 2 分钟左右。提升不算巨大但日积月累下来差别明显。6. 进阶玩法把 superpowers 接入现有开发流程6.1 与版本控制的结合superpowers的产出物需求文档、设计文档、测试文件、实现代码都应该纳入版本控制。我的做法是每个工作流跑完让 AI 自动生成一个 commitcommit message 里包含工作流的阶段信息。这样做的好处是工作流的历史可追溯。哪天发现某个功能的实现有问题可以顺着 commit 历史往回查看是需求阶段就错了还是设计阶段跑偏了还是实现阶段引入了 bug。技能定义文件本身也应该版本控制。团队共享的技能放在项目仓库里个人技能放在 dotfiles 仓库里。技能更新了团队成员拉一下代码就能同步。6.2 在 CI/CD 流水线中调用技能Codex CLI 的非交互式执行能力让它很适合在 CI/CD 里跑。比如在 PR 提交时自动触发一个“代码审查”技能把审查结果作为评论贴到 PR 上。这个玩法的关键是技能的输出格式要机器可读。审查结果不能是一段自然语言而应该是结构化的 JSON 或 Markdown 表格方便 CI 系统解析和展示。我试过在 GitHub Actions 里跑一个简化版的审查技能效果还不错。它不能替代人工审查但能抓到一些明显的规范问题减少人工审查的负担。6.3 团队协作中的技能共享与定制团队用superpowers最大的价值是统一工作标准。大家用同一套技能定义产出物的格式和质量标准就一致了代码审查和交接的成本都降低了。但统一不等于一刀切。不同项目、不同技术栈需要的技能可能不一样。我的建议是基础技能团队共享项目技能项目自定个人技能个人自定。三层结构既保证了一致性又保留了灵活性。技能共享的载体可以是 Git 仓库也可以是内部的包管理服务。关键是版本管理要做好技能更新了要通知到使用的人避免有人用旧版本踩坑。6.4 技能定义的迭代与维护技能定义不是写完就完了需要持续迭代。迭代的驱动力来自两个方面一是使用中发现的不足比如某个技能总是漏掉某个检查项二是工作流程的变化比如团队引入了新的测试框架测试先行技能需要更新。我自己的迭代节奏是每跑完一个完整工作流花五分钟回顾一下哪个环节卡住了、哪个产出物质量不够、哪个技能触发不顺畅。攒够几个问题就集中改一次技能定义。技能定义的修改也要走版本控制每次修改记录改了什么、为什么改。这样过一段时间回头看能清楚看到工作流的演进过程。7. 我踩过的坑与实操心得7.1 不要一上来就追求全自动我刚开始用superpowers的时候恨不得把所有环节都自动化从需求到部署一条龙。结果发现全自动的代价是失控。AI 在某个环节做了个错误决策后面全跟着错等你发现的时候已经跑偏很远了。后来我改成半自动关键决策点需求确认、设计评审、审查结果处理由我手动确认其他环节自动跑。这样既保留了效率又保证了方向可控。实测下来半自动的总体效率反而比全自动高因为返工少了。7.2 技能定义要“具体到能执行”写技能定义最容易犯的错误是太抽象。比如写“检查代码质量”AI 不知道检查什么。要写成“检查函数命名是否符合 camelCase、检查每个函数是否有错误处理、检查是否有未使用的变量”这样 AI 才能执行。我的经验是技能定义里的每一条指令都要能回答“AI 具体做什么动作”。如果一条指令需要 AI“理解”或“判断”那就要补充判断标准。标准越具体执行越稳定。7.3 上下文管理比技能定义更重要用了一段时间之后我发现工作流跑得顺不顺很大程度上取决于上下文管理而不是技能定义本身。技能定义得再好上下文丢了AI 还是抓瞎。所以我现在花在上下文管理上的时间比花在技能定义上的还多。具体做法包括产出物落盘、关键信息摘要、对话历史定期清理、外部文件引用代替内容内联。这些做法看起来琐碎但效果立竿见影。7.4 给 AI 留“说不”的空间最后一个心得可能有点反直觉不要逼 AI 在所有情况下都按流程走。有些任务就是很简单走完整流程反而浪费时间。有些任务就是很模糊强行澄清也澄清不出什么。我在技能定义里加了一个“跳过”机制如果 AI 判断当前任务不适合走完整流程可以提议跳过某些环节由我确认。这个机制让工作流更灵活不会为了流程而流程。superpowers这套东西说到底是个工具。工具的价值在于用的人怎么用。我见过有人把它当银弹装完就指望 AI 全自动写代码也见过有人把它当脚手架根据自己的习惯裁剪改造。后者才是正确的打开方式。技能框架提供的是结构和约束真正的效率提升来自于你在这个结构里找到适合自己的节奏。
阅读完成 · 觉得有帮助？
