Claude Code Subagents: Best Practices With Copy-Ready Configs

Claude Code subagents are Markdown files with YAML frontmatter, stored in .claude/agents/ or ~/.claude/agents/, that hand a side task to a helper with its own context window, system prompt, tool list and model. The best practices come down to four choices per file: one job, a description that tells Claude when to delegate, the smallest tool list that works, and the cheapest model that can do it.

Checked October 2026 against Anthropic's Claude Code docs on subagents, agent teams, model configuration and costs. The rules on this page are distilled from that documentation, not from benchmark logs, and every field in the three configs is in the official frontmatter reference. Version notes below refer to Claude Code 2.1.x; behaviour changes often.

This is the deep dive on one feature. If you want the whole picture first, including CLAUDE.md, skills, hooks and MCP, read our Claude Code complete guide and come back. This page is for people who already use Claude Code daily and keep watching a long session fill with test output and search results.

How do Claude Code subagents work?

A subagent is a second agent loop that runs inside your session. Claude writes it a brief, it works in a separate context window, and only its final report comes back. Everything it read along the way, the 4,000-line test log or the forty files it grepped, never touches your main conversation.

Two details shape every rule that follows. First, a subagent starts fresh: the docs list its starting context as its own system prompt, the task message, your CLAUDE.md files, a git status snapshot and any preloaded skills. It does not see your chat history. Second, it is not free. Each subagent sends its own requests, and those count toward the same usage limits as your main conversation.

Claude Code ships built-in subagents you have already used without noticing. Explore is a read-only agent for searching a codebase, Plan gathers context in plan mode, and general-purpose handles multi-step tasks that need both reading and editing. Custom subagents are for the jobs you keep delegating with the same instructions.

Where do subagent files live?

Location decides who gets the subagent. Put project agents in .claude/agents/ and commit them; put personal ones in ~/.claude/agents/. When two definitions share a name, the higher-priority location wins.

Claude Code watches both folders and picks up a new or edited file within a few seconds. The one catch: if the agents directory did not exist when the session started, restart once. Older tutorials tell you to run /agents to open a creation wizard; in current versions that command only prints a reminder to ask Claude or edit the files directly, so the fastest route is to ask Claude to write the file and then edit it yourself.

The file is frontmatter plus a prompt. Only name and description are required. Field names are camelCase and must match exactly, because Claude Code silently ignores a field it does not recognise.

Claude Code subagents best practices: eight rules

Each rule below traces to a specific behaviour in the docs. Follow the first four and most subagents work on the first try.

1. One job per file. Anthropic's own guidance is that each subagent should excel at one specific task. A reviewer that also fixes and also writes docs has a description too vague to route to.
2. Write the description as a trigger. Claude delegates based on the description, so say when: "Use after any code change, before committing." The phrase "use proactively" encourages automatic delegation. Keep it to a sentence or two; descriptions load into every session, and Claude Code warns at startup when they pass 15,000 tokens combined.
3. Allowlist tools. Omit tools and the subagent inherits everything available, MCP servers included. A reviewer needs Read, Grep, Glob and perhaps Bash. Leaving out Edit and Write is what makes it read-only.
4. Choose the model on purpose. The model field is the main cost lever. Simple, noisy jobs go to Haiku; judgment calls stay on the main model.
5. Put the rules in the prompt. The subagent cannot see your conversation. Anything it must obey, such as "ignore the vendor directory", belongs in its system prompt or in the request you give Claude when delegating.
6. Specify the return format. The report is the only thing that comes back, and a long one eats the context you were trying to protect. Cap it: ten findings, file and line, one-line fix.
7. Isolate anything that writes in parallel. Two subagents editing the same checkout will collide. isolation: worktree gives a writer its own temporary copy of the repository.
8. Bound the loop. maxTurns stops a subagent that is going in circles. Claude Code returns what it has, marked as partial, and Claude can resume it.

Which model should each subagent use?

Match the model to how much judgment the job needs. The aliases are the same ones /model accepts, and inherit means "whatever the main conversation is running".

Claude Code resolves a subagent's model in a fixed order: a model Claude passes for that one invocation, then the model field in the file, then the CLAUDE_CODE_SUBAGENT_MODEL environment variable, then the main conversation's model. Run /tasks while a subagent is working to see which model it actually got. One trap: a subagent's context window is sized by its own model, so delegating to a smaller model also means a smaller window.

Claude Code subagents examples: three copy-ready agent files

Save each block as a file in .claude/agents/. They use only documented fields. Change the commands to match your stack, then ask Claude to use the subagent by name once to confirm it loads.

1. A read-only code reviewer

No Edit or Write, so it cannot change files. model: inherit keeps review quality level with your main session, and the capped return format keeps the report short.

---
name: code-reviewer
description: Reviews the current diff for bugs, security problems and missing tests. Use proactively after any code change, before committing.
tools: Read, Grep, Glob, Bash
model: inherit
maxTurns: 20
---

You are a code reviewer. You never edit files.

When invoked:
1. Run git diff to see what changed.
2. Read the changed files and the code they call.
3. Check for bugs, unhandled errors, exposed secrets and missing tests.

Return at most 10 findings, most serious first. For each one give the
file and line, what is wrong, and the smallest fix. If nothing is wrong,
say so in one line. Do not restate the diff.

2. A test runner that returns only failures

This is the highest-value subagent for most projects, because test output is the biggest source of context you will never read again. It runs on Haiku: the job is to execute a command and filter the result.

---
name: test-runner
description: Runs the test suite and reports only the failures. Use after code changes or when asked whether tests pass.
tools: Bash, Read, Grep, Glob
model: haiku
maxTurns: 15
---

You run tests and report results. You never edit files.

1. Run the project's test command (npm test unless told otherwise).
2. If everything passes, reply with one line: the command and the pass count.
3. If anything fails, list each failing test with its file, the assertion
   message and the first relevant stack frame.

Never paste the full test output. The main conversation only needs
the failures.

3. A migrator for mechanical changes

The one writer of the three. isolation: worktree puts its edits in a temporary git worktree, and permissionMode: acceptEdits stops it asking about every file. Two things to know: the worktree branches from your default branch, not from uncommitted work in your checkout, and if your main session is already in auto, acceptEdits or bypassPermissions mode, the subagent uses that mode instead of the one in the file.

---
name: migrator
description: Applies one mechanical change across many files, such as renaming an API or updating imports. Use when the same edit repeats in more than five files.
tools: Read, Edit, Write, Grep, Glob, Bash
model: sonnet
permissionMode: acceptEdits
isolation: worktree
maxTurns: 40
---

You apply one mechanical migration and nothing else.

1. Restate the migration rule you were given in one sentence.
2. Find every affected file with Grep before editing any of them.
3. Apply the same change to each file. Do not refactor nearby code.
4. Run the type check or build and fix only errors your change caused.

Return the list of files changed, any files you skipped and why, and
the result of the final check.

How do you invoke a subagent, and how do subagents communicate?

There are three ways to call one, in rising order of certainty. Naming it in plain language leaves the decision to Claude. An @-mention makes that subagent run for the task. The --agent flag turns the whole session into that agent, with its prompt, tools and model.

# Natural language: Claude decides whether to delegate
Use the test-runner subagent to check whether the suite passes

# @-mention: that subagent runs for this task
@agent-code-reviewer look at the auth changes

# Whole session runs as the agent
claude --agent code-reviewer

Communication runs one way by default: the subagent reports to whoever launched it. When a subagent finishes, Claude gets its ID and can resume it later with the full history intact, which is how "continue that review and now check the authorisation logic" works. Explore and Plan are the exceptions; they are one-shot and cannot be resumed. Subagents that Claude gave a name can also message each other, but if your design needs workers to talk among themselves, that is the signal to look at agent teams.

Subagents, forks, skills or Claude Code agent teams?

Use a subagent when the work is self-contained and you only want the result. The other three options exist for the cases where that does not fit.

Agent teams are several full Claude Code sessions: one lead, plus teammates that message each other and share a task list. They are experimental and off by default. To try them, add this to settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Three cautions from the docs before you do. Teams cost more: Anthropic's cost page puts them at roughly seven times the tokens of a standard session when teammates run in plan mode, and recommends starting with three to five teammates. Enabling the flag also changes ordinary delegation, because a subagent that Claude names will launch as a teammate. And you can reuse the agent files above as teammate roles, by asking Claude to "spawn a teammate using the code-reviewer agent type".

Subagents also pair well with the other extension points. Hooks in your settings files fire inside subagents too, so a guard from our Claude Code hooks examples covers every subagent's tool calls. You can also scope an MCP server to a single subagent with the mcpServers field, so its tool descriptions never load into the main conversation; our MCP guide explains the servers themselves, and the best MCP servers for coding list covers which ones are worth scoping. For running several full sessions side by side rather than helpers inside one, see the Claude Code desktop app guide.

Mistakes that waste context and quota

• Expecting subagents to cut your bill. They protect context. Usage still counts against the same plan limits, so the saving comes from the model you assign, not from delegating. Our Claude pricing guide covers what those limits are.
• Delegating a quick question. A fresh subagent has to gather context first. For something already in your conversation, the docs point to /btw instead.
• Letting reports run long. Ten parallel researchers that each return two pages will fill the main window anyway.
• Leaving the tools field out. The subagent inherits everything, including write access you did not mean to give a reviewer.
• Wondering why a file does not load. A missing name or description, broken YAML, or an opening --- that is not the first line all cause a silent skip. Run claude --debug, or claude plugin validate .claude/agents, to find it.
• Running parallel writers in one checkout. Give each its own worktree or its own set of files.

Subagents are one part of building with an agent rather than chatting with one. Our AI SaaS Builder program goes further into the workflow around them: specs, review loops and shipping a product on Claude Code, Supabase and Next.js.

Claude Code subagents: FAQ