🎚️ Model by task

Think of a auto repair shop. You don't call the chief engineer to change a tire — you send the assistant; it's quick and cheap. To rebuild the engine, that's when the master steps in. AI models work the same way: there's a low tier (fast, cheap, great for grunt work), a mid tier (the competent worker who builds and reviews) and a high tier (the master you only call on when the problem requires real reasoning). In Claude Code, these three are Haiku, Sonnet e Opus — and each subagent can run its own.

↑ The tier ladder: each step up adds reasoning power, but costs more and increases latency. Go only as high as the task requires.

Haiku is the tier cheap and fast. It shines at high-volume mechanical work: scan an entire folder, search a string across hundreds of files, summarize a huge log, read documentation and return the 5 points that matter. Tasks where the answer is “find and report,” not “think deeply.”

Sonnet is the tier medium — the workhorse for day-to-day use. It builds (writes code, creates files, implements a step in a plan) and reviews (reads a diff and points out bugs). It’s smart enough for most real-world tasks and still much cheaper than the high tier. When you’re unsure, Sonnet is usually the safe default.

Opus is the tier expensive and slower, reserved for what truly requires deep reasoning: decisions about architecture, analysis of security, careful planning, debugging a problem no one understands. Here, the extra cost pays off: an architecture mistake costs far more than a few extra tokens.

Moving up a tier isn’t just “getting smarter.” They’re three dials that move together: more reasoning comes with more cost and more latency (takes longer to respond). Choosing a model means deciding of each one the precise task — and stop paying for what it doesn’t use.

Here’s the detail that catches many people. The subagent doesn't inherit your conversation — it starts from scratch, with an empty window. Before producing anything, it needs to gather the context on its own: read the files, understand the terrain. This changes the calculation: part of its work is just “getting oriented,” and that reading work is exactly what a low-cost tier does well.

# o maestro já conversou com você por 1h.
# o subagente NÃO sabe nada disso. ele nasce assim:

contexto: (vazio)
tarefa:   "ache onde o login quebra nos 40 arquivos de /auth"

# 1º ele GASTA tokens só pra se situar:
#   - lista a pasta /auth
#   - abre os 40 arquivos
#   - mapeia o fluxo de login
# SÓ DEPOIS ele começa a raciocinar sobre o bug.

# lição: essa fase de "reunir contexto" é leitura bruta
# → é trabalho de Haiku, não de Opus.

There is a fixed cost to launch a subagent: it starts with a blank slate, gathers context, then works. For a large task, that cost is spread out—it’s worth it. For a 30-second microtask, the overhead of “getting oriented” is greater than the work itself: it’s wasteful. And for the common case, there’s an honest shortcut— inherit the parent's model.

This is the canonical table from the course to choose a model. Read from left to right: each tier has a reasoning level, a relative cost, a latency — and a set of tasks where it's the right choice. Keep it handy; it comes back in Track 4 when we compare models from other providers.

The model choice lives in the field model from the frontmatter. Here are three subagents from the same project, each in the tier justified for your task — and read the comment that explains why each one is where it is.

# ── 1) file-scout.md ── varre o repo atrás de um padrão
---
name: file-scout
description: Varre o repositório atrás de onde um símbolo
  ou string aparece e devolve só os caminhos + linhas.
tools: Read, Grep, Glob       # só leitura
model: haiku                  # ← é "ache e relate": tier barato basta
---
You are a fast code scout. Liste apenas os arquivos e linhas
onde o alvo aparece. Não explique, não opine. Só o mapa.


# ── 2) feature-builder.md ── implementa um passo do plano
---
name: feature-builder
description: Implementa um passo bem-definido de um plano
  (uma função, uma validação, um endpoint) e roda os testes.
tools: Read, Edit, Write, Bash
model: sonnet                 # ← constrói código: o operário competente
---
You are a focused implementer. Implemente exatamente o passo
pedido, siga o padrão do projeto e rode os testes ao final.


# ── 3) security-reviewer.md ── caça falha de segurança
---
name: security-reviewer
description: Revisa o diff em busca de falhas de segurança
  (injeção, vazamento, authz). Use após mexer em auth/pagamentos.
tools: Read, Grep, Glob       # read-only: revisor não edita
model: opus                   # ← raciocínio de segurança: o erro é caro
---
You are a senior security reviewer. Pense como atacante.
Aponte cada risco com arquivo:linha e a gravidade. Não conserte.

Three prompts to tell the orchestrator match model to task. Notice the pattern: you say the tier e a reason — and keep the cheap work on Haiku and the expensive work on Opus.

Use um subagente em Haiku pra escanear /auth e me
trazer só os trechos que tocam o login. Depois,
com esse resumo, use Opus só pra decidir onde está
o bug. Não rode o Opus na varredura.

Crie um subagente "doc-summarizer" read-only com
model: haiku — a tarefa é só ler docs e resumir,
então quero o tier mais barato e rápido.

Esse é um revisor de segurança: coloque model: opus.
O erro aqui é caro, então quero o raciocínio máximo,
mesmo custando mais. Mantenha o agente read-only.

This is how the choice appears in the terminal. The lead launched three subagents, and the status line shows, for each one, which model is running. Notice the design: the scanning fleet in Haiku, the builder in Sonnet, and only the security reviewer in Opus — expensive boss, cheap workers.

↑ Illustrative recreation of the terminal (not a real screenshot). The status line reveals each subagent's model — and the cheap fleet carries most of the workload.