06 - Subagents and Parallel Work

🎁 What if the tedious part of a task, reading twelve files to find where a function is used, could happen without ever cluttering your main conversation?

Claude Code can hand work to subagents: separate helpers that go off, do a job, and report back just the answer. Used well, they make big tasks faster and keep your main thread focused. Used badly, they add cost and confusion. This lesson is about the difference.

What Subagents Are

A subagent is a fresh Claude instance spawned to handle one sub-task. It gets its own context window, does the work, and returns a result to the main agent, not the raw pile of files it read to get there.

You: "Find every place we call the old `sendEmail()` helper and
      list the files and line numbers. Don't change anything yet."

→ A subagent greps the repo, reads matches, and returns:
  "12 call sites across 5 files: notifications.ts:44, billing.ts:88, ..."

The main thread never sees the twelve files. It gets the conclusion. That's the whole point.

Automatic vs Manual Delegation

Claude spawns subagents on its own. When a task looks big, independent, and read-heavy, it reaches for its built-in Task tool and delegates without being asked. That's why you sometimes see it fan out mid-task: it judged the reading wasn't worth cluttering your main thread.

You can also trigger delegation yourself. The simplest way is to say so in your prompt.

"Use a subagent to find every call site of sendEmail().
 Spawn one agent per service and review them in parallel."

For work you repeat, define a custom subagent as a markdown file in .claude/agents/. It gets a name, a description, and its own set of tools.

---
name: test-runner
description: Runs the test suite and reports failures. Use after code changes.
tools: Bash, Read, Grep
---

Run the test suite. Report only the failing tests with the
assertion and the file and line number. Nothing else.

The description line is the part that controls automation. Claude reads it to decide when to reach for this agent on its own, so "Use after code changes" makes it fire automatically once you edit code. Word it broadly and Claude delegates often. Word it narrowly and it waits until you name the agent.

So that's the boundary. Automatic delegation is Claude's own judgment plus how you wrote the description. Manual delegation is naming the agent in your prompt. Manage these files with the /agents command.

Fan-Out vs Serial

Fan out when the work is independent: many files to summarize, several modules to audit, a batch of searches with no dependency between them. Each subagent runs its own slice.

"Review these three services for missing error handling, one subagent
 each: cmd/api, cmd/worker, cmd/scheduler. Report issues per service."

Keep it serial when each step depends on the last. You can't parallelize "find the bug, then fix it, then verify the fix", those are a chain. Fanning out a chain just produces three confused helpers stepping on each other.

Delegating Searches and Reads

Broad exploration is the ideal thing to delegate. "Where does auth happen?" or "how is config loaded?" means reading a lot to answer a little. Send that to a subagent and keep only the map it returns.

"Explore how request authentication flows through this codebase.
 Return a short summary: entry points, middleware, where the token
 is validated. I don't need the full file contents."

You get the architecture back in a paragraph instead of burning your main context on ten files you'll never look at again.

Keeping the Main Thread Clean

Your main context window is finite. Every file dump, every long log, every search result competes for space with the actual task. Subagents are a pressure valve: the noisy reading happens in their context, and yours stays lean.

Main thread stays about: "implement the new rate limiter"
Subagent absorbs: reading the existing middleware, the config
  loader, and three similar limiters elsewhere in the repo

A clean main thread means Claude keeps track of what you actually asked for instead of drowning in reference material.

Costs of Delegation

Subagents aren't free. Each one has startup overhead, and it can't see your live conversation, so it only knows what you put in its instructions. Delegate a vague task and you get a vague answer, with no shared context to fall back on.

❌ "Go look into the payments thing."
   (subagent has no idea what "the payments thing" means)

✅ "Read internal/payments/*.go and list every function that
   touches the Stripe client. Return name + file + one-line purpose."

Don't delegate work you could do in one read. Reach for subagents when the reading is large, independent, or would otherwise flood your main thread, not for every little lookup.

Key Takeaways

• A subagent is a separate helper with its own context that returns a result, not its raw work
• Fan out for independent work (many files, many searches); keep dependent steps serial
• Delegating broad exploration keeps only the conclusion in your main thread
• Subagents protect your main context window from large file and log dumps
• Each subagent has setup cost and can't see your live conversation, so give it complete instructions
• Don't over-delegate: a single quick read doesn't need a subagent

🎁 What if you never had to remember to run the tests after an edit, because Claude ran them for you every single time, automatically?