diff --git a/claude-plugins/plugins/base/skills/claude-subagents/SKILL.md b/claude-plugins/plugins/base/skills/claude-subagents/SKILL.md index f8135642..eb316a1b 100644 --- a/claude-plugins/plugins/base/skills/claude-subagents/SKILL.md +++ b/claude-plugins/plugins/base/skills/claude-subagents/SKILL.md @@ -72,6 +72,39 @@ work while the sub-agent grinds. turn it loose on the full batch. A prompt bug replicated across 100 items is 100 cleanups. +## Split a big independent batch across parallel subagents + +One subagent is a sequential worker — a 50-item batch takes roughly 50 +items' worth of wall-clock even though nothing about the recipe forces +serialization. If the items are independent (each one touches its own +file/issue/row, nothing depends on another item's result) and the batch +is big enough that wall-clock matters, chunk it across N subagents +running at once instead of handing the whole thing to one. + +- **Split by natural boundaries**, not an arbitrary item count — one + subagent per file, per directory, per module, per label, whatever + grouping keeps each worker's slice self-contained. A worker that has + to coordinate with another worker mid-task isn't actually independent + work; re-scope the split until it is. +- **Isolate each worker's writes.** For a git-based batch, give each + worker its own `git worktree` (own working directory, own branch, same + underlying repo — cheap, no full reclone) so N workers editing + different files never race on the same working tree or index. For a + non-git batch (issue relabeling, API calls), independent items don't + need filesystem isolation at all — just launch N in parallel. +- **Launch all N in the background and don't babysit any single one** — + same as the one-subagent case, just N background bash tasks instead of + one. Check on them as a batch, not by polling each individually in a + loop. +- **You own the merge.** Once all N report done, review + verify each + worker's slice (same "don't trust the self-report blind" rule as + below), then combine — for a git-based split, that's you merging N + branches (or cherry-picking) into one, not each worker pushing/PRing + its own slice. + +Skip this for a batch small enough to finish in a couple minutes single- +threaded — the coordination overhead isn't worth it below that size. + ## Resume for follow-ups `claude --resume -p "Now run the same procedure over the second batch."` @@ -99,3 +132,6 @@ anything the sub-agent left ambiguous or exempted for a human call. suggests something "isn't possible" or "doesn't exist," confirm it before writing that conclusion into the prompt; a wrong assumption gets replicated across the whole batch. +- Handing a big independent batch to one subagent instead of splitting + it across several in parallel - a 50-item sequential run burns wall- + clock the split-by-worktree approach above would've avoided for free.