Converge Loop 是一个面向代码库的收敛循环技能,目标是通过一系列小而经过验证的步骤,把代码从当前状态推进到目标状态,并在四种情况之一发生时立即停止:已收敛、迭代次数耗尽、预算耗尽、或不再有进展。其核心价值不在于“会循环”,而在于“会循环并且可靠地停止,无论结果如何都给出诚实的判定”。
用途
该技能用于把代码库驱动到某个可测量的目标状态。目标以可测量的方式陈述,例如让 pnpm -w test 退出码为 0、移除 knip 报告的所有未使用导出、安全审计无发现。
主要能力
支持两种模式。until-green:存在一条命令,其成功即目标(如 tsc --noEmit、pytest、cargo build、eslint、validate 脚本),循环把该命令的退出状态驱动到 0。until-dry:目标是“不再存在 X”,X 每轮被发现(如死代码、lint 发现、缺失测试、审计发现),循环重复“查找→处理”直到某一轮找不到任何项。
使用方式
第 0 步:选择模式并固定终止集合。在改动代码前写下终止集合,包括 done-condition、maxIterations、budget、maxStall、scope-per-iteration 四个字段,可根据任务调整数值但不得删除字段。
第 1 步:基线信号。在改动前先运行一次检查并记录起始信号。until-green 记录退出码和结构化失败列表;until-dry 记录每项的数量与身份(file:line)。若信号已达标则直接停止,零次迭代。
第 2 步:迭代——每次一个小而经过验证的步骤。选择最小的下一个单元(一个失败类或一个新发现),做最小改动,重新测量,比较信号:改善则保留并继续;无变化或回退则视为停滞,必要时回退,记录停滞,尝试不同方法或标记该单元受阻并转向下一个。同时递减迭代计数、检查预算、更新停滞计数。对于繁重或可并行的工作,可将每单元工作委托给 Agent 或 fan-out-work,但循环控制、测量和终止记账仍留在协调者处。
第 3 步:检测无进展与防抖动。进展是测量出来的而非假设的。需防范:信号持平(连续两轮相同计数/失败集)、振荡(修复 A 重新破坏 B,修复 B 又破坏 A,通过哈希失败集检测)、回退(计数上升,立即回退上次改动)、范围蔓延(编辑与任何失败/发现无关的文件)。触发任一项时,循环以 converged: false 停止并指出阻塞单元。
第 4 步:终止并诚实报告。退出原因分为 converged、exhausted-iterations / exhausted-budget、stalled。始终报告增量:起始信号→结束信号、使用的迭代次数、花费的预算。
适用场景
适用于需要把代码库推进到可测量目标状态的工程任务,例如让测试通过、清除死代码、消除 lint 发现、修复类型错误、处理安全审计发现等。
限制与护栏
不得在没有全部四个终止字段的情况下循环;不得在机器可检查的 done-condition 未真正通过时报告 converged: true;每次迭代的改动不得大于所处理的单元;不得重复尝试相同的失败改动;不得让循环把代码库往回拉;不得通过删除/跳过失败测试、批量 eslint-disable、@ts-ignore 等方式压制信号来“通过”。遇到用户拥有的决策应升级而非在循环内猜测。
原生目标/循环路由
Claude Code 原生提供循环脚手架,可将终止集合编译进去:/goal 为 done-condition,每轮后由独立模型验证;/loop 为循环周期,以时间/次数/事件停止作为外层 maxIterations。仍需手工实现的是防抖动检测器(第 3 步)和每次迭代一个单元的范围控制。
参考文档
references/native-goal-loop.md:终止集合到原生 /goal + /loop 的编译(含 Codex 映射)。references/termination-and-thrash.md:终止集合的完整理由、无进展/振荡检测器(失败集哈希)与预算记账方法。references/loop-patterns.md:具体的 until-green 与 until-dry 模式(内联与 Workflow 工具形态、带对抗验证的 fan-out、每单元有界修复循环)。
输出契约
报告内容:模式与所用终止集合;起始信号→结束信号(增量);使用的迭代次数、花费的预算、退出原因;已解决的单元,若未收敛则枚举未解决单元及各自仍受阻的原因。