Catalog My learning Blog
AI-Assisted Coding Course: Agentic Development in 30 Days · Phase 4 · Lesson 18 · 5 min read

Claude Code Subagents: Context Isolation Explained

On this page
  1. Learning Objective
  2. Concept Explanation
  3. Worked Example: A Read-Only Reviewer Subagent
  4. Real-World Examples
  5. Review Questions & Answers

Learning Objective

Use subagents to keep the main session focused: delegate exploration, test runs and reviews to agents with their own context windows, restricted tools and suitable models, define custom subagents as files, and know when delegation helps and when it loses important detail.

Concept Explanation

A long coding session accumulates noise. Searching a large codebase, reading a dozen files to find where something happens, running a test suite with verbose output: each of these fills the main context with material that mattered for one step and then becomes clutter (Day 3). Subagents move that work into a separate context window. The main agent sends a task, the subagent does the work in its own fresh context, and only a concise result comes back.

Claude Code ships built-in subagents, such as an Explore agent for read-only codebase research and a Plan agent, and lets you define your own as markdown files in .claude/agents for a project or in your home directory for all projects. Each file has a header with a name, a description that tells the main agent when to delegate, an optional list of allowed tools, and an optional model, followed by the subagent's system prompt. Other tools have similar ideas, such as background agents in Cursor and custom agents in GitHub Copilot.

Restricting tools is a large part of the value. A code reviewer subagent that can only read and run git diff cannot accidentally edit files. A database reader that only runs a read-only query tool cannot drop a table. Choosing the model per subagent controls cost: a fast, inexpensive model is often enough for searching and summarizing, while the main session keeps the most capable model for design and implementation.

Good uses share a shape: the task is self-contained, produces a lot of intermediate material, and has a result that summarizes well. Finding all callers of a function and reporting file paths. Running the full test suite and reporting only failures. Reviewing a diff against a checklist with a fresh perspective (Day 14). Researching how a library is used across a monorepo. Several such subagents can run in parallel, for example exploring three modules at once.

Delegation also has a cost. The subagent does not see the main conversation, so it needs a self-contained brief, and the main agent sees only the summary, so details the summary omits are lost. Tasks where every decision depends on the full context, such as implementing a subtle change across tightly coupled files, are usually better done in the main session. A good rule: delegate reading and checking freely, and delegate writing only when the task is well specified and separable.

SubagentToolsModelReturns
ExplorerRead, Grep, GlobFast and inexpensiveFile paths and short explanations
Test runnerBash for tests, ReadFastFailing tests and key error lines only
Code reviewerRead, Grep, Bash for git diffCapablePrioritized findings with file and line
Migration workerRead, Edit, Bash for testsCapableSummary of files changed and test results

Worked Example: A Read-Only Reviewer Subagent

This project subagent reviews the current branch with a fresh context. It cannot edit files, and its description tells the main agent to use it after implementation.

Code
<!-- .claude/agents/reviewer.md -->
---
name: reviewer
description: Reviews the current branch's diff against main for bugs, weakened tests, security issues and scope creep. Use after finishing an implementation and before committing or opening a PR.
tools: Read, Grep, Glob, Bash(git diff *), Bash(git log *)
model: sonnet
---

You are a senior reviewer seeing this change for the first time.

1. Run git diff main...HEAD --stat, then read the full diff.
2. Read the tests first. Report any assertion that was loosened, any skipped or deleted test,
   and any new code path without a test.
3. Check for: unvalidated input reaching queries or shell commands, missing authorization on
   new endpoints, secrets or personal data in logs, broad exception handling, duplicated helpers
   (search for similar function names), and files changed that are unrelated to the task.
4. Report findings ordered by severity as: severity, file:line, problem, suggested fix.
   If you find nothing significant, say so in one line. Do not restate the diff.

After implementing a feature, asking "use the reviewer agent on this branch" runs the review in a separate context: the main session receives a short, prioritized list instead of the reviewer's file reads and reasoning. Because the reviewer did not write the code, it is less inclined to confirm its own choices.

The main session sends self-contained briefs to subagents. Each works in its own context window with restricted tools and a suitable model, and returns only a concise result, keeping the main context focused.
The main session sends self-contained briefs to subagents. Each works in its own context window with restricted tools and a suitable model, and returns only a concise result, keeping the main context focused.

Real-World Examples

  • Claude Code's subagent documentation describes custom subagents as markdown files with name, description, tools and model fields, highlighting separate context windows, tool restrictions and cost control through faster models as their main benefits.
  • Anthropic's engineering write-ups on context engineering recommend sub-agent architectures for exploration-heavy work, where subagents search extensively but return condensed summaries of one to two thousand tokens to the lead agent.
Key TakeawaysSubagents keep the main session focused by doing noisy, self-contained work in their own context window and returning a concise result. Define them as files with a clear description, restricted tools and a suitable model. Delegate exploration, test runs and reviews freely; delegate implementation only when it is well specified and separable, because subagents do not see the main conversation and summaries lose detail.

Review Questions & Answers

They keep the main session's context focused by doing work that produces a lot of intermediate material, such as searches, file reads and test output, in a separate context window and returning only a concise result.

It limits what the subagent can do to what its job requires, for example a reviewer that cannot edit files or a database reader that cannot write, which prevents accidents and reduces risk.

The subagent does not see the main conversation, so it needs a self-contained brief, and the main agent sees only the summary, so details the summary omits are unavailable.

It does not share the reasoning and assumptions that produced the code, so it is less inclined to confirm earlier choices and looks at the change with fresh eyes.