Sub-agents in Claude Code — the orchestration pattern that works

A sub-agent in Claude Code is an agent instance fired from the main session as a Tool call (Agent(...)). It has its own context, its own tools, returns one result. After a few months I see four patterns where they pay off. Showing them.

Anatomy of a sub-agent

Call:

Agent({
  description: "Find auth middleware",
  subagent_type: "Explore",
  prompt: "Locate file containing JWT validation logic. Return path + key line numbers."
})

The sub-agent gets fresh context (system prompt + the single prompt I provided). It works, returns one message. The main session only sees that message, all deliberation is invisible.

Key intuition: the sub-agent protects your main context. It does work, returns synthesis, doesn't pollute the main session.

Pattern #1: parallel research

Most common use case. 3 independent questions about a codebase:

Agent({ description: "Find auth flow", subagent_type: "Explore", prompt: "..." })
Agent({ description: "Map RBAC roles", subagent_type: "Explore", prompt: "..." })
Agent({ description: "Audit token storage", subagent_type: "Explore", prompt: "..." })

All three in a single message → fire in parallel. 3-minute wall time instead of 9. Each returns a report under 500 words.

Pattern #2: isolating a narrow task

A test failed, the agent has to debug and fix. In the main session I'm mid-refactor, I don't want debug to clobber my context.

Agent({
  description: "Debug failing auth test",
  subagent_type: "general-purpose",
  prompt: `Test 'auth validates JWT signature' fails in CI. Logs: [paste].
           Find root cause, fix, push commit. Return summary < 200 words.`
})

The sub-agent can spend 15 minutes debugging, use 50 tool calls, run experiments. The main session sees only "fixed by changing X in Y, commit ABC123".

Pattern #3: review before merge

Sharp role separation: main session writes code, sub-agent with a dedicated subagent_type does review.

Agent({
  description: "Review my changes for silent failures",
  subagent_type: "pr-review-toolkit:silent-failure-hunter",
  prompt: `Review unstaged changes in current dir. Focus on catch blocks
           that swallow errors. Report each with path:line.`
})

The sub-agent has its own system prompt (specialist), different rules. Gives feedback the mainstream agent would give worse.

Pattern #4: bounded creative task

I have to generate 10 cold-outreach email variants. Each has to differ, all coherent in brand voice.

Without sub-agent: main session generates 10 variants, context bloats, quality drops.

With sub-agent:

// 10 independent calls
for (i in 1..10) {
  Agent({
    description: `Generate cold-outreach variant ${i}`,
    prompt: `Write variant ${i}/10 of cold-outreach email for [client].
             Brand voice: ... Hook: vary with ${variation_seed}`
  })
}

Each sub-agent gets fresh context, the same brand prompt. Generates its version. Main session collects 10 results and picks the best.

What sub-agents DO NOT do

1. They don't remember previous calls. Every run is a fresh start. To carry something between calls, git, file, database.

2. They don't modify main state outside explicit operations. File edits, yes. Memory, no (each has its own). Tasks, yes.

3. They don't know the intent behind the prompt. If you say "fix this bug", the sub-agent won't ask "but why?", it starts fixing. That's why prompts must be self-contained.

Rules for writing sub-agent prompts

Most important: brief like a smart colleague who just walked into the room.

✅ "Audit migration 0042_user_schema.sql for safety. Context: adding NOT NULL column to 50M-row table with default backfill. I want a second opinion on backfill safety under concurrent writes. Report: safe yes/no, what breaks if not."

❌ "Check the migration."

The first gives the agent a goal, context, expected format. The second returns generic feedback.

Costing

Sub-agent = separate Claude API session. You pay separately for its context + outputs. 3 parallel sub-agents = 3× token cost.

Rules:

• One sub-agent = ok for any non-trivial narrow task
• 3 in parallel = ok for research/exploration

• 5 in parallel = sign that the prompt design is poorly partitioned

In my billing sub-agents are ~30% of monthly Claude Code cost. Worth it for main-context protection.

When NOT to use

1. When the task needs continuous feedback from you. Sub-agent returns one message, no dialogue. UI iteration = nope.

2. When the task is trivial. "Change button color from red to green", main session in 5 seconds, sub-agent in 20.

3. When you want to learn by watching. Sub-agent hides deliberation. If you're debugging something for the first time and want to see the chain of thought, main session.

Sub-agents aren't sci-fi orchestration. They're the simple "outsource one task to protect main context" pattern. Used without ceremony on every explore and every bounded debug, measurable savings. Try, use naturally, measure.