Agent Skill 自动修复实战：从追加规则到可审批补丁的重构指南

自动修复工具最容易犯的错，是把“发现问题”直接翻译成“再加一段说明”。这样做看似聪明，实际很危险，因为每一次追加都可能把正文推向更大的冲突面。真正值得保留的，不是某次修复时写得多，而是修复过程能不能留下一个可审批、可复查、可回滚的补丁。对自动修复来说，能被验证的修改，比会说话的修改重要得多。

393.ee 这个角度更偏落地：怎么把自动修复从“随手写正文”改成“先生成候选补丁，再走审核，再合并”。在一个从 400 行膨胀到 1500 行的个案里，问题不是某一句话写错了，而是自动修复把多个职责混成了一个长串。只要补丁流程不拆开，这种膨胀就会一轮接一轮地发生。

所以这里讨论的不是更会写，而是更会收。收的是重复，收的是冲突，收的是临时例外，收的是没法回归的长句。只有把这些东西收回各自的位置，自动修复才像工程，不像即兴作文。

一、把补丁和正文分开，别让工具直接改主文档

最重要的一条原则是：自动修复工具不要直接把新内容写进主文档。它应该先产出候选补丁，列出改了什么、为什么改、依赖哪条 badcase、预期解决什么问题、是否触发预算。只有当这些信息完整时，补丁才值得进入审批。直接改正文的坏处很简单：一旦错了，修复痕迹就和正式规则混在一起，后面的人很难分辨哪些是治理产物，哪些只是仓促判断。

候选补丁最好带差异说明。不是只展示新句子，而是说明它替换了哪条重复规则、合并了哪组同义表达、移动了哪段例外、删除了哪类旧补充。这样人就能快速判断这次修复是在收敛，还是在继续堆字。没有差异说明，审批只能靠读全文，效率会很低。

补丁字段	为什么需要	缺失时的问题
change_reason	说明触发来源	看不出是修复还是任性扩写
affected_rules	说明改动范围	容易把无关规则一起改坏
badcase_link	说明失败来源	无法追溯问题起点
regression_result	说明是否回归通过	修复没有验证闭环
rollback_note	说明如何撤销	上线后发现问题也退不回去

二、先做语义去重，再谈新增内容

很多自动修复看起来像新增，其实只是把旧规则换了几种说法。比如“不要输出建议”“不要给额外建议”“结尾不允许扩写建议”“只保留结论”这些句子，如果都进入正文，就会让同一个意图占据多处注意力。语义去重的任务，就是在写入前先认出它们属于同一簇，然后决定是合并、替换还是删除。

这里最容易犯的错，是把去重理解成文本相同才算重复。真正该查的是意图重复。只要目标、触发条件和执行结果一致，就应该考虑合并到一条主规则下面，再通过示例和回归样本补足语境，而不是让正文继续长出平行版本。去重做得好，文档会明显变短，但能力不会丢。

如果去重做不好，自动修复会把一条规则越修越散。今天补在开头，明天补在示例，后天补在附录，最后谁也不知道哪一段才是权威。那时的长度增长，看似在增强，实则在分权。

三、冲突矩阵比自然语言解释更可靠

自动修复最怕的是局部正确、整体打架。为了避免这个问题，补丁流程里应该有一份冲突矩阵。矩阵不需要复杂，但要能说明：哪条规则是主干，哪条是例外，哪条会覆盖哪条，哪类输出必须先服从格式，哪类安全边界不能被工具步骤绕过。只靠自然语言解释冲突，最后通常会变成更长的自然语言解释。

矩阵最好是结构化的。行放规则，列放优先级、适用场景、依赖对象、覆盖关系、回滚方式。每次修补前先更新矩阵，能够减少很多凭感觉写进去的句子。因为一旦矩阵摆出来，很多“好像也可以”的说法就会暴露出它们其实冲突很大。

对自动修复工具来说，冲突矩阵还有一个好处：它能告诉工具什么时候不该继续写。只要发现某组规则已经互相抢位置，就先停下来做重构，而不是继续往正文加句子。停一下，往往比再写一段更专业。

四、坏例子要绑定修复动作，而不是只留在备注里

一个靠谱的自动修复闭环，必须让 badcase 和修复动作一一对应。这个 badcase 触发了哪条修复建议，最终是删除、合并、外置参考，还是新增回归样本，这些都应该留下记录。否则以后再遇到相似问题，系统只会知道“曾经改过”，不会知道“为什么这么改”。

建议把 badcase 分成三种：重复型、冲突型、遗漏型。重复型意味着已有规则说了太多遍；冲突型意味着不同规则在争夺执行权；遗漏型意味着缺了真正需要的主规则。三种类型对应三种动作，不能混着处理。只要分类清楚，自动修复就更像维护，而不是随机补丁。

每个 badcase 最后都要回到回归集里，成为后续版本的守门员。这样，自动修复才不会每次都忘记自己刚刚为什么改。

五、回归集应当包含“修好过”的样本

回归集不能只装失败样本，还要装那些曾经修好过、但很容易被再次改坏的样本。很多团队在修复时能一次通过，过几周又开始走样，就是因为回归集缺少这种样本。它们是最适合防止反复膨胀的样本，因为它们能提醒你：这条规则虽然当前有效，但一旦被改写，就可能重新散掉。

对自动修复工具来说，回归集不是装饰，而是拦截器。每次候选补丁生成后，先跑回归，再决定是否进入审批。只要回归没过，修复就只能算候选，不算完成。这个顺序不能反过来，否则人会被“写得很像对的”诱导，最后把不稳定版本放进正文。

如果想让回归集更强一点，可以把样本按场景分层：核心业务、边界输入、工具调用、格式输出、安全限制。分层之后，修复会更有方向，评估也更准确。

六、规则预算要写到工具里，不要只写在文档里

很多团队嘴上说“不能再长了”，但工具完全不知道这件事。结果自动修复照样每次加几段，直到正文快要失去重心。规则预算如果只写在说明文档里，约束力很弱；如果写到工具里，工具就会在超限时主动停下、报警、或者要求人工确认。前者是愿望，后者是门槛。

预算可以按类型设：新增规则数、总字符数、重复簇数、冲突簇数、外部引用数、回归未覆盖数。只要超标，就不允许直接合并。这样做的好处是，修复者会主动寻找压缩方案，而不是默认扩写。自动修复真正应该练的不是“写更多”，而是“写得更准”。

预算存在的意义，不是让系统变慢，而是让系统停止无意识膨胀。只要预算能生效，很多正文就会自然转向外部参考、结构化表格和回归样本，而不是继续堆叠自然语言。

七、正向行为模板要比禁止句更适合机器执行

如果你希望自动修复工具真的会把规则写对，就不要只给它一串“不要做什么”。工具更容易执行的是正向模板：先找重复，再找冲突；先列出来源，再决定合并；先补回归，再写正文；先说明回滚，再请求审批。这样的顺序让动作可见，也让失败点可见。

正向模板还有一个现实好处：它更容易转成结构化检查。比如“先找重复”可以对应重复检测脚本，“先列出来源”可以对应 badcase 绑定，“先补回归”可以对应测试目录，“再请求审批”可以对应人工签核。这样一来，自动修复就不是靠语言感觉，而是靠流程跑通。

当模板足够清楚时，正文本身会更短。因为工具知道什么该外置，什么该留在主文档，什么该只是注释。短不是偷懒，短是职责分离后的结果。

八、参考文件一致性决定修复是不是在原地打转

自动修复常常把问题改到别的地方去。主文档改了，参考文件没改；说明页改了，示例没改；回归集更新了，正文却还在引用旧定义。这样的结果，就是看似修完了，实际上只是把不一致扩散到更多文件。修复流程如果不检查参考一致性，就永远不能算真正完成。

最稳妥的办法，是把正文、参考、示例、测试四类文件做联动。正文说原则，参考说细节，示例说边界，测试说判定。任何一处改动，都要检查其他三处有没有相应变化。这样自动修复才不会在一个文件里打赢，在另一个文件里又把自己打回去。

一致性检查做得越早，后面越省事。不要等到发布前才发现定义对不上，那时往往已经堆了很多补丁，谁也不愿意重拆。

九、人工审批应该看补丁，而不是看修复者信心

自动修复越顺手，越需要人工按住最后一关。审批不该被理解成“看一眼就签”，而是要认真看补丁的结构：它删了什么，保留了什么，为什么不是别的做法，是否触发预算，是否已经有回归，是否存在未解决的冲突。信心很容易演出来，补丁却演不了。

对于高风险变更，最好要求二次复核。比如涉及权限、边界、工具调用、回滚点的改动，不要只过一双眼。补丁越关键，审批越不能省。因为自动修复的效率优势，往往就是它的风险来源。

审批做到位时，团队会慢慢建立一种很重要的感觉：不是每个错误都必须立刻写进正文。很多时候，先把它放回回归集、外部参考或说明文件，反而是更成熟的做法。

十、回滚方案要和补丁一起生成

每一个自动修复候选补丁，最好在生成时就同时写出回滚方案。因为如果等补丁合并之后再想回滚，很多上下文就已经散了。回滚方案不需要华丽，只需要明确：撤销哪条修改，恢复哪一版参考，重跑哪些回归，谁有权限执行回滚。能说清楚这些，出了问题就不会乱。

回滚不是失败，而是补丁质量的一部分。一个真正成熟的修复系统，不是永远不退，而是知道什么时候该退，退到哪里，退完怎么再走。自动修复如果没有回滚意识，文档就会越来越像不可逆拼接。

所以在流程里，最好把回滚和审批并列。补丁没回滚方案，不进审批；审批没通过，不进正文。这个习惯一旦养成，系统会明显稳定很多。

十一、一个实战版流程可以这样排

先采集 badcase，再分类；先查重复，再查冲突；先对齐参考，再写候选补丁；先跑回归，再走人工审批；最后才合并版本并登记回滚。这个顺序看上去多了一些步骤，但它其实是在减少后续返工。每一个前置步骤，都在帮你避免把临时判断变成正式规则。

如果你现在就要把自动修复接到现有 Skill 上，别一上来就追求全面重写。先把补丁化、去重、冲突矩阵、回归集、预算、审批、回滚这七件事接起来。只要这七件事能工作，正文就会从“越改越长”慢慢变成“越改越清楚”。

自动修复真正值得追求的，不是写得快，而是写完还能收回来。