For Claude Code multi-agent work, use the main conversation as coordinator, delegate bounded tasks to Claude Code subagents, and give a fresh reviewer the diff plus explicit acceptance criteria. “Parent,” “worker,” and “reviewer” are our operating labels, not named roles that Claude Code requires.
Set up the Claude Code multi-agent pattern
Claude Code documents custom subagents rather than a fixed three-role topology. Each subagent has its own context window, system prompt, tool access, and permissions, which makes the division of labor explicit instead of relying on several vague prompts in one conversation (Create custom subagents).
For repository work shared by a team, place project subagents in .claude/agents/ and check them into version control. Personal subagents belong in ~/.claude/agents/ and are available across your projects; they are the wrong scope for a role the whole repository should share (Create custom subagents).
A minimal project layout is:
.claude/agents/
├── repository-worker.md
└── change-reviewer.md
There is no fixed command that installs this topology. The setup consists of the role files, their boundaries, and the delegations sent from the main conversation.
Parent: own the whole task
Treat the main conversation as the parent because it retains the overall objective and receives completed subagent results. It should decide what belongs in the task, assign non-overlapping work, enforce the shared constraints, and decide whether an answer is ready for the user.
Do not assume the worker already knows the background. A subagent starts with a fresh, isolated context and does not inherit the parent conversation, previously invoked skills, or files already read; Claude supplies a delegation message instead (Create custom subagents). Give every worker a brief containing:
- One concrete outcome.
- Relevant paths, interfaces, and constraints.
- Work already ruled out.
- A runnable definition of done.
- A compact return format.
- The exact next step if the task stops early.
Ask for findings in the final response rather than a report file. Subagent results return to the main conversation, and several detailed results can consume significant context, so the parent should receive conclusions, changed paths, checks, and unresolved risks rather than full transcripts (Create custom subagents).
In our setup, planning, file writes, deployment decisions, and final verification stay with the main session. We delegate noisy searches, independent investigation, and first drafts. That keeps the parent responsible for joining the results instead of collecting disconnected answers.
Worker: give it one bounded job
Create .claude/agents/repository-worker.md. Its frontmatter contains the required fields:
name: repository-worker
description: Investigate one bounded repository task and return evidence.
Only name and description are required. Write the worker’s system prompt as Markdown after the frontmatter (Create custom subagents).
A practical worker prompt is:
Work only on the bounded task in the delegation message.
Use the supplied paths and constraints. Do not expand the task into
unrelated cleanup. Report the outcome, files inspected or changed,
checks actually run, unresolved risks, and the exact next step.
An unrun check is not a passed check.
The prompt supplies operating rules, not a transcript of the parent conversation. A subagent receives its own system prompt plus basic environment details such as the working directory, but not the Claude Code system prompt (Create custom subagents). Put task-specific information in the delegation message.
Control capabilities deliberately. The tools field is an allowlist, while disallowedTools is a denylist; the subagent’s declared access determines what work it can actually perform (Create custom subagents). Give a reviewer only the access needed to inspect the change, and give a search worker no reason to hold deployment or modification access.
The optional model field accepts a model alias, a full model ID, or inherit. Documented choices include sonnet, opus, haiku, fable, a full ID such as claude-opus-5-5, and inherit; this describes accepted configuration values, not a claim about their relative quality (Create custom subagents).
Reviewer: start without the writer’s rationale
Create .claude/agents/change-reviewer.md with its own description:
name: change-reviewer
description: Review a supplied diff against explicit acceptance criteria.
Use a system prompt that keeps review separate from implementation:
Evaluate only the supplied diff and acceptance criteria.
Identify correctness problems, unintended scope, missing checks, and
violated constraints. Support each finding with the relevant change.
Do not assume the implementation is correct because it is already written.
A fresh reviewer does not receive the reasoning that produced the change. Claude Code’s best-practices guidance describes this Writer/Reviewer pattern and says the fresh context helps prevent attachment to code Claude has just written (Best practices for Claude Code).
Put necessary constraints and non-goals into the acceptance criteria. Do not send a persuasive account of why the implementation should work. The reviewer needs a testable description of what the change must preserve and satisfy.
The reviewer produces findings; the parent still performs the repository’s runnable verification. A second agent reading a diff is useful, but it is not equivalent to exercising the affected behavior.
Choose the worker’s scope
For a worker that needs a separate repository copy, add this field to its frontmatter:
isolation: worktree
Claude Code runs that subagent in a temporary Git worktree. By default, the worktree branches from the default branch rather than the parent session’s HEAD, so it can omit work that exists only at the session’s current head (Create custom subagents). Confirm the base before treating the worker’s diff as complete.
The documentation does not define a universal merge step for this pattern. Use the current worktree documentation and your repository’s integration process rather than inventing a command or assuming the parent’s changes are already present.
Check it worked
Start with a single bounded task and inspect the artifact, not the agent’s confidence. Claude Code’s best-practices guidance warns that without a check it can run, “looks done” may be the only available signal, leaving the human as the verification loop (Best practices for Claude Code).
Check the handoff in this order:
- Read the worker’s final response. Confirm that it states the outcome, paths touched, checks actually run, unresolved risks, and next step. A summary without those fields is not a complete handoff.
- Inspect the real change. Compare the files or diff with the requested scope. Do not accept the final message as a substitute for the repository state.
- Run the existing project check. Use the verification command defined by the repository or service. This article cannot name one because the project stack has not been specified; if no runnable check exists, record that gap instead of calling the task complete.
- Exercise the affected user path. Read back the rendered output, response, or other result where a user would encounter it. In our setup, an agent’s summary, a zero exit code, a green build, and an HTTP success are signals rather than the definition of done.
- Give the reviewer the actual diff and criteria. Ask for findings tied to specific changes. Then resolve those findings in the parent context rather than letting the reviewer silently approve its own work.
Also check that the parent can summarize the result without replaying the worker transcript. If important context exists only inside a long subagent result, the handoff is still too lossy.
Where it breaks
Context loss and confirmation
Fresh context protects the worker from inherited assumptions, but it also removes useful history. In our setup, both handoffs lose detail: the parent receives a summary, while the worker begins with only its brief. A worker handed a hypothesis also tends to return it confirmed, so include disconfirming checks and state what has already been ruled out.
The reviewer reduces one form of attachment because it evaluates the change without the writer’s reasoning, but independence is not proof. The parent must still compare the result with the repository and its runnable checks.
Shared working directories
Many of our sessions share working directories. Uncommitted changes there belong to every session, not only the one currently looking at them. We have seen a plain commit collect files another session had staged, so our rule is one writer per file at a time, disjoint task ownership, and commits limited to the agent’s own lines.
Use unique scratch directories and output paths as well. Generic temporary names and batch directory names have caused concurrent sessions to overwrite each other in our setup. Isolation helps only when task boundaries and identifiers are also disjoint.
The wrong worktree base
A worktree does not automatically represent the parent session’s current state. Because it branches from the default branch rather than the parent session’s HEAD, unmerged parent work may be absent (Create custom subagents). Check the base and inspect the resulting diff before review.
Too much delegation
By default, a subagent can spawn more subagents up to three layers below the main conversation (Create custom subagents). Recursive delegation can make ownership difficult to see, while many detailed results can crowd the main context. Keep this three-role structure flat: parent to workers, then parent to reviewer.
Delegate noisy searches and genuinely independent work. Do not delegate a check that the parent can run directly and interpret more reliably.
When workers need real coordination
Subagents fit quick, focused workers that report back. Claude Code directs teams of workers toward agent teams when participants need to share findings, challenge one another, and coordinate autonomously (Orchestrate teams of Claude Code sessions). If the parent is spending most of its turn relaying findings between workers, the task may require that different coordination model.