GuidesEngineering
Subagents: When Splitting the Context Actually Helps
Shiplight AI Team
Updated on July 31, 2026
Long agent sessions degrade. Not because the model gets worse, but because the context fills with exploration that mattered twenty steps ago and does not now: files that turned out to be irrelevant, a search that returned nothing, an approach that was abandoned. All of it stays, and all of it competes with what matters.
Subagents exist to stop that. The mechanism is simple and the judgment about when to use one is not.
What a subagent is
A subagent is a separate context window running a delegated piece of work, which returns a result to the main agent without returning everything it read to get there.
That last clause is the whole point. If a subagent reads forty files to answer "which module owns authentication," the main context receives the answer, not the forty files.
Two properties follow. Isolation, which keeps the main context clean. And parallelism, since several subagents can work at once when their tasks do not depend on each other.
When it genuinely helps
Search and exploration. "Find every place we call this deprecated API" involves reading a lot to produce a short answer. Perfect delegation: high read volume, low output volume.
Independent parallel work. Several files needing the same mechanical change, with no interdependence. Running them concurrently is faster in wall-clock time and each stays out of the others' way.
Work you might discard. Investigating an approach that may not pan out. If it fails in a subagent, the main context never carries the dead end.
Distinct perspectives on the same artifact. Reviewing a change for correctness, for security, and for performance are different questions. Separate contexts avoid the first answer anchoring the rest.
The pattern that unites these: high input, low output, and no need to remember how you got there.
When it is the wrong tool
This is where teams overreach, because subagents feel sophisticated.
Short tasks. Spinning up a context to read one file costs more than it saves.
Work needing the main context. A subagent starts fresh. If the task depends on the conversation so far, you either re-explain it, which defeats the purpose, or get a worse answer from a context that lacks it.
Anything where the reasoning matters. If you need to know why the agent concluded something, a mechanism that discards the intermediate steps is the wrong one.
A rule you need enforced. That is a hook. Deterministic code on an event, not an instruction another agent may interpret differently.
Knowledge the agent should have. That is a skill: domain instruction loaded on demand. See Claude Code skills for how the layers divide.
The coordination cost
Two costs get underestimated.
Instructions have to be complete. A subagent has none of your conversation. Everything it needs goes in the delegation, and the most common failure is a subagent doing competent work on a slightly wrong understanding because the brief was thin.
Results have to be integrated. Three subagents returning three findings leaves someone reconciling them, and if they disagree you need a way to decide. Parallel work is faster only when the merge is cheap.
Rule of thumb: delegate when you can describe the task completely in a paragraph and would be satisfied with a short answer. If you cannot write that paragraph, the task is not ready to delegate.
The verification case
Reviewing code is a natural fit, and worth being precise about why.
An agent that just wrote a change and then reviews it is judging its own work from the context that produced it. It knows what it meant to build, and it reads the output through that lens. It approves. This is structural rather than a model quality issue, and it is covered in can coding agents test their own code?
A subagent reviewing the same diff without the authoring context is genuinely more skeptical. It has no investment in the approach and no memory of why a shortcut seemed reasonable.
That is a real improvement and it is not sufficient. Both agents are still reading code. Neither has run the software. A silently removed rate limiter looks like a tidy-up to any reader who does not know why the line was there. See regression risk in AI-generated code.
What settles it is evidence from outside every agent's context: a real browser exercising the flow, assertions derived from what the feature was supposed to do rather than from the diff, and a durable test artifact. Shiplight provides that over MCP, and the successful check is committed to your repository so it runs on every future change rather than scrolling past. Web applications; native mobile is not in it.
Isolating context makes a reviewer more honest. Running the software is what makes a claim evidence.
Frequently Asked Questions
1
What is a subagent?
A separate context window running a delegated task, which returns its result to the main agent without returning everything it read along the way.
2
When should I use a subagent instead of just asking?
When the work involves reading a lot to produce a short answer, when several independent pieces can run at once, or when you might discard the result.
3
Subagents vs skills vs hooks?
A subagent isolates context, a skill supplies knowledge on demand, and a hook enforces a rule with deterministic code. Reach for the one matching the problem rather than the most powerful one.
4
Do subagents make code review better?
Somewhat. A reviewer without the authoring context is less likely to rubber-stamp. It is still reading code rather than running it, so it does not catch a removed safeguard.
5
What is the main cost?
Briefing and reconciliation. A subagent knows nothing of your conversation, so an incomplete instruction produces competent work on a wrong understanding.
Related Reading
- Claude Code skills: how the extension layers divide
- Claude Code agent teams: coordinating several at once
- Context engineering for coding agents: the wider discipline
- Planner, generator, evaluator: why separating roles works