futuregerald Future Code Search — Tiered Model Routing
Never use Opus for raw codebase exploration. When you need to search, explore, or read code to gather context, delegate to a cheaper model via the Agent tool. Opus stays as the orchestrator — it plans, reasons, writes code, and synthesizes results.
Routing Table
| Task | Model | When to use |
|---|---|---|
| Simple file/symbol lookup | haiku |
You know the name — just need the path or definition |
| Multi-step codebase exploration | sonnet |
Tracing flows, understanding features, exploring patterns |
| Architecture overview / broad search | sonnet |
Cross-package dependencies, high-level structure questions |
| Planning, reasoning, code writing | opus (default) |
Implementation, PR review, debugging decisions, synthesis |
How to Dispatch
Simple lookup (Haiku)
Agent({
model: "haiku",
subagent_type: "Explore",
prompt: "Find all files matching **/finding_serializer*.rb and report their paths and line counts"
})
Deep exploration (Sonnet)
Agent({
model: "sonnet",
subagent_type: "Explore",
prompt: "Trace how a finding is created: from the API controller through any interactors to the database. Report the full call chain with file paths and key method names."
})
Parallel searches (multiple agents)
When you need multiple independent pieces of context, dispatch them in parallel in a single message:
// Both in one message — they run concurrently
Agent({ model: "haiku", subagent_type: "Explore", prompt: "Find the InvoiceSerializer definition..." })
Agent({ model: "sonnet", subagent_type: "Explore", prompt: "Trace the invoice creation flow..." })
Rules
Write specific, self-contained prompts — the sub-agent has zero conversation context. Include what you're looking for, why, and what format you want the answer in.
Use Grep/Glob directly for trivial lookups — if you already know the file name or exact symbol, don't spawn an agent. Just grep for it. Agents are for multi-step exploration.
Escalate on insufficient results — if a Haiku agent returns vague or incomplete context, re-dispatch with Sonnet before trying the same tier again.
Opus reads files directly when it knows the target — if you already have the exact path and line range (from a previous search or the user), use
Readdirectly. No agent needed for targeted reads.Parallelize independent searches — if you need 3 different pieces of context, dispatch 3 agents in one message. Don't serialize them.
Include output format in the prompt — tell the agent exactly what to return: file paths, line numbers, method signatures, call chains. Structured output is easier to synthesize.
Do NOT Delegate to Cheaper Models
These tasks require Opus-level reasoning and must stay with the orchestrator:
- Code writing or editing
- Code review, security review, SQL review
- Planning or architectural reasoning
- Synthesizing results from multiple searches into a decision
- Debugging decisions (root cause analysis)
- Writing commit messages, PR descriptions, or documentation
Escalation Path
Can't find it? ──> Was it Haiku? ──yes──> Retry with Sonnet
│
no (already Sonnet)
│
v
Opus reads files directly
(fall back to manual search)
Quality Check
After receiving search results from a sub-agent, the orchestrator (Opus) should:
- Verify the results make sense given what you already know
- Check that file paths mentioned actually exist (quick Glob if uncertain)
- Read key files directly if the summary seems incomplete
- Only then proceed with planning/implementation