Claude Code Subagents: The Brief, the Wave, the Handback

A Claude Code subagent is a separate worker your main session spawns through the Agent tool. It runs in its own context window, with its own system prompt, its own tools and its own permissions, does one job, and hands back a result. Spawn one when a task would flood your main context or can run in parallel.

That's the definition. Here's the practice, from someone running 40-plus named ones. And yeah, the first draft of the article you're reading came out of one of them.

What a subagent is, and when it beats doing it yourself

A subagent is an agent definition Claude Code can hand work to. Each one is a Markdown file with YAML frontmatter up top, name, description, tools and model, and a system prompt as the body. You can keep them at project level in .claude/agents/, shared with anyone working in that repo, or at user level in ~/.claude/agents/, available in every project. You can also create them through the /agents screen.

Project level is usually the better default when the work depends on that codebase's conventions. User level is for the generalists you want everywhere.

Now the part most tutorials bury. The whole value of a subagent is context isolation. Its file reads and tool output don't land in your main session's context. Only its final answer comes back.

Why does that matter so much? Because in Claude Code every file read and every tool call draws from the same allowance, and it all piles into whatever context it happens in. Send a subagent to read 30 files and summarize them, and your main session gets the summary, not the 30 files. That's what makes fanning work out affordable.

So a subagent beats doing it yourself when:

• The job is heavy on reading. Research, audits, "go find every place we do X."
• The job splits cleanly. Five slugs, five pages, five repos. Independent pieces.
• The job needs a specialist's rules. A content lead with content rules loaded, a security lead with security rules loaded, without cluttering your main session with both.

If you're still getting set up, here are the Claude Code basics this builds on.

Spawning your first subagent and giving it a clean brief

You spawn one by having your main session call the Agent tool with a task, and optionally a specific agent type. The mechanics take seconds. The brief is where subagents win or lose.

A subagent starts with none of your conversation. Whatever it needs, you have to hand it. My own lead definitions spell out what every worker gets: a clear, specific task, the skills to load, and file boundaries if it's editing anything.

Let me show you a real one, because I'm living in it. This article came from a brief that gave the writing lead exactly five slugs, said "ONLY these," and pointed it at the briefs file, the SEO plan, the research files and my voice profile. It named the files it had to create for each slug and the fields each one needed. It listed what not to touch. And it ended with how to verify the work before reporting back.

Look at what that brief does. It kills every question the subagent would otherwise have to guess at. What's in scope? Where's the source material? What does done look like? How do I prove it?

The failure mode is the lazy brief. "Write some articles about Claude Code." A subagent handed that will do something. It just won't be what you meant, and you'll burn more time fixing it than you saved by spawning it. The brief is the job.

Running several in parallel without them colliding

You run several at once by giving each one a slice nobody else owns. Parallel is easy. Parallel without collisions is the whole skill.

My doctrine calls this a WAVE: where the work splits, run several instances of the SAME lead on different slices, then reconcile. The reasoning is written right into the rule: "one lead exploring six directions at once beats six sequential prompts from a generalist."

This article is part of a wave. Three instances of my content lead wrote this batch of articles in the same worktree at the same time. Each instance got its own slugs and a hard line: never touch a directory that isn't yours. Same shared files, three writers, zero overlap, because ownership was decided before anybody started typing.

Three rules keep a wave clean:

1. Split by ownership, not by effort. Each subagent owns whole directories or whole files. Never "you take the top half of this file."
2. Share read-only inputs freely. Briefs, research, style guides. Reading doesn't collide.
3. Reconcile in one place. The parent checks all the results together at the end, with the same validators, before anything ships.

For code, the same idea goes one level deeper: every task gets its own git worktree, so two agents never write to the same working directory at all.

Above the waves sits the orchestration layer, the chain. My fleet runs three lanes: plan, where an orchestrator writes scored briefs; execute, where a conductor sequences the leads and manages handoffs; and check, an independent QA lane that can veto a bad delivery. There used to be a fourth lane. I removed it on July 28 of this year, commit 7eb708e. Three lanes now. That's how those subagents get coordinated once there are dozens of them.

Naming: why every one of mine is a role, not a tool

Every subagent in my fleet has a name and a role, not a function name. Einstein owns semantic SEO. Ghost owns local and GMB. Tommy owns technical SEO. Linx owns link building. Shakespeare owns content. Dan owns engineering. Raven goes wide on research, Sherlock goes deep on one thing. Knox owns security. Queen runs QA.

This isn't branding. It's doctrine, and it's written down as a principle: "everything named is a keyword." A verbose, semantic name is implicit context for every agent that reads it.

Think about what that buys you in a brief. When the main session sees "hand this to Ghost," it already knows the job is local SEO. Nobody has to explain what seo_helper_v2 does, because there's no seo_helper_v2. The routing is in the name.

It also changes the rules of the fleet. My instruction file says routing to a named lead is "the default, not a judgment call," and it tells every session not to do a lead's work directly "because it looks quick." That rule only works if the leads have names you can route to without thinking.

Here's more on why I name every one of them, and on what a full fleet of them looks like running day to day.

What a subagent should hand back, and in what shape

A subagent should hand back a verdict against the ask, backed by evidence, plus anything that blocked it. Not a diary of what it did. The parent never sees the subagent's scratch work, only the handback, so the handback has to carry everything that matters.

My rule for the whole fleet is that every lead records its own proof of work, because only the lead knows whether what it was asked to do actually got done. The default proof is a stated verdict against the ask, backed by real evidence.

The handback on this article carried:

• A table of every slug with its word count against the target, its title length and its excerpt length.
• The raw output from the atom validator and the anti-duplication check.
• A proof that there are no banned characters or words in any of the files.
• Every spot where my own records didn't cover something the brief asked for.
• Every claim it left out because the research couldn't back it.

That last pair is the part people skip, and it's the most valuable part. A handback that only reports wins is a handback you can't trust. I want to see the gaps.

And labels are literal. If the report says PROOF, there's proof attached. If it says VALIDATION, a validator ran. No decorative labels on work that didn't happen.

The three jobs a subagent is the wrong answer for

Subagents cost something. A fresh context, a brief to write, a handback to read. For a lot of work that overhead is bigger than the job.

1. Small, quick work. My instruction file lists exactly what doesn't get delegated: admin, a question, a one-line fix, a config edit, a doc tweak, or reading and reporting. Spawning a worker to change one line is like calling a meeting to send an email.

1. Work that needs the whole conversation. Isolation cuts both ways. The subagent doesn't carry your last hour of back-and-forth, the decision you made twenty minutes ago, the thing you ruled out. If the job depends on all that and it can't be written into a brief, keep it in the main session.

1. Rules that have to fire every time. A subagent is model-discretionary, the main session decides whether to call it. If something must happen on every commit or every session no matter what, that's not a subagent's job. That's a hook. Hooks fire whether the model wanted them to or not.

Get those three out of the way and what's left is where subagents shine: heavy, splittable, specialist work, briefed clean and handed back with proof. That's most of what my fleet does all day, you know? And it's the reason one person can run 40-plus agents without spending the whole day translating between them.