Sub-Agent Routing

Problem: Your main Claude Code session spawns sub-agents all day. It has no built-in sense of when to run them side by side, when to chain them, or when to push them into the background. With no routing rules in CLAUDE.md, it just picks one. It often picks wrong.

Quick Win: Drop this routing block into your CLAUDE.md:

## Sub-Agent Routing Rules
 
**Parallel dispatch** (ALL conditions must be met):
 
- 3+ unrelated tasks or independent domains
- No shared state between tasks
- Clear file boundaries with no overlap
 
**Sequential dispatch** (ANY condition triggers):
 
- Tasks have dependencies (B needs output from A)
- Shared files or state (merge conflict risk)
- Unclear scope (need to understand before proceeding)
 
**Background dispatch**:
 
- Research or analysis tasks (not file modifications)
- Results aren't blocking your current work

Your main thread reads the block and starts making smarter handoffs on its own.

Your Main Thread Is the Router

Here's the piece most people miss. Claude Code is not one model. It's a small crew, and your main chat is the lead. That lead hands work to specialist sub-agents. Everything downstream only works as well as you've taught the lead to hand out jobs.

Three execution modes exist on the Task tool. Each fits a different shape of work:

Skip the rules and your lead falls back on slow, careful, one-at-a-time execution. Safe. Also slow.

Parallel: Split by Domain

Parallel dispatch fits work that spans separate corners of the codebase. Put the domain map in CLAUDE.md so the lead knows where the lines are:

## Domain Parallel Patterns
 
When implementing features across domains, spawn parallel agents:
 
- **Frontend agent**: React components, UI state, forms
- **Backend agent**: API routes, server actions, business logic
- **Database agent**: Schema, migrations, queries
 
Each agent owns their domain. No file overlap.

The hard rule: parallel only holds when agents touch different files. Your lead has to see those domain edges to split work cleanly.

Sequential: Chains That Depend on Each Other

Some work only makes sense in order. Step two needs what step one produced. The lead has to hold that line.

List your common chains in CLAUDE.md. That way the lead spots them and stops trying to run a chain in parallel.

Background: Research That Doesn't Block You

Research-shaped tasks should drop into the background on their own, so you can keep working. Hit Ctrl+B during any sub-agent run, or set the rule up front:

## Background Execution Rules
 
Run in background automatically:
 
- Web research and documentation lookups
- Codebase exploration and analysis
- Security audits and performance profiling
- Any task where results aren't immediately needed

Run /tasks whenever you want to peek at what's running. Results float up when the agent is done. The async workflows guide has the long version.

Configuring Sub-Agent Behavior

Routing is one layer. Claude Code also hands you direct knobs for how sub-agents behave.

Pick the Sub-Agent Model

CLAUDE_CODE_SUBAGENT_MODEL tells Claude Code which model to boot for sub-agents. This single variable moves the cost and speed dial more than almost anything else:

# Use a lighter model for sub-agents to save tokens
export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-5-20250929"

A clean split: Opus on the main thread for the hard thinking, Sonnet on the sub-agents for focused follow-up work. Token spend drops and the work still lands, because each sub-agent job is already well-scoped.

Pin Specialists in .claude/agents/

Instead of spinning up new Task calls every time, keep named specialists as Markdown files with YAML frontmatter in .claude/agents/. Claude's orchestrator finds them on its own.

.claude/agents/ holds project agents that live with the repo and ship to your team. ~/.claude/agents/ holds user agents that follow you across every project.

Agents here inherit your CLAUDE.md, so they show up already knowing your conventions, coding rules, and project quirks.

Lock Down Agents With Permission Rules

Task(AgentName) rules in your permissions file decide which sub-agents are allowed to run at all:

{
  "permissions": {
    "deny": ["Task(Explore)", "Task(Plan)"]
  }
}

The --disallowedTools flag does the same thing at launch:

claude --disallowedTools "Task(Explore)"

Handy for keeping token spend tight, or for locking autonomous exploration out of a production repo.

Bad Invocations Are the Real Bug

Most sub-agent trouble is not execution. It's the invocation that kicked it off. The lead sends a sub-agent in with fuzzy instructions, missing context, and no clear finish line. The sub-agent does what it can with what it got.

Bad invocation: "Fix authentication"

Good invocation: "Fix OAuth redirect loop where successful login redirects to /login instead of /dashboard. Reference the auth middleware in src/lib/auth.ts."

The gap is context. Sub-agents run in their own short-lived window. They cannot come back mid-run and ask what you meant. Your lead needs hard rules for writing full invocations the first time.

This is where many CLAUDE.md files stop. Routing gets handled. Invocation quality does not. A solid setup covers both: every dispatch carries full context, clear instructions, linked files, and a concrete definition of done.

Common Orchestration Mistakes

Over-parallelizing: Ten parallel agents for a small feature burns tokens and adds coordination work. Group small, related tasks into one agent.

Under-parallelizing: Four independent passes running back to back when they could have run at once. Look for domain independence.

Vague invocations: "Implement the feature" with no scope, no files, no expected output.

Where to Go Next

Those routing rules alone will sharpen how your lead hands out work. There's more pro-level orchestration on top of that:

• Constitutional invocation requirements that force every dispatch to carry the four core pieces
• Agent routing tables that map task types to specialist agents
• Context handoff protocols that carry state through a sequential chain
• Session-based coordination for tracking multi-step work

Start with the routing rules. Paste them into CLAUDE.md today. The lead will pick better lanes tomorrow. For deeper patterns, read up on task distribution and agent fundamentals.