A subagent router is the thing that decides which subagent handles what. Most teams don't design theirs explicitly — they add subagents one at a time, and the routing that emerges is whatever Claude does by default. This works fine until you have five or ten subagents; then it stops working and you get the wrong subagent for the wrong task. This guide is about designing the router explicitly.
What a router is
Claude Code's subagent system works like this: you register subagents (each with a name, description, tools, prompt); when a task comes in, Claude picks a subagent based on which one seems most appropriate. The picking is the routing.
The router isn't a separate component you install. It's an emergent property of how you write your subagent descriptions and how Claude interprets them. Design the descriptions well, and routing works; design them poorly, and routing feels random.
Three types of routing exist in practice: implicit (Claude picks based on task keywords), explicit (developer names the subagent to use), and orchestrator (a master subagent that picks other subagents). Each has a fit.
Why routing matters
Bad routing feels like this: you ask Claude to write a Postgres query; instead of using your postgres-dba subagent, Claude writes the query from scratch. Or you ask for security review; instead of using your security-reviewer, Claude gives generic advice.
Two root causes. Either the subagent description doesn't match the task language (the subagent exists but Claude didn't identify it as relevant), or two subagents both match and Claude picked the wrong one.
Both are description problems. Fixing them means being explicit about when each subagent should be used.
The three router patterns
Three patterns, in order of complexity:
Implicit routing. No explicit routing logic. Each subagent has a description; Claude picks based on task match. Works for small teams with few subagents (fewer than 10).
Explicit routing. Developers specify the subagent in their prompt: "use the postgres-dba subagent to write this query." Bypasses ambiguity but requires developers to remember the subagent names.
Orchestrator routing. A master subagent (often called orchestrator or router) receives the task, decides which specialist subagent should handle it, hands off. Adds layer but scales to many specialists.
Most teams should start with implicit and stay there until they have 10+ subagents. At that scale, orchestrator becomes worth the complexity. Explicit routing is always available as override, regardless of primary pattern.
1. Implicit routing
Implicit routing depends entirely on subagent descriptions. Claude reads the descriptions and matches against the task.
The description shape that works:
Two important pieces. First, the description says what the subagent does. Second, "Use PROACTIVELY" tells Claude when to route to it. Without "PROACTIVELY," Claude often waits for explicit invocation; with it, Claude self-routes when relevant.
The description language matters. If your subagent's description says "database specialist" but developers say "SQL" in their prompts, Claude might not connect them. Match the language your team uses.
2. Explicit routing
Explicit routing is developer-driven: they specify which subagent in the prompt.
"Use the postgres-dba subagent to write a query for daily active users."
Advantage: unambiguous. Disadvantage: developers must remember subagent names.
Best pattern: implicit as default, explicit as override. Developers rely on implicit routing for common cases; use explicit when they know which subagent they want or when implicit has picked wrong before.
Explicit is also how you test routing. If you're evaluating whether a subagent's description works for implicit routing, first prompt without explicit invocation and see what Claude does; then try explicit invocation to compare. Discrepancy = description needs work.
3. Orchestrator routing
Orchestrator routing adds a master subagent whose job is picking other subagents. Task flow:
- Developer prompts (or Claude invokes orchestrator).
- Orchestrator reads task; identifies which specialist should handle it.
- Orchestrator invokes specialist with appropriate context.
- Specialist does the work; returns result.
- Orchestrator formats and returns to developer.
Example orchestrator description:
Two costs of orchestrator: extra latency (one more Claude round-trip) and extra cost (orchestrator uses tokens). Benefits: consistent routing across the team; explicit routing logic that's reviewable in git; ability to invoke multiple specialists for complex tasks.
Worth it at 10+ subagents. Not worth it at 5.
Designing your router
Whichever pattern, three steps:
1. List your subagents. Names, current descriptions.
2. For each pair of subagents, identify boundary conditions. When could a task go to either? Write down the deciding factor. E.g., "unit-test-writer vs. e2e-test-writer: deciding factor is test level (single unit vs. user journey)."
3. Update descriptions to make boundaries explicit. The description for unit-test-writer should say "for unit-level tests" and mention the deciding factor.
Reviewing this exercise typically reveals two-three ambiguities that were previously invisible.
The writing of descriptions
Rules for descriptions that route well:
Rule 1: State when to use PROACTIVELY. Without this, Claude waits for explicit invocation. With it, Claude self-routes.
Rule 2: Match the language your team uses. If team says "SQL" more than "database," description says SQL.
Rule 3: Explicitly exclude adjacent responsibilities. "For unit tests; NOT for E2E or integration tests." Explicit boundaries reduce mis-routing.
Rule 4: Name specific tools or frameworks. "postgres-dba (not MySQL, not MongoDB)" — helps Claude route by tech stack, not just domain.
Rule 5: Include "first step, always" in the prompt. Distinguishes subagents that would otherwise sound similar. postgres-dba's first step is EXPLAIN ANALYZE; database-migration-planner's first step is schema diff. Both databases; different first steps clarify which one is right for which task.
Handling ambiguity
Some tasks are genuinely ambiguous. "Add authentication to the API" could route to security-reviewer (for approach review), backend framework specialist (for implementation), or architect-reviewer (for high-level design).
Two options:
Option 1: Orchestrator handles. Orchestrator invokes multiple specialists in sequence; coordinates output. Higher cost but produces multi-perspective answer.
Option 2: Ask for clarification. Orchestrator (or Claude, in implicit mode) asks the developer: "this could be architectural design or implementation work — which do you need?" Adds a round-trip but produces the right specialist.
Both are valid. For fast iterative work, option 2 is better (avoid multi-specialist cost). For thorough investigation, option 1 is better (multi-perspective).
Measuring router quality
Two metrics worth tracking:
Right-subagent rate. When developers use implicit routing, what percentage of the time does Claude pick the "correct" subagent (as judged by the developer)? Track by asking developers occasionally: "did the right subagent handle that?" Aggregate over a week.
Ambiguity rate. How often does routing hit an ambiguity that requires clarification or manual override? Track by counting explicit-invocation prompts vs. implicit ones.
Rough targets: right-subagent rate above 80%; ambiguity rate below 20%. Below these, iterate on descriptions.
What to do next
- List your team's current subagents.
- For each pair, identify boundary conditions.
- Update descriptions per the five rules.
- Deploy and observe routing quality over one week.
- Iterate on descriptions where routing is wrong.
- If you have 10+ subagents, add an orchestrator.
A well-designed router makes subagents feel invisible — you write a natural prompt, the right specialist handles it. A poorly-designed router makes them feel like a maze — you can't remember which subagent to use and Claude keeps picking wrong. The difference is 4-6 hours of description work upfront.
Cost Optimization for Claude Code at Scale
30 min read