Most developers using Claude Code are still thinking in single-agent terms. One prompt, one agent, one task.
That's fine for simple work. But for complex projects — multiple services, parallel workstreams, large codebases — there's a better model. And most people haven't discovered it yet.
This is about sub-agents: spawning multiple Claude Code instances that work in parallel, coordinated by a lead agent. It's one of the most powerful patterns available right now, and one of the least documented.
Why single-agent falls short on complex projects
When you give Claude Code a large, multi-part task, it works sequentially. It finishes the backend, then starts the frontend, then handles the tests. This is fine, but it has a ceiling.
The bigger problem is context. A single agent working across a large codebase accumulates context as it goes. By the time it reaches the fifth service it's building, it's carrying everything from the first four. Output quality can drift. Focus narrows.
Sub-agents solve this by splitting the work. Each agent gets a specific, bounded task. Fresh context. Full focus.
How sub-agents work in Claude Code
The model is simple:
Lead agent
├── Sub-agent A: backend service
├── Sub-agent B: frontend component
├── Sub-agent C: tests and verification
└── Sub-agent D: documentation
The lead agent:
- Breaks the work into isolated units
- Spawns sub-agents for each unit
- Monitors progress
- Merges results and resolves conflicts
Each sub-agent:
- Gets a specific, self-contained task
- Works independently with its own context window
- Reports back to the lead
- Has no awareness of the other sub-agents' work
The key constraint: sub-agents work best on tasks that are logically independent. If sub-agent A's output is a dependency for sub-agent B, they can't run in parallel — they need to be sequenced.
A real example: building two new services in parallel
Here's a concrete case from a recent session building the NEXUS Ecosystem — a self-hosted Docker management suite. I needed to create two new services from scratch: Security and Notify.
They shared the same tech stack and design system but had completely independent functionality. Perfect for parallel sub-agents.
The lead agent prompt:
You are coordinating the creation of two new services for the
NEXUS Ecosystem. Spawn two sub-agents to work in parallel:
Sub-agent 1 — nexus-security:
Create a complete security monitoring service.
Reference: nexus-pulse/ as the structural template.
Accent color: #ef4444. Port: 9093.
Functionality: container scanning, exposed port detection.
[full spec...]
Sub-agent 2 — nexus-notify:
Create a complete alert routing service.
Reference: nexus-pulse/ as the structural template.
Accent color: #f97316. Port: 9094.
Functionality: channels, rules, Resend email integration.
[full spec...]
Once both complete, verify both build successfully and
integrate them into the Hub service.
Both services were built simultaneously. The lead agent then handled the integration phase — which had dependencies on both — sequentially.
Total time: 29 minutes for two complete services plus integration.
When to use sub-agents vs a single agent
This is the judgment call that matters most.
Use a single agent when:
- The task is sequential by nature (each step depends on the last)
- The codebase is small enough to fit in one context window comfortably
- You need tight coherence across all changes (design system work, refactoring)
- You're debugging — diagnosis benefits from seeing everything at once
Use sub-agents when:
- You're building multiple independent services or modules
- Different parts of the task require different expertise (backend vs frontend vs tests)
- The total work would push a single agent's context to its limits
- Speed matters and the tasks can genuinely run in parallel
The test: can you describe task A to someone without mentioning task B? If yes, they can probably run in parallel.
Structuring prompts for multi-agent work
The lead agent prompt needs more structure than a single-agent prompt. Here's the pattern that works:
## Your role
You are coordinating [project]. Your job is to:
1. Spawn sub-agents for independent workstreams
2. Verify each sub-agent's output before proceeding
3. Handle integration tasks yourself (these have cross-dependencies)
4. Report the final state
## Sub-agent 1 — [name]
Scope: [exactly what this agent builds]
Reference: [specific files to follow as templates]
Constraints: [what NOT to change]
Output: [what done looks like]
## Sub-agent 2 — [name]
Scope: [exactly what this agent builds]
Reference: [specific files to follow as templates]
Constraints: [what NOT to change]
Output: [what done looks like]
## Integration phase (lead agent, after both complete)
[tasks that depend on both sub-agents' output]
## Verification
[how to confirm everything works end-to-end]
The clearer the scope boundaries, the better the output. Vague scope = overlap = conflicts at merge time.
Handling conflicts at merge time
Sub-agents working in parallel will sometimes produce conflicting output. Common cases:
Shared files: If both sub-agents need to modify the same config file (a docker-compose, a shared constants file), don't let them both touch it. Assign shared files to the lead agent for the integration phase.
Naming collisions: Two agents creating similarly-named utilities independently. Solve this by being explicit in the scope definition: "do not create any shared utilities — those will be handled in the integration phase."
Style drift: Two agents with slightly different interpretations of the design system. Solve this with CLAUDE.md — a shared design system document that both agents read at the start of their session. One source of truth.
The CLAUDE.md role in multi-agent work
This is even more important with sub-agents than with single agents.
Each sub-agent starts with fresh context. Without a CLAUDE.md, each one will make its own assumptions about conventions, naming, style, and architecture. The outputs will technically work but feel like they were written by different teams.
With a well-written CLAUDE.md at the root of your project, every sub-agent reads the same context before starting. Design tokens, naming conventions, file structure, architectural decisions — all shared.
This is how you get coherent output from parallel agents.
Limitations to be aware of
Coordination overhead: The lead agent adds latency. For simple two-part tasks, a single agent with two sequential phases is often faster.
Context isolation cuts both ways: Sub-agents don't see each other's work, which is good for focus but bad if they need to make compatible decisions. Solve this in the prompt design, not after the fact.
Review scales with agent count: One agent produces one diff to review. Four agents produce four diffs. The productivity gain is real, but so is the review surface. Don't skip review because it feels redundant.
Not all tasks parallelize: Some work is fundamentally sequential. Auth before protected routes. Schema before queries. Forcing parallelism on sequential work creates more problems than it solves.
Summary
Sub-agents aren't a feature you turn on — they're a pattern you design for. The work is in the upfront thinking: which tasks are truly independent, where are the shared dependencies, what does done look like for each unit.
Get that right, and the execution takes care of itself.
The shift happening in 2026 isn't just about individual developers moving faster. It's about the nature of the work changing — from writing code to designing systems that write code. Sub-agents are one of the clearest examples of what that looks like in practice.
I write about self-hosted tools, Docker, and AI-assisted development.
- GitHub: github.com/Alvarito1983
- Docker Hub: hub.docker.com/u/afraguas1983
Top comments (0)