← Back to Guides · CLAUDE CODE
Claude Code Subagents Best Practices: Choosing Your Delegation Model
Short answer: the subagents that actually get used instead of ignored follow the same five rules — one responsibility per agent, a description written to trigger auto-delegation ("use proactively" phrasing, not a vague summary), an explicit understanding of what it inherits from CLAUDE.md versus what it doesn't, tool grants that match the job instead of defaulting to everything, and a hard boundary against the one failure mode that breaks all of the above: an agent that quietly grows to cover two jobs. Below is each practice with the actual mechanism behind it, not just the recommendation.
1. Single-responsibility subagent design
A subagent definition is a YAML-frontmatter file in .claude/agents/<name>.md with a name, a description, an optional tools list, and a system-prompt body. Claude Code routes a task to a subagent by matching the task against that description field — which means two agents with overlapping descriptions don't "share" the work, they compete for it, and which one wins becomes nondeterministic across runs.
The fix isn't a longer description — it's a narrower one. backend-architect should own the contract (what an endpoint returns, how a schema is shaped) and explicitly not implement it; api-engineer implements against a contract that already exists and says so if one doesn't. One line in each file — "do not implement," "do not design the contract" — resolves the overlap that a paragraph of elaboration won't, because routing is driven by what the description rules out, not by how much it explains. We cover this specific overlap case, and the tool-permission version of the same mistake, in our subagent audit post.
2. Trigger phrases for auto-delegation
Claude Code decides whether to auto-delegate a task to a subagent by reading that agent's description field against the task at hand — it's a semantic match, not a keyword lookup, but certain phrasings make the match far more reliable in practice. The two that matter most:
- "Use proactively" in the description tells Claude Code this agent should be invoked without being explicitly named, whenever a matching task appears — the difference between "a security-focused agent exists" and "route here automatically before anything touching auth or payments ships."
- A concrete trigger condition, not a role summary. "Reviews code for bugs" is a role summary; "use proactively before every merge to check for logic errors, unhandled edge cases, and security issues" is a trigger condition that tells the router when, not just what.
The difference shows up directly in whether you have to remember to invoke the agent by name or whether it fires on its own. A description with no trigger language still works when you call the agent explicitly — e.g. "have the security-auditor check this" — but loses proactive routing entirely.
3. What subagents inherit from CLAUDE.md (and what they don't)
This is the single most common point of confusion in subagent setups. A subagent runs in its own isolated context window — it does not inherit the running conversation's history, the files the main thread has already read, or anything the user said earlier in the session. What it does get:
- Its own system prompt, defined entirely by the body of its
.mdfile. - The project's
CLAUDE.mdconventions, because Claude Code loads project-level instructions into every agent's context at the start of its run — a subagent still knows your repo's conventions (package manager, test command, code style) without you repeating them. - Whatever tools its
tools:frontmatter grants — a restricted list if specified, or the full default set if omitted.
What it does not get is implicit: if the main thread read five files and formed a plan, the subagent starts blind to all of it unless the invocation explicitly passes that context in the prompt handed to it. This is why a subagent invoked mid-task needs a self-contained brief — "review the diff in api/billing.ts for the Stripe webhook handler we just added" — rather than "review what we just did," which means nothing in a fresh context window.
4. Concurrency limits in practice
Claude Code can dispatch several subagents from a single message — multiple Task tool calls fired together rather than one at a time — and genuinely independent subagents (separate files, separate concerns, no shared state) run that way with close to linear speedup. The limit in practice isn't a hard cap so much as diminishing returns: once two dispatched subagents would touch the same file or depend on each other's output, running them concurrently just creates merge conflicts and duplicate edits that cost more to reconcile than running them one after another would have. The practical rule is the same one that applies to Agent Teams (the workflow pattern of running several agents against one repo at once, usually in separate worktrees) — size the parallel dispatch to the number of actually independent slices the task has, covered in more detail in Agent Teams vs. Subagents.
5. The common mistake: subagents that do too much
Every other practice above fails the same way if this one is ignored. An agent description that starts narrow — "reviews API route files for contract compliance" — drifts over time as someone adds "and also checks for security issues" and "and suggests performance improvements" to the same file, because each addition feels small in isolation. Six months in, the agent is routed to for three unrelated jobs, its description no longer cleanly rules out any other agent's territory, and routing becomes inconsistent in exactly the way Practice 1 warns against.
The tell is in the tool grant: an agent that needs Read, Write, Edit, Bash, and web access to do its "one job" is usually covering more than one job. code-reviewer needing no Edit access, security-auditor needing no Write access — the tool list should be a direct consequence of the single responsibility, and if it keeps growing, that's the signal to split the agent rather than widen its grant. Our ranked list of 20 subagents is built entirely around this split — note how often a "does X and also reviews X" job became two agents instead of one.
FAQ
How many subagents is too many? There's no fixed count — the signal to watch is whether two agents' descriptions could plausibly claim the same task. If they can, split one of them further or merge them; the total number matters less than whether every agent's territory is unambiguous.
Does a subagent need a tools: field if I want it to have full access? No — omitting tools: from the frontmatter grants the default full tool set. Only specify the field when you want to restrict access, which is the common case for review-only or design-only agents.
Can a subagent call another subagent? Not directly in the way a main thread dispatches one — subagent-to-subagent delegation isn't the standard pattern. The calling thread (main session or a command/workflow) is what sequences multiple subagents; a single subagent's job is to do its one bounded task and return.
Is "use proactively" required for every agent? No — it's only useful for agents you want auto-invoked without being named. A narrowly-scoped agent you always call explicitly (e.g. by typing its name in a prompt) doesn't need proactive-trigger language, since you're doing the routing yourself.
Where do I see which subagents would actually fire for a given task? Agent Chain simulates the routing for a typed feature description against a given agent roster, which is the fastest way to catch an overlap before you've written the 21st agent file.
Sources
- How and when to use subagents in Claude Code (Anthropic), fetched 2026-11-17 — the proactive-delegation and isolated-context-window behavior referenced above
- We Audited Our Own 34-Agent Claude Code Setup (first-party) — the overlap and over-permissioning findings Practice 1 and 5 are built on
- 20 Best Claude Code Subagents for SaaS Founders in 2026 (Ranked) (first-party) — the full roster this post's single-responsibility examples are drawn from
Next steps
Start by auditing your existing agents for the one tell that matters most: a tool grant wider than the stated job needs, or a description that overlaps another agent's. Agent Chain shows the actual routing for a typed task before you add another agent file, and Kit Picker suggests which of AgenticKit's pre-scoped roster to install for a specific priority rather than all 34 at once.
Written by Rakshit Yadav. Published 2026-11-17, last updated 2026-11-17.
Related Tools & Agents
Check your own agents for scope overlap
Type a feature and watch which subagents would actually run, in order, before you add one more.
Open Agent Chain →