Lesson 35: Subagents: Divide and Conquer

Day 35 of 50 · ~7 min read · Phase 5: Advanced Patterns

The Opening Question

Imagine you need Claude Code to do three things:

1. Review your entire codebase for security issues
2. Write tests for an untested module
3. Document the API endpoints

These are all useful, but they're also big tasks. Each one could consume your entire context window. Do them in sequence, and you've used up your token budget before you even get to your actual work.

Here's the question: what if Claude could split itself into three different versions, all working in parallel, on different problems, with their own context windows?

This isn't sci-fi. It's a real feature in Claude Code called subagents.

Discovery

Question 1: What happens when you run out of context?

Let's think about a real constraint. Claude has a finite context window (currently ~200K tokens). That sounds like a lot until you realize:

• Reading a 10,000-line codebase: ~30K tokens
• Adding test files: ~10K tokens
• Maintaining conversation history: ~20K tokens
• Room to reason and respond: ~50K tokens

And you've just consumed your budget. Now if you ask Claude to do something else, you have to forget context to make room for new information.

But what if you could say: "Claude, spawn a worker to review security. Don't involve me. Just summarize the findings and come back to me when it's done."

That worker gets a fresh context window. It does the job. You get a summary. Main context is still available for your next task.

Pause and think: why would parallelism matter even if you're just one person?

Question 2: What exactly is a subagent?

A subagent is a separate Claude Code session that runs with these properties:

• Isolated context: Its own context window, not shared with the main session
• Autonomous: Works without needing you to watch or prompt repeatedly
• Summarization: Returns results back to the main session in compressed form
• Time-bounded: Can work while you're doing something else

Here's what a subagent flow looks like:

Main session: "Review this codebase for SQL injection vulnerabilities"

Claude spawns a subagent to:
  - Read all database query code
  - Check for parameterized queries
  - Identify risky patterns
  - Compile a report

[Subagent works...]

After 2-3 minutes: Subagent returns:
  "Found 3 potential SQL injection risks in auth.js (line 42, 67, 103).
   All other queries are properly parameterized."

Main session can now act on this summary without losing context.

Question 3: When should you use a subagent instead of doing it yourself?

There are clear use cases:

Good for subagents:

• Code review (independent evaluation)
• Research across the codebase (security, performance, style)
• Bulk operations (refactoring a pattern across many files)
• Testing coverage analysis (finding untested functions)
• Documentation generation (building comprehensive docs)

Not ideal for subagents:

• Decisions that need human judgment
• Tasks that depend on your real-time feedback
• Anything where you need to watch progress (it's less interactive)

The key question: Can the task be completed autonomously, with a summary at the end? If yes, subagent. If you need back-and-forth conversation, main session.

Question 4: What's the tradeoff?

Subagents are powerful, but they're not free:

Advantages:

• Parallel work (things happen at the same time)
• Fresh context (no bloat from main session)
• Summaries (compressed results, don't pollute main context)
• Autonomy (you don't have to manage them step-by-step)

Disadvantages:

• Loss of details (summaries can miss nuance)
• No real-time course correction (subagent runs to completion)
• More complex to set up
• Not every task benefits (small tasks don't justify the overhead)

The Insight

Subagents are how you scale Claude Code's work beyond the constraints of a single context window. They let you parallelize independent tasks, keep main context clean, and get summaries instead of raw output. The tradeoff is autonomy for detail — subagent results are compressed, not exhaustive.

The mental model: Subagents are like delegating to interns. You don't manage every step. You give them the task, they work independently, and they bring you a summary at the end. You trust them to be thorough, but you don't need to watch.

Try It

Let's spawn a subagent to analyze your current codebase.

1. In Claude Code, use the Agent tool to spawn a subagent:

   I need a security review of my codebase. 
   
   Can you spawn a subagent to:
   1. Read all .js files in src/
   2. Look for common security issues (eval, innerHTML, etc.)
   3. Report findings in a summary
   

2. Watch what happens: Claude will create a new session (a subagent) that works independently. It will appear in your session list.

3. The subagent will:

   • Read your codebase
   • Analyze it
   • Compile a report
   • Return results to main session

4. You'll see in main session:

   "Subagent completed. Found [N] security issues. Summary: ..."

5. Review the summary and decide next steps without your context being consumed by the deep analysis.

Key Concepts Introduced

Bridge to Lesson 36

You've now learned to scale work horizontally (subagents) and keep it consistent (hooks), test it (testing), and debug it holistically (debugging).

But all of this assumes you're there, watching, prompting. What if you're not?

Tomorrow's question: What happens when Claude Code runs without a human in the loop?

We'll explore headless mode and CI/CD integration — where Claude works on your codebase automatically, and you just check the results.

← Back to Curriculum · Lesson 36 →