1. 从“superpowers”说起这套 agentic skills framework 到底在解决什么问题第一次看到 “superpowers” 这个词很多人会以为是某个游戏模组或者某个超级英雄主题的插件。但如果你最近在折腾 Claude Code、Codex CLI 这类终端里的 AI 编程代理大概率已经在各种社区里刷到过它。简单说superpowers 是一套面向 AI 编程代理的 agentic skills framework本质上是一套“技能包 工作方法论”的组合它把软件开发过程中那些高频、重复、容易出错的环节抽象成代理可以直接调用的技能单元再配上一套约束代理行为的开发流程规范。它要解决的问题其实很具体。你在用 Claude Code 或者 Codex CLI 的时候有没有遇到过这种情况你让它改一个功能它上来就噼里啪啦写一堆代码改完之后你一看测试没跑、边界没考虑、原来的代码风格全被打乱甚至把不该动的文件也顺手改了。这不是模型不够聪明而是缺少一套稳定的“行为脚手架”。superpowers 干的事情就是给这些代理装上这套脚手架让它在动手之前先想清楚要做什么、按什么顺序做、做完之后怎么验证。这套框架适合谁我的判断是三类人。第一类是已经把 Claude Code 或 Codex CLI 当成日常开发工具但总觉得输出质量忽高忽低的开发者第二类是想把 AI 代理引入团队流程但苦于没有统一规范可落地的技术负责人第三类是对 agentic skills 这个概念感兴趣想找一个真实可参考的框架来研究其设计思路的人。不管你用的是 Claude Code 还是 Codex CLI甚至是在 VS Code 里通过插件调用superpowers 的思路都是通用的因为它约束的是“代理怎么干活”而不是“代理跑在哪个壳里”。需要提前说明的是superpowers 本身不是一个可以双击安装的软件它更像是一套约定和技能定义的集合。你需要在理解它的设计逻辑之后把它落到你自己的代理配置里。这也是为什么很多人搜“想要安装 superpowers”却找不到一个标准安装包——它的“安装”过程其实是把这套技能体系接入你的代理工作流。2. 核心设计思路拆解为什么是“技能”而不是“提示词”2.1 从提示词工程到技能工程的关键转变大部分人用 AI 编程代理的方式是在对话框里写一段提示词然后等结果。这种方式在单次任务上还行但一旦任务变复杂提示词就会越写越长最后变成一篇小作文代理反而抓不住重点。superpowers 的设计思路跳出了这个循环它不追求“写一个完美的提示词”而是把能力拆成一个个独立的、可组合的技能单元。打个比方提示词工程像是你每次做饭都从头口述一遍菜谱而技能工程像是你提前把“切菜”“调酱汁”“控火候”这些动作练成肌肉记忆做菜的时候直接调用就行。superpowers 里的每个 skill就是这样一个肌肉记忆单元。比如“先写测试再写实现”是一个 skill“改动前先读相关文件”是一个 skill“完成后运行验证命令”也是一个 skill。这些 skill 单独看都很朴素但组合起来就能形成一套稳定的开发行为。这个转变背后的逻辑是代理的不可靠往往不是知识不足而是行为顺序混乱。模型知道怎么写测试但它不一定会在写实现之前先写测试。模型知道要读文件但它可能只读了被直接修改的那个文件忽略了依赖它的其他文件。superpowers 通过把正确的行为顺序固化成技能让代理在执行任务时按部就班而不是凭“感觉”发挥。2.2 技能框架的三层结构触发、执行、验证拆开来看superpowers 的技能框架大致可以分成三层。最上面一层是触发条件也就是“什么时候该用这个技能”。比如当任务涉及修改已有函数时触发“先读后写”技能当任务涉及新增功能时触发“测试先行”技能。触发条件的设计很关键它决定了代理能不能在正确的时机想起正确的技能。中间一层是执行步骤也就是“这个技能具体怎么做”。这一步需要足够具体具体到代理可以直接照着执行。比如“先读后写”技能的执行步骤可能是第一步定位目标函数所在文件第二步读取该文件完整内容第三步搜索该函数被哪些地方调用第四步确认修改影响范围后再动手。步骤越清晰代理的执行偏差就越小。最下面一层是验证标准也就是“怎么判断这个技能执行到位了”。验证标准可以是运行测试、检查输出、对比修改前后的行为差异等。这一层最容易被忽略但恰恰是最重要的。没有验证标准的技能就像没有验收标准的施工做完也不知道对不对。superpowers 强调每个技能都要有可验证的产出这样代理才能形成“执行—验证—修正”的闭环。2.3 为什么这套思路对 Claude Code 和 Codex CLI 都适用Claude Code 和 Codex CLI 虽然底层模型和交互方式不同但它们在“代理行为”这个层面面临的问题是相似的都需要读文件、改代码、跑命令、验证结果。superpowers 的技能定义不依赖具体某个模型的 API而是描述“代理应该做什么”所以它天然具有跨工具的适应性。我在实际使用中的体会是Claude Code 在长上下文理解上比较强适合处理需要通读多个文件的复杂任务Codex CLI 在命令执行和快速迭代上比较顺手适合处理边界清晰的局部修改。但不管用哪个如果没有技能框架约束都会出现“跳步”的问题。superpowers 的价值就在于它提供了一套与工具无关的行为规范你可以在 Claude Code 里用也可以在 Codex CLI 里用甚至可以在两者之间切换时保持行为一致。3. 核心技能单元详解与实操要点3.1 读改分离为什么“先读后写”是最重要的基础技能在所有技能里如果只能保留一个我会选“先读后写”。这个技能看起来简单到不值一提但它是绝大多数代理翻车的根源。代理在没有充分读取上下文的情况下直接改代码轻则改错位置重则破坏依赖关系而且这种错误往往在运行测试时才暴露排查成本很高。“先读后写”技能的执行要点有几个。第一读取范围要覆盖直接目标和间接依赖。不能只读被修改的那个文件还要读它引用的模块和引用它的模块。第二读取时要关注代码风格和命名约定这样改出来的代码才能和现有代码保持一致。第三读取后要先输出一个修改计划说明打算改哪些地方、为什么改、预期影响是什么确认无误后再动手。注意很多代理在“先读后写”这一步会偷懒只读文件的前几十行就下结论。实操中建议在技能定义里明确要求“读取完整文件”如果文件过长至少读取目标函数及其上下文各五十行。我在用 Claude Code 处理一个中型项目时踩过一个坑让它给一个工具函数加参数它只读了那个函数本身没注意到这个函数在另外三个文件里被以位置参数的方式调用。结果它加了参数之后那三个调用点全部报错。后来我把“先读后写”技能加进去要求它在修改函数签名前必须搜索所有调用点这类问题就再没出现过。3.2 测试先行让代理自己给自己出考卷“测试先行”是另一个高频技能。它的核心逻辑是在写实现之前先让代理写出验证这个实现的测试。这样做有两个好处。第一测试写出来之后代理对“什么算完成”有了明确标准不会写着写着跑偏。第二测试本身也是对需求的一次校验如果测试写不出来说明需求本身可能没想清楚。执行这个技能时要注意测试的粒度。对于新增功能测试应该覆盖正常路径和至少一个边界情况。对于修改功能测试应该先能复现修改前的行为再验证修改后的行为。对于修复 bug测试应该先能稳定复现 bug再验证修复后 bug 消失。这个顺序不能乱否则测试就失去了“考卷”的意义。提示如果项目本身没有测试框架不要强行引入一个重型框架。可以用最简单的断言脚本代替关键是让代理有一个可执行的验证手段而不是追求测试覆盖率。3.3 小步提交把大任务拆成可验证的小步骤代理处理大任务时最容易失控。你让它“重构用户模块”它可能一口气改十几个文件改完之后你根本不知道从哪里开始检查。superpowers 里的“小步提交”技能就是要求代理把大任务拆成一系列小步骤每个步骤都有独立的验证点完成一步验证一步验证通过再进入下一步。拆步骤的原则是每个步骤的改动范围可控、验证方式明确。比如“重构用户模块”可以拆成第一步提取用户相关的常量第二步把用户校验逻辑抽成独立函数第三步替换所有调用点第四步删除旧代码。每一步做完都跑一次测试确保没有引入回归。这样即使某一步出了问题也能快速定位到具体步骤而不是在一大堆改动里大海捞针。这个技能在 Codex CLI 里尤其好用因为 Codex CLI 的命令执行反馈很快你可以让它每完成一步就运行一次测试命令根据输出决定是否继续。我在处理一个遗留项目时用这种方式把原本需要一次性改二十多个文件的任务拆成了七个小步骤每一步都验证通过后再继续最终一次性通过没有出现反复调试的情况。3.4 上下文管理什么时候该压缩什么时候该重开Claude Code 和 Codex CLI 都有上下文长度的限制任务做久了上下文会越来越长代理的注意力也会被稀释。superpowers 里有一个容易被忽视但很实用的技能就是上下文管理。它要求代理在上下文接近饱和时主动压缩把已经完成的部分总结成简短记录释放上下文空间给后续任务。压缩的时机很关键。太早压缩会丢失细节太晚压缩又来不及。我的经验是当代理开始出现“忘记之前约定”或者“重复询问已经确认过的信息”时就是该压缩的信号。压缩时要把已完成的工作、当前状态、待办事项、关键决策记录清楚这样即使上下文被压缩代理也能快速恢复状态。如果任务已经完成了一个阶段而下一个阶段和之前关联不大更好的做法是重开一个会话而不是在旧会话里继续。重开会话可以让代理轻装上阵避免被之前的历史包袱拖累。我在用 Claude Code 做多阶段任务时习惯在每个阶段结束后把关键结论记录下来然后开新会话继续下一阶段效果比一直在一个会话里硬撑要好得多。4. 完整实操流程从零接入 superpowers 思路4.1 环境准备Claude Code 与 Codex CLI 的基础配置在接入 superpowers 思路之前先把基础环境搭好。Claude Code 的安装方式根据平台不同略有差异Mac 和 Ubuntu 下通常通过命令行工具安装Windows 下需要注意 64 位兼容性问题。安装完成后第一次运行需要完成账号注册和登录流程如果遇到组织策略限制导致无法使用的情况需要检查账号权限配置。Codex CLI 的安装相对直接通过包管理器安装后即可在终端调用。它的常用命令包括/compact用于压缩上下文、/model用于切换模型、/resume用于恢复会话。如果你需要在 VS Code 里使用可以安装对应的插件把 Claude Code 或 Codex CLI 接入编辑器工作流。对于想用本地模型的场景可以通过配置把请求转发到本地推理服务这样可以在不依赖外部服务的情况下使用代理能力。注意不同平台的安装细节和权限要求差异较大建议先确认自己的操作系统版本和账号状态再按官方文档逐步操作。遇到“当前地区不可用”之类的提示时优先检查账号配置和网络环境是否符合要求。4.2 技能定义落地把 superpowers 思路写进你的代理配置环境准备好之后下一步是把 superpowers 的技能思路落到实际配置里。具体做法是在你的项目根目录下创建一个技能定义文件把常用的技能单元写进去然后在每次启动代理时加载这个文件。技能定义不需要很复杂关键是清晰描述触发条件、执行步骤和验证标准。比如“先读后写”技能可以这样定义触发条件是“任务涉及修改已有代码”执行步骤是“读取目标文件完整内容、搜索所有调用点、输出修改计划”验证标准是“修改计划经确认后再执行”。类似地“测试先行”技能的触发条件是“任务涉及新增或修改功能”执行步骤是“先写测试、运行测试确认失败、再写实现、运行测试确认通过”验证标准是“测试从失败变为通过”。这些定义写一次之后可以复用不同项目之间只需要微调触发条件。我在多个项目里用同一套技能定义发现代理的行为一致性明显提升不再需要每次都在提示词里重复交代“先读再改”“记得跑测试”这些要求。4.3 一次完整任务的全流程演示假设现在有一个任务给一个现有的工具函数增加参数校验。按照 superpowers 的思路整个流程会这样走。第一步代理读取目标函数所在文件搜索该函数的所有调用点确认修改影响范围。第二步代理输出修改计划说明打算在哪里加校验、加什么校验、会影响哪些调用点。第三步代理先写一个测试验证不加校验时非法参数会导致什么问题。第四步代理运行测试确认测试失败。第五步代理实现参数校验逻辑。第六步代理再次运行测试确认测试通过。第七步代理检查修改后的代码风格是否与现有代码一致。第八步代理总结本次修改内容记录关键决策。这个流程看起来步骤很多但实际执行时代理可以连续完成你只需要在关键节点确认即可。相比“直接改代码然后祈祷没问题”的方式这套流程的返工率要低得多。我在实际项目里对比过用技能框架约束的代理任务一次通过率大概能从五成提升到八成以上剩下的两成问题也能在早期步骤里被发现而不是等到最后才暴露。5. 常见问题与排查技巧实录5.1 代理不按技能执行怎么办这是最常见的问题。你明明定义了“先读后写”代理还是直接动手改代码。原因通常有两个一是技能定义没有被正确加载二是技能定义的触发条件写得太模糊代理没有识别出当前任务应该触发这个技能。排查方法是先确认技能文件是否被读取可以在任务开始时让代理复述当前可用的技能列表。如果技能已加载但没触发就把触发条件写得更具体比如把“涉及修改代码”改成“涉及修改任何已存在的函数或类”。触发条件越具体代理越容易在正确时机想起来。5.2 上下文压缩后代理“失忆”怎么处理上下文压缩是必要的但压缩后代理可能会忘记之前的关键决策。解决办法是在压缩时保留一份“状态摘要”包含已完成工作、当前状态、待办事项和关键决策。这份摘要要放在上下文里显眼的位置让代理在压缩后能第一时间看到。如果压缩后代理还是出现失忆可以考虑把状态摘要单独存成一个文件每次任务开始时让代理先读这个文件。这样即使上下文完全重置代理也能通过读文件恢复状态。我在处理长周期任务时用这个方法效果比较稳定。5.3 测试先行写不出测试怎么办有时候代理会卡在“写测试”这一步尤其是面对一些难以测试的代码时。这时候不要硬逼代理写测试而是先让它分析“为什么这个代码难以测试”。通常分析下来会发现难以测试的代码往往也是耦合过高的代码这本身就是一个值得先处理的问题。如果确实无法写自动化测试可以退而求其次让代理写一个手动验证步骤明确说明“怎么操作、预期看到什么结果”。手动验证虽然不如自动化测试可靠但至少给了代理一个明确的完成标准比完全没有验证要好。5.4 技能框架让任务变慢值得吗短期看技能框架确实会让单个任务的执行步骤变多感觉变慢了。但把时间拉长看返工和调试的时间大幅减少整体效率是提升的。我自己的体感是简单任务改个变量名、加个日志用不用框架差别不大但复杂任务跨文件重构、新增功能模块用框架的收益非常明显。提示可以根据任务复杂度灵活调整技能启用范围。简单任务只启用“先读后写”复杂任务启用全套技能。不必一刀切。5.5 常见问题速查表问题现象可能原因排查方向解决建议代理直接改代码不读上下文技能未加载或触发条件模糊检查技能文件加载状态细化触发条件任务开始时复述技能列表压缩后忘记之前决策状态摘要缺失或不显眼检查压缩时是否保留摘要单独存状态文件任务开始时先读取写不出测试代码耦合过高或需求不清分析代码可测试性先解耦或改为手动验证步骤任务执行变慢技能启用范围过大评估任务复杂度简单任务只启用基础技能代理重复询问已确认信息上下文过长导致注意力稀释检查上下文长度及时压缩或重开会话6. 工具选型与组合建议Claude Code、Codex CLI 怎么搭6.1 两个工具的能力边界与适用场景Claude Code 和 Codex CLI 不是互斥关系而是可以互补的。Claude Code 的优势在于长上下文理解和多文件协同适合处理需要通读项目、理解复杂依赖关系的任务。Codex CLI 的优势在于命令执行和快速迭代适合处理边界清晰、验证方式明确的局部任务。我的组合方式是用 Claude Code 做前期的方案设计和跨文件分析把任务拆解清楚然后用 Codex CLI 执行具体的代码修改和测试验证。这样既发挥了 Claude Code 的理解能力又利用了 Codex CLI 的执行效率。两者之间通过技能定义文件共享同一套行为规范保证行为一致。6.2 本地模型接入的注意事项如果你想把代理接到本地模型上需要注意几点。第一本地模型的上下文长度通常比云端模型短技能定义要更精简避免占用过多上下文。第二本地模型的指令遵循能力可能弱一些技能定义要更具体减少模糊表述。第三本地模型的推理速度受硬件影响较大任务拆解要更细避免单次任务过重。在配置本地模型接入时关键是确认接口兼容性和参数映射是否正确。不同本地推理服务的 API 格式可能有差异需要根据实际情况调整配置。如果遇到调用失败优先检查模型名称、接口地址和认证配置这三项。6.3 第三方 API 使用的经验与边界有些场景下会用到第三方 API 来接入不同的模型。使用第三方 API 时要注意接口稳定性、响应格式兼容性和费用控制。建议在技能定义里加入“失败重试”和“降级处理”逻辑当第三方 API 不可用时代理能自动切换到备用方案而不是直接卡死。另外第三方 API 的响应格式可能和官方接口有差异需要在配置层做适配。我的做法是写一个简单的适配层把不同来源的响应统一成代理能理解的格式这样技能定义就不需要关心底层用的是哪个 API。7. 我个人的实操体会与后续扩展方向这套 superpowers 思路我用了一段时间最大的感受是代理的可靠性不取决于模型有多强而取决于行为有多稳。同一个模型加上技能框架约束之后输出质量的波动明显变小。以前我需要反复检查代理的改动现在大部分情况下只需要在关键节点确认一下就行。如果要把这套思路继续扩展我觉得有两个方向值得尝试。一个是技能的市场化把常用的技能单元做成可分享的包不同项目之间直接复用减少重复定义的成本。另一个是技能的自动化触发通过分析任务类型自动匹配应该启用的技能而不是靠人工判断。这两个方向都能进一步降低使用门槛让更多人享受到技能框架带来的稳定性提升。最后分享一个小技巧技能定义不要一次写太多先从“先读后写”和“测试先行”这两个最基础的开始用顺了再逐步增加。技能太多反而会让代理无所适从少而精比多而杂更有效。 
长河君 · 2026/10/7 23:06:41 · 阅读 1.2k superpowers：AI编程代理的agentic skills框架与实操指南
1. 从“superpowers”说起这套 agentic skills framework 到底在解决什么问题第一次看到 “superpowers” 这个词很多人会以为是某个游戏模组或者某个超级英雄主题的插件。但如果你最近在折腾 Claude Code、Codex CLI 这类终端里的 AI 编程代理大概率已经在各种社区里刷到过它。简单说superpowers 是一套面向 AI 编程代理的 agentic skills framework本质上是一套“技能包 工作方法论”的组合它把软件开发过程中那些高频、重复、容易出错的环节抽象成代理可以直接调用的技能单元再配上一套约束代理行为的开发流程规范。它要解决的问题其实很具体。你在用 Claude Code 或者 Codex CLI 的时候有没有遇到过这种情况你让它改一个功能它上来就噼里啪啦写一堆代码改完之后你一看测试没跑、边界没考虑、原来的代码风格全被打乱甚至把不该动的文件也顺手改了。这不是模型不够聪明而是缺少一套稳定的“行为脚手架”。superpowers 干的事情就是给这些代理装上这套脚手架让它在动手之前先想清楚要做什么、按什么顺序做、做完之后怎么验证。这套框架适合谁我的判断是三类人。第一类是已经把 Claude Code 或 Codex CLI 当成日常开发工具但总觉得输出质量忽高忽低的开发者第二类是想把 AI 代理引入团队流程但苦于没有统一规范可落地的技术负责人第三类是对 agentic skills 这个概念感兴趣想找一个真实可参考的框架来研究其设计思路的人。不管你用的是 Claude Code 还是 Codex CLI甚至是在 VS Code 里通过插件调用superpowers 的思路都是通用的因为它约束的是“代理怎么干活”而不是“代理跑在哪个壳里”。需要提前说明的是superpowers 本身不是一个可以双击安装的软件它更像是一套约定和技能定义的集合。你需要在理解它的设计逻辑之后把它落到你自己的代理配置里。这也是为什么很多人搜“想要安装 superpowers”却找不到一个标准安装包——它的“安装”过程其实是把这套技能体系接入你的代理工作流。2. 核心设计思路拆解为什么是“技能”而不是“提示词”2.1 从提示词工程到技能工程的关键转变大部分人用 AI 编程代理的方式是在对话框里写一段提示词然后等结果。这种方式在单次任务上还行但一旦任务变复杂提示词就会越写越长最后变成一篇小作文代理反而抓不住重点。superpowers 的设计思路跳出了这个循环它不追求“写一个完美的提示词”而是把能力拆成一个个独立的、可组合的技能单元。打个比方提示词工程像是你每次做饭都从头口述一遍菜谱而技能工程像是你提前把“切菜”“调酱汁”“控火候”这些动作练成肌肉记忆做菜的时候直接调用就行。superpowers 里的每个 skill就是这样一个肌肉记忆单元。比如“先写测试再写实现”是一个 skill“改动前先读相关文件”是一个 skill“完成后运行验证命令”也是一个 skill。这些 skill 单独看都很朴素但组合起来就能形成一套稳定的开发行为。这个转变背后的逻辑是代理的不可靠往往不是知识不足而是行为顺序混乱。模型知道怎么写测试但它不一定会在写实现之前先写测试。模型知道要读文件但它可能只读了被直接修改的那个文件忽略了依赖它的其他文件。superpowers 通过把正确的行为顺序固化成技能让代理在执行任务时按部就班而不是凭“感觉”发挥。2.2 技能框架的三层结构触发、执行、验证拆开来看superpowers 的技能框架大致可以分成三层。最上面一层是触发条件也就是“什么时候该用这个技能”。比如当任务涉及修改已有函数时触发“先读后写”技能当任务涉及新增功能时触发“测试先行”技能。触发条件的设计很关键它决定了代理能不能在正确的时机想起正确的技能。中间一层是执行步骤也就是“这个技能具体怎么做”。这一步需要足够具体具体到代理可以直接照着执行。比如“先读后写”技能的执行步骤可能是第一步定位目标函数所在文件第二步读取该文件完整内容第三步搜索该函数被哪些地方调用第四步确认修改影响范围后再动手。步骤越清晰代理的执行偏差就越小。最下面一层是验证标准也就是“怎么判断这个技能执行到位了”。验证标准可以是运行测试、检查输出、对比修改前后的行为差异等。这一层最容易被忽略但恰恰是最重要的。没有验证标准的技能就像没有验收标准的施工做完也不知道对不对。superpowers 强调每个技能都要有可验证的产出这样代理才能形成“执行—验证—修正”的闭环。2.3 为什么这套思路对 Claude Code 和 Codex CLI 都适用Claude Code 和 Codex CLI 虽然底层模型和交互方式不同但它们在“代理行为”这个层面面临的问题是相似的都需要读文件、改代码、跑命令、验证结果。superpowers 的技能定义不依赖具体某个模型的 API而是描述“代理应该做什么”所以它天然具有跨工具的适应性。我在实际使用中的体会是Claude Code 在长上下文理解上比较强适合处理需要通读多个文件的复杂任务Codex CLI 在命令执行和快速迭代上比较顺手适合处理边界清晰的局部修改。但不管用哪个如果没有技能框架约束都会出现“跳步”的问题。superpowers 的价值就在于它提供了一套与工具无关的行为规范你可以在 Claude Code 里用也可以在 Codex CLI 里用甚至可以在两者之间切换时保持行为一致。3. 核心技能单元详解与实操要点3.1 读改分离为什么“先读后写”是最重要的基础技能在所有技能里如果只能保留一个我会选“先读后写”。这个技能看起来简单到不值一提但它是绝大多数代理翻车的根源。代理在没有充分读取上下文的情况下直接改代码轻则改错位置重则破坏依赖关系而且这种错误往往在运行测试时才暴露排查成本很高。“先读后写”技能的执行要点有几个。第一读取范围要覆盖直接目标和间接依赖。不能只读被修改的那个文件还要读它引用的模块和引用它的模块。第二读取时要关注代码风格和命名约定这样改出来的代码才能和现有代码保持一致。第三读取后要先输出一个修改计划说明打算改哪些地方、为什么改、预期影响是什么确认无误后再动手。注意很多代理在“先读后写”这一步会偷懒只读文件的前几十行就下结论。实操中建议在技能定义里明确要求“读取完整文件”如果文件过长至少读取目标函数及其上下文各五十行。我在用 Claude Code 处理一个中型项目时踩过一个坑让它给一个工具函数加参数它只读了那个函数本身没注意到这个函数在另外三个文件里被以位置参数的方式调用。结果它加了参数之后那三个调用点全部报错。后来我把“先读后写”技能加进去要求它在修改函数签名前必须搜索所有调用点这类问题就再没出现过。3.2 测试先行让代理自己给自己出考卷“测试先行”是另一个高频技能。它的核心逻辑是在写实现之前先让代理写出验证这个实现的测试。这样做有两个好处。第一测试写出来之后代理对“什么算完成”有了明确标准不会写着写着跑偏。第二测试本身也是对需求的一次校验如果测试写不出来说明需求本身可能没想清楚。执行这个技能时要注意测试的粒度。对于新增功能测试应该覆盖正常路径和至少一个边界情况。对于修改功能测试应该先能复现修改前的行为再验证修改后的行为。对于修复 bug测试应该先能稳定复现 bug再验证修复后 bug 消失。这个顺序不能乱否则测试就失去了“考卷”的意义。提示如果项目本身没有测试框架不要强行引入一个重型框架。可以用最简单的断言脚本代替关键是让代理有一个可执行的验证手段而不是追求测试覆盖率。3.3 小步提交把大任务拆成可验证的小步骤代理处理大任务时最容易失控。你让它“重构用户模块”它可能一口气改十几个文件改完之后你根本不知道从哪里开始检查。superpowers 里的“小步提交”技能就是要求代理把大任务拆成一系列小步骤每个步骤都有独立的验证点完成一步验证一步验证通过再进入下一步。拆步骤的原则是每个步骤的改动范围可控、验证方式明确。比如“重构用户模块”可以拆成第一步提取用户相关的常量第二步把用户校验逻辑抽成独立函数第三步替换所有调用点第四步删除旧代码。每一步做完都跑一次测试确保没有引入回归。这样即使某一步出了问题也能快速定位到具体步骤而不是在一大堆改动里大海捞针。这个技能在 Codex CLI 里尤其好用因为 Codex CLI 的命令执行反馈很快你可以让它每完成一步就运行一次测试命令根据输出决定是否继续。我在处理一个遗留项目时用这种方式把原本需要一次性改二十多个文件的任务拆成了七个小步骤每一步都验证通过后再继续最终一次性通过没有出现反复调试的情况。3.4 上下文管理什么时候该压缩什么时候该重开Claude Code 和 Codex CLI 都有上下文长度的限制任务做久了上下文会越来越长代理的注意力也会被稀释。superpowers 里有一个容易被忽视但很实用的技能就是上下文管理。它要求代理在上下文接近饱和时主动压缩把已经完成的部分总结成简短记录释放上下文空间给后续任务。压缩的时机很关键。太早压缩会丢失细节太晚压缩又来不及。我的经验是当代理开始出现“忘记之前约定”或者“重复询问已经确认过的信息”时就是该压缩的信号。压缩时要把已完成的工作、当前状态、待办事项、关键决策记录清楚这样即使上下文被压缩代理也能快速恢复状态。如果任务已经完成了一个阶段而下一个阶段和之前关联不大更好的做法是重开一个会话而不是在旧会话里继续。重开会话可以让代理轻装上阵避免被之前的历史包袱拖累。我在用 Claude Code 做多阶段任务时习惯在每个阶段结束后把关键结论记录下来然后开新会话继续下一阶段效果比一直在一个会话里硬撑要好得多。4. 完整实操流程从零接入 superpowers 思路4.1 环境准备Claude Code 与 Codex CLI 的基础配置在接入 superpowers 思路之前先把基础环境搭好。Claude Code 的安装方式根据平台不同略有差异Mac 和 Ubuntu 下通常通过命令行工具安装Windows 下需要注意 64 位兼容性问题。安装完成后第一次运行需要完成账号注册和登录流程如果遇到组织策略限制导致无法使用的情况需要检查账号权限配置。Codex CLI 的安装相对直接通过包管理器安装后即可在终端调用。它的常用命令包括/compact用于压缩上下文、/model用于切换模型、/resume用于恢复会话。如果你需要在 VS Code 里使用可以安装对应的插件把 Claude Code 或 Codex CLI 接入编辑器工作流。对于想用本地模型的场景可以通过配置把请求转发到本地推理服务这样可以在不依赖外部服务的情况下使用代理能力。注意不同平台的安装细节和权限要求差异较大建议先确认自己的操作系统版本和账号状态再按官方文档逐步操作。遇到“当前地区不可用”之类的提示时优先检查账号配置和网络环境是否符合要求。4.2 技能定义落地把 superpowers 思路写进你的代理配置环境准备好之后下一步是把 superpowers 的技能思路落到实际配置里。具体做法是在你的项目根目录下创建一个技能定义文件把常用的技能单元写进去然后在每次启动代理时加载这个文件。技能定义不需要很复杂关键是清晰描述触发条件、执行步骤和验证标准。比如“先读后写”技能可以这样定义触发条件是“任务涉及修改已有代码”执行步骤是“读取目标文件完整内容、搜索所有调用点、输出修改计划”验证标准是“修改计划经确认后再执行”。类似地“测试先行”技能的触发条件是“任务涉及新增或修改功能”执行步骤是“先写测试、运行测试确认失败、再写实现、运行测试确认通过”验证标准是“测试从失败变为通过”。这些定义写一次之后可以复用不同项目之间只需要微调触发条件。我在多个项目里用同一套技能定义发现代理的行为一致性明显提升不再需要每次都在提示词里重复交代“先读再改”“记得跑测试”这些要求。4.3 一次完整任务的全流程演示假设现在有一个任务给一个现有的工具函数增加参数校验。按照 superpowers 的思路整个流程会这样走。第一步代理读取目标函数所在文件搜索该函数的所有调用点确认修改影响范围。第二步代理输出修改计划说明打算在哪里加校验、加什么校验、会影响哪些调用点。第三步代理先写一个测试验证不加校验时非法参数会导致什么问题。第四步代理运行测试确认测试失败。第五步代理实现参数校验逻辑。第六步代理再次运行测试确认测试通过。第七步代理检查修改后的代码风格是否与现有代码一致。第八步代理总结本次修改内容记录关键决策。这个流程看起来步骤很多但实际执行时代理可以连续完成你只需要在关键节点确认即可。相比“直接改代码然后祈祷没问题”的方式这套流程的返工率要低得多。我在实际项目里对比过用技能框架约束的代理任务一次通过率大概能从五成提升到八成以上剩下的两成问题也能在早期步骤里被发现而不是等到最后才暴露。5. 常见问题与排查技巧实录5.1 代理不按技能执行怎么办这是最常见的问题。你明明定义了“先读后写”代理还是直接动手改代码。原因通常有两个一是技能定义没有被正确加载二是技能定义的触发条件写得太模糊代理没有识别出当前任务应该触发这个技能。排查方法是先确认技能文件是否被读取可以在任务开始时让代理复述当前可用的技能列表。如果技能已加载但没触发就把触发条件写得更具体比如把“涉及修改代码”改成“涉及修改任何已存在的函数或类”。触发条件越具体代理越容易在正确时机想起来。5.2 上下文压缩后代理“失忆”怎么处理上下文压缩是必要的但压缩后代理可能会忘记之前的关键决策。解决办法是在压缩时保留一份“状态摘要”包含已完成工作、当前状态、待办事项和关键决策。这份摘要要放在上下文里显眼的位置让代理在压缩后能第一时间看到。如果压缩后代理还是出现失忆可以考虑把状态摘要单独存成一个文件每次任务开始时让代理先读这个文件。这样即使上下文完全重置代理也能通过读文件恢复状态。我在处理长周期任务时用这个方法效果比较稳定。5.3 测试先行写不出测试怎么办有时候代理会卡在“写测试”这一步尤其是面对一些难以测试的代码时。这时候不要硬逼代理写测试而是先让它分析“为什么这个代码难以测试”。通常分析下来会发现难以测试的代码往往也是耦合过高的代码这本身就是一个值得先处理的问题。如果确实无法写自动化测试可以退而求其次让代理写一个手动验证步骤明确说明“怎么操作、预期看到什么结果”。手动验证虽然不如自动化测试可靠但至少给了代理一个明确的完成标准比完全没有验证要好。5.4 技能框架让任务变慢值得吗短期看技能框架确实会让单个任务的执行步骤变多感觉变慢了。但把时间拉长看返工和调试的时间大幅减少整体效率是提升的。我自己的体感是简单任务改个变量名、加个日志用不用框架差别不大但复杂任务跨文件重构、新增功能模块用框架的收益非常明显。提示可以根据任务复杂度灵活调整技能启用范围。简单任务只启用“先读后写”复杂任务启用全套技能。不必一刀切。5.5 常见问题速查表问题现象可能原因排查方向解决建议代理直接改代码不读上下文技能未加载或触发条件模糊检查技能文件加载状态细化触发条件任务开始时复述技能列表压缩后忘记之前决策状态摘要缺失或不显眼检查压缩时是否保留摘要单独存状态文件任务开始时先读取写不出测试代码耦合过高或需求不清分析代码可测试性先解耦或改为手动验证步骤任务执行变慢技能启用范围过大评估任务复杂度简单任务只启用基础技能代理重复询问已确认信息上下文过长导致注意力稀释检查上下文长度及时压缩或重开会话6. 工具选型与组合建议Claude Code、Codex CLI 怎么搭6.1 两个工具的能力边界与适用场景Claude Code 和 Codex CLI 不是互斥关系而是可以互补的。Claude Code 的优势在于长上下文理解和多文件协同适合处理需要通读项目、理解复杂依赖关系的任务。Codex CLI 的优势在于命令执行和快速迭代适合处理边界清晰、验证方式明确的局部任务。我的组合方式是用 Claude Code 做前期的方案设计和跨文件分析把任务拆解清楚然后用 Codex CLI 执行具体的代码修改和测试验证。这样既发挥了 Claude Code 的理解能力又利用了 Codex CLI 的执行效率。两者之间通过技能定义文件共享同一套行为规范保证行为一致。6.2 本地模型接入的注意事项如果你想把代理接到本地模型上需要注意几点。第一本地模型的上下文长度通常比云端模型短技能定义要更精简避免占用过多上下文。第二本地模型的指令遵循能力可能弱一些技能定义要更具体减少模糊表述。第三本地模型的推理速度受硬件影响较大任务拆解要更细避免单次任务过重。在配置本地模型接入时关键是确认接口兼容性和参数映射是否正确。不同本地推理服务的 API 格式可能有差异需要根据实际情况调整配置。如果遇到调用失败优先检查模型名称、接口地址和认证配置这三项。6.3 第三方 API 使用的经验与边界有些场景下会用到第三方 API 来接入不同的模型。使用第三方 API 时要注意接口稳定性、响应格式兼容性和费用控制。建议在技能定义里加入“失败重试”和“降级处理”逻辑当第三方 API 不可用时代理能自动切换到备用方案而不是直接卡死。另外第三方 API 的响应格式可能和官方接口有差异需要在配置层做适配。我的做法是写一个简单的适配层把不同来源的响应统一成代理能理解的格式这样技能定义就不需要关心底层用的是哪个 API。7. 我个人的实操体会与后续扩展方向这套 superpowers 思路我用了一段时间最大的感受是代理的可靠性不取决于模型有多强而取决于行为有多稳。同一个模型加上技能框架约束之后输出质量的波动明显变小。以前我需要反复检查代理的改动现在大部分情况下只需要在关键节点确认一下就行。如果要把这套思路继续扩展我觉得有两个方向值得尝试。一个是技能的市场化把常用的技能单元做成可分享的包不同项目之间直接复用减少重复定义的成本。另一个是技能的自动化触发通过分析任务类型自动匹配应该启用的技能而不是靠人工判断。这两个方向都能进一步降低使用门槛让更多人享受到技能框架带来的稳定性提升。最后分享一个小技巧技能定义不要一次写太多先从“先读后写”和“测试先行”这两个最基础的开始用顺了再逐步增加。技能太多反而会让代理无所适从少而精比多而杂更有效。