1. 从“superpowers”这个词说起它到底指什么第一次看到“superpowers”这个标题加上“agentic skills framework”“software development methodology”这几个关键词我脑子里第一反应是这不是某个具体软件的名字而是一套给 AI 编程代理agent用的技能框架和方法论。换句话说它想解决的不是“AI 能不能写代码”而是“AI 写代码时怎么像一支有纪律的工程团队那样干活”。我接触过不少把 AI 塞进开发流程的尝试绝大多数最后都卡在同一个地方模型本身很聪明但一到真实项目里就开始乱来——改一个函数顺手把隔壁模块重构了跑测试失败三次之后开始瞎猜遇到不确定的需求直接编一个看起来合理的实现。这些问题的根源不是模型能力不够而是缺少一套约束它行为的工作方法。superpowers 这类框架的价值就是把这套方法固化下来让 agent 按套路出牌。需要先说明一点superpowers 本身不是一个能独立运行的软件它更像是一组技能定义skills和工作流约定挂载在 Claude Code、Codex CLI 这类命令行 AI 编程工具上使用。所以想真正用起来你得先有一个能跑 agent 的宿主环境。这也是为什么相关热搜里全是“claude code 安装”“codex cli 安装”“vscode 配置 claude code”这类词——大家卡的第一步根本不是 superpowers 本身而是宿主工具没跑通。这篇文章我打算按真实上手顺序来写先讲清楚 superpowers 这套方法论的内核是什么、为什么值得用再讲宿主环境怎么选、怎么装然后是技能框架怎么落地到日常开发最后是我自己踩过的坑和排查思路。如果你已经在用 Claude Code 或 Codex CLI但总觉得 agent 干活不靠谱这篇应该能帮你把思路理顺。2. superpowers 的内核把工程纪律翻译成 agent 能懂的语言2.1 为什么“让 AI 写代码”不等于“让 AI 做工程”大部分人用 AI 编程的起点是打开对话框描述需求复制代码粘贴到项目里。这个模式在写一个独立函数、一个算法题时很好用但一旦进入真实项目就崩了。真实项目的代码是有上下文的——命名规范、目录结构、依赖关系、测试覆盖、错误处理约定这些东西不会写在你的需求描述里但缺了它们代码就是不能合并。superpowers 的核心洞察就在这里agent 需要的不是更强的代码生成能力而是一套“先理解再动手”的作业流程。它把资深工程师的工作习惯拆成一个个可复用的技能模块比如“动手前先读相关文件”“改动前先确认影响范围”“写完必须跑测试”“失败后先定位再修改而不是重写”。这些听起来都是常识但 agent 默认不会这么做必须显式地教它。我自己的体会是用了这套框架之后agent 的行为从“一个急于表现的新人”变成了“一个知道先看再做的中级工程师”。它不会一上来就给你一大段代码而是先列出它打算改哪些文件、为什么改、改完怎么验证。这个转变对实际开发效率的影响比模型升级一代还明显。2.2 技能skills是怎么组织的superpowers 里的“技能”不是抽象概念而是结构化的提示词模块每个技能通常包含几个部分触发条件什么时候该用这个技能、执行步骤具体怎么做、检查点做完怎么确认没跑偏。这种结构和人类给新人写的 SOP标准作业程序几乎一样。举个具体的例子。一个“安全重构”技能大概长这样触发条件是“需要修改已有代码结构但不改变外部行为”执行步骤是“先跑一遍现有测试确认基线是绿的 → 定位所有调用点 → 逐个修改并保持接口不变 → 每改一处跑一次相关测试”检查点是“所有原有测试仍然通过且没有新增未覆盖的分支”。你看这就是一个工程师带徒弟时会说的话只不过现在写成了 agent 能解析的格式。这种组织方式的好处是可组合。一个复杂任务可以拆成多个技能串联先“理解需求”再“探索代码库”然后“制定方案”接着“分步实现”最后“验证与收尾”。每个技能只负责一件事做扎实了再交给下一个。这比让 agent 一口气完成整个任务要可靠得多因为每一步都有明确的输入输出和验收标准。2.3 它和普通提示词工程的区别在哪有人可能会问这不就是写更长的提示词吗区别在于系统性和可维护性。普通提示词是每次对话临时写的写完就扔下次遇到类似场景还得重写。superpowers 的技能是沉淀下来的资产可以版本管理、可以复用、可以针对项目定制。你今天调好了一个“处理数据库迁移”的技能明天换个项目还能接着用只需要微调触发条件。另一个区别是约束的强制性。普通提示词里写“请先读代码再改”agent 可能读也可能不读取决于它当时怎么理解。而技能框架通常会和宿主工具的机制结合比如在特定阶段强制注入某个技能的内容或者用检查点机制卡住流程不通过就不让继续。这种“流程上的硬约束”才是它真正区别于随手写提示词的地方。3. 宿主环境怎么选Claude Code 与 Codex CLI 的实际差异3.1 两个工具解决的是同一类问题但路子不同superpowers 要跑起来得有个宿主。目前主流选择就是 Claude Code 和 Codex CLI两者都是命令行形态的 AI 编程代理都能读写文件、执行命令、跑测试。但用下来感觉它们的性格不太一样。Claude Code 更像一个深度集成的结对程序员。它对项目上下文的理解比较细腻会主动去读相关文件、理解目录结构交互上偏向“边聊边做”。它的技能挂载机制也比较成熟superpowers 这类框架在它上面跑得比较顺。缺点是它对账号和网络环境有一定要求热搜里那句“your organization has disabled claude subscription access”就是典型的企业策略限制问题。Codex CLI 更像一个轻量级的任务执行器。它的命令集比较精简像/compact、/model、/resume这几个是高频使用的——/compact压缩上下文省 token/model切换模型/resume恢复之前的会话。它对接第三方模型和本地模型相对灵活热搜里“codex cli remotion”“codex cli 命令哪些”说明不少人在研究它的具体用法。如果你手头有本地模型或者第三方 APICodex CLI 的接入门槛会低一些。3.2 选型时我实际会看的几个维度维度Claude CodeCodex CLI上下文理解深度较强主动探索代码库中等依赖明确指令技能框架兼容性成熟superpowers 原生适配可用需手动配置模型灵活性绑定官方模型为主可接第三方与本地模型命令丰富度交互式命令偏自然语言斜杠命令清晰如 /compact /model /resume上手门槛账号与环境配置是主要障碍配置项多但可控性强我的建议是如果你追求“开箱即用的工程体验”并且环境允许优先 Claude Code如果你需要接本地模型、或者想精细控制每一步的模型调用Codex CLI 更合适。两者不冲突我自己的机器上是都装了的简单任务用 Codex CLI 快速跑复杂重构用 Claude Code 慢慢磨。3.3 安装前必须想清楚的一件事热搜里大量“claude code 安装”“ubuntu 配置 claude code”“mac 安装 claude code”的问题说明安装本身就是一道坎。这里我不展开具体命令各平台差异大且更新快但有一个原则必须强调先把宿主工具单独跑通再考虑挂 superpowers。很多人一上来就想把框架和工具一起配好结果出问题时根本分不清是哪一层的问题。正确的顺序是装好宿主 → 跑一个最简单的“读文件并总结”任务 → 确认能正常读写和执行 → 再挂技能框架。4. 把 superpowers 落到日常开发一套可复用的作业流程4.1 任务开始前的“三问”技能我现在让 agent 干活第一步永远是让它回答三个问题这个任务要改哪些文件这些文件之间是什么关系改完之后怎么验证这三个问题对应 superpowers 里“理解与探索”阶段的技能。别小看这一步它能挡掉至少一半的返工。举个真实例子。有次我让 agent 给一个接口加参数校验它直接就开始改 controller。我拦住它让它先回答三问。结果它一探索发现这个接口的参数其实在中间件层已经被处理过一次了controller 里再加校验是重复的而且会覆盖掉中间件的默认值逻辑。如果它直接改就是一个隐蔽的 bug。这就是“先理解再动手”的价值——agent 不缺写代码的能力缺的是动手前的那几秒犹豫。4.2 分步实现与检查点设置superpowers 强调把大任务拆成小步每步都有检查点。我通常会把一个功能拆成“数据层 → 逻辑层 → 接口层 → 测试”四步每步做完让 agent 停下来我确认后再继续。这个节奏看起来慢但实际比“一口气生成然后大改”快得多。检查点具体检查什么我的清单是这一步的改动是否只涉及预期文件是否有未使用的导入或变量相关测试是否通过有没有引入新的依赖这四条过一遍基本能拦住大部分低级问题。特别是“只涉及预期文件”这条能有效防止 agent 顺手重构——它经常觉得“既然改到这里了不如把隔壁也优化一下”这种“热心”在真实项目里是灾难。4.3 失败后的处理技能定位而非重写agent 跑测试失败时的默认反应是“重写一遍”这是最危险的行为。superpowers 里有个专门的技能处理这种情况失败后先读错误信息定位到具体行分析原因再决定是改这一行还是改设计。我要求 agent 在修改前必须用一句话说清楚“失败的根本原因是什么”说不清楚就不许改。这个约束救过我很多次。有一次测试报了一个类型错误agent 第一反应是把类型断言加上去强行通过。我让它先解释原因它读了一圈发现是上游数据结构变了但下游没同步。如果直接加断言问题就被掩盖了上线后会在运行时炸掉。让 agent 解释原因本质上是在逼它做真正的调试而不是做表面修补。4.4 收尾阶段的清理技能任务做完不等于结束。superpowers 的收尾技能包括删除调试代码、检查是否有遗留的 console.log、确认没有注释掉的大段代码、更新相关文档。这些琐事人类工程师也经常忘交给 agent 按清单过一遍反而更可靠。我还会加一条自己的习惯让 agent 用一段话总结这次改动包括改了什么、为什么这么改、有什么遗留问题。这段话我直接拿来当 commit message 或者 PR 描述省了不少事。而且写总结的过程本身也是一种自检——如果它总结得含糊其辞说明它自己也没完全搞清楚改了什么。5. 踩坑实录那些让我停下来重新思考的瞬间5.1 上下文膨胀导致的“失忆”用了一段时间之后我发现一个规律会话越长agent 越容易忘事。前面确认过的约定聊到后面它就不记得了开始按自己的理解来。这不是模型的问题是上下文窗口的物理限制。热搜里 Codex CLI 的/compact命令就是干这个的——压缩历史上下文保留关键信息。我的应对策略是主动分段。一个任务如果预计超过一定轮次我会在关键节点手动总结当前状态开一个新会话继续。总结内容包括已完成的部分、当前的文件状态、下一步要做什么、有哪些约定不能忘。这个总结我让 agent 自己写我审核。这样新会话开始时它拿到的是一个干净的、聚焦的上下文而不是一堆历史对话的残渣。5.2 技能冲突与优先级问题当多个技能同时被触发时会出现冲突。比如“快速实现”技能和“充分测试”技能在某些场景下是矛盾的——前者想尽快出结果后者要求每步都验证。如果框架没有明确的优先级agent 就会摇摆行为变得不可预测。我的处理办法是给技能排优先级并且显式告诉 agent。在项目配置里写明正确性 可维护性 速度。这样当技能冲突时agent 知道该听谁的。这个优先级不是一成不变的赶进度的时候我会临时调整但调整必须显式说出来不能让它自己猜。5.3 本地模型接入后的能力落差热搜里“claude code 调用 lmstudio 的本地模型”“使用 cc switch 接入 deepseek、qwen、glm 等模型”说明很多人想用本地或第三方模型替代官方模型。这条路能走通但要有心理准备不同模型对技能框架的遵循程度差异很大。有些模型能很好地理解结构化技能有些则会把技能内容当成普通文本忽略掉。我实测下来的经验是技能框架越复杂对模型能力的要求越高。如果你的本地模型规模较小建议先用简化版的技能——只保留最核心的“先读后写”和“失败先定位”两条跑顺了再逐步加。一上来就挂全套技能小模型会直接懵掉表现反而不如不用框架。5.4 环境配置的隐蔽陷阱安装配置阶段的坑特别多而且往往报错信息不明确。我遇到过的情况包括路径里有空格导致命令解析失败、权限不足导致无法写入配置目录、系统版本与工具要求不匹配。热搜里“claude code 由于与 64 位版本的 windows 不兼容”就是典型的平台兼容问题。排查这类问题的通用思路是从最简环境开始逐步加变量。先确认基础命令能跑再加配置再加技能每加一层测一次。出问题时最近加的那一层就是嫌疑最大的。另外养成看日志的习惯——大部分工具都会把详细错误写到日志文件里比终端上显示的那一行有用得多。6. 我对这套方法论的真实看法用了一段时间 superpowers 这类框架之后我最大的感受是它改变的不是 AI 的能力上限而是 AI 的可靠性下限。模型再聪明如果没有约束在真实项目里的表现就是不可预测的有了这套作业流程它的输出变得可预期、可审查、可复现。对个人开发者来说这意味着你可以放心地把更多任务交给它对团队来说这意味着 AI 生成的代码有了进入代码库的基本质量保证。但它不是银弹。框架本身需要维护技能需要根据项目调整模型能力仍然是天花板。我见过有人把 superpowers 当成“装上就变强”的插件结果发现 agent 还是该犯错犯错——因为框架只是给了方法执行方法还需要你盯着。真正有效的用法是把它当成一个给 agent 看的工程规范文档你写规范它照着做你验收。最后分享一个我自己的小习惯每次 agent 干完活我会问它一句“这次哪里做得不够好”。它的回答经常能指出一些我没注意到的流程漏洞比如某个检查点设得太晚、某个技能触发条件写得太宽。把这些反馈攒起来定期更新技能配置这套框架才会越用越顺手。工具是死的方法是活的真正让 superpowers 发挥作用的还是用它的人愿不愿意持续打磨。
