Once an agent starts performing well, it is tempting to reach for more of them. If one agent can read a file and propose a change, surely five agents can read five files and propose five changes in a fifth of the time. Sometimes that intuition is right. Often it is a trap, and an expensive one, because getting orchestration wrong rarely produces a crash. What you get instead is quiet degradation: results that look complete but are subtly inconsistent, conclusions stitched together from contexts that never saw each other.
This is the sixth article in a series on engineering with Claude Code. By now the foundations are in place: context discipline, permission boundaries, the planning loop. Orchestration sits on top of all of it. It is the step where a single agent stops being the unit of work and becomes a coordinator of other agents. That shift multiplies capability, but it multiplies risk along with it, and what I want to develop here is a feel for which of the two you are actually multiplying in a given case.
A single agent with full context is the default, and it is a strong one. Orchestration is what you reach for when the work genuinely decomposes, and a large part of architectural judgement is recognising when it does not.
What a subagent actually is
A subagent is a scoped delegation. The coordinator hands a fresh agent a self-contained task, that agent runs in its own context window with its own tools, and it returns only its conclusion. Its working, and the dozens of files it read to get there, stay behind. The coordinator gets the answer without the mess.
That clean context boundary is the whole point, so it is worth spending a moment on. The most valuable thing an agent has is the relevance of what sits in its context. Asking the main agent to read forty files to locate one function pollutes its working memory with thirty-nine irrelevant ones. Delegate that search to a subagent and the main agent receives a single sentence: "the handler is in src/net/listener.go, line 212." The forty-file slog happened somewhere else and was discarded. It is context hygiene applied as an architectural pattern, and it follows directly from the discipline in Part 2.
The second property is concurrency. Because a subagent runs independently, several of them can run at once. That is where fan-out begins, though delegation and parallelism are separate ideas. You can delegate a single task for context reasons alone, with no parallelism involved at all, and frequently that is the more valuable use.
Custom agent types
For roles that recur, it is worth defining a custom agent type rather than re-describing the role each time. An agent definition is a small, declarative block (typically front-matter plus a prose brief) that pins down who the agent is, what it may touch, and when the coordinator should reach for it. The shape is deliberately simple:
---
name: explorer
description: >
Read-only codebase scout. Use to locate where something
lives across many files when you only need the conclusion,
not a tour of every file read along the way.
tools: [Read, Grep, Glob] # deliberately no write access
model: fast
---
You are a search specialist. Given a target — a symbol, a
behaviour, a configuration value — find where it is defined
and where it is used. Read excerpts, not whole files.
Return only:
- the file path(s) and line numbers that matter
- a one-line note on how the pieces connect
Do NOT propose changes. Do NOT summarise unrelated code.
If you cannot find it after a broad sweep, say so plainly
rather than guessing.Two things in that sketch carry most of the weight. The tools list is a capability boundary. An explorer that cannot write cannot do damage no matter how it is prompted, which is the permissions principle from Part 3 applied at the agent level. And the closing instructions constrain the output, because the entire benefit of a subagent collapses if it returns a wall of text instead of a conclusion. So define the output contract as well as the role.
Fanning out: parallel work that pays off
Some work is embarrassingly parallel, and for that work fan-out makes a real difference. The pattern is always the same: a coordinator decomposes the task, dispatches independent workers, and then synthesises what comes back.
+---------------------+
| Coordinator |
| decompose the task |
+----------+----------+
|
+----------+-----------+-----------+----------+
| | | | |
v v v v v
+--------+ +--------+ +--------+ +--------+ +--------+
|Worker 1| |Worker 2| |Worker 3| |Worker 4| |Worker N|
| scope | | scope | | scope | | scope | | scope |
+---+----+ +---+----+ +---+----+ +---+----+ +---+----+
| | | | |
+----------+-----------+-----------+----------+
|
v
+---------------------+
| Synthesis |
| merge, reconcile, |
| resolve conflicts |
+---------------------+The kinds of work that fit this shape are recognisable once you have the template in mind:
- Broad searches across a codebase. "Where do we construct database connections?" fans out naturally. Each worker sweeps a region of the tree and reports back coordinates. The coordinator merges a handful of one-line answers.
- Reviewing many files by dimension. Rather than one agent reading everything for everything, dispatch one worker for security concerns, one for error handling, one for test coverage. Each holds a narrow lens, so each looks harder through it.
- Large mechanical migrations. Renaming an API across two hundred files, or applying a consistent codemod, partitions cleanly. Workers operate on disjoint file sets, so they cannot collide.
- Gathering independent perspectives. When you want genuinely divergent takes on a design question, isolated agents produce real diversity precisely because they cannot see one another and converge.
The common thread is independence. Where the subtasks do not need to talk to each other, parallelism is close to free of coordination cost and the wall-clock saving is real.
Fan-out is not free
Now the other side of the ledger, because it is the side that gets skipped in the enthusiasm of spinning up a swarm.
Every subagent consumes tokens for its own system prompt, its own context and its own reasoning. Ten workers is, roughly, ten times the token spend of one, and unlike a single long-running agent that spend is not amortised across a shared understanding. There is latency, too, but not the kind people expect: the workers may run concurrently, yet the coordinator must wait for the slowest of them and then do the genuinely hard part, which is merging.
Merging is where orchestration earns its difficulty. Subagents cannot see each other's context. That is the feature that keeps them clean, and it is also the liability. Worker 2 may rename a function that Worker 5 is, at that very moment, calling, and neither knows. Each returns a locally coherent result; the union is globally inconsistent. The coordinator is now responsible for reconciling answers that were produced in mutual ignorance, and reconciliation is harder than any of the original subtasks. The work you saved on the leaves you pay back at the root, with interest.
Fan-out trades coordination cost for parallelism. That is only a good trade when the work was genuinely independent to begin with. Otherwise you have paid the coordination tax and bought yourself a merge problem on top.
When not to fan out
The default should be a single agent. Reach for orchestration deliberately, and treat the following as signals to stay single-threaded:
- Sequential dependencies. If step B needs the output of step A, there is no parallelism to harvest, only coordination overhead to pay. Worse, splitting a dependent chain across agents means each one is working from a partial picture, which is exactly the condition under which mistakes compound.
- Trivial tasks. Spinning up a subagent to read one known file is pure overhead. The delegation costs more than the work. If you already know the path, just read it.
- Work that benefits from continuity. Some tasks improve as a single agent accumulates understanding: debugging a subtle failure, say, or refactoring around a design you are still forming an opinion on. Fragmenting that understanding across isolated contexts throws away the very thing that was making progress.
- Anything where one agent with full context is simpler. Simplicity is a feature. A single agent is easier to follow, easier to correct mid-flight, and easier to trust. If fan-out does not buy a clear, concrete advantage, it is just extra moving parts.
The mental test is short: does this work decompose into pieces that genuinely do not need to talk to each other? If yes, fan out. If you have to squint, or if you find yourself planning how the pieces will coordinate, that planning is the tell. The work is not independent, and a single agent will be both simpler and more reliable.
Patterns worth knowing
A handful of orchestration shapes recur often enough to be worth holding in mind. One warning matters more than the patterns themselves: using them is a matter of architectural judgement, and they are not recipes. Reaching for a pattern because it is named, rather than because the work calls for it, is how orchestration turns into ceremony.
- Explore → plan → implement → verify. The workhorse. A read-only explorer maps the territory and returns findings; a planning step turns findings into an ordered approach; implementation executes it; a verification pass confirms the result. The phases are sequential, but each can fan out internally, with exploration across many files and verification across many checks.
- The adversarial reviewer. After an implementing agent finishes, a separate agent reviews the diff with fresh, sceptical eyes and no attachment to the work. The independence is the value: the reviewer never fell in love with the approach, so it sees what the author cannot.
- The judge, or panel. For a question with genuinely divergent good answers, dispatch several agents to produce competing approaches, then have a judge agent weigh them against stated criteria. Useful for design exploration; wasteful for anything with one obvious answer.
- Loop until done. When the size of the work is unknown (discovery tasks, "find and fix every instance of X"), an agent works, assesses whether more remains, and loops until the territory is exhausted. The discipline is a hard stop condition, so the loop terminates on completion rather than on running out of patience.
Notice that these are not really about parallelism at all. Several are sequential pipelines whose phases happen to permit internal fan-out. That ordering is the point: structure first, concurrency only where the structure admits it.
explore ──► plan ──► implement ──► verify
│ │ │
│ (fan-out: │ (single │ (fan-out:
│ many files, │ agent, │ many checks,
│ one report) │ full ctx) │ one verdict)
▼ ▼ ▼
findings ───────────────────► diff ──────────► pass / fail ──► loop?Where this leaves us
Orchestration multiplies whatever you point it at. Point it at well-decomposed, independent work and you get more done, faster, with cleaner context. Point it at tangled, dependent, or trivial work and you get more tokens spent, more latency waiting on the slowest worker, and a merge problem the original task never had.
This is precisely why the earlier discipline in this series matters more here, not less. Every subagent you dispatch is a fresh context that must be set up well (Part 2) and a fresh set of capabilities that must be bounded deliberately (Part 3), and you are now doing both several times over, across agents that cannot watch each other. A loose permission or a sloppy brief that was survivable in a single agent becomes a pattern replicated N times the moment you fan out. If anything, orchestration leans on the foundations harder.
So default to one agent. Reach for many only when the work genuinely splits, size the fan-out to the independence actually present, and remember that the coordinator's hardest job is not dispatching the workers but reconciling what they bring back. The next article takes the final step, from agent as tool to agent as teammate, where this same orchestration moves out of the interactive session and into headless, programmatic use.
NK