What it does
Sets explicit rules for which Claude model each subagent should use. The main conversation stays on Opus for the reasoning thread that drives correctness. Subagents default to Sonnet because most subagent work — exploration, search, test generation, file enumeration — is grunt work where Sonnet is equally capable at a fraction of the cost.
When to use it
- Any project that uses Claude Code subagents heavily
- Teams running on a budget where token spend matters
- When you want fast main-thread reasoning without paying Opus rates for every file search
- After watching subagent costs balloon during a long session
How it works
Add to your CLAUDE.md:
## Model Strategy
- Main conversation runs on Opus (default). Getting it right the first time
matters more than cost savings on the primary reasoning thread.
- Subagents use `model: "sonnet"` by default. Most subagent work is grunt
work (exploration, test generation, boilerplate, file search) where Sonnet
is equally capable and ~5x cheaper.
- Escalate a subagent to `model: "claude-opus-4-7"` only for:
- Multi-file architectural refactors
- Security/auth code review
- Complex debugging that's gone in circles
- The test suite is the safety net, not manual diff review. Always verify with
tests before marking work done.Decision matrix
| Subagent task | Default model | Why |
|---|---|---|
| Find files matching a pattern | Sonnet | Pattern matching, no judgment needed |
| Read 20 files and summarize | Sonnet | Summarization, not architecture |
| Generate boilerplate tests | Sonnet | Pattern application |
| Refactor across 8+ files | Opus | Cross-file consistency demands sharper reasoning |
| Security audit on auth code | Opus | False negatives are expensive; pay for the better detector |
| Debugging that hit 3 dead ends | Opus | Sonnet probably exhausted its angle |
| Generate one-off CRUD endpoint | Sonnet | Well-trodden path |
| Review your own diff for issues | Sonnet | Cheap second pair of eyes |
Example subagent invocation
// Cheap exploration — Sonnet
Agent({
description: "Find all API endpoints",
subagent_type: "general-purpose",
model: "sonnet",
prompt: "List every Hono route in apps/api/src/routes/ with method + path.",
});
// High-stakes review — Opus
Agent({
description: "Security review of auth changes",
subagent_type: "security-reviewer",
model: "claude-opus-4-7",
prompt:
"Review the JWT validation changes in this PR. Look specifically for ...",
});Why it matters
Token costs add up fast in agentic workflows. A typical session might spawn 10–20 subagents, each reading dozens of files. If every one of those runs on Opus, you’re paying premium rates for tasks where the model is overkill. Routing by task complexity keeps the main reasoning thread sharp and the supporting work cheap. The test suite, not the model name, is what proves correctness.