★ FEATURED ARTICLE 1. 从“superpowers”说起一个让 AI 编码助手真正长出“工程肌肉”的技能框架第一次看到 “superpowers” 这个词是在几个做 AI 辅助开发的朋友群里。有人甩了张截图说“这玩意儿装完之后Claude Code 像换了个脑子”。我当时的第一反应是又一个包装提示词的噱头。但耐着性子把它的设计思路翻完之后我改主意了——它解决的是一个非常具体、非常痛的问题AI 编码助手很聪明但它不懂“工程规矩”。你肯定有过这种体验让 Claude Code 或者 Codex CLI 帮你写个功能它三下五除二给你吐出一大段代码跑起来也能用但代码风格飘忽、没有测试、边界条件全靠运气、改两行就崩。问题不在模型能力而在于它默认的“工作方式”是一次性生成而不是工程化交付。superpowers 这个 agentic skills framework 要做的就是给 AI 助手装上一套“软件开发的肌肉记忆”——需求先澄清、方案先设计、代码先测试、改完先验证。它本质上是一套软件开发的技能框架把资深工程师的工作流拆成一个个可复用的 skill让 AI 在每一步都按规矩来。这篇文章适合三类人看一是已经在用 Claude Code、Codex CLI 但觉得“差点意思”的开发者二是想把这套方法论迁移到自己团队 AI 工作流里的技术负责人三是刚接触 agentic 工具、想知道“除了聊天还能干嘛”的新手。我会把 superpowers 的核心设计、安装配置、实操流程、踩坑经验全部拆开讲代码和命令都能直接抄。注意本文讲的是方法论和工具使用不涉及任何网络访问相关的操作所有安装都基于官方公开渠道。2. superpowers 到底解决了什么问题AI 编码的“最后一公里”2.1 为什么“能写代码”不等于“能交付代码”我先说个真实场景。上个月帮一个朋友看他的小项目他用 Claude Code 生成了一个用户注册模块代码逻辑没问题但打开一看密码明文存了、没有输入校验、异常处理是空的、连个单元测试都没有。他跟我说“AI 写的我也不太懂”。这就是典型的生成即完成的错觉。AI 编码助手的能力边界很清楚它擅长把“明确的意图”翻译成“可运行的代码”但它不擅长主动补全工程约束。什么叫工程约束就是那些“你不说它就不做但做了才叫专业”的东西——错误处理、边界测试、日志、类型定义、依赖管理、代码分层。superpowers 的核心价值就是把这些约束固化成 AI 必须走的流程。它的设计逻辑我拆成三层来理解第一层是技能skill每个 skill 是一个独立的、可复用的工作单元比如“写测试”“做代码审查”“设计接口”。skill 不是提示词模板而是带执行步骤和验收标准的流程定义。第二层是编排orchestration框架决定在什么阶段调用哪个 skill。比如接到一个新需求先走“需求澄清”skill再走“方案设计”skill最后才进“编码”skill。第三层是验证verification每个 skill 执行完都有明确的产出物和检查点AI 不能跳过验证直接进入下一步。这三层叠起来AI 的工作方式就从“一次性生成”变成了“分阶段交付”。这个转变听起来简单但实际效果差别巨大——我实测下来同一个需求走 superpowers 流程产出的代码返工率能降一半以上。2.2 和直接写提示词的本质区别有人会问我直接在提示词里写“请先写测试再写代码”不就行了我试过不行。原因有两个。第一提示词是软的流程是硬的。你在提示词里写“请写测试”AI 可能写也可能因为上下文太长忘了写。而 superpowers 把测试作为编码 skill 的前置依赖不完成测试环节编码环节根本不会启动。这是机制上的强制不是靠 AI 自觉。第二提示词是一次性的skill 是可积累的。你今天写一段提示词让 AI 做代码审查明天换个项目又得重写。而 skill 是文件化的、可版本管理的、可跨项目复用的。你团队里沉淀下来的 skill 越多AI 的“工程素养”就越高。这才是 agentic skills framework 真正的价值——它让 AI 的能力可沉淀、可传承。提示不要把 superpowers 理解成“更长的提示词”。它的核心是流程编排和技能复用提示词只是 skill 内部的一个组成部分。2.3 适用场景与不适用场景不是所有任务都值得上这套框架。我总结了一个简单的判断标准场景类型是否适合原因新功能开发多文件、有逻辑适合需要设计、测试、验证全流程重构现有代码适合需要先理解现状再动手skill 能强制“先读后写”写一次性脚本不太适合流程开销大于收益改个配置、调个参数不适合直接改更快学习新技术、做实验看情况可以用“探索”类 skill但不必走完整流程我的经验是任务越复杂、越需要多人协作、越需要长期维护superpowers 的价值就越大。反过来如果你只是想让 AI 帮你写个正则表达式那确实没必要。3. 环境准备Claude Code 与 Codex CLI 的安装配置3.1 先搞清楚你要用哪个宿主工具superpowers 本身是一个技能框架它需要宿主工具来承载——也就是实际执行 AI 对话和代码操作的那个 CLI 或 IDE 插件。目前主流的有两个Claude Code和Codex CLI。两者都能跑 superpowers但体验有差异。Claude Code 是 Anthropic 官方出的命令行工具优势是和 Claude 模型深度集成skill 的调用和上下文管理做得比较顺。Codex CLI 是另一套命令行工具优势是模型选择更灵活可以接不同的后端。我两个都用过说下实际感受如果你主要用 Claude 系列模型优先选 Claude Code配置简单skill 兼容性好。如果你需要切换不同模型比如某些任务用这个、某些任务用那个Codex CLI 更合适。如果你在 VS Code 里工作两个都有对应的插件Claude Code for VS Code 的体验更完整一些。下面我分别讲安装。所有安装都基于官方公开的包管理渠道不涉及任何特殊网络配置。3.2 Claude Code 的安装与初始化Claude Code 的安装依赖 Node.js 环境。先确认你的 Node 版本node -v npm -v建议 Node 18 以上。如果版本太低先升级 Node。然后安装 Claude Codenpm install -g anthropic-ai/claude-code安装完成后进入你的项目目录运行claude第一次运行会引导你做初始化配置。这里有个新手最容易卡住的点它会要求你登录或配置 API 访问方式。如果你用的是官方订阅按引导登录即可如果你用的是第三方 API 或本地模型需要额外配置。关于本地模型的接入我在第 5 章会专门讲。初始化完成后你会看到 Claude Code 的交互界面。这时候输入/help可以看到所有可用命令。几个高频命令先记一下/compact压缩当前对话上下文长会话必备/model切换模型/resume恢复之前的会话/clear清空当前上下文注意如果你在安装过程中遇到 “your organization has disabled claude subscription access” 这类提示通常是账号权限或组织策略问题需要检查你的账号配置而不是工具本身的问题。3.3 Codex CLI 的安装与常见坑Codex CLI 同样基于 Node.js。安装命令npm install -g openai/codex这里我要重点说一个很多人踩过的坑node安装codex cli很慢。这不是你的网络问题而是 npm 默认源在拉取某些依赖时确实慢。解决办法是配置国内镜像源npm config set registry https://registry.npmmirror.com配完之后再装速度会快很多。如果已经装了一半卡住先卸载再重装npm uninstall -g openai/codex npm install -g openai/codex安装完成后运行codex进入交互界面。Codex CLI 的命令体系和 Claude Code 略有不同常用的有/compact压缩上下文/model切换模型/resume恢复会话如果你要删除 Codex CLI用npm uninstall -g openai/codex3.4 VS Code 插件配置要点如果你习惯在 VS Code 里工作两个工具都有插件。Claude Code for VS Code 的配置相对简单装完插件后在设置里填入你的 API 配置即可。有几个配置项值得注意模型选择插件里可以指定用哪个模型建议和 CLI 保持一致避免行为差异。上下文范围插件默认会把当前打开的文件作为上下文如果项目大建议手动控制不然 token 消耗很快。终端集成Claude Code 可以直接执行终端命令这个功能在插件里也能用但建议先在小项目里试确认行为符合预期再放开。Ubuntu 和 Mac 上的配置流程基本一致主要差异在 Node 环境的安装方式。Ubuntu 上建议用nvm管理 Node 版本Mac 上用brew更省事。Windows 用户要注意某些版本可能存在兼容性问题如果遇到 “与64位版本不兼容” 的提示优先检查 Node 和 npm 的位数是否匹配。4. superpowers 的核心机制技能框架是怎么运转的4.1 skill 的文件结构与组织方式superpowers 的 skill 本质上是结构化的 Markdown 文件放在项目的特定目录下。一个典型的 skill 文件包含几个部分# Skill: 编写单元测试 ## 触发条件 当需要为新功能或修改的功能编写测试时 ## 前置依赖 - 已完成需求澄清 - 已确定接口定义 ## 执行步骤 1. 读取目标函数的签名和文档 2. 识别所有输入边界和异常路径 3. 为每个边界生成测试用例 4. 运行测试并确认全部通过 ## 验收标准 - 测试覆盖率不低于 80% - 所有边界条件都有对应用例 - 测试可独立运行不依赖外部状态这个结构的关键在于前置依赖和验收标准。前置依赖确保 skill 不会在错误的时机被调用验收标准确保执行结果可检查。这两点是把“提示词”升级成“流程”的核心。我建议你在组织 skill 时遵循一个原则一个 skill 只做一件事。不要写“写代码并测试并部署”这种大杂烩拆成“写代码”“写测试”“部署”三个独立 skill编排层负责把它们串起来。这样每个 skill 都容易维护、容易复用、容易替换。4.2 编排层如何决定“下一步做什么”编排层是 superpowers 的“大脑”。它根据当前任务的状态决定调用哪个 skill。这个决策逻辑通常基于两个输入任务类型和当前进度。举个例子当你给 AI 一个“实现用户登录功能”的任务时编排层的决策链大致是任务类型是“新功能开发”进入开发流程当前进度是“零”先调用“需求澄清”skill需求澄清完成后调用“方案设计”skill方案确认后调用“接口定义”skill接口定义完成后调用“编写测试”skill测试通过后调用“编写实现”skill实现完成后调用“代码审查”skill每一步的产出物都是下一步的输入形成一条可追溯的交付链。这个链条的价值在于任何一步出问题你都能定位到具体环节而不是面对一坨“AI 生成的代码”无从下手。4.3 验证机制让 AI 不能“糊弄过去”验证机制是我认为 superpowers 最被低估的部分。大多数 AI 工具的问题是AI 说“完成了”但你不知道它到底完成了没有。superpowers 通过强制产出物检查来解决这个问题。每个 skill 执行完必须产出可验证的结果。比如“编写测试”skill 的产出物是测试文件和测试运行报告“代码审查”skill 的产出物是审查意见列表。编排层会检查这些产出物是否存在、是否符合验收标准不符合就打回重做。这个机制的实际效果是AI 没法用“我觉得可以了”来蒙混过关。它必须拿出实际的东西。我实测下来这个约束能显著减少“看起来完成了但实际不能用”的情况。提示验证标准要写得具体、可量化。“代码质量好”不是标准“函数复杂度不超过 10、无重复代码块”才是标准。5. 实操全流程从零跑通一个 superpowers 项目5.1 项目初始化与 skill 目录搭建假设你有一个新项目想用 superpowers 来管理 AI 的开发流程。第一步是建立 skill 目录结构。我常用的结构是这样的project/ ├── .superpowers/ │ ├── skills/ │ │ ├── requirement-clarify.md │ │ ├── design.md │ │ ├── write-test.md │ │ ├── implement.md │ │ └── review.md │ └── config.yaml ├── src/ └── tests/.superpowers/skills/放所有 skill 文件config.yaml放编排配置。config 里主要定义两件事流程顺序和每个阶段的验收标准。workflow: - name: requirement-clarify next: design - name: design next: write-test - name: write-test next: implement - name: implement next: review - name: review next: done这个配置告诉编排层接到新任务后按这个顺序走。每个 skill 完成后自动进入下一个除非验收不通过。5.2 需求澄清 skill 的实际执行需求澄清是整条链的起点也是最容易被跳过的一步。很多人觉得“需求很清楚啊直接写就行了”但实际执行下来这一步能省掉后面大量的返工。我写的需求澄清 skill 大致是这样的# Skill: 需求澄清 ## 目标 把模糊的需求转化为明确的、可验证的功能描述 ## 执行步骤 1. 用一句话复述需求确认理解无误 2. 列出所有不确定的点逐条向用户确认 3. 明确输入、输出、边界条件 4. 明确不做什么范围外事项 5. 输出需求文档等待用户确认 ## 验收标准 - 需求文档包含明确的输入输出定义 - 所有歧义点都已澄清 - 用户明确确认实际跑的时候AI 会先复述你的需求然后抛出一堆问题“用户登录失败时返回什么”“密码错误几次锁定”“是否需要记住登录状态”这些问题你平时可能想不到但都是实现时必须回答的。这一步的价值就是把“实现时才发现的坑”提前到“动手前就填平”。5.3 测试先行让 AI 先写测试再写实现测试先行是 superpowers 流程里最“反直觉”但最有效的一环。大多数人让 AI 写代码的顺序是“先实现再补测试”但 superpowers 强制反过来先写测试测试通过后再写实现。为什么因为测试是对需求的可执行验证。你先写测试等于先把“什么叫完成”定义清楚了。AI 写实现的时候目标就变成了“让这些测试通过”而不是“写一段看起来对的代码”。这个目标转变能极大减少“代码能跑但不符合需求”的情况。实际操作时write-test skill 会读取需求文档和接口定义为每个功能点生成测试用例运行测试确认全部失败因为实现还没写输出测试报告第 3 步很关键——测试必须先失败。如果测试一开始就通过说明测试写错了或者测的是已有功能。这个“红-绿-重构”的节奏是测试驱动开发的核心superpowers 把它固化进了流程。5.4 实现与审查闭环是怎么形成的测试写完后进入 implement skill。这时候 AI 的任务很明确写最少的代码让所有测试通过。这个约束很重要它防止 AI 过度设计、写一堆用不上的代码。实现完成后自动进入 review skill。代码审查不是走过场它有具体的检查项检查项标准不通过的处理测试覆盖所有新增函数都有测试打回补测试边界处理所有输入边界都有处理打回补边界错误处理异常路径有明确处理打回补异常代码重复无重复代码块打回重构命名规范符合项目约定打回重命名审查不通过就打回上一步直到全部通过。这个闭环跑下来产出的代码质量比我手动写再让 AI 补测试要高不少。核心原因是每一步都有明确的验收标准AI 没有“差不多就行”的空间。6. 进阶玩法本地模型接入与多模型切换6.1 用本地模型跑 Claude Code 的思路有些场景下你可能想用本地模型来跑 Claude Code比如数据敏感、或者想省 API 成本。Claude Code 支持通过配置接入本地模型服务前提是你本地有一个兼容的模型服务在跑。配置的核心是指定模型服务的地址和模型名称。具体配置方式因版本而异但思路是一致的在 Claude Code 的配置文件里把模型端点指向本地服务的地址。这里我不展开具体配置细节因为不同版本的配置项可能变化建议以官方文档为准。需要提醒的是本地模型的能力和云端模型有差距尤其是在复杂推理和长上下文处理上。superpowers 的流程对模型的指令遵循能力要求比较高如果本地模型跟不上skill 的执行质量会打折扣。我的建议是简单任务用本地模型复杂任务还是用云端模型。6.2 多模型切换的实操技巧Codex CLI 在多模型切换上更灵活。你可以通过/model命令在会话中切换模型也可以在不同项目里配置不同的默认模型。我的使用策略是这样的需求澄清和方案设计用推理能力强的模型这一步质量决定后面所有环节写测试和写实现用代码能力强的模型速度也要考虑代码审查用另一个模型避免“自己审自己”的盲区这个策略的核心是让不同模型发挥各自优势同时通过“换模型审查”来引入不同的视角。实测下来换模型审查能发现不少同模型审查漏掉的问题。6.3 第三方 API 接入的注意事项如果你用的是第三方 API 服务有几个点要注意兼容性确认 API 的接口格式和 Claude Code / Codex CLI 兼容不兼容的话需要中间层转换上下文长度第三方服务的上下文窗口可能和官方不同配置时要对应调整稳定性第三方服务的响应稳定性直接影响 skill 执行建议先小规模测试注意接入任何第三方服务前先确认其合规性和数据安全策略避免敏感代码外泄。7. 常见问题与排查技巧实录7.1 安装与配置类问题速查问题现象可能原因解决方法npm 安装很慢默认源速度慢配置国内镜像源安装后命令找不到全局路径未加入 PATH检查 npm 全局 bin 路径登录失败账号权限或配置问题检查账号状态和配置文件VS Code 插件不生效插件版本与 CLI 不匹配升级插件和 CLI 到同版本Windows 兼容性报错Node 位数不匹配重装对应位数的 Node7.2 skill 执行中的典型故障故障一skill 不触发。通常是触发条件写得太窄或者编排配置里没把 skill 挂上。排查方法是手动调用 skill看是否能执行。能执行说明是编排问题不能执行说明是 skill 文件本身有问题。故障二skill 执行到一半卡住。最常见的原因是上下文超限。长会话里前面的内容把上下文占满了后面的 skill 没有足够空间执行。解决办法是用/compact压缩上下文或者把大任务拆成小任务。故障三验收标准总是通不过。要么是标准定得太高要么是 skill 的执行步骤不够具体。我的经验是验收标准要可量化执行步骤要可操作。“写好代码”不是标准“函数不超过 50 行、有类型标注、有错误处理”才是。7.3 我踩过的三个坑第一个坑skill 写得太细。一开始我把每个操作都写成一个 skill结果编排层要调几十个 skill光切换开销就很大。后来我改成按阶段划分一个阶段一个 skill内部步骤在 skill 里描述效率高很多。第二个坑忽略上下文管理。superpowers 的流程比较长一个完整流程跑下来上下文消耗很大。我后来养成了习惯每个阶段结束后手动/compact一次保持上下文清爽。第三个坑验收标准形同虚设。早期我写的验收标准太模糊AI 随便糊弄一下就过了。后来我把标准改成必须产出具体文件或具体数据比如“测试报告里必须包含覆盖率数字”效果立刻不一样。7.4 性能与成本优化建议superpowers 的流程比直接对话消耗更多 token这是必然的——它做了更多的事。但有几个优化空间按需启用不是所有任务都走完整流程简单任务可以跳过部分 skill上下文复用相似的 skill 之间共享上下文避免重复读取模型分级不同阶段用不同档位的模型贵的模型用在关键决策上缓存机制对重复执行的结果做缓存避免重复计算我实测下来合理配置后superpowers 的 token 消耗大约是同任务直接对话的 1.5 到 2 倍但返工率降低带来的时间节省远超这个成本。8. 把 superpowers 用成自己的东西superpowers 这套框架最有意思的地方不是它自带的那些 skill而是它提供了一种把工程经验固化成 AI 可执行流程的方法。你团队里那些“老司机才知道”的规矩——比如“改数据库必须写迁移脚本”“接口必须版本化”“日志必须带 trace id”——都可以写成 skill让 AI 每次都遵守。我自己在实际使用中的体会是skill 的质量比数量重要得多。与其写二十个半吊子 skill不如把三五个核心 skill 打磨到“AI 执行完你完全放心”的程度。我现在项目里常驻的 skill 就五个需求澄清、方案设计、测试先行、实现、审查。这五个跑顺了AI 产出的代码质量已经能稳定在一个可接受的水平。最后分享一个小技巧定期回顾 skill 的执行记录。看看哪些 skill 经常被打回、哪些验收标准从来没触发过。经常被打回的 skill 说明步骤不够清晰从来没触发过的标准说明定得太松。根据这些记录迭代 skill比一次性写完就不管效果好得多。这个框架后续还可以往“团队共享 skill 库”的方向扩展——把每个人沉淀的 skill 汇总起来新项目直接复用这才是 agentic skills framework 真正的长期价值。
阅读完成 · 觉得有帮助？
技术演进与工程实践指南)
