| name | paper-pilot-before-batch |
| description | 在执行任何 ≥ 30 条目的批量任务（批量改文件、批量核查引用、批量重命名、批量格式统一）之前，
必须先在 3–5 个样本上跑一遍，把样本结果给用户看，确认逻辑正确后再推全量。
Use when 用户请求处理"全部"、"所有"、"批量"、"逐个"某类对象，
且对象数量 ≥ 30，或数量未知（"把整个目录的..."）。
|
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「批量文献核查」
