One giant agent session looks productive until it collapses. Too many file reads, too many failed attempts, too much stale intent in one thread.
I get better results with sub-agents. Each one gets a narrow scope, short runtime, and explicit output format.
Main agent as scheduler
The primary agent should coordinate, not do everything. It delegates search, refactor prep, or test analysis to smaller workers.
This keeps the main context window clean. It also lowers the chance of hallucination from old noise.
Where sub-agents help most
- Large codebase search and summarization.
- Test failure triage with exact repro notes.
- Migration prep where one module at a time is safer.
- Documentation extraction from many files.
These tasks create big token footprints. Isolation keeps that load out of the main flow.
Isolation rules I use
Give each sub-agent one question. One output contract. One stop condition. No open-ended "go explore." That is how sessions stay fast.
I also merge only verified outputs back into the main thread. Otherwise you import context poisoning from failed runs.
The payoff
You get fewer surprises, cleaner diffs, and easier review. The big win is not speed. It is predictability.
Context isolation feels like overhead at first. After a week, it feels like basic safety.