Subagents: stop putting all the work into one context
- date
- category
- AI Agents
- also in
- AI Engineering · Automation · Engineering Practices
- reading
- 4 min / 784 words
We already have a very capable Claude.
It can:
- work in the repository,
- use project context,
- get additional information,
- use tools and MCP,
- execute repeatable skills.
The natural next step is giving it larger and larger tasks:
Analyze the requirements, find the place to change, implement the feature, add tests, review and fix all problems.
This is possible.
But everything happens in one context window.
One context starts having several problems
1. The amount of information grows
Research, implementation, test results, earlier mistakes and fixes stay in the history of the same session.
The longer the task, the more noise.
2. Roles start mixing
The same agent:
- designed the solution,
- implemented it,
- now has to independently evaluate its own implementation.
Technically it can find bugs.
But review makes more sense when it gets a fresh context focused on evaluating the result, not the whole history of how the result was reached.
3. Part of the work is independent
Research of several modules or analysis of several possible problems can be done in parallel.
There is no reason to keep everything in one thread.
A subagent is primarily a separate context
The worst introduction to multi-agent systems sounds like this:
We will create a team of agents: a senior engineer, a product manager and an architect.
At the start, you do not need an "AI company".
You need a simpler model:
A subagent is a separate work instance with its own context, delegated a specific task.
Main Claude can say:
reviewer:
analyze this diff and find blocking issues
The reviewer does not need the whole implementation history.
It needs:
- requirements,
- diff,
- project rules,
- review instructions.
Fresh context is a feature
Imagine a task:
main Claude:
- read 40 files,
- tried two approaches,
- got 5 failing tests,
- fixed the implementation,
- changed the plan.
After a few dozen minutes you ask:
Now do an independent review.
In the same context window, the word "independent" is somewhat aspirational.
A subagent can start from:
requirements
+ final diff
+ project rules
+ review instructions
Without the whole implementation baggage.
This is one of the most important reasons to use subagents.
Not parallelism.
Context isolation.
Minimal setup: reviewer and tester
Do not start with eight roles.
At the beginning, two are enough.
.claude/
+-- agents/
+-- reviewer.md
+-- tester.md
Reviewer
Responsibility:
- read the result,
- find problems,
- do not fix them.
Example contract:
Review the change independently.
Focus on:
- correctness
- regressions
- error handling
- security
- unnecessary complexity
Do not edit code.
Return:
- blocking findings
- important findings
- suggestions
Tester
Responsibility:
- evaluate verification,
- find missing cases,
- run or propose relevant tests.
Verify the implemented behavior.
Check:
- existing test coverage
- missing edge cases
- integration impact
Do not redesign the implementation unless verification requires it.
What does the task look like after leveling up?
Before:
Claude
-> implement
-> test
-> review itself
-> fix
After:
main Claude
-> implement
reviewer -> findings
tester -> findings
findings
-> main Claude
-> fix
Reviewer and tester can be run independently if they do not need each other's results.
Dynamic subagent vs your own definition
Claude can delegate a one-off task to a subagent without creating a permanent role.
This is good for something like:
Analyze this module and return the public API and change risks.
But when a role repeats in the SDLC:
reviewer
tester
security-reviewer
it is worth defining it explicitly.
That gives you:
- stable instructions,
- control over responsibility,
- repeatable results,
- the ability to iteratively improve the role.
When not to use a subagent?
A subagent is not automatically "better".
Do not delegate:
find the function name in the repository
if main Claude can grep.
Do not delegate a simple:
run the test
if it is a single tool call.
A subagent has a cost:
- separate context,
- additional calls,
- the need to pass a task and receive a result.
Use it when at least one of these is true:
I need fresh context
I need independent evaluation
the task is clearly separated
the work can be meaningfully parallelized
What does this change in SDLC?
Implementation + review
The most obvious upgrade.
Author and reviewer stop being the same context.
Research
Several independent parts of the system can be analyzed separately.
Testing
Verification can be performed without the whole implementation history.
Incident analysis
One subagent analyzes logs, another deployment history, a third relevant code, and the main agent synthesizes results.
Not every task requires multi-agent work.
The point is a conscious split of responsibilities where it provides real value.
Implement this today
1. Create reviewer
It should:
- not edit code,
- return findings,
- have explicit review criteria.
2. Create tester
It should:
- evaluate verification,
- find missing cases,
- focus on behavior, not implementation history.
3. Use them on the next larger task
Sequence:
main -> implementation
reviewer -> review
tester -> verification
main -> fixes
4. Do not create more agents without need
Add the next role only when you can say:
This part of the work needs a separate context.
Level complete
The level is complete if implementation and at least one independent verification no longer happen in the same context window.
At the next level, another problem appears: even with subagents, we can still rely on the main LLM remembering which one to run later and which steps are still left.