diff --git a/claude-plugins/plugins/base/skills/claude-subagents/SKILL.md b/claude-plugins/plugins/base/skills/claude-subagents/SKILL.md index e5f5e2a7..f8135642 100644 --- a/claude-plugins/plugins/base/skills/claude-subagents/SKILL.md +++ b/claude-plugins/plugins/base/skills/claude-subagents/SKILL.md @@ -72,50 +72,6 @@ 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. -- **Mind the container's memory cap before picking N.** Your whole - container shares one `MemoryMax` (a few GB by default) with every - subagent you spawn *and* your own process. A `claude` process plus its - MCP servers can hold several hundred MB to ~1GB depending on the task; - spawning a dozen at once on a small container doesn't just slow - things down, it can OOM the whole container — taking your own - in-flight turn down with it, not just the subagents. Rule of thumb: - **2-4 concurrent workers** on a default-sized container; check - `free -h` (or ask whoever owns the container's config for its - `MemoryMax`) before going higher, and chunk a bigger batch into - successive waves of that size rather than firing everything at once. -- **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."` @@ -143,6 +99,3 @@ 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.