Claude Code Subagents: Build Teams That Actually Work

What a subagent actually is

Almost everything written about Claude Code subagents covers the same ten minutes: create a markdown file with a name, a description and a list of tools, and Claude will start handing work to it. That part is genuinely simple, and the docs cover it well. What almost nobody writes about is what comes after: what happens when you wire a dozen of them into a process, pair them up and let them run against real work for weeks. I run subagents in production. Nightly bots that open issues and pull requests on one of my repos, a reviewer-per-task development workflow, and a hand-wired graph of headless agents that has been running my research loop for weeks. This guide is what that has actually taught me: the wiring, the team patterns that earn their cost, and the visibility problem nobody talks about.

One honest note up front, because it changes how you should read the numbers here. My own comparison of single agents against agent teams is not measured, it is a judgement from running both. Where this guide quotes numbers about teams beating singles, they are other people’s experiments, cited, not mine. What is mine is the wiring and the war stories.

The concept that explains everything is isolation, not parallelism. A subagent does not run inside your main conversation. It runs in its own context window, reads what it needs itself, and returns an answer. When Claude Code explores a repo or plans a change, a built-in subagent is doing exactly that. What isolation buys you: parallel work that does not pollute your main context, a bounded failure radius, and delegation that actually delegates. What it costs: the agent re-reads everything it needs, tokens multiply, and the quality of the delegation lives almost entirely in the description, because the description is what the model uses to decide whether to spawn the agent at all.

Built-in subagents

Claude Code ships with built-in subagents: Explore, Plan and general-purpose. You have used them even if you never named them. Explore reads the codebase and reports back, Plan lays out a change. They work the same way a custom subagent does: isolated context, a role, a tool allowlist. The current docs at code.claude.com are the reference for the full field list, and this corner of the product moves fast enough that you should check them rather than trust a blog post, this one included.

How to create a custom subagent

A custom subagent is a Markdown file with frontmatter. It lives in your agents directory, project-level or user-level depending on where you want it, and the exact directory has moved between releases, so check the docs rather than trusting a memory. If the agent needs longer instructions, put them after the frontmatter as the file body. Most useful agents are just frontmatter:

---
name: code-reviewer
description: Reviews diffs for correctness bugs, missing edge cases and secrets. Use after any code change.
tools: Read, Grep, Glob, Bash
---

That file is the agent. The name is the identifier. The description is the routing cue, and it deserves more care than the rest of the file combined: it is what the model reads to decide whether to spawn the agent at all, so write it like a job description, not a slogan. “Use after any code change” is specific about when. “Helps with code” is not. The tools line is the allowlist: the only tools the agent can call. A code reviewer might need Read, Grep, Glob and Bash. A researcher might need only Read and Grep. The docs list more options (a model per agent, permission modes, skills, hooks, scoping MCP servers), but those two fields decide most of what happens in practice.

Using subagents: delegation and the headless path

Automatic delegation happens from the description: Claude reads it, decides the task fits, and spawns the agent. Explicit delegation happens when you tell it to use a specific agent on a specific piece of work. Context is not shared. The subagent reads what it needs from the repo or from the input you pass, and tools are restricted to the allowlist. If an agent has Read and Grep but not Bash, it cannot run commands, and that is the point.

The detail that turns subagents from a convenience into infrastructure is that they do not need your chat session at all. The claude -p headless command starts one from a shell with a prompt and gets the answer back. Every agent in my graph is instantiated that way: claude -p with a task, input on one side, output on the other. No chat session required. That is the moment subagents stop being a feature of the editor and become process nodes you can wire.

Subagents vs Skills vs Plugins

They are not competitors. A plugin can ship subagents, and a subagent can preload a skill. The decision is just: does this work need isolation (subagent), does it need a procedure in the current loop (skill), or is it something you want to install from elsewhere (plugin)?

Wiring them into a graph

A single subagent is a convenience. A graph of them is a process. The graph I run is a research process: a start, an end, and a loopback inside the graph for iterating on a result. The structure is hardcoded rules with conditional connections. Each node in the graph is an agent with a specific task, an input and an output, and the output is passed on to a different node, or to an agent team, which is what I call a pair of nodes.

The node roles are not exotic: fact-checking, research that expands the context other agents will read, code generation, and review agents sitting on top of the code generators. The review pair gets its own section below. What matters about the graph itself is the discipline it forces. A node is not a prompt, it is a contract: this input goes in, this output must come out, and the next node either gets a well-formed answer or the run fails visibly. There is no model in the plumbing, so there is nothing to improvise with. I engineer the graph myself and test it. The graph does not improve upon itself, not yet, and I am not sure I want it to.

Testing a graph means testing the wiring, not the models. The models change under you with every release; the wiring is the thing you own. Does the right output reach the right node? Does the loopback actually loop? Does a failed node kill the run or silently hand garbage to the next one? Those questions decide whether the process tells you the truth, and they are all questions about your design. That is why this is engineering and not prompt tweaking.

Agent teams: pair a critic with a writer

The single best pattern I have found is the adversarial pair. One agent writes, a second agent is told to critique it, and the writer iterates on the criticism. In my research loop the split is also a cost split: a cheap worker-tier model generates, an expensive frontier model refutes. The critic catches real defects the writer’s own self-check signed off on, and a refutation before the expensive step is the cheapest mistake the system can make. The full loop lives in my lab post [TODO: link the autoresearch-lab post when it is published], which is personal research I run in my own free time outside the day-job; this guide only borrows the engineering.

That the pattern works is not just my feeling, but I want to be precise about what the evidence says. The multiagent debate paper from Du et al. (arXiv:2305.14325) had several instances of a model debate each other over multiple rounds, and the gains were real but uneven: on arithmetic tasks accuracy went from 67.0 percent single-agent to 81.8 percent with debate, and on GSM8K from 77 to 85 percent. The same paper found that self-reflection, one agent reading its own prior reasoning, barely helped. The exchange with another agent is what moved the needle. The agent-forest line of work (arXiv:2402.05120) took the simpler route, many agents voting, and got a Llama2-13B from 35 percent to 59 percent on GSM8K, which beats a single Llama2-70B at 54 percent. A mid-sized model, run as a team, beating a much larger model run alone. Worth sitting with that one.

The uncomfortable detail in that same paper: plain voting beat the fancier debate framework in their comparison, 59 against 48 percent on the same model. So the honest summary is that teams help, but the more elaborate the coordination you invent, the less certain the win. Start with the boring version: one writer, one critic, iterate.

The large-scale version of the same idea is the C compiler experiment by Anthropic researcher Nicholas Carlini (Ars Technica, The Register): 16 Claude agents in agent-team mode, each in its own container, no orchestrator, claiming tasks by writing lock files. Roughly 2,000 sessions over two weeks, about 20,000 dollars in API costs, 100,000 lines of Rust, and a compiler that builds a bootable Linux kernel and passes 99 percent of the GCC torture suite. The other numbers from that experiment matter just as much: the code quality was, by Carlini’s own account, nowhere near expert-programmer level, and the agents lost coherence around the 100,000 line mark, new features breaking old functionality. Teams scale output, not judgement.

What a small team looks like in production

You do not need a compiler experiment to get value out of this. The smallest version I run is three cron-scheduled bots on one of my repos. One bot scans the repository and flags issues it finds. A different bot picks a flagged issue up, tries to fix it, and opens a pull request. A human, me, decides what actually gets merged.

What that pipeline taught me is not that the bots are good, it is that their output quality tracks the project’s momentum. On a new project where there is real work to find, genuinely good things get flagged. On a stale project that is not actively developed, the bots start hunting for very small things that are not really worth merging, and the queue fills with noise. An agent team amplifies whatever signal the work already has. That is not a reason to skip the bots, it is a reason to aim them only at active work, and to keep the merge decision human.

What it costs and when not to bother

The costs are structural, and you can plan around them instead of discovering them on a bill.

The measured version of the last row comes from my superpowers fork work [TODO: link the superpowers post when it is published]. One slice of a build ran 27 subagent runs across 11 tasks. A single fix loop took three commits and three review passes, and that one task ate about 22 percent of all subagent runs, one task out of eleven. The product outcome was good, around 897 tests green. The process cost was not. Teams do not make work free, they move the expensive part from catching errors late to paying reviewers early.

The honest when-not-to-bother list is short. If the task fits in your own context window, do it yourself. If the task is trivial, a critic pair is ceremony. If the repo is quiet, scheduled agents will generate noise instead of signal. And if you cannot watch the thing run, none of this is worth building yet.

Performance and security considerations

Performance is the cost table above plus one multiplier: every subagent re-reads what it needs, so a task split across three agents costs more than the same task done inline, sometimes several times more. That is the price of isolation, and the correct response is not to avoid subagents, it is to give each one a task big enough to be worth a fresh context.

Security is mostly allowlist discipline and third-party hygiene. A subagent can only call the tools you gave it and the MCP servers you scoped, so the frontmatter is your security boundary. When you install someone else’s subagent, you are trusting their instructions and tool choices. Read the frontmatter before you install anything, the same way you would review a shell script before running it. The biggest community collection I have found is VoltAgent/awesome-claude-code-subagents on GitHub, 158 plus subagents across 10 categories, installable as plugins or copied as standalone files.

The visibility problem

Every expensive mistake I have made with agent systems had one thing in common: the failure was sitting in the artifacts the entire time, and completely invisible in the prose output. An agent’s summary tells you what the agent believes it did. A wall of model output tells you what the loop believes it did. A graph tells you what it did.

That is why the research loop has a live dashboard that draws the graph as it runs: which stage is executing, what it produced, what failed. When a run goes wrong you see the shape of the failure before you read a single line of model narration, and most of the time the shape is enough. The full argument for visibility, with the scoreboard, lives in the lab post [TODO: same link as above]; the guide-sized version is: build the view before you trust the system. A hand-wired graph is only a black box if you let the output be a wall of text.

Common pitfalls and troubleshooting

• The agent never triggers: the description is too vague or too broad. Write the exact trigger: when, on what, to what end.

• The agent cannot do the task: a tool is missing from the allowlist. Add the tool, or split the task differently.

• Context cost balloons: every agent re-reads what it needs. Do not spawn an agent for something that fits in your own context window.

• The review stage becomes the bottleneck: every team adds a critic, and the critic can become the slowest part. The 22 percent fix loop above is what this looks like in practice.

• Quiet repo, noisy bots: scheduled agents on inactive work start nitpicking. Aim automation at active repos.

• You cannot tell what happened: if the only output is prose, you will miss the bug. Build the view.

Honest caveats

Everything I know about whether this works comes from my own setups. No other human has used my graph, my bots or my workflow, and they might not fit anyone else. I have noticed teams produce sharper output, but I have not measured it, and this guide says so wherever it matters.

The graph does not improve upon itself. That is a limitation today and a design choice tomorrow; if I ever let agents edit their own wiring, the testing burden changes completely, because then the thing being tested is no longer mine.

Everything here about Claude Code specifics has a half-life. The subagents docs have already changed several times this year, agent teams arrived recently and are still moving, and any config block you copy will rot. When something here stops matching what the tool does, trust the tool.

And the noise problem repeats itself anywhere you add automation: on active work my bots find real issues, on quiet work they nitpick. The amplification works in both directions, and it is your merge button that keeps it honest.

Where this sits now

The bots still run every night, the graph and its dashboard are live, and I am building the editor around the graph so stages can be inspected and tweaked mid-cycle. If you are still deciding between Claude Code and Cursor at all, that is a different question, and the comparison I wrote in claude-or-cursor is where I worked through it.

Start with one critic pair

If you take one thing from this, make it the smallest team that still teaches you something: one writer agent, one critic agent with adversarial instructions, and one human at the merge button. Wire them so you can see every handoff, run it against active work for a week, and let the noise on quiet days tell you where the boundary of the thing actually is. The graph, the dashboard and the bigger teams are all just that pair, scaled up and given contracts. And the one habit I would copy from the compiler experiment is not the scale, it is the harness: the value was never in the agents, it was in the environment that made the agents observable.