Claude Code escolhe o modelo certo sozinho

Quem comentou AGENTE no vídeo, seja bem-vindo(a). Essa página é o "e agora?" de tudo que apareceu rápido demais no Reels. Sem pressa, com exemplo, sem economizar explicação.

Resumo de 30 segundos: o Claude Code deixa você criar "ajudantes" especializados (subagentes). Cada um pode usar um modelo de IA diferente — um mais rápido pra tarefa simples, um mais caro e poderoso pra tarefa difícil. Você escolhe o modelo de cada um na hora de criar, pedindo pro próprio Claude Code (ou escrevendo o arquivo você mesmo). Mais abaixo tem o passo a passo, o exemplo pronto e a regra de ouro de quando isso realmente vale a pena.

O que é um subagente, na prática

Pensa assim: você está numa conversa longa com o Claude Code, já tem bastante contexto acumulado (arquivos abertos, decisões tomadas, erros resolvidos). Se você pedisse pra ele "agora procura em todo o projeto onde essa função é usada", ele ia fazer isso carregando toda aquela bagagem de conversa junto — mais lento, mais caro, e com chance de se confundir com informação que não tem nada a ver com a busca.

Um subagente resolve isso: é como chamar um estagiário de fora, que não viu nada da sua conversa, recebe só a tarefa específica ("procura essa função"), faz o trabalho isolado, e devolve o resultado pronto. Ele tem contexto próprio, separado da conversa principal.

Tecnicamente, cada subagente é só um arquivo Markdown com um cabeçalho em YAML, guardado em uma destas duas pastas:

• .claude/agents/ → vale só pra esse projeto
• ~/.claude/agents/ → vale pra qualquer projeto seu, global

Por que o modelo de cada um importa

Modelo de IA tem trade-off conhecido: uns são mais rápidos e mais baratos, outros são mais lentos e mais caros, mas pensam melhor em problema complicado. Isso é contexto geral do mercado de IA, não é regra específica do Claude Code — mas é o motivo de essa configuração existir.

Quando usar	Por quê
Tarefa mecânica: buscar arquivo, ler código, listar ocorrências	Rápido e barato já resolve, não precisa de "poder de fogo"
Tarefa de raciocínio: decidir arquitetura, debugar algo não óbvio, escrever lógica nova	Vale pagar mais caro por um modelo mais capaz

No Claude Code, essa escolha fica no campo model do cabeçalho do subagente, com 4 opções:

• haiku
• sonnet
• opus
• inherit → usa o mesmo modelo que já está rodando na conversa principal

Se você não escrever nada nesse campo, vale o mesmo efeito do inherit: o subagente herda o modelo que já está rodando na conversa principal. Não existe uma escolha automática por dificuldade sem você configurar isso — é exatamente por isso que vale a pena montar um agente por nível, como no exemplo abaixo.

Passo a passo: criando um subagente com modelo definido

Importante: o comando /agents mudou recentemente — a versão antiga abria um menu guiado, mas esse menu foi removido. Hoje /agents só mostra um aviso lembrando as duas formas de criar um subagente. São essas duas que valem:

1. Pedir pro Claude Code, em português, já dizendo o modelo. Foi assim que montei os três agentes de exemplo deste post — um prompt por nível. Aqui está o print de cada um, prompt e resposta, sem cortes:

Nível rápido e barato — Haiku:

Crie um subagente chamado leitor-rapido, para tarefas simples e mecânicas como buscar código, ler arquivos e fazer ajustes pequenos. Use o modelo haiku.

Nível padrão — Sonnet:

Crie um subagente chamado revisor-de-codigo, que revisa o código em busca de bugs, erros e falhas silenciosas. Use o modelo Sonnet.

Nível pesado — Opus:

Crie um subagente chamado arquiteto-critico, para decisões complexas de arquitetura e debug de bugs difíceis que exigem raciocínio pesado. Use o modelo opus.

Repare no detalhe que faz toda a diferença: é preciso falar o modelo explicitamente no pedido. Se você só descrever a tarefa e não mencionar o modelo, o Claude Code não escolhe um nível sozinho — ele simplesmente deixa o campo model de fora, e o agente herda o modelo da conversa principal.

2. Ou editar o arquivo Markdown você mesmo, direto em .claude/agents/<nome>.md (só vale nesse projeto) ou ~/.claude/agents/<nome>.md (vale em todos). Foi isso que os três prompts acima geraram — os três arquivos reais, completos, abertos no editor:

Repare que cada um tem seu model fixo no cabeçalho (haiku, sonnet, opus) — é só isso que muda de arquivo pra arquivo nesse quesito.

Com os três criados, quem decide qual chamar é o próprio Claude Code: quando você pede algo simples ("acha onde essa função é usada"), ele aciona o leitor-rapido (Haiku). Quando pede uma revisão de bug, aciona o revisor-de-codigo (Sonnet). Quando o problema é arquitetura ou um bug difícil, aciona o arquiteto-critico (Opus). Essa escolha depende de a description de cada agente estar clara — é o que guia a decisão. Não é mágica 100% garantida, mas funciona bem na prática e evita você trocar de modelo na mão toda hora.

A regra de ouro: quando delegar (e quando NÃO)

Essa é a parte que mais gente erra, inclusive eu já errei.

A orientação oficial da Anthropic pro Opus 5/5.5 é direta: delegar pra um subagente só compensa numa tarefa grande, genuinamente independente e paralelizável.

Delegar uma tarefa pequena — daquelas que se resolvem em poucas chamadas de ferramenta — não economiza nada. Pelo contrário: aumenta o custo e aumenta o tempo, porque o subagente precisa montar o próprio contexto do zero antes de sequer começar.

Pra deixar concreto, pensando no dia a dia:

• ❌ "Corrige esse typo nessa linha" → não delega. É rápido demais, o custo de montar um subagente novo é maior que a própria tarefa.
• ❌ "Explica o que esse arquivo faz" → não delega. Poucas chamadas, resolve na conversa principal.
• ✅ "Refatora essas 40 chamadas de API espalhadas pelo projeto pro novo formato" → aqui sim: grande, dá pra dividir, e cada parte não depende do resultado da outra.

Exemplo real de uso certo, dentro do próprio Claude Code: o agente nativo Explore, que já vem pronto, roda no Haiku. Ele é só leitura (não edita nada) e serve exatamente pra buscar e analisar código dentro do projeto. Isso libera o Opus — que é mais caro e mais lento — pra fazer o que só ele faz bem: decisão de arquitetura e debug complicado, em vez de gastar tempo (e dinheiro) procurando onde uma função está definida.

Bônus: um time de agentes, não um só que troca de modelo sozinho

Não existe uma configuração escondida que faz um único agente trocar de modelo no meio da tarefa, dependendo da dificuldade. O que existe — e já resolve o problema na prática — é você montar vários agentes, cada um travado num nível, com a description deixando claro quando cada um entra em ação, igual aos três exemplos acima (leitor-rapido/Haiku, revisor-de-codigo/Sonnet, arquiteto-critico/Opus). Sem isso, se você criar um subagente sem falar o modelo, ele não escolhe sozinho entre Haiku/Sonnet/Opus — ele só herda o modelo da conversa principal.

Perguntas que já me fizeram

"Preciso saber escrever YAML pra usar isso?" Não. Peça pro próprio Claude Code, descrevendo a tarefa e já dizendo qual modelo usar — ele escreve o arquivo pra você.

"E se eu esquecer de definir o modelo?" O agente herda o modelo que já está rodando na conversa principal. Não existe seleção automática por dificuldade sem você configurar isso em cada agente.

"Vale delegar 'de boa', só pra testar?" Só se a tarefa for grande e independente de verdade. Se não for, você só vai gastar mais e esperar mais.

Pra quem quer ver na tela, passo a passo

Três tutoriais em vídeo (de outros criadores, não da Anthropic — então datas e telas específicas podem já ter mudado um pouco, principalmente a parte do /agents, que foi removida):

• How to Create Sub Agents in Claude Code
• Claude Code Sub-Agents: Step-by-Step Beginner Tutorial
• Claude Code Hooks & Subagents Explained

Referências oficiais

• Documentação oficial de subagentes
• Visão geral do Claude Code