用途
contract-conformance-loop 是一个配置于 loop-controller 之上的循环技能,用于“构建直到规范成立”:驱动一个实现过程,直到作者编写的契约(contract)中每一条标准都通过验证。它把契约审计(contract-auditor)包装成一个默认 FAIL 的评估器,并采用生成器/评估器分离的 Plan-Generate-Evaluate(PGE / GAN 风格)循环,防止构建者给自己的作品打分。
主要能力
- 五部分契约结构:触发条件(存在作者编写的契约,或显式调用 /contract-conformance-loop)、动作(一轮迭代:生成器针对一条未通过标准实现或修复,评估器检查全部标准)、证明(评估器确认每条标准均有通过证据)、记忆(criteria.json、PROGRESS.md、每条标准转绿时的 git 检查点)、停止(全部通过、迭代上限、连续 3 轮无进展或预算上限)。
- 默认 FAIL 的证明机制:criteria.json 中每条标准初始为 "passed": false,只有评估器引用证据的判定才能将其翻转为 true。
- 两条收敛规则:评分者不是执行者(评估器为全新子代理,只看到产物与契约,看不到构建推理);评估器不能编辑(不携带 Write/Edit 工具,只能报告失败,不能悄悄降低标准)。
- 与既有配对协作:contract-author 编写规范,contract-auditor 作为评估器;本循环不重新实现二者,而是将它们编排进一个有界、默认 FAIL 的循环中。
使用方式
- 构建默认 FAIL 的 criteria JSON:从 contracts/ 读取作者编写的契约(openapi.yaml、data-layer.yaml、types.<ext> 以及 contracts/README.md 中的 Domain Rules),将每个可检查事实分解为一条可测试标准,写入 JSON 条目并设 "passed": false,存放在 profile 定义的路径(默认 criteria.json)。评估器无法对照证据检查的标准不算标准,需继续拆分。
- 生成器:针对一条失败标准实现:选取最高杠杆的 "passed": false 标准,让构建者只实现或修复这一条。每轮一条标准,不要批量处理,批量会破坏“哪个改动影响了哪条标准”的信号。更新 PROGRESS.md。
- 评估器:从全新上下文给全部标准评分:全新启动评估器子代理(contract-auditor),不携带 Write/Edit 工具,对构建推理不可见,只交给它契约、实现和 criteria.json。它对照证据重新检查每一条标准(重新验证整体,而非仅刚触碰的那条),返回 criteria JSON,每条要么仍为 false(附反馈),要么翻转为 true(附翻转证据)。构建者永远不编辑 criteria.json,只有评估器的判定可以。
- 反馈失败、检查点、重复:将评估器判定合并进 criteria.json。在转绿轮次(某条标准新变为 true 且无回退)提交一个检查点,命名所满足的标准。将仍失败的标准及其反馈送入下一轮生成器。当评估器在一次整体重新检查中确认全部标准通过时,循环结束,报告最终 criteria.json 作为证据。
适用场景
- 存在作者编写的契约,且需要构建或验证一个实现使其符合契约。
- 任何标准具有主观性,或需要跨文件判断(例如实现是否导入了共享类型、领域规则是否真正成立)。
- 作为编排器下的“构建直到规范”内循环(archetype 2):编排器通过 contract-author 编写契约(其 Phase 4),然后派发本循环,以构建者角色为生成器、contract-auditor 为评估器。
限制
- 默认禁用模型自动调用:该循环会自行编辑并提交代码,且每轮花费 token 启动评估器子代理,直到每条契约标准通过。应显式输入 /contract-conformance-loop 或由编排器派发,而非让 Claude 因存在契约就静默启动自主构建循环。
- 迭代上限:默认约 10–15 轮构建/评估(若 .claude/profile.yaml 有设置则读取)。达到上限是停止并升级,不是削弱契约或让构建者自行通过标准的许可。
- 无进展检测:若同一组标准连续 3 轮保持 false,停止并升级。三轮标准数量不变意味着方法错误或标准含糊,需暴露出来(可能是契约缺口,contract-auditor 会标记而非让实现失败)。
- 预算上限:评估器子代理每轮消耗一个完整全新上下文,长跑比自评分循环昂贵得多。需关注 /cost,到达上限即终止,而非仅警告。
- 禁止构建者自评:构建者将 criteria.json 条目翻转为 true、软化标准,或评估器复用构建者上下文(必须全新且无 Write/Edit),均属禁止,且每一项都是发现项。构建者写的绿色不是证明,只有评估器的判定才是。
- 不可逆操作前需 HITL:若满足某条标准会触及不可逆事物(对真实数据库的迁移、外部 API),这是 HITL 检查点,需暂停等待人工。
- 驱动原语选择:规范形式是技能编排生成器 + 评估器子代理,评估器子代理即证明,因此本循环总是启动它(故 allowed-tools 含 Agent)。仅当每条标准都能从命令输出完全证明时(例如契约完全归约为测试套件 + schema 验证退出码),才可用 /goal 替代,此时循环退化为“修复直到变绿”。一旦某条标准需要判断,就回退到全新评估器。
- 与相邻技能的区别:与 contract-auditor 相比,后者是一次性静态审计报告不匹配,本技能是有界迭代循环将其驱动到零,把审计器包装为默认 FAIL 的评估器装置;与 fix-until-green 相比,后者的证明是三个退出码,本技能的证明是逐条契约证据由全新评估器评分。当“完成”是测试套件时用 fix-until-green,当“完成”是“契约标准全部成立”且其中一些无法由单一退出码证明时用本技能。
- 编排器下的规则:编排器不覆盖卡住的循环;若循环在无进展后升级,那是真实的符合性阻塞或契约缺口,不是可以掩盖的数字。满足的 criteria.json 为构建提供信息,但 qe-agent 的 qa-report.json 仍决定门禁(循环提供信息,门禁做决定)。
参考文件
references/pge-loop.md — 完整的生成器/评估器分离、带具体 JSON 示例的 criteria.json 默认 FAIL schema,以及全新上下文评估器派发(无 Write/Edit、对构建推理不可见、返回逐条判定)。