Claude Code subagents are separate agent instances that handle focused subtasks in their own context windows and return results to the main conversation. Current Claude Code includes built-in Explore, Plan, and general-purpose subagents and lets teams define custom agents as Markdown files with YAML frontmatter controlling name, description, tools, model, permission mode, skills, hooks, memory, effort, background behavior, maximum turns, MCP access, and optional worktree isolation.
Within Claude Engineering, subagents are primarily a context-management and responsibility-separation tool. They help keep broad search, logs, file reads, or specialized review out of the main conversation while allowing the primary agent to coordinate the overall task.
The current docs explicitly recommend subagents when exploration would flood the main context. This becomes especially valuable in large repositories.
Use the built-in Explore agent for read-only codebase research
Explore is optimized for file discovery, code search, and analysis and runs with read-only tools. Claude can choose a quick, medium, or very thorough exploration depending on the task.
Because the file reads stay in the subagent context, the main thread receives a summary rather than every grep result.
Use Explore when the result is knowledge, not code modification.
Plan subagents keep planning research separate from the read-only main plan flow
When Claude is in plan mode and needs codebase context, the built-in Plan agent can gather that context without polluting the main planning conversation.
This is useful for architecture changes, multi-package migrations, or unfamiliar code where a good plan requires substantial exploration.
The final plan should still state assumptions and unknowns rather than hiding them behind the subagent summary.
General-purpose and custom agents can modify code when appropriate
The general-purpose agent handles complex multi-step tasks that need both exploration and action.
Custom agents let teams specialize behavior further—for example a database reviewer, API compatibility checker, test writer, or security analyst.
Use focused descriptions so Claude can decide when delegation is appropriate, and keep detailed instructions in the agent body rather than bloating every session with long descriptions.
Tool allowlists are a strong isolation mechanism
Subagents inherit available tools subject to Claude Code’s subagent filters, but custom definitions can narrow access with tools or disallowedTools.
A code-reviewer can receive Read/Grep/Glob without Write/Edit. A test agent might receive Bash and Edit but no external deployment MCP server.
Capability reduction is often more reliable than telling a broadly privileged agent “please don’t change files.”
Model selection can match task cost and difficulty
Custom subagents can specify a model, and organizations can configure environment variables that influence or force the model used for subagents according to the current Claude Code version.
Use a faster/cheaper model for large search/summarization work when quality is sufficient and reserve the strongest model for high-impact reasoning or implementation.
Measure real output quality; routing purely on price can increase total cost if the main agent must repeat weak subagent work.
Worktree isolation lets a subagent edit without colliding with the main checkout
Current subagent frontmatter supports isolation: worktree. The subagent’s Bash/PowerShell work runs inside a temporary Git worktree rather than the main conversation’s working tree.
This is useful when several agents may edit or run destructive build steps concurrently.
Claude Code Worktrees covers repository-level isolation and cleanup in more detail.
Background subagents have a narrower built-in tool surface
Current docs describe additional filtering for background agents so they keep a defined set of built-in tools plus MCP tools rather than every foreground capability.
This reflects an important design principle: unattended work should have fewer ways to surprise the user.
When designing a custom agent, verify which tools remain available in the execution mode you expect rather than assuming the foreground and background tool pools are identical.
Parallel research is valuable only when tasks are independent enough
Subagents can investigate several questions at once: map authentication, inspect tests, analyze migration risk, and review deployment separately.
Parallelism helps when each worker has a bounded question and returns concise findings.
It hurts when agents depend on each other’s intermediate results or edit the same files without isolation, because the coordination overhead and merge conflicts exceed the speedup.
Agent outputs should be structured for the main coordinator
Ask each subagent to return decisions, evidence, files/lines, risks, and recommended next actions rather than a long diary of everything it read.
This keeps the main context focused and makes conflicting findings easy to compare.
For repeated workflows, create a custom agent with a fixed output format so the main agent receives consistent handoffs.
Subagent context still needs hygiene
Subagents can hit their own turn/context limits and can return partial results. Current Claude Code marks certain max-turn completions as partial and can provide agent IDs for resumable agents.
Do not give one subagent an unbounded “analyze the whole company” task. Split investigation by domain and resume only where the summary indicates remaining gaps.
This keeps delegation predictable and limits wasted token spend.
Subagents are successful when delegation reduces context and clarifies responsibility
The mature pattern gives each agent a narrow objective, minimum tools, appropriate model, independent context, optional worktree isolation, and a concise handback contract.
Subagents should make the main conversation smarter by hiding irrelevant exploration—not create a swarm whose work cannot be reviewed or reconciled.
Agent definitions should be versioned with the workflow they serve. A subagent that reviews database migrations or API compatibility is effectively executable process documentation: its description determines when Claude delegates, its tool list defines authority, and its prompt defines the review standard. Treat changes to those files like changes to CI policy or shared library code.
Use project-level agents for repository-specific architecture and user-level agents for reusable personal workflows. A team reviewer that understands one monorepo’s services belongs in .claude/agents/; a generic documentation summarizer can live under the user’s home configuration. Keeping scope aligned with ownership avoids leaking project-specific assumptions into unrelated repositories.
Skills can preload specialist procedures into a subagent. This works well when a test agent needs the repository’s test-generation skill or a security agent needs a standardized review checklist. Preload only what the agent uses regularly; huge skill bundles recreate the context-bloat problem subagents were meant to solve.
Hooks can enforce behavior inside subagents as well. A read-mostly reviewer can be protected by PreToolUse rules, while a code-writing worker can automatically run targeted tests after edits. Because subagent tool calls trigger configured hooks, the same organization guardrails can surround delegated work without duplicating policy inside every prompt.
Parallel agents should receive nonoverlapping ownership when they edit. One agent can update backend code while another updates tests or docs, but two agents changing the same central file invite merge conflict and inconsistent assumptions. Worktree isolation helps technically; task decomposition still needs to avoid semantic conflict where both workers redesign the same interface independently.
Resumable agents are useful for iterative review. If a custom or general-purpose subagent returns an agent ID, the main conversation can continue that worker with follow-up evidence instead of starting a fresh agent that repeats exploration. Use this for “review the fix after changes” or “investigate the failing test using the same context.”
Subagent quality should be measured by handoff usefulness, not activity. A good worker returns concise findings with file references, risks, confidence, and decisions the coordinator can act on. A 5,000-word transcript that repeats source code defeats the purpose of isolated context even if the subagent worked hard.
Cost governance should account for fan-out. Ten subagents can consume more total tokens than one careful main-thread investigation. Use parallelism when tasks are genuinely independent or context isolation has clear value, and cap turns/model choice for exploratory agents that do not need the highest reasoning depth.
Delegation prompts should carry the minimum shared context needed for the subtask: objective, relevant files or scope, constraints, and expected output. Do not copy the entire main conversation into every agent manually. Claude Code already supplies environment/context according to the subagent model, and redundant prompt history wastes the isolation benefit.
Agent depth should remain shallow unless nested delegation has a clear purpose. A coordinator spawning a specialist that spawns several more specialists can become difficult to audit and expensive quickly. Prefer one coordinator plus a small set of domain workers whose outputs are easy to reconcile.
For risky tasks, use a read-only reviewer and a separate writer. One subagent can analyze security or architecture without modification rights, then the main agent or another isolated worker implements the approved plan. This separation makes it harder for the same reasoning process to both discover and silently “fix” a questionable issue without independent review.
Agent catalogs should remain small enough that delegation stays predictable. Claude reads subagent descriptions to decide when to use them, so dozens of overlapping agents with vague scopes can consume context and create inconsistent routing. Consolidate agents that differ only slightly, keep descriptions crisp, and review which types are actually invoked in real projects before adding another specialist.
Keep delegation boundaries reviewable as the agent catalog evolves, and remove specialist agents that no longer provide distinct value.
Delegation works best when each subagent receives a bounded objective, the minimum useful context, and a clearly defined output. That structure makes it easier for the parent workflow to compare results, detect conflicts, and avoid multiplying the same misunderstanding across several parallel agents.
