Claude Code Subagents: Context Isolation, Orchestrator and Reviewer, When You Do Not Need Them

What Claude Code subagents are

A subagent is another instance of the agent that the main agent launches for a separate task. It has its own context window, its own system prompt and its own list of allowed tools. The main agent passes it a task description, the subagent works on its own — reads files, runs commands — and returns only the final message.

The key word here is isolation. Everything the subagent read along the way — dozens of files, a long test output, dead-end hypotheses — stays in its context and does not get into the main session's context. The main agent sees a short result: "the bug is in function X, the cause is such-and-such, here are three places it affects".

Claude Code subagents are a particular case of the general idea of multi-agent systems: instead of one loop of "think, act, check", there is a graph of several nodes, each with its own role and its own responsibility.

Why context isolation matters

The context window is the agent's main resource. It holds at once the instructions from CLAUDE.md, the dialogue history, the code that was read and the output of commands. When the agent spends half an hour looking for the cause of a bug, the context fills with junk: files that turned out to be irrelevant and logs of which only one line matters.

The consequences are familiar to anyone who has worked with agents for a long time: the model starts to hold the project's rules less well, mixes up details, and when the history is compressed automatically it loses what was important. A subagent solves this structurally: the dirty work is done in a separate context, which is thrown away after the answer.

• Search and research. "Find all places where the payment function is called and describe how they are built" is a typical task for a subagent.
• Noisy checks. Running the tests and analyzing the failures can be handed to a subagent, which returns the list of causes.
• Reading large documents. A specification of hundreds of pages is needed for a few facts — let the subagent extract them.

How to set up a subagent: the .claude/agents folder

A custom subagent is described by a Markdown file with a YAML header. Project files live in .claude/agents/ in the repository and are available to the whole team through git; personal ones live in ~/.claude/agents/ and work in all your projects. You can also create and edit a subagent interactively with the /agents command in Claude Code.

---
name: code-reviewer
description: Checks code changes for bugs and violations of project rules. Use after finishing a task, before committing.
tools: Read, Grep, Glob, Bash
---
You are a code reviewer. You do not need to fix anything.

1. Look at the changes: git diff.
2. Check each change for logic errors, error handling,
   security (SQL, output escaping, secrets).
3. Compare against the rules in AGENTS.md.
4. Return a list of remarks: file, line, problem, why it matters.
   If there are no remarks, say so.

What the fields mean:

The body of the file is the subagent's system prompt. It does not see the history of your dialogue, so everything it needs to know about its role and response format must be in the prompt or in the task the main agent passes.

How to call a subagent

The main agent can pick a subagent by itself if the task fits its description. It is more reliable to ask explicitly: "Use the code-reviewer subagent to check the changes". Phrases like "use proactively" in the description raise the chance that the agent calls it without a reminder, but do not guarantee it.

A research subagent

A second file worth creating in almost any project is a read-only researcher. It answers questions about the code and changes nothing.

---
name: explorer
description: Searches the codebase for answers about where and how something is built. Use when you need to read many files for a short answer.
tools: Read, Grep, Glob
---
You explore the code and change nothing.
Return: a brief answer to the question, a list of files with lines
the answer relies on, and what could not be verified.

Such a subagent is especially useful at the start of a task: the main agent gets a map of the relevant places without spending context on reading everything, and then works with specific files.

The "orchestrator and workers" scheme

The most common multi-agent scheme: one orchestrator agent holds the plan and the big picture, and hands the concrete steps to workers. The orchestrator does not read all the code itself — it formulates tasks, accepts results and decides what to do next.

1. The orchestrator splits the task into independent parts and writes a self-contained brief for each: the goal, where to look, what counts as done, and in what form to return the answer.
2. The workers carry out the briefs in their own contexts.
3. The orchestrator collects the answers, checks that the parts fit together, and launches the next step or a rollback to the previous one.

The weak point of the scheme is the handoff. A subagent knows only what it was told. The brief "fix the bug we discussed" is empty for it: it did not see the discussion. A good brief reads like a task for a new colleague who has just opened the repository for the first time.

What the worker should return

Set the response format in advance: a list of files, the output, the causes found, what could not be verified. A short structured answer saves the orchestrator's context, and the "not verified" item protects against false confidence — a worker, like any agent, tends to report success.

A separate reviewer: why to separate the judge from the worker

When the same agent writes code and checks it itself, the judge and the defendant share one head. The agent remembers what it meant to do and sees its intent in the code rather than what is actually written. Besides, it is motivated to finish: the check turns into a formality.

A reviewer in a separate context is free of these problems. It does not know the history of decisions, sees only the diff and the project rules, and assesses the result with a fresh eye. It is the same principle as in a live team: the author does not approve their own pull request.

• Give the reviewer only read and run-checks tools, without the right to edit files. Then it will not start "quietly fixing" things instead of reporting the problem.
• State the review criteria explicitly: what counts as an error, which project rules are mandatory.
• Leave the decision of what to do with the remarks to the orchestrator or to a human. The reviewer finds, the worker fixes.

A reviewer does not replace mechanical checks. Tests, the linter and the type check are deterministic nodes, more reliable than any model. The reviewer catches what mechanics cannot see: wrong logic, violated agreements, unnecessary complexity.

Running subagents in parallel

Claude Code can run several subagents at the same time. This speeds things up when the parts of the task are truly independent: studying three modules, checking the changes from three angles (security, performance, tests), collecting information from several sources.

Parallelism works well for reading and poorly for writing. If two workers edit the same files at once, they overwrite each other's changes, and neither knows it. In graph terms, this is shared state without a merge rule. Practical rules:

• Run research, analysis and review in parallel. Make edits to overlapping files sequentially.
• If workers do write in parallel, split the zones: each works only in its own files or in its own copy of the repository (for example, in a separate git worktree).
• Results are merged by one node — the orchestrator — not by the workers among themselves.

When subagents are not needed

A multi-agent scheme has a cost: more tokens, more time, more places where information is lost during handoffs. Claude Code subagents do not always pay off.

Before building a graph of agents, answer simple questions: who owns the overall goal, who can veto and roll back a change, which metrics count as success. If there are no answers, several agents will only multiply one agent's confusion.

Common mistakes with subagents

A vague description

A description like "a helper for code" does not help the main agent choose when to call it. Write a trigger: "after changes in the api/ folder, before a commit".

A brief without context

The subagent gets a task without paths, without done criteria and without constraints, and spends half the work guessing what is wanted. The fix is a brief template: goal, inputs, constraints, response format.

Overly broad permissions

A researcher and a reviewer do not need the right to edit files. The tools restriction is a cheap way to make a role a mechanism rather than a request in the prompt.

Trusting a report without checking

"All tests passed" in a subagent's answer is a claim, not a fact. The orchestrator should rely on what can be verified: command output, the exit code, specific lines.

Summary

Claude Code subagents are a tool for three jobs: keeping the main context clean, separating verification from execution, and parallelizing independent work. They are described by short Markdown files in .claude/agents/, and the quality of their work depends almost entirely on the description of the role, the set of tools, and how self-contained the brief is. Where the task is small or tightly bound to the dialogue, one agent is still better. The move from a single loop to a system of nodes, edges and shared state is covered in practice in the course.