Claude Code Subagents: Setup and Workflow Guide

A single Claude Code session does everything in one context window, and that window is its scarcest resource. Read twenty files to answer one question and all twenty stay in context, crowding out the task you actually care about. Subagents are the built-in fix: a way to hand a slice of work to a separate assistant that thinks in its own window and hands back only the answer.

This guide covers what a subagent really is, how to create one, when delegation is worth it, and how subagents change what a session costs. The examples use Claude Code, but the same delegation pattern applies to any agentic coding tool that supports isolated sub-tasks.

What a subagent actually is

A subagent is a second Claude with its own context window, its own system prompt, and its own permissions. It cannot see your main conversation and your main conversation cannot see its working notes. The parent describes a job, the subagent does it in isolation, and only the final summary crosses back. That isolation is the whole point: bulky intermediate work never touches the main window.

Each subagent is a plain Markdown file with YAML frontmatter. Three fields do most of the work:

• A name and a description that Claude reads to decide when to route work to this agent, so write the description for the trigger, not for humans.
• An allowlist of tools, so a reviewer can read and grep but never write files or run shell commands.
• An optional model, so cheap high-volume work runs on a smaller model like Haiku while the main session stays on a stronger one.

Create your first subagent

The fastest path is the /agents command, which walks you through creating an agent and writes the file for you. You can also create the file by hand at .claude/agents/security-reviewer.md in your project, or under your home directory to make it available everywhere. The frontmatter configures the agent; the body is its system prompt.

A minimal, tightly scoped security reviewer looks like this:

---
name: security-reviewer
description: Reviews diffs for auth, injection and secret-handling issues
tools: Read, Grep, Glob
model: haiku
---

You are a security reviewer. Given a diff, report only concrete,
exploitable issues with a file:line and a one-line fix. Do not
comment on style. If you find nothing, say so plainly.

When delegation pays off

The rule of thumb is simple: delegate when the work generates far more tokens than the conclusion is worth keeping. Good candidates share that shape.

• Codebase exploration, where an agent reads dozens of files and returns a two-paragraph map instead of the raw dumps.
• Adversarial review, where a fresh agent sees only the diff and the acceptance criteria, not your reasoning, so it can catch what the author is blind to.
• Parallel research, where a lead agent spawns several workers at once. Anthropic reported that this orchestrator-worker setup beat a single agent by about 90 percent on their internal research evaluation.
• Repetitive scoped edits, where each file goes to its own short-lived agent so one failure does not derail the whole batch.

Wire subagents into a workflow

In practice the main session becomes an orchestrator. It plans the work, decides which pieces to delegate, and stitches the summaries back together. Your job is to describe each delegated task well: state the objective, the boundaries, and the exact shape of the output you want back.

Treat the delegation prompt like an API contract. A subagent that is told to return a ranked list of findings with file and line references gives you something you can act on; one told to please review the code gives you an essay you then have to parse.

Cost and context discipline

Subagents are a spend lever that cuts both ways, and treating them as free is the fastest way to a surprising bill.

• They save context by keeping bulky file reads and tool output out of the main window, which slows the drift that fills a long session.
• They can raise total cost, because each agent re-reads the context it needs; multi-agent runs use far more tokens than a single chat, so reserve them for genuinely breadth-first work.
• Route low-stakes, high-volume subagents to a cheaper model and keep the orchestrator on your strongest one, so you pay top rates only where judgment matters.

Subagents turn Claude Code from one assistant into a small team you direct. Start with two you will actually use, a codebase explorer and a diff reviewer, keep each one narrow, and let the main session stay focused on the task instead of drowning in its own research.