Claude Model Routing

Claude Code model routing works best when each subagent has one narrow job and an explicit model field. Put cheap, bounded repository searches on Haiku, normal implementation on Sonnet, and reserve Opus for decisions where a bad answer is more expensive than a slower one.

The model name is the easy part. Good routing also needs tight descriptions, restricted tools, small inputs, and a clear output contract. Without those, you have three expensive personalities reading the same files.

The routing rule

Anthropic's own cost guidance is blunt: Sonnet handles most coding tasks well, Opus is for complex architecture or multi-step reasoning, and simple subagent tasks can use model: haiku (Claude Code cost documentation).

Turn that into a task rule:

Use aliases when you want Claude Code to follow the current model family. Use a full model ID when reproducibility matters more than automatic upgrades. Anthropic supports both, plus inherit, in subagent frontmatter (custom subagent reference).

Do not route by file extension. A Markdown change can require an Opus-level product decision. A 20-file rename can be mechanical. Route by uncertainty, blast radius, and how easy the answer is to verify.

What Claude Code actually resolves

The model field is not always the final word. Claude Code resolves a subagent model in this order:

1. CLAUDE_CODE_SUBAGENT_MODEL, when set.
2. A model passed for that individual invocation.
3. The subagent's model frontmatter.
4. The main conversation's model.

That order is documented in the Claude Code subagent guide. It explains the most common routing bug: every agent says model: haiku, but all of them still run another model because a shell profile exports a global override.

Check before debugging your agent files:

if [[ -n "${CLAUDE_CODE_SUBAGENT_MODEL:-}" ]]; then
  printf 'Global subagent override: %s\n' "$CLAUDE_CODE_SUBAGENT_MODEL"
else
  printf 'No global subagent model override\n'
fi

If you want frontmatter to decide, remove the override from the current shell:

unset CLAUDE_CODE_SUBAGENT_MODEL

Also check organization policy. Managed availableModels settings can restrict what users and subagents may select. When a requested model is excluded, Claude Code can fall back to an inherited allowed model (model configuration documentation).

Final file tree

The complete setup uses three project subagents and one project instruction file:

.
├── CLAUDE.md
└── .claude
    └── agents
        ├── repo-scout.md
        ├── feature-builder.md
        └── risk-reviewer.md

Project subagents live in .claude/agents/. Claude watches that directory and reloads edits for later delegations. If the directory did not exist when the session started, restart Claude after creating the first file (Anthropic subagent documentation).

Haiku agent for repository scouting

The scout is read-only. It can search and inspect files, but it cannot edit them or run arbitrary shell commands. Its answer has a fixed shape so the parent receives a compact map instead of a transcript dump.

Create .claude/agents/repo-scout.md:

---
name: repo-scout
description: Maps relevant files, symbols, tests, and conventions before implementation. Use for bounded repository discovery when no edits are needed.
tools: Read, Glob, Grep
model: haiku
maxTurns: 8
---

You are a repository scout. Investigate only the delegated question.

Return:

1. Relevant files, with one sentence explaining each.
2. Existing patterns the implementation should copy.
3. Tests that cover the affected behavior.
4. Unknowns the parent must resolve.

Do not propose broad refactors. Do not edit files. Do not guess about files you did not inspect. Keep the response under 700 words.

The description matters. Claude uses it to decide when to delegate. "Helpful coding agent" is useless because it overlaps every task. "Maps relevant files before implementation" creates a clean boundary.

maxTurns is a guard, not a performance target. Eight turns are enough for a bounded search. If the scout repeatedly runs out, narrow the delegation prompt before raising the cap.

Sonnet agent for implementation

The builder owns normal feature work. It can read, edit, and run focused commands. The prompt tells it to inspect the existing pattern first, which prevents a second architecture from appearing beside the first.

Create .claude/agents/feature-builder.md:

---
name: feature-builder
description: Implements a scoped feature or bug fix after requirements and relevant files are known. Use for normal code and test changes.
tools: Read, Glob, Grep, Edit, Write, Bash
model: sonnet
permissionMode: default
maxTurns: 24
---

You are the implementation worker for a scoped change.

Before editing:

1. Read the delegated requirements.
2. Inspect the nearest existing implementation and its tests.
3. State the files you expect to change.

During implementation:

- Follow repository conventions already present in code.
- Keep the diff inside the delegated scope.
- Add or update tests for changed behavior.
- Run the narrowest relevant test after edits.
- Never change deployment, billing, secrets, or production data unless the delegation explicitly authorizes it.

Return the changed files, commands run, results, and any remaining risk. Do not claim a test passed unless you ran it and saw a successful exit.

permissionMode: default keeps the normal permission flow. A model choice should never silently become a permission choice. Anthropic warns that bypass modes can let a subagent write sensitive project configuration without a prompt, so leave them out of a general-purpose builder (subagent permission documentation).

If builders work concurrently, add isolation: worktree and partition files. A worktree gives a subagent an isolated checkout, but it does not solve two workers making incompatible designs. The parent still has to split ownership cleanly.

Opus agent for risk review

Opus should receive a small, consequential question. Sending it the whole repository "for a deep review" is not routing. It is a costly scavenger hunt.

Create .claude/agents/risk-reviewer.md:

---
name: risk-reviewer
description: Reviews a completed high-risk change for architecture, security boundaries, data integrity, or irreversible failure modes.
tools: Read, Glob, Grep, Bash
model: opus
effort: high
permissionMode: plan
maxTurns: 16
---

You are the final risk reviewer. Review the delegated diff and the smallest set of surrounding files needed to understand it.

Focus on:

- Broken trust boundaries or permission checks.
- Data loss, unsafe migrations, and non-idempotent operations.
- Race conditions and failure recovery.
- Requirements the implementation quietly skipped.
- Tests that can pass while the production behavior is still wrong.

Run read-only inspection and test commands only. Do not edit files.

Return findings ordered by severity. For each finding, include the file, the concrete failure path, and the smallest credible fix. If no blocking issue exists, say so and list the residual risks. Do not invent a finding to justify the review.

permissionMode: plan gives the reviewer read-only exploration. effort: high asks for deeper reasoning on models that support effort. The supported effort levels depend on the active model and organization policy (Claude model configuration).

There is a small trap here. A reviewer with Bash can still be noisy even in a read-oriented workflow. Keep the task prompt explicit about allowed commands, and use project permission denies for anything that must never run.

Teach the parent how to route

Claude can discover agents from their descriptions, but a short policy in CLAUDE.md makes the intended sequence harder to miss.

Add this section:

## Subagent routing

- Use repo-scout for bounded, read-only discovery before unfamiliar changes.
- Use feature-builder for scoped implementation once requirements are settled.
- Use risk-reviewer only after a completed change affects auth, billing, permissions, migrations, destructive operations, or public API compatibility.
- Pass each agent a narrow task with explicit files and acceptance criteria.
- Do not spawn agents for work the main conversation can finish with one or two direct tool calls.
- Never let two agents edit the same files concurrently.

Claude Code loads project CLAUDE.md files into the main session and most custom subagents. A subagent still begins with a fresh context window and does not inherit the conversation transcript, so the delegation must carry the actual requirements (Claude Code subagent context documentation).

That isolation is useful. The scout can read 20 files and return a 500-word map. The main conversation gets the answer without keeping every file in its own active context.

Run the routed workflow

Restart Claude if .claude/agents/ was created after the current session started:

claude --model opusplan

opusplan is a main-session hybrid. It uses Opus in plan mode and Sonnet for execution. It is separate from the model field inside each custom subagent (Anthropic model configuration).

Use a prompt with a real acceptance test:

Add a per-user API request limit.

Acceptance criteria:
- Existing authenticated routes keep their response shape.
- The limit is enforced before the handler performs work.
- A focused test covers allowed and rejected requests.
- No deployment or billing configuration changes.

First use repo-scout to map the current middleware and tests.
Then use feature-builder for the scoped implementation.
After tests pass, use risk-reviewer because this changes an authorization boundary.

Watch the sequence in /agents and inspect the transcript. The point is not that three agents ran. The point is that each received a task it could finish without rediscovering the whole project.

Test whether routing is helping

Take five tasks your repository has already solved. Pick a small bug, a normal feature, a refactor, a permission change, and a migration review. Run the baseline with one Sonnet session, then run the routed setup from the same commits.

Record:

Parallel and delegated work can multiply token usage because each worker has its own context. Anthropic explicitly warns that running multiple agents increases usage (parallel agents documentation). A Haiku scout is not cheaper if four scouts each map the same folder.

Keep routing only where it wins on the whole task. Sometimes one Sonnet session is the boring, correct answer.

Common routing failures

Every subagent runs the same model

Check CLAUDE_CODE_SUBAGENT_MODEL, per-invocation overrides, and managed model allowlists. Frontmatter is third in the documented resolution order.

The parent ignores the specialist

Tighten the specialist's description and name the agent explicitly in the prompt. Test with an @repo-scout mention before expecting automatic delegation.

The scout returns a wall of text

Give it an output schema and a word limit. Read-only does not mean concise.

The builder asks for permissions constantly

Do not jump to bypass mode. Add narrowly scoped project permission rules for commands you have reviewed, or let the main session perform sensitive operations.

Opus reviews everything

Define a trigger list. Auth, payments, data migrations, destructive actions, and public compatibility deserve the expensive lane. A CSS spacing fix does not.

For a deeper look at agent boundaries, read Claude Code subagent best practices and Claude Code model selection. If context size is driving your routing decisions, start with how to fix the Claude Code context limit.

Where the $29 Code Kit fits

The three agent files above give Claude a routing policy. They do not give you a complete product delivery loop. The $29 Code Kit is a one-time harness on top of Claude Code that connects planning, building, evaluation, browser testing, and quality gates into a repeatable workflow. There is no Code Kit subscription. Claude Code still runs on your own paid Anthropic plan, which is separate. If you only need one scout and one builder, use the files in this post. The Kit makes the same discipline repeatable across a real feature backlog.

Posted by @speedy_devv