ablate-ai-layer

剥离 AI 层

模型升级会悄然让指令过时。为了弥补较弱模型的不足而编写的规则，会变成累赘，与仍然重要的规则争夺注意力。阅读文件无法判断哪些规则已经过时。只有实验才能说明。

由你运行实验。由用户选择任务并批准结论。 不要把一串要运行的命令交给用户；脚本会驱动实验的两组测试。

如何确保结果可信

• 两组测试，每组多次运行。 剥离后的 Agent 不会明显失败，因此单次运行没有可供比较的对象，“看起来没问题”就会变成“删掉了关键规则”。同一组测试的两次运行也可能比两组测试之间的差异更大，所以每组至少运行一对，而这只是起点，不是目标。
• 不会把任何内容移到一旁。 每次运行都会在仓库外的临时目录中，从 HEAD 创建一个独立的 git worktree，运行后再删除。用户的工作树不会被修改，因此也不会忘记恢复。
• 默认只剥离始终加载的内容。 技能、子 Agent 和路径范围规则只有在触发时才会产生成本，因此删除它们并不能省下上下文。钩子和权限绝不会被改动：它们以代码形式运行，不会占用注意力。

---

第 1 步：梳理这一层

python <skill>/scripts/map_layer.py [repo_root]

只读操作。将每项内容归类为始终加载、按需加载或强制执行，并显示始终加载的内容在用户输入任何内容之前，每次会话都会占用多少成本。把这个数字展示给用户。

如果什么都没找到，就说明这一点并停止。没有内容可供测试。

第 2 步：获取探测任务

这是唯一不能替用户决定的事。 任务决定实验能否检测出任何差异。

好的探测任务是用户本来就会做的实际工作，涉及可能受项目约定影响的代码，并且需要添加需要接入的内容：测试、端点、迁移或命令。

坏的探测任务包括拼写错误、重命名或任何单行修复。这类任务完全可以直接推导出来，两组测试的结果会一致，用户就会错误地得出整个规则层毫无价值的结论。如果用户提出这类任务，要明确指出这一点，并请他们改选一个涉及项目约定的任务。

将双方商定的任务原封不动地写入文件。每次运行都要逐字节复用。

第 3 步：展示计划并征得批准

在花费任何资源之前，报告运行次数、所用模型、大致成本，以及不会触碰工作树。

python <skill>/scripts/run_ablation.py <repo> --task-file <task.md> --dry-run

试运行还会提示两件值得暂停确认的事：

• 工作树不干净。 worktree 基于 HEAD 创建，因此不会测试尚未提交的编辑。建议先提交或暂存。
• 构建依赖警告。 有些仓库会将自己的 AI 层作为源码导入。如果 CLI 在构建时读取技能 Markdown，那么这些文件一旦缺失就会导致构建失败，而用户可能会把编译错误误认为 Agent 退化。如果出现此警告，请保留 --scope always。

第 4 步：运行实验

python <skill>/scripts/run_ablation.py <repo> --task-file <task.md> --runs 2

这就是完整的实验流程。它会为每次运行创建全新的 worktree，在剥离组中移除这一层，在每组中运行相同的提示词，捕获所有差异，清理所有 worktree，并将结果写入 .ablation/<timestamp>/（已加入 gitignore）。

实用标志：用户打算依据结果采取行动时使用 --runs 3；使用 --scope all 测试更大胆的假设，即技能和子 Agent 也已过时；使用 --model 指定模型；使用 --jobs 设置并发数；使用 --runner 指定非 Claude Agent，以便从 stdin 读取提示词。

如果某一组没有产出任何可用结果，就停止。某组没有结果意味着实验出了问题，并非得出了结论。请重新运行，再据此作出任何判断。

第 5 步：评分

分析前先阅读 references/comparison.md。这是评分标准，其中包含两条决定结果是真实发现还是自信的误判的关键原则：逐条规则评分，而不是比较两组之间的差异；评分时不要看差异来自哪一组。

简而言之：

1. 将始终加载的文件整理成编号清单，每项都是可测试的主张。把任何不可证伪的内容（如“编写整洁的代码”）明确标记为不可证伪。
2. 根据每项主张评判每次运行的差异：followed、violated 或 n/a。
3. 只有完成评分后，才将判定对应回各组并查看模式。

第 6 步：报告

向用户提供一张表格，每条规则占一行，并按可采取行动的优先级排序：

多次运行中的模式	判定	行动
对照组遵循，剥离组违反	有关键作用	保留，改写得更简短
两组都遵循	模型本来就会这样做	删除
两组都违反	即使加载也被忽略	将其做成钩子或测试，或者删除
从未适用	未经测试	保留，目前没有证据支持任何一方
同一组内结果不一致	噪声	增加运行次数，或换一个更好的任务

要让“未经测试”在视觉上与“没有差异”明确区分。它们在数据中看起来相同，含义却正好相反；混为一谈，就会导致误删一条规则，而这条规则保护的情形在本次任务中从未涉及。

第 7 步：征得用户同意后应用修改

未经用户同意，绝不擅自编辑规则文件。先提出修改建议并展示差异，然后等待用户回复。

仅对有观察证据支持的规则，逐条重新添加或保留；优先采用测试，其次是钩子，再次是按需指令，最后才考虑始终加载的规则。完成后重新运行 map_layer.py，让新的始终加载规则总量与旧总量并列显示。

---

向用户坦诚说明的内容

• 一次探测任务只是一个数据点，不是最终结论。 在删除大块内容前，建议再针对代码库的其他部分执行一次任务。
• 没有差异也是一种真实结果。 如果两组结果相同，说明该层的这一部分确实已经失去作用，可以删除。
• 反过来也一样。 不要因为一次顺利运行，就认定可以删除那些针对本次任务未涉及情形的规则：安全、合规、发布流程。
• 现有代码可以替代规则文件。 如果附近有可供参考的代码，剥离后的运行会沿用其约定。同一条规则在修改已有文件时可能有效，在新文件中却可能失效。应更重视新文件的证据，并说明每项判定依据的是哪类证据。
• 与前沿模型相比，成本较低、规模较小的模型更依赖指令。 在前沿模型下看似多余的一层，对成本较低的模型仍可能有用。如果团队使用多种模型，应针对所用模型中能力最弱的那个进行消融测试。

资源

• scripts/map_layer.py：只读地清点该层内容，与 Agent 无关。
• scripts/run_ablation.py：运行两组并收集差异。--help 会列出所有标志。不要将任一脚本读入上下文；只查看脚本输出。
• references/comparison.md：评分标准。第 5 步前请先阅读。