Claude Code batch Skill 详解：用 5–30 个 Git Worktree 并行 Agent 完成跨仓库大规模变更

本文以 Claude Code 内置的 batch 技能（Anthropic/claude-code/skills/batch/SKILL.md）为核心，完整拆解其"研究规划 → 并行执行 → 进度跟踪"三阶段编排流程，并结合仓库中 Claude Code 主系统提示词对 Agent 工具的 isolation / run_in_background 参数、git worktree 隔离机制以及配套 code-review 技能的源码级定义，讲清楚如何把一次可分解的机械式大改动（迁移、重构、批量重命名）安全地拆成 5–30 个互不依赖的并行工作单元，每个单元独立开 PR。读完后你可以理解该技能的完整 Prompt 工程结构，并掌握将其编排思路迁移到自己 Agent 工作流中的关键约束：分解独立性、e2e 验证配方、自包含 Prompt 与 PR: <url> 汇报协议。

batch 是什么：定位与触发条件

batch 是 Claude Code 的内置 Skill，其 frontmatter 完整声明了技能身份：

---
name: batch
description: Research and plan a large-scale change, then execute it in
  parallel across 5–30 isolated worktree agents that each open a PR.
when_to_use: Use when the user wants to make a sweeping, mechanical change
  across many files (migrations, refactors, bulk renames) that can be
  decomposed into independent parallel units.
---

三个字段划定了它的能力边界：

• 做什么：先研究和规划一次大规模变更，再在 5–30 个相互隔离的 worktree Agent 中并行执行，每个 Agent 各自开一个 PR；
• 何时用：仅当变更是"横扫式、机械式"且可分解为独立并行单元时——数据库迁移、批量重构、大规模重命名这类任务；
• 不做什么：Skill 正文第一句即声明角色——"You are orchestrating a large, parallelizable change across this codebase"（你正在编排一次可并行的代码库级变更），它是协调者（coordinator），不是直接改代码的执行者。

用户通过 Skill 调用传入的原始指令会被注入到模板中的 $ARGUMENTS 占位符处（## User Instruction 一节），协调者后续所有研究与分解都以该指令为源头。

Phase 1：研究规划（Plan Mode）

1.1 进入计划模式并调研范围

Skill 要求协调者立即调用 EnterPlanMode 工具进入计划模式，随后执行第一步调研：

1. 理解范围（Understand the scope）：启动一个或多个子代理在前台运行（"in the foreground — you need their results"），深入调研该指令触及的所有内容——找出所有需要改动的文件、模式和调用点，并理解现有代码约定，确保迁移风格一致。

前台运行是关键细节：规划阶段的结果要当场被协调者消费来设计分解方案，不能丢进后台等通知。这与 Claude Code 系统提示词中 Agent 工具的行为设定一致：子代理默认后台运行，需要立即拿到结果时必须显式传 run_in_background: false 同步执行（见 claude-code-opus-5.md）。

1.2 分解为独立工作单元（5–30 个）

第二步是核心的分解规则，原文给出了三条硬性约束和两条扩展原则：

每条工作单元（work unit）必须满足：

• 可在隔离的 git worktree 中独立实现——与兄弟单元零共享状态；
• 可独立合并——不依赖其他单元的 PR 先落地；
• 体量大致均匀——拆大合小。

数量与工作规模挂钩：文件少 → 接近 5 个单元；几百个文件 → 接近 30 个单元。切分方式上，优先按目录或按模块切（per-directory / per-module slicing），而不是随手罗列任意文件清单。

这一"5–30"区间与按模块切片的偏好，实质上是在并行收益与协调成本之间取平衡：单元太少，并行度不足；单元太多，规划、汇报、PR 审查的开销反噬收益。而"无共享状态 + 可独立合并"两条约束，正是 git worktree 隔离能成立的前提——若两个单元同时改一个文件，隔离 worktree 也无法避免合并冲突。

1.3 确定 e2e 测试配方

第三步要求为每个 worker 找到一条端到端验证路径——"不是单元测过了就行"（not just that unit tests pass）。Skill 给出四条候选路径，按变更类型对号入座：

变更类型	验证手段
UI 改动	使用 claude-in-chrome 技能或浏览器自动化工具：点穿受影响的流程，截图结果
CLI 改动	使用 tmux 或 CLI-verifier 技能：交互式启动应用，演练被改动的行为
API 改动	dev-server + curl 模式：启动服务器，请求受影响的端点
已有 e2e 套件	让 worker 直接跑现有的 e2e/集成测试套件

其中浏览器路径在仓库中确有对应实现：claude-in-chrome 技能定义了 mcp__claude-in-chrome__* 工具族（点击、填表、截图、读控制台日志、导航），batch 的 e2e 配方就是让 worker 在 worktree 里起本地服务后走这套流程截图取证。

若找不到具体 e2e 路径，Skill 规定必须用 AskUserQuestion 工具向用户提问，并基于调研结果给出 2–3 个具体选项（示例原文："Screenshot via chrome extension"、"Run bun run dev and curl the endpoint"、"No e2e — unit tests are sufficient"）。原文特别强调"不要跳过这一步——worker 自己无法向用户提问"：后台并行 Agent 没有向用户澄清的通道，所以验证方式必须在规划期一次性锁定。

最终配方要写成"worker 可自主执行的简短具体步骤"，包含任何前置准备（启动 dev server、先构建）和精确的验证命令/交互。

1.4 写计划文件并请求批准

计划文件（plan file）必须包含四样东西：

1. 调研发现摘要；
2. 编号的工作单元清单——每个单元含短标题、覆盖的文件/目录列表、一句话变更描述；
3. e2e 测试配方（若用户选择跳过，则写明 "skip e2e because …" 及理由）；
4. 将原样（verbatim）发给每个 Agent 的 worker 指令模板。

写完后调用 ExitPlanMode 向用户呈交计划。计划批准是 Phase 2 的唯一门禁——在用户点头之前不启动任何后台 Agent。

Phase 2：生成 Worker（计划批准后）

2.1 并行生成的硬性参数

计划批准后，用 Agent 工具为每个工作单元生成一个后台 Agent，原文的强制性措辞是：

All agents must use isolation: "worktree" and run_in_background: true. Launch them all in a single message block so they run in parallel.

这两个参数在 Claude Code 主系统提示词的 Agent 工具定义中有对应说明（claude-code-opus-5.md）：

• isolation: "worktree"：为 Agent 创建一个临时 git worktree，让它在仓库的隔离副本上工作，"auto-cleaned if unchanged"——若 Agent 没有产生任何改动，worktree 会被自动清理；
• run_in_background: true：Agent 进入后台，完成后以完成通知回报协调者；
• "在单个 message block 中全部发出"对应系统提示词中的并发规则："When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently"（claude-code-opus-5.md）。

从源码结构看，worktree 的底层管理还有更细的机制：Claude Code 的 EnterWorktree 工具会在 .claude/worktrees/ 目录下按新分支创建 worktree，基线由 worktree.baseRef 设置决定——fresh（默认）从 origin/<默认分支> 拉出，head 从当前本地 HEAD 拉出（claude-code-opus-5.md）。对 batch 场景而言，fresh 基线意味着每个 worker 都基于远端最新主干起分支，天然避免了"worker 之间基于彼此的未合并提交"这种隐性依赖。

worker 类型默认用 subagent_type: "general-purpose"，除非有更贴切的 Agent 类型。该类型的定义见 agents/general-purpose.md：一个 model: inherit、全工具（Tools: *）的通用执行代理，擅长跨大代码库搜索与多步任务——正好匹配"拿到一份自包含任务书，独立改完并自测"的 worker 角色。

2.2 Worker Prompt 的五要素：必须完全自包含

每个 Agent 的 Prompt 必须完全自包含（fully self-contained），因为后台 worker 既不能追问协调者，也看不到规划阶段的对话历史。原文列出五个必含要素：

1. 总体目标——用户的原始指令；
2. 本单元的具体任务——标题、文件清单、变更描述，从计划中逐字复制；
3. 调研发现的代码库约定——worker 需要遵守的现有规范；
4. e2e 测试配方——或直接写明 "skip e2e because …"；
5. 下方 worker 指令块——逐字复制（copied verbatim）。

这种"协调者把所有上下文压进单条 Prompt"的模式，是批量 Agent 系统规避"上下文丢失"缺陷的标准做法：worker 的成败只取决于它收到的那一段文字，规划期发现的一切知识（约定、陷阱、验证方式）都必须显式序列化进 Prompt。

2.3 Worker 收尾指令：五步流水线

原文要求逐字下发给每个 worker 的指令块如下（完整保留）：

After you finish implementing the change:
1. **Code review** — Invoke the `Skill` tool with `skill: "code-review"` to find
   correctness bugs (it reports findings; it does not edit code). Fix any
   findings it surfaces before continuing.
2. **Run unit tests** — Run the project's test suite (check for package.json
   scripts, Makefile targets, or common commands like `npm test`, `bun test`,
   `pytest`, `go test`). If tests fail, fix them.
3. **Test end-to-end** — Follow the e2e test recipe from the coordinator's
   prompt (below). If the recipe says to skip e2e for this unit, skip it.
4. **Commit and push** — Commit all changes with a clear message, push the
   branch, and create a PR with `gh pr create`. Use a descriptive title. If
   `gh` is not available or the push fails, note it in your final message.
5. **Report** — End with a single line: `PR: <url>` so the coordinator can
   track it. If no PR was created, end with `PR: none — <reason>`.

这条流水线值得逐条拆解：

第 1 步调用 code-review 技能——该技能在仓库中有完整定义（code-review/SKILL.md）：先跑 git diff @{upstream}...HEAD（无上游时退化为 git diff main...HEAD 或 git diff HEAD~1）确定审查范围，再用 8 个独立视角（逐行 diff 扫描、被删除行为审计、跨文件调用追踪、复用/简化/效率清理、实现深度、CLAUDE.md 约定）各找最多 6 个候选缺陷，随后经"单票验证"按 CONFIRMED / PLAUSIBLE / REFUTED 过滤，最终输出最多 10 条 JSON 格式的 findings。注意原文的括号说明——"it reports findings; it does not edit code"：review 是只读的，修复责任在 worker 自己，改完再继续。这等于给每个并行单元内置了一道独立于"作者视角"的审查关卡。

第 2 步单元测试覆盖了四种常见技术栈的探测顺序：package.json scripts、Makefile targets、npm test / bun test / pytest / go test。worker 需要自己发现项目的测试入口而不是假设固定命令。

第 4 步提交推送依赖 gh pr create 创建 PR，并预置了降级路径：gh 不可用或 push 失败时不崩溃、不静默，而是在最终消息中注明——失败信息会随完成通知回到协调者处，进入 Phase 3 的失败记录。

第 5 步汇报协议是全流程中最精巧的设计：worker 的最终消息以固定格式的一行 PR: <url> 结尾（未建 PR 则 PR: none — <reason>）。这行结构化输出是协调者机器可解析的"合约"——Phase 3 的进度表完全靠解析这行来更新状态。

Phase 3：跟踪进度

所有 worker 启动后，协调者立即渲染初始状态表：

#	Unit	Status	PR
1