Claude Code subagents work well when you follow six rules: each subagent gets its own file in .claude/agents/ with a clear description, it only gets the tools its task needs, you pick the model per role instead of globally, you run fewer subagents in parallel than the docs allow, you put everything it needs into the task text because it cannot see your conversation, and anything that leaves the house is reviewed by a second, separate role in a fresh context, in my setup usually a subagent. What comes back is never the full work log, only the summary. That is the whole point of subagents: your main conversation stays lean while the noisy work (research, tests, logs) happens somewhere else.
I run my AI workforce on Claude, and several of its members are defined as subagents. What follows comes from the official docs and from our own protocols, which record when a subagent run worked and when it failed at an approval step. What a subagent is compared to a skill or an agent is covered in Claude Subagents, Skills, Agents; this post is about the practical rules. Everything I write about Claude is collected on the Claude page.
What a subagent sees, what it doesn't, and what comes back
According to Anthropic's subagent documentation, a subagent is a separate Claude instance with its own system prompt, its own context window, and its own set of tools. It sees its system prompt, your task text, the project's CLAUDE.md hierarchy, and any skills you preload in the frontmatter. It does not see your conversation so far, the main session's auto memory, or skills you already invoked in the main conversation.
The most important rule for the task follows: everything the subagent needs to know is in the task text or in files it may read. "Do it the way we discussed earlier" does not work, because there is no earlier. That is why a subagent in my workforce always gets a letter with my exact wording, links to the context, and the mandatory checks, rather than a copy of the content.
Only the subagent's final report returns to the main conversation. The docs name this as the core benefit: "use subagents to keep research out of it," because the context window is the scarcest resource. If you have ten files searched, you want the conclusion, not the ten files. How the main session keeps its knowledge across sessions is in CLAUDE.md: Claude Code's Memory.
Creating the file: location, required fields, one example
Where a subagent lives and which fields exist at all is covered briefly in Claude Subagents, Skills, Agents; this section is about the fields that make a difference day to day. Subagents live as Markdown files with frontmatter in .claude/agents/ inside the project or in ~/.claude/agents/ for all projects. Both folders are read recursively according to the docs; if names collide, the higher level wins, and in nested projects the file closest to your working directory wins. Only name (lowercase letters and hyphens) and description are required. Optional fields include tools, disallowedTools, model, permissionMode, maxTurns, skills, memory, isolation, background, and hooks.
Here is a minimal working file. It is modeled on our SEO employee and is not his actual file, which I do not publish. You set the model value per role, see the next section:
---
name: seo-reviewer
description: Evaluates a website with real tools and delivers a prioritized action plan. Use when an SEO audit or a follow-up measurement is due.
tools: Read, Glob, Grep, Bash, Write, WebSearch, WebFetch
model: inherit
memory: project
---
You are the SEO reviewer. Every rating rests on a tool output stored in
the job folder. No invented metrics, no promises. At the end, report only
the findings with their location, not the path you took to get there.
The text below the frontmatter is the subagent's system prompt. The description decides when Claude Code picks the subagent on its own; the docs recommend phrases like "use proactively" and keeping the sum of all descriptions under 15,000 tokens. You can also call it directly with @agent-seo-reviewer, with a natural sentence, or for a whole session with claude --agent seo-reviewer. Sebastian in my workforce follows the same pattern, a subagent with an isolated context.
Model per role: the resolution order
Claude Code resolves a subagent's model in this order: first the parameter at call time, second the model field in the frontmatter, third the environment variable CLAUDE_CODE_SUBAGENT_MODEL, fourth the main session's model. In the frontmatter you can enter a small, medium, or large model of the current family, a full model ID, or inherit.
The docs themselves use a large model for the security reviewer, a medium one for the code reviewer, and a small one for the test runner. The logic: a role that only starts tests and summarizes error messages does not need an expensive model; a role that judges security flaws does. Whether that saves you money is a hypothesis, not a measurement. I have no separate usage figures per model, so my recommendation stays cautious: start with inherit and deviate only once you have a role that demonstrably gets by with less.
Working in parallel: limits, background, worktrees
According to the docs, up to 20 subagents run at once by default (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS), and subagents may spawn further subagents up to three levels deep (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH). A foreground subagent blocks your main session until it finishes; in the background (background) it runs in parallel with a reduced tool set, and you get a notification when it is done. With isolation: worktree, each subagent gets its own Git worktree from the default branch, cleaned up if nothing was changed. The best practices page also describes /batch, which spreads one change across many subagents, each with its own pull request. I know worktrees and /batch from the docs, not from my own operation.
The number 20 is a limit, not a recommendation. My rule in daily operation is to prefer less parallelism. Every subagent reads the CLAUDE.md hierarchy and its preloaded skills from scratch, and every parallel instance pays that entry cost. Add a documented mistake from our learnings: on September 8, 2026, Conny ran building and checking in parallel and had to retract the message "done and verified." Parallel pays off when the tasks are truly independent: five blog posts on five topics, yes; five changes to the same file, no.
Tool permissions: tools and disallowedTools
Without any setting, a subagent inherits all tools of the main session, including MCP servers. With tools you give an allowlist; with disallowedTools you take individual tools away. One detail from the docs that easily goes wrong: disallowedTools: Bash(git push *) removes the entire Bash tool, not just that one command. Selective blocks belong in permissions.deny in your settings. The built-in subagents Explore and Plan are read-only according to the docs, with Write and Edit denied; general-purpose has all tools.
The doc examples show the principle: the security reviewer gets Read, Grep, Glob, and Bash, but no Write; the database reader gets Bash with a hook in front of it that intercepts write commands. My own setup differs, and I say so openly: what an employee in my workforce may do is written in three tiers in its personnel file, free, only after approval, never. That is a role rule in a text file, not a technical lock. My reviewing subagents do not run with reduced tool permissions; the second and third tier I enforce with Claude Code Hooks: Rules That Always Apply and the approval gate in the conversation. If you want the role locked down technically, tools is the place for it, and the docs recommend exactly that. MCP servers a subagent needs go into the mcpServers field; how to set one up is in Set Up a Claude MCP Server.
Subagent, skill, or main conversation: the decision rule
The docs give a clear rule: main conversation for iteration and shared context, subagent for lots of output, tool restrictions, self-contained tasks, or parallelism, skill for reusable workflows that need the conversation history. Skills can be preloaded into a subagent through the skills field; how to write skills is in Claude Skills: How to Create and Use Them.
My workforce as Claude Code subagents: three documented cases
The first case is a rule, not a single event: anything that leaves our house is checked by a separate role, never by the same context that produced it. Our house rules cite Huang et al. (ICLR 2024) for this: a model checking its own work in the same context is poor at finding its own mistakes. Anthropic's docs call the same pattern an "adversarial review step": a reviewer subagent in a fresh context sees only the diff and the criteria. They also warn that a reviewer you ask to find gaps will always report gaps, which is why the task says "flag only gaps that affect correctness." For me the lever is the fresh context and the different task, not a reduced tool set. During the editing pass on September 7, 2026, this separate role corrected technical errors in a good half of the Kubernetes posts and removed unsupported pricing claims from the Claude posts.
The second case shows when a subagent is the rescue. On September 7, 2026, Sebastian wrote the handover for a blog release to Ralf, and I approved it at 6:24 pm. Delivery to Ralf's running session failed at the approval step, so Ralf ran as a subagent: fresh context, the handover letter as the task, and Sebastian checked the result live afterwards. The work did not end with the subagent; it ended with my approval and a check by a second role.
The third case is everyday routine. On September 16, 2026, Sebastian asked Conny through the mailbox for experiences to use in five posts. Conny answered as a subagent with a letter in Sebastian's inbox. The mailbox protocol is how subagents without a shared context work together in my workforce: the sender puts the handover in its outbox and a copy in the recipient's inbox, with a link to the context instead of a copy of the content. Everything stays traceable, and I can see who handed over what and when.
Seven rules from the docs plus my additions
The doc list reads: write descriptions so that Claude picks the subagent on its own; keep the sum of all descriptions under 15,000 tokens; offload noisy tasks like tests and logs; use memory: project to build knowledge across sessions; preload skills instead of repeating them in the task; enforce boundaries through tools and disallowedTools; and check final reports for command-like patterns, because a subagent that has read outside content must not pass on instructions from it.
My three additions from daily operation: first, every subagent task is a letter with exact wording, context links, and mandatory checks, never a half sentence. Second, less parallelism than allowed, because every instance has entry costs. Third, a subagent ends at a rule, a briefing, or an approval gate; anything that changes state or leaves the house I approve myself, and the employee documents the approval with a timestamp.
Frequently asked questions
Does a subagent see my CLAUDE.md and my previous chat?
The CLAUDE.md hierarchy, yes, unless you set omitClaudeMd. The previous chat, no, and neither the main session's auto memory nor skills already invoked there. Everything it needs to know belongs in the task or in files it may read.
How many Claude Code subagents can I run in parallel?
By default 20 at once, adjustable via CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS, with up to three levels of nesting. My rule is still: prefer less parallelism, because every instance costs context and tokens, and parallel instances get in each other's way on the same file.
Which model does a Claude Code subagent use if I don't specify one?
The main session's model, provided neither a call-time parameter, nor model in the frontmatter, nor the environment variable CLAUDE_CODE_SUBAGENT_MODEL is set. The order is exactly this: call, frontmatter, environment variable, main session.
Claude Code subagents vs skills: what is the difference?
A skill is a reusable workflow that runs in the main conversation and sees its history. A subagent is a separate instance with a fresh context and its own tool set. The two combine: in the skills field you preload the skills a subagent needs.
Can a subagent break files in my project?
Yes, if it gets Write, Edit, or Bash. That is why you give only what the role needs through tools, use permissionMode: plan for pure reviewers, isolation: worktree for risky changes, and route anything that changes state through an approval.
Where does the subagent file go, in the project or for all projects?
Both work: .claude/agents/ in the project applies only there, ~/.claude/agents/ applies to all projects. If names collide, the higher level wins according to the docs; managed settings and the --agents flag at startup come before both.
What happens when a subagent is finished?
It delivers its final report to the main conversation; the work log stays with it. With SendMessage and its agent ID you can resume it, and its history is preserved. According to the docs, that does not apply to the built-in Explore and Plan subagents.
How to continue
Create a single subagent, the reviewer, with the task "flag only gaps that affect correctness." The docs recommend Read, Grep and Glob without Write for it; in my workforce the separation of creator and reviewer is a role rule, and it carries that way too. For one week, have it check every result you would otherwise have passed on unchecked. If that holds up, add the second subagent for the noisy work. The concepts behind all of this are explained in Claude Subagents, Skills, Agents, and the first steps in the terminal in Claude Code: A Guide for Beginners.
