paper-pilot-before-batch：批量任务先小样本

核心理念

批量任务的可怕之处：跑错 1 个 = 跑错 100 个。 小样本花 1 分钟，全量跑错回滚要 1 小时。

批量是放大器。脚本对了，放大效率；脚本错了，放大灾难。

---

触发条件

满足任一条 → 触发：

• 用户说"全部"、"所有"、"每一个"、"逐个"、"批量"、"统一"
• 操作对象数量 ≥ 30（文件 / 段落 / 引用 / 行）
• 操作对象数量未知（"整个目录的"、"全篇的"、"剩下的"）
• 涉及修改性操作（不是只读 / 查询）

---

强制流程

检测到批量操作
        │
        ▼
随机抽 3–5 个样本（不要只取前 3 个，前 3 个常常是规整数据）
        │
        ▼
只对样本执行
        │
        ▼
把样本结果展示给用户：
  - 每个样本的"改动前 vs 改动后"
  - 每个样本的"判断依据"（为什么这样改）
        │
        ▼
明确问用户：
「这是 N 个样本的改法，逻辑对的话我推全量（共 M 个）。
有不对的请指出，我调整后重新跑样本。」
        │
        ▼
确认 → 全量（≥ 30 时配合 paper-parallel-audit 用并行 Agent）
不对 → 改逻辑 → 重新跑样本

---

抽样策略（不是随便抽）

抽样要覆盖边界情况：

• 1 个最常见的情况
• 1 个看起来可能出问题的情况（最长 / 最短 / 含特殊符号 / 跨行）
• 1 个完全不该被处理的情况（验证你的判定逻辑不会误伤）

不要 head -3 —— 前 3 个常常是规整数据，跑过样本不代表跑过全量。

---

标准回复模板

这是个批量操作，共 M 个对象。 先抽 5 个样本跑一下，包括 1 个常见情况、1 个边界情况、1 个不该被改的情况。

[样本 1] 改前 → 改后，依据：… [样本 2] … [样本 3] …

5 个看着对的话，我就推剩下的 M-5 个。 有看着不对的请指出来，我调整后重跑样本。

---

❌ 反例（书 §10）

用户：「把所有引用的格式按 GB/T 7714 统一一下。」（共 156 条）

错误做法：写一个正则脚本，一次性跑 156 条——结果发现：

• 部分引用里的"等"被当成 et al. 多处理了一次
• 部分中文姓名拼音被错拆
• 全部 156 条都错，且原始格式没存

正确做法：先跑 5 条样本（含 1 条中文姓名、1 条多作者带"等"、1 条单作者）→ 用户检查 → 修正脚本 → 再推 156 条。

---

"可以跳过样本" 的极少数情况

• 纯只读：批量统计、批量列出（不修改任何文件）
• 逐条用户确认：每条都让用户点头才下一条（实质就是没批量）
• 数量 < 30 且每条 < 1 秒：直接做完，结果可视

---

Rationalization Table

念头	现实
"我已经在脑子里推演过了，肯定对"	推演 ≠ 实测。书里的 156 条惨案，AI 也"推演过"
"用户着急，跳过样本更快"	跑样本 1 分钟 vs 跑错回滚 1 小时
"这个任务很简单，正则一行就搞定"	简单的正则吃掉的都是边界情况
"我跑前 3 个验证一下"	前 3 个不是样本，是规整数据
"我备份了，跑错了能回滚"	回滚是兜底，不是策略
"用户说他相信我直接全量跑"	仍然先 5 个样本，跑出来给他看

---

Red Flags

• 你即将对 ≥ 30 个对象 / 文件循环调用 Edit / Write → 停，先样本
• 你写了一段 for 循环 / 正则替换准备 apply 全量 → 停，先样本
• 你想"先跑一半看看" → 一半不是样本，跑错就 50 个错的
• 用户说"直接跑全量" → 仍然先 5 个样本，把结果给他看

---

配套 skill

• 全量阶段如果 ≥ 30，配合 paper-parallel-audit 用并行 Agent
• 修改性操作前必须 paper-confirm-before-doing 已经确认过方案

---

来源

《Claude Code 科研手记》第 10 章「并行 Agent」、§4.2「批量文献核查」