DEV Community

diggidydale
diggidydale

Posted on

Escaping the Dumbzone, Part 2: Subagents — Divide and Conquer

#agents #architecture #ai #llm

Part 2 of 4 in the "Escaping the Dumbzone" series

In Part 1, we covered why your AI gets dumber as context fills up. The "Lost in the Middle" problem, the MCP tool tax, the ~75k token smart zone.

Now let's fix it.

The most powerful technique for staying out of the Dumbzone is deceptively simple: don't put everything in one context.

What Are Subagents?

Subagents are specialised AI assistants that run in their own isolated context windows. Instead of one agent doing everything in one giant context, you spawn focused agents for specific tasks.

When Claude needs to research something, it spawns a subagent. The subagent investigates in its own space, reading files, running searches, hitting dead ends. Then it returns just the answer. Not the whole investigation. Just the insight.

Subagent Context Isolation

The key insight: your main context receives 30 tokens of insight instead of 30,000 tokens of investigation.

A Real Example

You're debugging why authentication fails intermittently in production.

Without Subagents

Your main context accumulates everything:

- Read AuthService.java (500 tokens)
- Read SessionRepository.java (400 tokens)
- Search for "token" (200 tokens)
- Read JwtTokenProvider.java (600 tokens)
- Hmm, that wasn't it
- Search for "expire" (150 tokens)
- Read RedisSessionStore.java (450 tokens)
- Dead end, try something else
- Read 5 more files...
- Finally found it
Enter fullscreen mode Exit fullscreen mode

Total added to your main context: ~30,000 tokens

You found the bug, but you've burned a huge chunk of context on the journey. Now you have less room for actually fixing it.

With Subagents

Your main context stays clean:

You: "Investigate why auth fails intermittently in production"

[Subagent spawns, does all the investigation in its own context]

Subagent returns: "Typo in SessionRepository.java:156:
`getUsrSession()` instead of `getUserSession()`.
The fallback method silently returns null when the
primary lookup fails, causing intermittent auth
failures under load."
Enter fullscreen mode Exit fullscreen mode

Total added to your main context: ~50 tokens

Same answer. 600x less context consumed.

Built-in Subagents

Claude Code comes with several subagents already:

Subagent What It Does Tools It Gets
Explore Fast codebase searching and analysis Read-only (Glob, Grep, Read)
Plan Research during planning mode Analysis tools only
General-purpose Complex multi-step tasks Everything

The Explore agent is your workhorse. Use it any time you need to understand something in the codebase. It can read files, search code, and analyse patterns, but it can't edit anything. Perfect for investigation.

Creating Custom Subagents

Want a subagent for your specific needs? Drop a markdown file in .claude/agents/:

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools:
  - Read
  - Grep
  - Glob
---

You're a security-focused code reviewer.
Find OWASP Top 10 vulnerabilities.

## What to Look For
- SQL injection
- XSS vulnerabilities
- Auth/authz flaws
- Sensitive data exposure

## Return Format
A structured report with:
- Severity (Critical/High/Medium/Low)
- Location (file:line)
- What's wrong
- How to fix it
Enter fullscreen mode Exit fullscreen mode

That's it. Claude will now spawn this subagent when security review makes sense. The subagent runs in its own context, follows its own rules, and returns a concise report.

Custom Subagent Definition

Subagent Best Practices

1. Scope Tools Intentionally

The tools field in the frontmatter controls what the subagent can do:

tools:
  - Read    # Can read files
  - Grep    # Can search content
  - Glob    # Can find files
  # No Edit, Write, or Bash — read-only
Enter fullscreen mode Exit fullscreen mode

Read-heavy agents (research, review, analysis) shouldn't have write access. Implementation agents need Edit/Write/Bash.

If you omit the tools field entirely, the subagent gets access to everything. Be intentional.

2. Define Clear Completion Criteria

Each subagent should know exactly what "done" looks like:

## Definition of Done
Return when you have:
- [ ] Identified the root cause
- [ ] Found the specific file and line
- [ ] Confirmed with evidence (error message, stack trace, etc.)
- [ ] Suggested a fix
Enter fullscreen mode Exit fullscreen mode

Vague instructions = vague results = wasted context.

3. Use Parallel Execution

Subagents can run simultaneously. Researching options for a decision?

Spawn three subagents in parallel:
- "Research Kia Ceed for fleet use"
- "Research Hyundai Kona for fleet use"
- "Research Toyota Yaris for fleet use"
Enter fullscreen mode Exit fullscreen mode

Three investigations, three separate contexts, results merge into your main context. Way faster than sequential research, and your main context only receives the summaries.

Parallel Subagent Execution

4. Watch the Cost

Here's the tradeoff: each subagent is a separate API call. Chaining lots of subagents multiplies your token usage.

For simple tasks, the overhead isn't worth it. For complex investigations? The context savings are massive.

Rule of thumb: if the investigation would add more than ~1000 tokens to your main context, consider a subagent.

When to Use Subagents

Good fit:

  • Codebase exploration ("How does auth work here?")
  • Bug investigation ("Why is this failing?")
  • Research tasks ("What patterns does this codebase use?")
  • Security/quality review
  • Comparing options

Skip it:

  • Simple, focused tasks
  • When you already know where to look
  • Quick one-file fixes
  • When you need the full context for a decision

Don't overcomplicate simple work. The overhead isn't worth it.

The Explore Subagent in Action

Claude Code's built-in Explore agent is incredibly useful. Here's how to leverage it:

Instead of:

"Read AuthService.java, then read SessionRepository.java, then search for token validation..."
Enter fullscreen mode Exit fullscreen mode

Try:

"Use the Explore agent to understand how authentication
works in this codebase, particularly session management
and token validation."
Enter fullscreen mode Exit fullscreen mode

The Explore agent will:

  1. Search for relevant files
  2. Read and analyse them
  3. Follow the code paths
  4. Return a coherent summary

Your main context gets the summary. The exploration stays isolated.

Key Takeaways

  1. Subagents = isolated context — Investigation happens separately, only insights return
  2. 30 tokens vs 30,000 — That's the difference between insight and investigation log
  3. Scope tools intentionally — Read-only for research, full access for implementation
  4. Define done clearly — Vague instructions waste context on both sides
  5. Parallelise when possible — Multiple subagents can run simultaneously
  6. Mind the cost — Each subagent is an API call; use for complex tasks

Further Reading

Top comments (0)