---
name: auto-converge
description: >
  通过外部对标+对抗迭代让规则/技能/SKILL.md 收敛到可执行状态。
  当用户说"打磨这个 skill""收敛规则""这个 skill 写出来不 work，帮我调"
  "怎么让 agent 严格按规则执行"时触发。
  也适用于任何需要把一份规则文档从"写完了但 agent 不遵守"
  变成"agent 能稳定执行"的场景。
---

# auto-converge——让规则从写完了变成能执行

两个策略驱动——

1. **外部对标**：先研读高质量参考（同类工具的文档、博客、规范），提取差距和缺失项，不闭门造车
2. **对抗收敛**：写样例 → subagent 零容忍审查 → 量化违规数 → 修复 → 重复直到违规 < 5，规则不是改一次就对的

两条策略必须同时执行。只看参考不迭代，规则停留在理论正确但 agent 执行不走；只迭代不看参考，规则在低水平收敛但没有吸收业界最佳实践。

---

## 适用于什么

不限于 SKILL.md——任何需要 agent 稳定遵守的规范都可以收敛。常见场景——

| 用户说的 | 实际要收敛的东西 | 样例是什么 |
|---------|----------------|-----------|
| "这个 prompt 写好了但 agent 返回格式老不对" | prompt 模板 | 一组 agent 的实际输出 |
| "团队的 code review checklist 没人真按那个查" | review 检查清单 | 对同一段代码的审查记录 |
| "想让 agent 写的 API 文档风格统一" | 文档写作规范 | 几篇按规范写的 API 文档 |
| "这个部署检查表每次都有项漏掉" | 部署 checklist | 模拟执行记录 |
| "agent 回复用户的语气不统一" | 回复风格指南 | agent 对话记录 |
| "这个 project README 永远写不规范" | README 模板/规范 | 按模板写的 README |
| "git commit message 格式老不一致" | commit 规范 | 一组 commit message |
| "这个 skill 写出来了但 agent 不遵守" | SKILL.md 规则 | 按 skill 写的输出 |
| "想让 agent 列出来的东西都有这个格式" | 输出格式规范 | 格式化的输出样例 |

核心模式不变——只要你能说明**agent 应该遵守什么**且有**参考源可以学习**，auto-converge 就能做。收敛对象可以是 markdown 文件、prompt 字符串、JSON schema、checklist、或者任何有规则的文本文档。

---

## 触发条件

- 用户描述了一个规范/规则但 agent 屡次违反
- 用户给了一个文件路径，说"让它能执行""让它变得可验证"
- 用户说"帮我打磨""收敛""这个写出来不 work"

如果用户只说了"agent 做得不好"但没明确规范在哪——先帮他把规范落到文件里，再收敛。收敛的前提是规范有地方写。

---

## 工作流程

### 第 1 步：澄清三个问题

在开始对标之前，必须确认以下三点。不问清楚就动手，收敛方向可能和用户实际需求完全错位——

1. **收敛什么东西？**——如果有现成文件，拿路径。如果没有，帮用户把规范写下来再收敛。文件格式不限（.md、.json、.txt、prompt 字符串都可以）。
2. **"agent 遵守"怎么验证？**——对 commit 规范来说是生成的 message 是否合规，对 prompt 来说是 agent 的输出是否按格式，对 checklist 来说是检查项是否全部覆盖。这个验证方式决定了样例长什么样。
3. **参考源是什么？**——没有参考不启动。参考可以是同类项目的文档、官方规范（如 Conventional Commits）、用户认为写得好的范例、或者实际运行中成功的输出记录。外部对标是收敛的方向感来源。

### 第 2 步：对标差距分析

并行读目标规范和参考源，产出**对标差距清单**——逐项列出参考有而目标规范缺的东西，按优先级排序。差距清单不追求全面，追求可操作：每条差距必须能在第 3 步转化为一条写前红灯或一条规则补充。

### 第 3 步：提取写前红灯 checklist

从对标差距清单中提炼 5-10 条写前自检项，作为生成样例前 30 秒扫一眼的红灯。红灯覆盖的不是"好的写法"（那是规则层面的事），而是"写完必然会犯、审查再修、下次还会犯"的机械性违规——对 commit 规范来说是前缀格式/语言/长度，对 prompt 来说是占位符/转义/必填字段。

红灯清单嵌入目标规范的执行流程中，放在"生成输出"之前。写完再查就是抓虫，写之前查是避坑。

### 第 4 步：对抗收敛循环

每轮——

1. **按当前规范生成一组样例**——样例形式取决于第 1 步确认的验证方式（commit message、prompt 输出、代码审查记录、README 草稿等等）。数量以 5-10 个为宜，太少测不全，太多审查成本高。
2. **派 subagent 审查**——独立上下文，prompt 中嵌入目标规范全文（不是摘要），要求零容忍、只报违规、逐条给出位置+原文+规则+建议。审查 subagent 的默认倾向是放水——prompt 里必须写明"宁可误判也不漏判"。
3. **量化**——统计违规数，按类别分类。
4. **决策**——
   - 违规 < 5 且无系统性类别（某类违规 > 2）→ 收敛，进入第 5 步
   - 违规 ≥ 5 或有系统性类别 → 修复样例 + 调整规范（补红灯、强化条款、新增反例），进入下一轮
5. **换场景**——每轮样例换个场景/主题，避免 agent 从"按规则做"退化为"背答案"。不同场景是对规则泛化能力的压力测试。

收敛判定标准：违规 < 5 且无任何违规类别超过 2 处。连续 2 轮违规数不降反升→回滚上轮规则变更后重新分析（通常是新增规则过于模糊或互相矛盾）。

### 第 5 步：输出收敛报告

包含——

- 违规收敛曲线（每轮违规数）
- 规范文件变更清单（新增/修改了哪些规则）
- 样例列表（每轮主题+是否通过）
- 残留问题（若未完全收敛则标注原因和建议）
- 红灯 checklist 最终版本

---

## 收敛循环的关键约束

**审查 subagent 的 prompt 必须嵌入规范全文。** 不能用摘要，不能在 prompt 里口头描述规则——subagent 只能对照原文审查，不能用自己对规则的理解替代原文。prompt 中必须包含"零容忍、只报违规"的对抗指令。

**样例必须涉及不同场景/主题。** 同一场景连写多轮会让 agent 退化为背答案——违规数表面下降，换个场景就反弹。

**规则调整必须有针对性。** 审查挑出 A 类违规后不要本能地往规范里加一堆 A 类细则——先判断违规是"规则不够细"还是"执行没注意到"。规则细就补规则，执行问题就补红灯。规则膨胀是收敛的敌人。

**规范的格式不能成为审查的盲区。** 如果目标规范是一段 prompt，审查 subagent 的 prompt 里要包含规范原文 + 对格式的明确检查项（如"输出是否包含必填字段""占位符是否全部替换"）。格式类违规 subagent 有时会忽略，需要显式提醒。

---

## 参考案例

| 案例 | 规范类型 | 收敛轮数 | 终局违规 |
|------|---------|:--:|:--:|
| `blog-writer` SKILL.md | 写作规则（~50 条） | 6 | 3 |
| `git-commit-style` SKILL.md | 格式规范（8 条） | 1 | 1 |

完整记录见对应 git 提交 `5757b879`。