Overview
Subagents are Claude Code instances spawned by a parent agent to parallelize work. Each subagent operates independently, reads the same CLAUDE.md, and produces a branch for the parent to merge. The hardest part of multi-agent file work is conflict avoidance, not spawning. Get isolation right first. See multi-agent for the coordination patterns; this page covers the Claude Code specifics.
Isolate every file-writing subagent in a git worktree
A subagent that writes files without worktree isolation races with every other agent touching the same tree. Worktrees give each agent a private checkout at .claude/worktrees/<id>/.
Set isolation: "worktree" in the agent invocation or configure it in .claude/settings.json:
{
"subagents": {
"defaultIsolation": "worktree"
}
}The cost is a few seconds per worktree setup. The benefit is that two subagents can write to the same filename without one overwriting the other.
Skip worktree isolation only for read-only subagents: research, search, diff analysis. If the agent calls Write, Edit, or Bash with side effects, give it a worktree.
Assign each subagent its own branch
Worktree isolation alone is not enough. Commit every subagent’s work to a named branch.
Parent creates worktrees:
.claude/worktrees/agent-abc/ → branch: claude/feature-abc
.claude/worktrees/agent-def/ → branch: claude/feature-def
Agents commit to their own branches.
Parent merges or opens PRs from each branch.Name branches deterministically so the parent can find them: claude/<task-id> or claude/<slug>. Avoid generic names like claude/work-1 that clash across sessions.
Run subagents in parallel for independent tasks
Parallel execution makes sense when tasks do not share output files and do not depend on each other’s results.
Good candidates for parallelism: generating independent content pages, reviewing a list of PRs, running tests for separate packages in a monorepo, scraping a list of URLs.
Bad candidates: tasks where agent B needs the output of agent A; tasks where both agents write to the same file. Sequential execution is cheaper to debug and produces less merge noise when the dependency is real.
The multi-agent orchestrator-worker pattern applies here: the parent decomposes, fans out, and merges. Workers do not communicate with each other.
Use the one-PR-per-agent rule to keep reviews tractable
Each subagent opens exactly one pull request against a staging branch or main. The parent reviews the diffs independently before merging any.
Reasons this rule exists:
- A diff from one agent is reviewable in isolation. A diff from three merged agents is not.
- A broken agent’s PR can be closed without reverting work from other agents.
- CI runs per PR, giving per-agent signal.
When a task genuinely requires all agents’ work to land together, use a staging branch. Each agent’s PR merges into the staging branch; the staging branch merges into main as a single merge commit.
Pass context through the brief, not through shared state
Subagents read CLAUDE.md and the task brief. They do not read each other’s in-progress work. Design tasks so each agent gets everything it needs in its brief.
If agent B genuinely needs agent A’s output, sequence them: A runs, commits, and the parent feeds A’s output into B’s brief. Parallel execution with shared state produces non-deterministic output and is hard to replay.
Avoid conflict zones in parallel runs
Before spawning parallel agents, identify the files that every agent will plausibly touch.
High-conflict files: index.md MOCs, llms.txt, shared config files, schema definitions. Route all writes to these files through the parent agent or a designated merge agent, not through individual workers.
Workers write to their own scoped files. The parent reads all branches and produces the merge. See claude-code-workflow for the concrete merge flow.