1. 从“superpowers”说起这套方法论到底在解决什么问题第一次看到“superpowers”这个词很多人会以为是某个超级英雄题材的游戏或者插件合集。但如果你最近在折腾 Claude Code、Codex CLI 这类终端里的 AI 编程助手大概率已经在各种讨论里撞见过它。它本质上是一套面向 AI 编程代理的技能框架与开发方法论核心思路是把“让 AI 帮我写代码”这件事从随缘聊天式的提问变成一套有结构、可复用、能沉淀的工程流程。我最初接触它的时候正卡在一个很典型的状态里单个函数让 AI 写没问题一旦涉及跨文件改动、多步骤重构、需要跑测试再回改的循环整个对话就开始失控。要么是 AI 忘了前面定好的约束要么是我自己都说不清当前改到哪一步了。superpowers 想解决的正是这个断层——它不教你某个具体命令怎么敲而是给你一套组织 AI 协作过程的骨架让代理知道“现在处于哪个阶段、下一步该做什么、做完怎么验证”。这套东西适合谁如果你只是偶尔让 AI 补个正则、写个正则解释那用不上。但只要你开始把 Claude Code 或 Codex CLI 当成日常开发的一部分尤其是需要它连续完成“读代码、改代码、跑测试、修错误”这种多轮任务那这套方法论就值得花时间理解。它不绑定某一个工具Claude Code 能用Codex CLI 也能用甚至你换成别的支持工具调用的代理框架思路照样迁移得过去。需要先说明一点superpowers 本身不是一个你npm install就能装上的包它更像一套约定和习惯的集合。网上流传的很多“安装 superpowers”的说法其实指的是把它的技能定义、提示词模板、工作流约定配置到你的代理环境里。所以下面我讲的内容会围绕“怎么把这套思路落地到 Claude Code 和 Codex CLI 的实际使用中”来展开而不是给你一个不存在的安装命令。2. 核心思路拆解为什么要把 AI 编程拆成“技能”2.1 从“一次性提问”到“技能化协作”的转变传统用 AI 写代码的方式基本是“我描述需求它给一段代码我复制粘贴出问题再问”。这个模式在任务简单时效率很高但任务一复杂就暴露三个问题上下文丢失、责任边界模糊、过程不可复用。你这次让它按某种风格写了一个模块下次换个对话它又用另一套风格你还得重新解释一遍项目约定。superpowers 的核心洞察是把开发过程中反复出现的动作抽象成一个个“技能单元”。比如“阅读并理解一个陌生模块”“为现有函数补测试”“按项目规范重构命名”“定位一个失败的测试并修复”。每个技能单元有自己的输入、输出、检查清单和完成标准。代理在执行时不是自由发挥而是按技能定义一步步走。这样做的好处很直接——过程可预期结果可验证经验可沉淀。我自己的体会是这套思路把 AI 从“一个很聪明的实习生”变成了“一个按 SOP 干活的工程助手”。实习生聪明但需要你盯着SOP 助手可能没那么灵活但在重复性、规范性任务上稳定性高出一大截。而实际开发里大部分时间恰恰花在这些重复性、规范性的环节上。2.2 技能框架与工具的关系Claude Code 和 Codex CLI 各自扮演什么角色这里要理清一个容易混淆的点superpowers 是方法论层Claude Code 和 Codex CLI 是执行层。方法论告诉你“该做什么、按什么顺序做、做到什么程度算完成”执行层负责“实际去读文件、改代码、跑命令”。Claude Code 的强项在于它对项目上下文的感知比较细腻能读整个仓库结构适合做需要理解全局的改动。Codex CLI 则更偏向命令行的直接操作适合把一系列 shell 级别的动作串起来。两者都能承载 superpowers 的技能定义区别在于你更习惯哪种交互方式。我个人的搭配是需要深度理解代码库、做架构级调整时用 Claude Code需要快速跑一批命令、做批量文件处理时用 Codex CLI。技能定义是共享的只是调用入口不同。这也是为什么热词里同时出现这两个工具——它们不是竞争关系而是同一套方法论下的两个执行终端。2.3 为什么“技能化”比“提示词工程”更进一层提示词工程解决的是“怎么问才能让 AI 答得好”技能框架解决的是“怎么组织一系列问答才能完成一个工程任务”。前者是单点优化后者是流程优化。你提示词写得再好面对一个需要改五个文件、跑三轮测试的任务还是得靠流程来兜底。superpowers 里每个技能通常包含几个固定部分触发条件什么时候用这个技能、前置检查开始前要确认什么、执行步骤具体做什么、验证方式怎么知道做完了、回退策略出问题怎么办。这套结构逼着你在动手前就想清楚边界而不是边做边猜。实测下来光是“前置检查”这一项就能挡掉很多返工——比如改代码前先确认当前分支干净、测试基线是绿的这两条能省掉后面大量排查时间。3. 落地实操把技能框架配置到你的工作流里3.1 环境准备Claude Code 与 Codex CLI 的基础配置在谈技能配置之前得先把执行环境跑通。Claude Code 的安装方式根据系统不同有差异Mac 和 Ubuntu 下通常通过包管理器或官方提供的安装脚本完成Windows 下则要注意版本兼容性热词里提到的“与64位版本不兼容”就是这类问题。安装完成后第一次启动一般需要完成账号或订阅相关的配置如果遇到组织策略限制导致订阅不可用那是账号层面的问题跟工具本身无关需要走对应的账号管理渠道处理。Codex CLI 的安装依赖 Node 环境国内网络下npm安装慢是常见现象可以配置镜像源来加速。安装完成后codex命令会进入交互模式里面有几个高频命令值得先记住/compact用来压缩当前上下文避免对话过长导致性能下降/model切换底层模型/resume恢复之前的会话。这几个命令在长任务里几乎每天都要用。提示安装过程中如果遇到下载缓慢优先检查镜像源配置而不是反复重装。很多“装不上”的问题其实是网络问题不是包本身的问题。环境跑通后建议先做一个最小验证让代理读一个简单文件并总结内容。这一步能确认工具链是通的再去配置复杂的技能定义否则出了问题你分不清是环境问题还是配置问题。3.2 技能定义怎么写一个可复用的模板结构技能定义不需要多复杂关键是结构完整。我常用的模板包含五个字段用 Markdown 或 YAML 都行看你的代理支持哪种解析方式。下面是一个“修复失败测试”技能的示例结构skill: fix-failing-test trigger: 当测试套件中存在失败用例时 preconditions: - 当前分支工作区干净 - 已确认失败用例的复现命令 steps: - 单独运行失败用例记录完整错误输出 - 定位报错涉及的源文件与测试文件 - 分析失败原因区分是代码缺陷还是测试预期过时 - 修改代码或测试只做最小改动 - 重新运行该用例确认通过 - 运行完整测试套件确认无回归 verification: 完整测试套件全部通过 rollback: 若改动引入新失败回退到修改前状态这个结构的好处是代理每次执行时都有明确的检查点。比如“只做最小改动”这一条能有效防止 AI 顺手重构一堆无关代码。我踩过的坑就是早期没写这条约束结果让它修一个测试它把整个模块的命名风格都改了review 起来非常痛苦。3.3 把技能串成流程从单技能到工作流单个技能解决单点问题但真实开发任务是多个技能的串联。比如“实现一个新功能”可能包含理解需求、阅读相关模块、设计接口、写实现、写测试、跑测试、修复失败、更新文档。每个环节都可以是一个技能串起来就是一条工作流。串联的关键是定义技能之间的交接条件。上一个技能的验证结果就是下一个技能的触发条件。这样代理不会在没完成前一步的情况下跳到下一步。我通常会在工作流定义里加一个“状态标记”每完成一个技能就更新一次代理每次开始新技能前先读这个标记确认自己该做什么。这套做法在 Claude Code 里尤其顺手因为它能持续读取项目里的文件状态标记文件它随时能看到。Codex CLI 下则需要你手动在命令之间传递状态稍微麻烦一点但用 shell 变量或临时文件也能实现。4. 实操过程记录一次完整的技能化重构4.1 任务背景与技能选择前段时间我需要把一个旧模块里的回调式异步逻辑改成 Promise 风格。这个模块大概四百行涉及六个函数还有对应的测试文件。如果直接让 AI“帮我改成 Promise”大概率会改得面目全非。所以我按技能框架拆成了三步先做“理解模块”技能再做“设计改造方案”技能最后做“执行改造并验证”技能。选择这个拆法的理由是改造类任务最大的风险是改错语义。回调改 Promise 看似机械但错误处理、执行顺序、并发行为都可能变。先理解再设计再执行每一步都有验证点能把风险控制在局部。4.2 第一步理解模块的技能执行这一步我让代理做的第一件事不是改代码而是输出一份模块说明每个函数的输入输出、副作用、调用关系、错误处理方式。输出格式我指定了表格方便对照。代理读完文件后给出的表格里有一个函数的错误处理是“抛出异常”另一个是“返回错误对象”这个不一致在改造时必须统一否则 Promise 的 reject 语义会对不上。这一步的验证方式是我人工核对表格内容与源码是否一致。核对过程中发现代理漏掉了一个内部辅助函数补上后表格才完整。这个细节说明即使有技能框架人工验证环节也不能省。代理的理解能力很强但不是百分之百可靠。4.3 第二步设计改造方案的技能执行理解完成后进入方案设计。我要求代理输出改造前后的对照表每个函数一行列出改造后的签名、错误处理方式、调用方需要做的调整。这一步不写代码只出方案。方案里有一个关键决策原来用回调的并行调用改成 Promise 后用Promise.all还是Promise.allSettled。代理分析后建议用allSettled因为原逻辑里某个回调失败不影响其他回调继续执行all会在第一个 reject 时就中断语义不符。这个决策如果让代理直接改代码很可能就默认用了all然后测试跑不过再回头查浪费一轮。先出方案再执行把这个坑提前挡掉了。这也是技能框架里“设计”环节独立存在的价值。4.4 第三步执行改造与验证方案确认后执行改造。我让代理按函数逐个改每改完一个就跑对应的测试而不是六个函数一起改完再跑。这样出问题时能立刻定位到是哪个函数的改动引起的。六个函数改完测试全绿再跑一次完整套件确认无回归。整个改造过程大概花了四十分钟其中理解模块十分钟设计方案十分钟执行加验证二十分钟。如果不用技能框架直接让 AI 改可能十分钟就出一版代码但后面排查语义问题的时间大概率超过半小时。算总账技能化的方式反而更快而且改完的代码我敢直接提交不用反复 review。5. 常见问题与排查技巧实录5.1 代理不按技能定义执行怎么办这是最常见的问题。你定义得好好的代理执行时却跳步或者自由发挥。原因通常有两个一是技能定义里的触发条件不够明确代理不确定当前是否该用这个技能二是上下文里存在冲突指令比如你之前随口说了一句“快点搞完”代理就倾向于跳过验证步骤。解决办法是把触发条件写得更具体最好带上可判断的信号比如“当测试命令返回非零退出码时”而不是“当测试失败时”。另外在会话开始时明确告诉代理“严格按技能定义执行不要跳步”这句话看似废话但实测能明显降低跳步概率。5.2 上下文过长导致技能执行质量下降长任务里对话会越来越长代理对早期技能定义的记忆会衰减。这时候/compact就派上用场了。它的作用是压缩历史上下文保留关键信息丢掉冗余对话。我一般在完成两到三个技能后压缩一次压缩前会把当前状态标记更新好这样压缩后代理还能接上。Codex CLI 下如果不用/compact也可以手动把状态写到一个文件里新开会话时先读这个文件。两种方式效果差不多看个人习惯。5.3 技能定义与项目实际规范冲突有时候技能定义里的通用步骤跟具体项目的规范不一致。比如通用技能说“每个函数都要写单元测试”但你的项目里某些工具函数就是不写测试的。这种冲突不要硬套应该在技能定义里加一个“项目例外”字段把例外情况列清楚。代理读到例外就知道哪些可以跳过不会死板执行。我见过有人为了迁就技能定义硬给工具函数补测试结果测试本身比函数还长维护成本反而上去了。技能是为你服务的不是反过来。5.4 常见问题速查表问题现象可能原因排查方向处理方式代理跳步执行触发条件模糊或存在冲突指令检查技能定义与近期对话细化触发条件明确要求按序执行执行质量随对话变长下降上下文过长观察对话轮次定期/compact或手动保存状态技能步骤与项目规范冲突通用定义未考虑项目例外对照项目实际约定在技能定义中补充例外字段改造后测试通过但行为异常验证只覆盖了测试用例检查测试覆盖率补充边界用例人工核对关键路径安装后命令不可用环境变量或版本兼容问题检查安装日志与系统版本按官方文档核对依赖版本注意速查表里的处理方式都是方向性的具体操作要结合你的实际环境。尤其是版本兼容类问题不同系统差异很大不要照搬别人的命令。6. 工具选型与组合使用的经验6.1 Claude Code 与 Codex CLI 的分工建议用了一段时间后我形成了一个比较稳定的分工Claude Code 负责“需要理解全局”的任务比如读多个文件、分析调用链、设计改造方案Codex CLI 负责“执行明确动作”的任务比如批量重命名、跑测试、格式化代码。这个分工的依据是两者的交互模式差异——Claude Code 更适合多轮对话式的探索Codex CLI 更适合命令式的执行。当然这不是绝对的。如果你只用一个工具把技能框架配好单工具也能覆盖大部分场景。关键是技能定义要清晰工具只是载体。6.2 接入第三方模型的注意事项热词里提到用 cc switch 接入其他模型这个思路本身没问题但要注意技能框架对模型能力有要求。技能执行需要模型能稳定遵循多步指令、能理解结构化定义、能在长上下文里保持一致性。能力不足的模型执行复杂技能时跳步和误解的概率会明显上升。我的建议是先用能力较强的模型把技能框架跑通确认流程本身没问题再考虑换模型。如果换了模型后技能执行质量下降先怀疑模型能力再怀疑技能定义。反过来排查容易走弯路。6.3 技能库的积累与复用技能定义写多了就形成一个技能库。我的做法是按任务类型分目录重构类、测试类、文档类、排查类。每个技能定义文件头部写清楚适用场景和最后更新日期。这样新任务来时先翻技能库看有没有现成的没有就新建新建完也归档进去。积累到二十来个技能后大部分日常任务都能找到对应的技能定义直接调用或者稍作修改就行。这个复利效应是技能框架最大的价值——你花在定义技能上的时间会在后续每一次任务里省回来。7. 一些踩坑之后的个人体会技能框架这东西刚上手时容易走两个极端。一个是定义得太粗跟没定义差不多代理还是自由发挥另一个是定义得太细每个动作都写死代理变成机械执行遇到定义外的情况就卡住。我自己的平衡点是步骤写到“可验证”的粒度就够了具体怎么实现留给代理判断。比如“运行失败用例并记录输出”是步骤“用pytest -k test_xxx -v运行”就是过细因为不同项目测试命令不一样。另一个体会是技能框架的价值在任务复杂度超过某个阈值后才明显。简单任务用它反而增加开销。判断标准很简单如果这个任务你让 AI 直接做出问题后你能一眼看出哪里错了那就不需要技能框架如果出问题后你需要花时间排查是哪个环节出的错那就值得用技能框架把环节拆开。最后分享一个我常用的小技巧在每个技能定义的末尾加一行“完成后向用户确认”让代理在技能结束时停下来等你确认而不是自动进入下一个技能。这一行能给你一个介入点发现方向不对可以及时纠正避免一路错到底。刚开始我觉得这样会打断节奏用久了发现这个停顿省下的返工时间远多于它带来的等待时间。
1. 从“superpowers”说起这套方法论到底在解决什么问题第一次看到“superpowers”这个词很多人会以为是某个超级英雄题材的游戏或者插件合集。但如果你最近在折腾 Claude Code、Codex CLI 这类终端里的 AI 编程助手大概率已经在各种讨论里撞见过它。它本质上是一套面向 AI 编程代理的技能框架与开发方法论核心思路是把“让 AI 帮我写代码”这件事从随缘聊天式的提问变成一套有结构、可复用、能沉淀的工程流程。我最初接触它的时候正卡在一个很典型的状态里单个函数让 AI 写没问题一旦涉及跨文件改动、多步骤重构、需要跑测试再回改的循环整个对话就开始失控。要么是 AI 忘了前面定好的约束要么是我自己都说不清当前改到哪一步了。superpowers 想解决的正是这个断层——它不教你某个具体命令怎么敲而是给你一套组织 AI 协作过程的骨架让代理知道“现在处于哪个阶段、下一步该做什么、做完怎么验证”。这套东西适合谁如果你只是偶尔让 AI 补个正则、写个正则解释那用不上。但只要你开始把 Claude Code 或 Codex CLI 当成日常开发的一部分尤其是需要它连续完成“读代码、改代码、跑测试、修错误”这种多轮任务那这套方法论就值得花时间理解。它不绑定某一个工具Claude Code 能用Codex CLI 也能用甚至你换成别的支持工具调用的代理框架思路照样迁移得过去。需要先说明一点superpowers 本身不是一个你npm install就能装上的包它更像一套约定和习惯的集合。网上流传的很多“安装 superpowers”的说法其实指的是把它的技能定义、提示词模板、工作流约定配置到你的代理环境里。所以下面我讲的内容会围绕“怎么把这套思路落地到 Claude Code 和 Codex CLI 的实际使用中”来展开而不是给你一个不存在的安装命令。2. 核心思路拆解为什么要把 AI 编程拆成“技能”2.1 从“一次性提问”到“技能化协作”的转变传统用 AI 写代码的方式基本是“我描述需求它给一段代码我复制粘贴出问题再问”。这个模式在任务简单时效率很高但任务一复杂就暴露三个问题上下文丢失、责任边界模糊、过程不可复用。你这次让它按某种风格写了一个模块下次换个对话它又用另一套风格你还得重新解释一遍项目约定。superpowers 的核心洞察是把开发过程中反复出现的动作抽象成一个个“技能单元”。比如“阅读并理解一个陌生模块”“为现有函数补测试”“按项目规范重构命名”“定位一个失败的测试并修复”。每个技能单元有自己的输入、输出、检查清单和完成标准。代理在执行时不是自由发挥而是按技能定义一步步走。这样做的好处很直接——过程可预期结果可验证经验可沉淀。我自己的体会是这套思路把 AI 从“一个很聪明的实习生”变成了“一个按 SOP 干活的工程助手”。实习生聪明但需要你盯着SOP 助手可能没那么灵活但在重复性、规范性任务上稳定性高出一大截。而实际开发里大部分时间恰恰花在这些重复性、规范性的环节上。2.2 技能框架与工具的关系Claude Code 和 Codex CLI 各自扮演什么角色这里要理清一个容易混淆的点superpowers 是方法论层Claude Code 和 Codex CLI 是执行层。方法论告诉你“该做什么、按什么顺序做、做到什么程度算完成”执行层负责“实际去读文件、改代码、跑命令”。Claude Code 的强项在于它对项目上下文的感知比较细腻能读整个仓库结构适合做需要理解全局的改动。Codex CLI 则更偏向命令行的直接操作适合把一系列 shell 级别的动作串起来。两者都能承载 superpowers 的技能定义区别在于你更习惯哪种交互方式。我个人的搭配是需要深度理解代码库、做架构级调整时用 Claude Code需要快速跑一批命令、做批量文件处理时用 Codex CLI。技能定义是共享的只是调用入口不同。这也是为什么热词里同时出现这两个工具——它们不是竞争关系而是同一套方法论下的两个执行终端。2.3 为什么“技能化”比“提示词工程”更进一层提示词工程解决的是“怎么问才能让 AI 答得好”技能框架解决的是“怎么组织一系列问答才能完成一个工程任务”。前者是单点优化后者是流程优化。你提示词写得再好面对一个需要改五个文件、跑三轮测试的任务还是得靠流程来兜底。superpowers 里每个技能通常包含几个固定部分触发条件什么时候用这个技能、前置检查开始前要确认什么、执行步骤具体做什么、验证方式怎么知道做完了、回退策略出问题怎么办。这套结构逼着你在动手前就想清楚边界而不是边做边猜。实测下来光是“前置检查”这一项就能挡掉很多返工——比如改代码前先确认当前分支干净、测试基线是绿的这两条能省掉后面大量排查时间。3. 落地实操把技能框架配置到你的工作流里3.1 环境准备Claude Code 与 Codex CLI 的基础配置在谈技能配置之前得先把执行环境跑通。Claude Code 的安装方式根据系统不同有差异Mac 和 Ubuntu 下通常通过包管理器或官方提供的安装脚本完成Windows 下则要注意版本兼容性热词里提到的“与64位版本不兼容”就是这类问题。安装完成后第一次启动一般需要完成账号或订阅相关的配置如果遇到组织策略限制导致订阅不可用那是账号层面的问题跟工具本身无关需要走对应的账号管理渠道处理。Codex CLI 的安装依赖 Node 环境国内网络下npm安装慢是常见现象可以配置镜像源来加速。安装完成后codex命令会进入交互模式里面有几个高频命令值得先记住/compact用来压缩当前上下文避免对话过长导致性能下降/model切换底层模型/resume恢复之前的会话。这几个命令在长任务里几乎每天都要用。提示安装过程中如果遇到下载缓慢优先检查镜像源配置而不是反复重装。很多“装不上”的问题其实是网络问题不是包本身的问题。环境跑通后建议先做一个最小验证让代理读一个简单文件并总结内容。这一步能确认工具链是通的再去配置复杂的技能定义否则出了问题你分不清是环境问题还是配置问题。3.2 技能定义怎么写一个可复用的模板结构技能定义不需要多复杂关键是结构完整。我常用的模板包含五个字段用 Markdown 或 YAML 都行看你的代理支持哪种解析方式。下面是一个“修复失败测试”技能的示例结构skill: fix-failing-test trigger: 当测试套件中存在失败用例时 preconditions: - 当前分支工作区干净 - 已确认失败用例的复现命令 steps: - 单独运行失败用例记录完整错误输出 - 定位报错涉及的源文件与测试文件 - 分析失败原因区分是代码缺陷还是测试预期过时 - 修改代码或测试只做最小改动 - 重新运行该用例确认通过 - 运行完整测试套件确认无回归 verification: 完整测试套件全部通过 rollback: 若改动引入新失败回退到修改前状态这个结构的好处是代理每次执行时都有明确的检查点。比如“只做最小改动”这一条能有效防止 AI 顺手重构一堆无关代码。我踩过的坑就是早期没写这条约束结果让它修一个测试它把整个模块的命名风格都改了review 起来非常痛苦。3.3 把技能串成流程从单技能到工作流单个技能解决单点问题但真实开发任务是多个技能的串联。比如“实现一个新功能”可能包含理解需求、阅读相关模块、设计接口、写实现、写测试、跑测试、修复失败、更新文档。每个环节都可以是一个技能串起来就是一条工作流。串联的关键是定义技能之间的交接条件。上一个技能的验证结果就是下一个技能的触发条件。这样代理不会在没完成前一步的情况下跳到下一步。我通常会在工作流定义里加一个“状态标记”每完成一个技能就更新一次代理每次开始新技能前先读这个标记确认自己该做什么。这套做法在 Claude Code 里尤其顺手因为它能持续读取项目里的文件状态标记文件它随时能看到。Codex CLI 下则需要你手动在命令之间传递状态稍微麻烦一点但用 shell 变量或临时文件也能实现。4. 实操过程记录一次完整的技能化重构4.1 任务背景与技能选择前段时间我需要把一个旧模块里的回调式异步逻辑改成 Promise 风格。这个模块大概四百行涉及六个函数还有对应的测试文件。如果直接让 AI“帮我改成 Promise”大概率会改得面目全非。所以我按技能框架拆成了三步先做“理解模块”技能再做“设计改造方案”技能最后做“执行改造并验证”技能。选择这个拆法的理由是改造类任务最大的风险是改错语义。回调改 Promise 看似机械但错误处理、执行顺序、并发行为都可能变。先理解再设计再执行每一步都有验证点能把风险控制在局部。4.2 第一步理解模块的技能执行这一步我让代理做的第一件事不是改代码而是输出一份模块说明每个函数的输入输出、副作用、调用关系、错误处理方式。输出格式我指定了表格方便对照。代理读完文件后给出的表格里有一个函数的错误处理是“抛出异常”另一个是“返回错误对象”这个不一致在改造时必须统一否则 Promise 的 reject 语义会对不上。这一步的验证方式是我人工核对表格内容与源码是否一致。核对过程中发现代理漏掉了一个内部辅助函数补上后表格才完整。这个细节说明即使有技能框架人工验证环节也不能省。代理的理解能力很强但不是百分之百可靠。4.3 第二步设计改造方案的技能执行理解完成后进入方案设计。我要求代理输出改造前后的对照表每个函数一行列出改造后的签名、错误处理方式、调用方需要做的调整。这一步不写代码只出方案。方案里有一个关键决策原来用回调的并行调用改成 Promise 后用Promise.all还是Promise.allSettled。代理分析后建议用allSettled因为原逻辑里某个回调失败不影响其他回调继续执行all会在第一个 reject 时就中断语义不符。这个决策如果让代理直接改代码很可能就默认用了all然后测试跑不过再回头查浪费一轮。先出方案再执行把这个坑提前挡掉了。这也是技能框架里“设计”环节独立存在的价值。4.4 第三步执行改造与验证方案确认后执行改造。我让代理按函数逐个改每改完一个就跑对应的测试而不是六个函数一起改完再跑。这样出问题时能立刻定位到是哪个函数的改动引起的。六个函数改完测试全绿再跑一次完整套件确认无回归。整个改造过程大概花了四十分钟其中理解模块十分钟设计方案十分钟执行加验证二十分钟。如果不用技能框架直接让 AI 改可能十分钟就出一版代码但后面排查语义问题的时间大概率超过半小时。算总账技能化的方式反而更快而且改完的代码我敢直接提交不用反复 review。5. 常见问题与排查技巧实录5.1 代理不按技能定义执行怎么办这是最常见的问题。你定义得好好的代理执行时却跳步或者自由发挥。原因通常有两个一是技能定义里的触发条件不够明确代理不确定当前是否该用这个技能二是上下文里存在冲突指令比如你之前随口说了一句“快点搞完”代理就倾向于跳过验证步骤。解决办法是把触发条件写得更具体最好带上可判断的信号比如“当测试命令返回非零退出码时”而不是“当测试失败时”。另外在会话开始时明确告诉代理“严格按技能定义执行不要跳步”这句话看似废话但实测能明显降低跳步概率。5.2 上下文过长导致技能执行质量下降长任务里对话会越来越长代理对早期技能定义的记忆会衰减。这时候/compact就派上用场了。它的作用是压缩历史上下文保留关键信息丢掉冗余对话。我一般在完成两到三个技能后压缩一次压缩前会把当前状态标记更新好这样压缩后代理还能接上。Codex CLI 下如果不用/compact也可以手动把状态写到一个文件里新开会话时先读这个文件。两种方式效果差不多看个人习惯。5.3 技能定义与项目实际规范冲突有时候技能定义里的通用步骤跟具体项目的规范不一致。比如通用技能说“每个函数都要写单元测试”但你的项目里某些工具函数就是不写测试的。这种冲突不要硬套应该在技能定义里加一个“项目例外”字段把例外情况列清楚。代理读到例外就知道哪些可以跳过不会死板执行。我见过有人为了迁就技能定义硬给工具函数补测试结果测试本身比函数还长维护成本反而上去了。技能是为你服务的不是反过来。5.4 常见问题速查表问题现象可能原因排查方向处理方式代理跳步执行触发条件模糊或存在冲突指令检查技能定义与近期对话细化触发条件明确要求按序执行执行质量随对话变长下降上下文过长观察对话轮次定期/compact或手动保存状态技能步骤与项目规范冲突通用定义未考虑项目例外对照项目实际约定在技能定义中补充例外字段改造后测试通过但行为异常验证只覆盖了测试用例检查测试覆盖率补充边界用例人工核对关键路径安装后命令不可用环境变量或版本兼容问题检查安装日志与系统版本按官方文档核对依赖版本注意速查表里的处理方式都是方向性的具体操作要结合你的实际环境。尤其是版本兼容类问题不同系统差异很大不要照搬别人的命令。6. 工具选型与组合使用的经验6.1 Claude Code 与 Codex CLI 的分工建议用了一段时间后我形成了一个比较稳定的分工Claude Code 负责“需要理解全局”的任务比如读多个文件、分析调用链、设计改造方案Codex CLI 负责“执行明确动作”的任务比如批量重命名、跑测试、格式化代码。这个分工的依据是两者的交互模式差异——Claude Code 更适合多轮对话式的探索Codex CLI 更适合命令式的执行。当然这不是绝对的。如果你只用一个工具把技能框架配好单工具也能覆盖大部分场景。关键是技能定义要清晰工具只是载体。6.2 接入第三方模型的注意事项热词里提到用 cc switch 接入其他模型这个思路本身没问题但要注意技能框架对模型能力有要求。技能执行需要模型能稳定遵循多步指令、能理解结构化定义、能在长上下文里保持一致性。能力不足的模型执行复杂技能时跳步和误解的概率会明显上升。我的建议是先用能力较强的模型把技能框架跑通确认流程本身没问题再考虑换模型。如果换了模型后技能执行质量下降先怀疑模型能力再怀疑技能定义。反过来排查容易走弯路。6.3 技能库的积累与复用技能定义写多了就形成一个技能库。我的做法是按任务类型分目录重构类、测试类、文档类、排查类。每个技能定义文件头部写清楚适用场景和最后更新日期。这样新任务来时先翻技能库看有没有现成的没有就新建新建完也归档进去。积累到二十来个技能后大部分日常任务都能找到对应的技能定义直接调用或者稍作修改就行。这个复利效应是技能框架最大的价值——你花在定义技能上的时间会在后续每一次任务里省回来。7. 一些踩坑之后的个人体会技能框架这东西刚上手时容易走两个极端。一个是定义得太粗跟没定义差不多代理还是自由发挥另一个是定义得太细每个动作都写死代理变成机械执行遇到定义外的情况就卡住。我自己的平衡点是步骤写到“可验证”的粒度就够了具体怎么实现留给代理判断。比如“运行失败用例并记录输出”是步骤“用pytest -k test_xxx -v运行”就是过细因为不同项目测试命令不一样。另一个体会是技能框架的价值在任务复杂度超过某个阈值后才明显。简单任务用它反而增加开销。判断标准很简单如果这个任务你让 AI 直接做出问题后你能一眼看出哪里错了那就不需要技能框架如果出问题后你需要花时间排查是哪个环节出的错那就值得用技能框架把环节拆开。最后分享一个我常用的小技巧在每个技能定义的末尾加一行“完成后向用户确认”让代理在技能结束时停下来等你确认而不是自动进入下一个技能。这一行能给你一个介入点发现方向不对可以及时纠正避免一路错到底。刚开始我觉得这样会打断节奏用久了发现这个停顿省下的返工时间远多于它带来的等待时间。
