★ FEATURED ARTICLE 1. 从“superpowers”这个词说起它到底指什么第一次看到“superpowers”这个标题加上“agentic skills framework”“software development methodology”这几个关键词我脑子里第一反应是这不是某个具体软件的名字而更像是一套给 AI 编程助手“加装能力”的方法论框架。事实也确实如此。在 Claude Code、Codex CLI 这类终端里的 AI 编程代理越来越普及之后大家很快发现一个问题——模型本身很聪明但它在真实项目里干活时经常缺“手脚”不知道怎么规范地读文件、怎么安全地跑命令、怎么把一个大任务拆成可验证的小步骤。superpowers 想解决的就是这层“能力封装”的问题。我把它理解成一套技能包skills 工作流约定的组合。核心思路是不要每次都靠一句长长的提示词去指挥 AI而是把常见的开发动作比如“先探索代码库再动手”“写完必须自测”“提交前做一次代码审查”沉淀成可复用的技能模块让代理在合适的时机自动调用。这跟传统“写个 prompt 模板”最大的区别在于它强调的是代理的自主编排能力——也就是 agentic 这个词的真正含义。这篇文章适合谁看如果你已经在用 Claude Code 或 Codex CLI 做日常开发但总觉得“它有时候很聪明有时候又很莽”那这套框架的思路对你很有参考价值。如果你还没上手这些工具只是想了解 AI 编程代理的进阶玩法我也会把前置的安装、配置、模型接入这些基础环节讲清楚保证你能跟着走通。下面我会从“为什么需要它”讲到“怎么落地”中间穿插我自己踩过的坑。2. 为什么裸用 AI 编程代理会翻车2.1 模型能力不等于工程能力很多人有个误区觉得模型越强写代码就越靠谱。实际用下来你会发现模型能力比如代码补全、逻辑推理和工程能力比如遵守项目规范、控制改动范围、验证结果是两回事。我见过太多次这样的情况让代理改一个函数它顺手把整个文件重写了让它修一个 bug它引入了三个新 bug让它跑测试它说“测试通过了”结果根本没跑。这些问题的根源不是模型笨而是缺少约束和流程。人类工程师在团队里干活靠的是代码规范、CI 流程、code review 这些机制。AI 代理如果只是“裸奔”就等于把一个能力很强但完全不懂规矩的新人直接扔进生产环境。superpowers 这类框架的价值就是给代理补上这套“工程规矩”。2.2 一个真实的翻车场景我拿自己的一次经历举例。当时我用 Claude Code 改一个 Node 项目的接口需求很简单给某个返回字段加个默认值。我给的指令是“帮我把 user 接口的 name 字段加上默认值 anonymous”。结果它做了这么几件事先读了接口文件然后发现有个类型定义文件顺手改了类型接着发现有个测试文件又改了测试最后还“贴心”地更新了文档。改动横跨 4 个文件其中类型定义的改动还导致了另一个模块编译报错。问题出在哪它没有“先探索、再计划、后执行”的意识也没有“最小改动”的约束。如果当时有一套技能框架规定“修改前必须先输出改动计划并等待确认”“改动范围不得超过必要文件”这次翻车完全可以避免。这就是 agentic skills framework 要解决的核心痛点——把工程纪律编码进代理的行为里。2.3 技能框架和普通提示词的本质区别有人会问我写个详细的 system prompt 不就行了区别在于触发时机和组合方式。普通提示词是一股脑塞给模型模型要在一次推理里同时处理所有规则很容易顾此失彼。而技能框架是把能力拆成独立模块每个模块有自己的触发条件比如“当任务涉及多文件修改时激活计划技能”代理在运行时按需加载。这就像给一个员工一本员工手册提示词和一套标准作业程序技能包的区别——后者更容易执行到位。3. 把 superpowers 跑起来环境与工具链准备3.1 Claude Code 和 Codex CLI 的定位差异要玩转这套框架先得有个能跑代理的宿主环境。目前主流的两条路线是 Claude Code 和 Codex CLI。我两个都用过简单说下差异方便你选。维度Claude CodeCodex CLI交互风格对话式适合探索性任务命令式适合明确任务技能扩展对 skills 框架支持较成熟更偏脚本化调用本地模型可通过第三方方式接入配置相对灵活上手门槛中等配置项较多中等命令需要记我的建议是如果你主要做需要反复沟通、逐步明确需求的开发任务Claude Code 更顺手如果你习惯把任务写成明确指令一次性执行Codex CLI 更对味。两者不冲突可以都装。3.2 安装环节最容易卡住的地方安装 Claude Code 本身不复杂但有几个坑我踩过提前说。第一个是系统兼容性。Windows 上偶尔会遇到“与 64 位版本不兼容”的提示这通常是 Node 环境版本太老或者架构不匹配导致的。解决办法是确认 Node 版本在 18 以上并且用 64 位版本。Mac 和 Ubuntu 上相对省心Ubuntu 记得先装好 build-essential 和 git。第二个是账号与订阅状态。有时候会看到“your organization has disabled claude subscription access”这类提示意思是当前账号的订阅权限被组织策略限制了。这种情况要么换个人账号要么走 API 方式接入。注册账号和不注册的区别主要在于注册后能同步配置、有额度管理不注册则更依赖本地配置。第三个是桌面版和 CLI 版的选择。桌面版安装包适合不想折腾命令行的朋友但灵活性不如 CLI。我个人的习惯是 CLI 为主桌面版偶尔用来快速看个东西。3.3 接入本地模型和第三方模型这是很多人关心的点能不能不登录官方账号用本地模型或其他模型跑答案是可以的但需要借助一些中转配置工具。比如用 cc switch 这类工具可以把请求转发到 DeepSeek、Qwen、GLM 等模型上。配置的核心是改base URL 和 API key让代理以为自己在跟官方服务对话实际请求打到了你指定的模型。这里有个经验本地模型比如通过 LM Studio 跑的在代码补全和简单重构上够用但涉及多步骤规划和长上下文的任务还是得用能力更强的模型。我试过用本地小模型跑一个跨 5 个文件的改动它在第三步就忘了第一步的约束直接跑偏。所以我的建议是本地模型用来做轻量任务和隐私敏感场景复杂任务还是上强模型。4. 技能框架的落地从“会聊天”到“会干活”4.1 技能模块应该怎么拆superpowers 这类框架的核心是技能模块的设计。我总结了一个拆分原则按开发阶段拆而不是按功能拆。什么意思不要拆成“读文件技能”“写文件技能”“跑命令技能”这种底层操作而要拆成“探索代码库”“制定改动计划”“执行并自测”“提交前审查”这种阶段性的能力。为什么因为底层操作模型本来就会你封装了也是多此一举。真正需要约束的是阶段之间的衔接和纪律。比如“探索阶段”的技能应该规定在没搞清楚代码结构前禁止修改任何文件。“计划阶段”的技能应该规定改动超过 2 个文件必须先输出计划。“自测阶段”的技能应该规定改完必须跑相关测试跑不了的要说明原因。4.2 一个可复用的技能配置示例下面是我自己整理的一个技能配置骨架用 YAML 风格描述你可以根据自己的项目改。skills: - name: explore-first trigger: 任务开始时 rules: - 先列出相关目录结构 - 定位核心文件并阅读 - 输出对现状的理解等待确认 - name: plan-before-edit trigger: 需要修改代码时 rules: - 改动超过2个文件必须输出计划 - 计划需包含改哪些文件、为什么、预期影响 - 等待用户确认后再执行 - name: verify-after-change trigger: 代码修改完成后 rules: - 运行相关测试 - 无法运行时说明原因 - 输出改动摘要这套配置看起来简单但实际用起来效果很明显。我拿它跑了一个中等规模的重构任务代理的行为从“上来就改”变成了“先看、再说、后动”返工率下降了一大截。4.3 触发条件的设计比规则本身更重要很多人设计技能时把精力全花在“规则写得多细”上忽略了触发条件。这是个误区。规则再细如果触发时机不对要么该激活时没激活要么不该激活时乱激活。我的经验是触发条件要基于可观测的信号而不是模糊的语义判断。比如“改动超过 2 个文件”是个可观测信号代理能准确判断。“任务比较复杂”就是个模糊判断代理容易误判。所以设计触发条件时尽量用数量、文件类型、命令类型这类硬指标。这一点是我踩了好几次坑才悟出来的——早期我写了个“当任务重要时激活审查技能”结果它几乎从不激活因为“重要”这个词对模型来说太虚了。5. 日常使用中的命令与操作技巧5.1 那些高频命令的实战用法Claude Code 和 Codex CLI 都有一批高频命令用熟了效率翻倍。我挑几个最常用的说说。/compact是用来压缩上下文的。当你跟代理聊了很久上下文快满了它会开始“忘事”。这时候用/compact把前面的对话压缩成摘要能腾出空间继续干活。我的习惯是每完成一个阶段性任务就 compact 一次而不是等到快满了才想起来。/model用来切换模型。这个在“本地模型和强模型混用”的场景下特别有用。简单任务切本地模型省钱省时间复杂任务切强模型保质量。/resume用来恢复之前的会话。有时候你关掉终端去干别的回来想接着聊用这个能找回上下文。不过要注意恢复的会话如果隔了太久上下文可能已经不太准了重要任务建议重新开。5.2 让代理直接执行终端命令这是很多人又爱又怕的功能。爱的是效率怕的是它乱来。我的做法是分级授权读操作ls、cat、grep放开让它跑写操作rm、mv、git push必须我确认危险操作rm -rf、数据库操作直接禁用。具体怎么配大多数工具都支持命令白名单和黑名单。我把rm -rf、DROP TABLE、git push --force这类放进黑名单代理碰到就直接拒绝执行。白名单里放常用的只读命令。中间地带的操作让它先输出命令内容我看了再决定放不放行。这套机制跑下来既享受了自动化又没出过大事。5.3 在 VS Code 里用起来更顺手如果你习惯在 VS Code 里写代码把 Claude Code 接进编辑器会舒服很多。配置方式一般是装对应的插件然后在设置里填好 API 配置。接进去之后代理能直接看到你当前打开的文件、光标位置沟通成本低不少。有个小技巧在 VS Code 里用的时候先把相关文件打开再给指令。这样代理能直接读到文件内容不用自己去找响应更快也更准。我试过同样的指令开着文件和不打开文件代理的理解准确率差别挺明显的。6. 踩坑实录那些让我抓狂的瞬间6.1 上下文丢失导致的“失忆”最让我抓狂的一次是代理干到一半突然“失忆”。当时在做一个多步骤任务前两步都好好的到第三步它突然问“你刚才说的需求是什么”。一查上下文超限被截断了。这个坑的教训是长任务要主动分段每段结束用/compact压缩重要约束在每段开头重申一遍。别指望代理能记住几十轮对话前的细节。6.2 模型切换后的行为不一致还有一次我中途从强模型切到本地模型结果代理的行为风格完全变了。强模型之前建立的“先计划后执行”习惯本地模型完全不认上来就改代码。后来我明白了技能配置要跟着模型走切模型时最好重新加载一遍技能配置或者干脆在本地模型上也配一套简化版的约束。6.3 命令执行权限的边界模糊有次我让代理“清理一下临时文件”它理解成了删掉整个 temp 目录还好我配了确认机制拦下来了。这件事让我意识到自然语言指令的边界太模糊涉及删除、覆盖这类操作一定要用明确的路径和范围别用“清理一下”这种模糊表述。现在我给这类指令都会写成“删除 /project/tmp 目录下超过 7 天的 .log 文件”精确到路径和条件。7. 把 superpowers 思路用到团队协作里7.1 技能配置的版本化管理一个人用技能框架配置放本地就行。但如果是团队用就得把技能配置纳入版本管理。我们团队的做法是在项目根目录建一个.agent-skills目录把技能配置、命令白名单、常用提示词模板都放进去跟代码一起提交。这样每个人拉下代码代理的行为规范就是一致的不会出现“你那边代理很规矩我这边代理乱来”的情况。7.2 新人上手时的“代理行为规范”带新人的时候我发现一个有意思的现象新人用 AI 代理往往比老手更容易翻车。为什么因为老手心里有杆秤知道哪些操作危险、哪些改动范围过大会在指令里提前约束。新人没这个概念给的指令很随意代理也就很随意。所以我们现在会给新人一份“代理行为规范”其实就是把技能框架里的核心约束用大白话写出来改代码前先看、改动超过两个文件先说、跑命令前确认、改完必须自测。这份规范配合技能配置一起用新人上手代理的翻车率明显下降。7.3 审查环节不能省最后说个可能有点反直觉的观点代理越强审查越不能省。因为代理强了它一次能改的东西更多一旦方向错了损失也更大。我们现在的要求是代理改完的代码必须人工过一遍重点看改动范围是否合理、有没有引入不必要的依赖、测试是否真的跑了。这个环节花的时间远比事后修 bug 少。8. 关于这套框架我的一些个人体会用了一段时间 superpowers 这套思路之后我最大的感受是AI 编程代理的上限不取决于模型多强而取决于你给它搭的“脚手架”多稳。同样的模型裸用和配上技能框架产出质量能差出一个量级。另一个体会是这套东西不是一劳永逸的。项目在变、模型在变、你的习惯也在变技能配置得跟着迭代。我现在的做法是每个月回顾一次技能配置看看哪些规则从来没触发过可能是触发条件写错了哪些规则经常触发但没起作用可能是规则本身有问题。这个回顾习惯比一开始把配置写得多完美更重要。如果你刚开始接触我的建议是别贪多。先配三条最核心的规则探索优先、计划先行、改完自测。把这三条跑顺了再逐步加。一上来就配几十条规则代理反而会无所适从你也搞不清哪条在起作用。踩过几次坑、调过几轮配置之后你会慢慢找到适合自己项目的那套节奏。
阅读完成 · 觉得有帮助？
