Claude Code Subagents: How to Use Them for Real Work

What an AI coding agent actually is

The phrase gets used for two quite different things, and the difference is the whole story.

An autocomplete tool predicts the next few lines while you type. You remain the one who opens files, runs commands, and decides what happens. It is a faster keyboard.

An agent is given a goal and a set of tools, and it decides what to do. It reads files you did not name, runs commands you did not type, and keeps going until it judges the task finished. You describe the destination; it picks the route.

That second definition is what makes agents useful and what makes them risky. An agent will act on an assumption rather than surfacing it. Everything below is about controlling that — not by making the agent less capable, but by putting boundaries around what any single piece of work can touch.

If you are still choosing between categories of tool rather than configuring one, vibe coding tools and platforms compares them.

What a subagent is in Claude Code

A subagent is a specialised assistant that Claude Code can hand a task to. It runs in its own context window, with its own system prompt, its own tool permissions, and optionally its own model.

The important consequence: only the summary comes back to your main conversation. If a subagent reads forty files to answer one question, those forty files never enter your context. You get the answer.

That is the core value. Context is finite, and the fastest way to degrade a long session is to fill it with material that mattered for two minutes.

The three reasons to use one

The second one deserves emphasis. "Please don't change any files" is a request. A subagent whose tools list contains no write tool is a wall. When the cost of a mistake is high, prefer the wall.

The built-in subagents

Claude Code ships with four, and knowing what each is for saves you writing your own:

Reach for Explore far more than feels natural. "Find every place that depends on this function" is a question whose answer is one paragraph and whose research is fifty file reads. That trade is exactly what Explore exists for.

Writing your own

A subagent is a Markdown file with YAML frontmatter. Where you put it determines who gets it:

They resolve in that order, highest first. Project-level is where team-shared agents belong, for the same reason project CLAUDE.md beats personal: a convention that lives on one machine is a preference.

The file itself:

---
name: security-reviewer
description: Reviews changes for security problems. Use before merging
  anything that touches authentication, input handling, or data access.
tools: Read, Glob, Grep, Bash
model: sonnet
---

You review code for security defects. You do not fix them.

For every finding, give: the file and line, the exact request or input
that would exploit it, and the fix. A finding you cannot demonstrate
is a hypothesis — say so.

Check, in this order:
1. Authorisation — is ownership verified, not just authentication?
2. Input validation at the boundary
3. Output encoding
4. Secrets in source, history, config, or client bundles
5. Anything logged that should not be

If you find nothing, say so plainly. Do not manufacture findings.

Two things make this work. The description is what Claude reads when deciding whether to delegate, so it should say when to use this, not what it is. And the tool list contains no Edit or Write — a reviewer that can rewrite the code it is reviewing is not a reviewer.

The frontmatter fields that matter

There are many. These are the ones that change outcomes:

The single highest-value habit here is writing tools deliberately on every agent. It takes ten seconds and converts a hope into a property of the system.

Three ways to invoke one

Natural language — name it and let Claude decide:

Use the security-reviewer subagent on the auth changes.

@-mention — guarantee that specific agent runs, no judgement involved:

@"security-reviewer (agent)" look at the changes in src/auth/

Session-wide — run the whole session as that agent:

claude --agent security-reviewer

Or pin it in .claude/settings.json:

{ "agent": "security-reviewer" }

Use the @-mention form whenever it matters that the right agent ran. Natural language is a hint; @-mention is an instruction.

Patterns that earn their keep

Review in a fresh context

A session that wrote the code will defend it. A subagent starts clean, with no memory of the reasoning that produced the bug. This is the most valuable subagent pattern there is, and it costs one file.

The same argument applies in CI, where the reviewer never wrote anything by definition — see Claude Code and GitHub.

Research without polluting the plan

Mid-build, you need to know how something works elsewhere in the codebase. Ask Explore. Forty file reads happen somewhere else; one paragraph comes back. Your main thread still holds the plan.

Parallel work in worktrees

Several independent changes at once, each in its own git worktree via isolation: worktree. They cannot collide because they are not sharing a working tree. Worth knowing that a worktree costs real setup time and disk, so use it when agents genuinely write in parallel — not by default.

Cheap models for mechanical passes

Renaming across a hundred files, extracting a list, reformatting data — none of that needs your best model. model: haiku on the agent, and the cost of the pass drops without touching the session model.

Constrained agents as safety rails

An agent for anything that touches production, with permissionMode: plan and no write tools. It can only tell you what it would do. For deploy paths and migrations, that is the correct default.

A roster worth having

Most web projects are well served by four agents. More than that and they start competing for the delegation decision; fewer and you are writing constraints into every prompt.

1. Reviewer — read-only, fresh eyes

---
name: reviewer
description: Reviews uncommitted changes or a diff before merge. Use when
  work is finished and needs checking by something that did not write it.
tools: Read, Glob, Grep, Bash
model: opus
---

Review in this order: does it do what it claims; does it break anything
that works; is it secure; is it accessible; does it follow the conventions
already in this codebase; is it tested; will it be readable in six months.

Skip anything a linter or formatter settles.

Cite file and line for every point. If nothing is wrong, say so — do not
manufacture findings to appear thorough.

2. Explorer — for questions, not changes

The built-in Explore usually covers this. Write your own only if you want a house style for how findings are reported.

3. Auditor — one per standard you actually hold

---
name: a11y-auditor
description: Audits rendered pages for WCAG 2.2 AA problems. Use before
  shipping any UI change.
tools: Read, Glob, Grep, Bash
model: sonnet
---

Audit the RENDERED output, not the source. Templated markup is not what
the browser gets, and contrast has to be computed against the backdrop
that actually paints.

Report measured numbers: contrast ratios, target sizes in CSS px,
scrollWidth against clientWidth at 320px.

State which findings you verified in a browser and which you inferred
from markup. Do not assert compliance without the numbers.

That last instruction is the one that makes an audit trustworthy. Much of accessibility cannot be determined from source, and being told which half is inference is what makes the report usable rather than reassuring.

4. Migrator — constrained, for the dangerous stuff

---
name: migrator
description: Plans database migrations. Use before any schema change.
tools: Read, Glob, Grep
permissionMode: plan
model: opus
---

You plan migrations. You do not write or run them.

Additive first, always. Never add and remove in one step: add, backfill
in batches, switch reads, drop in a later release.

Every plan includes a tested down migration, expected duration against
realistic data volumes, and what breaks if it runs mid-traffic.

If a migration would lose data, stop and say so before planning further.

No write tools and permissionMode: plan. It is structurally incapable of running the thing you are worried about.

Resuming a subagent

A finished subagent can be picked back up. It keeps its full conversation history, so you are continuing rather than re-briefing:

Continue that review and now look at the authorisation logic specifically.

This matters more than it sounds. The expensive part of a subagent run is the context it built — the files it read, the structure it worked out. Resuming reuses all of it. Starting a second agent to ask a follow-up throws that away and pays for it again.

The practical habit: when a subagent gives you a report and you have a follow-up question about the same territory, resume it rather than spawning a fresh one.

Limits, and where they bite

That last one is the one that surprises people. Every custom agent's description is loaded so Claude can decide when to delegate. Thirty agents with paragraph-long descriptions is a real context cost paid on every session. Keep descriptions to a sentence or two, and delete agents you stopped using.

Also worth knowing: subagents do not get the full tool set. AskUserQuestion is removed, among others — a subagent cannot stop and ask you something. It has to decide or report back. Write their instructions accordingly: tell them what to do when uncertain, because "ask me" is not available to them.

When not to use a subagent

For a task you will need the details of

Only the summary returns. If you need the file contents to make the next decision, read them in the main thread.

For something trivial

Spinning up an isolated context to read one file is slower than reading it.

As a way to avoid writing constraints

An agent with a vague system prompt is a vague session with extra steps. The prompt is still the work — see the prompt library for what a good one contains.

Thirty agents where three would do

Every description competes for attention, and a crowded roster makes delegation worse, not better. Most projects need a handful.

For work that needs your judgement mid-flight

Subagents cannot ask you questions. Anything with a decision point belongs in the main conversation.

Where to go next

Subagents package who does the work. Skills package how a procedure runs, and plugins package both for distribution. The persistent project context they all inherit is covered in creating a production CLAUDE.md, and where all of this fits in a real build is in the complete website workflow. For rolling agents out across a team, see Claude Code for teams and enterprise.

Sources and further reading

• Claude Code: subagents — file locations, frontmatter fields, built-ins, and limits
• Claude Code: common workflows
• Claude Code: settings