Quando vale a pena usar Haiku nos subagentes do Claude Code?

Fala aí, beleza? Existe um gasto silencioso em quase todo fluxo de agente: você paga preço de modelo topo de linha pra alguém abrir 40 arquivos e te dizer em quais aparece a palavra auth

Esse é o caso clássico de modelo por papel

A ideia é simples: o modelo leve fica nos papéis de apoio (varrer arquivo, resumir saída longa, checar formato, conferir lista) e o forte fica onde existe decisão de verdade (escrever o patch, decidir a arquitetura, dar o veredito final)

Neste post eu mostro quando colocar Haiku nos subagentes compensa, como configurar isso no Claude Code passo a passo e, principalmente, o que quebra quando o papel de apoio erra

Bora? 🙂

Quais papéis aguentam o Haiku e quais não

Antes do como, o porquê

O Claude Haiku 4.5 entrega nível de desempenho em código parecido com o do Claude Sonnet 4, por um terço do custo e mais que o dobro da velocidade

No SWE-bench Verified ele marcou 73,3%, em média de 50 tentativas, sem test-time compute, com orçamento de thinking de 128K e parâmetros de sampling padrão, no conjunto completo de 500 problemas

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

E não é aquele modelinho capado de antigamente: o Haiku 4.5 foi o primeiro Haiku a incluir extended thinking, computer use e context awareness

Ou seja, ele pensa antes de responder quando você deixa

Só não confunda as contas: aquela comparação de desempenho e custo é contra o Sonnet 4, um modelo de geração anterior

A tabela abaixo é outra coisa, é o preço da linha atual, então a proporção entre os modelos aqui é diferente:

E aqui vale um aviso pra não te enganarem por aí: o Haiku 4.5 foi anunciado pela Anthropic em 15 de outubro de 2025 e é o Haiku mais recente da linha

Não existe um "Claude Haiku 5" lançado, beleza?

Papel de apoio (Haiku resolve bem):

• Busca ampla e leitura de muitos arquivos: o trabalho aqui é volume, não julgamento, e velocidade importa mais que sutileza
• Resumo de saída longa: log gigante, stack trace, retorno de build, tudo que precisa virar 10 linhas
• Checagem de formato: o JSON tem os campos? o frontmatter está válido? o arquivo segue o padrão?
• Conferência de lista contra critério: pegar uma lista de itens e marcar cada um como bate ou não bate

Papel de decisão (deixa no forte):

• Escrita de patch: aqui o modelo escolhe entre abordagens, e escolha ruim custa muito mais que token
• Decisão de arquitetura: o custo do erro aparece semanas depois, não na fatura
• Veredito final: o cara que decide se aquilo vai pro repositório

A régua que eu uso é essa: o papel EXECUTA ou o papel JULGA?

Se ele executa comando mecânico e devolve um resultado objetivo, o leve dá conta

Se ele julga qualidade, vai de forte

Se você quer aprofundar em qual modelo usar em cada tarefa, tem um post inteiro só sobre isso aqui no blog

O que você precisa antes de configurar

Subagente do Claude Code é arquivo Markdown com frontmatter YAML

O frontmatter traz a configuração e o corpo do arquivo vira o system prompt do subagente

Só isso, sem mistério

E tem dois lugares onde esse arquivo pode viver:

• ~/.claude/agents/ são os subagentes de usuário, que valem pra todos os seus projetos
• .claude/agents/ são os subagentes de projeto, específicos daquele projeto, que podem ser versionados e compartilhados com o time

Essa escolha não é decorativa

Regra de qualidade muda de projeto pra projeto, então revisor costuma ser de projeto

Tome cuidado com isso: a partir da versão 2.1.198 do Claude Code, o comando /agents não abre mais o assistente interativo de criação

Ele imprime um aviso apontando pros diretórios de subagentes

Então a criação hoje é manual, na mão, criando o arquivo você mesmo

Se tu procurou o painel e não achou, não é bug, é isso mesmo

Como definir o modelo de cada subagente no Claude Code

Agora sim, o passo a passo

Passo 1: Crie o arquivo .md no diretório certo

mkdir -p .claude/agents
touch .claude/agents/revisor.md

O erro comum deste passo é jogar tudo em ~/.claude/agents/ por preguiça e depois levar a regra de qualidade de um projeto pra dentro de outro

Outro tropeço clássico: o Claude Code não observa mudanças em .claude/agents/ dentro de diretórios adicionados com --add-dir ou /add-dir

Se você criou ou editou o subagente lá, precisa reiniciar pra alteração carregar

Passo 2: Preencha o frontmatter com o campo model

---
model: haiku
---

Você é o revisor deste projeto

Não escreva código e não conserte código

Rode os comandos de qualidade do projeto e responda apenas: aprovado ou reprovado

O campo model aceita alias de modelo (sonnet, opus, haiku ou fable), ID completo do modelo (como claude-opus-5 ou claude-sonnet-5) ou o valor inherit

Repara que tudo abaixo do frontmatter é o system prompt do subagente

O erro comum deste passo é fixar haiku num papel que decide, tipo o subagente que escreve o patch

Barato ali não é economia, é retrabalho

Passo 3: Entenda que omitir o campo equivale a inherit

Se você não colocar model na definição, o padrão é inherit: o subagente usa o mesmo modelo da conversa principal

O erro comum aqui é achar que subagente sem model roda no modelo mais barato por padrão

Não roda

Se a sua sessão está em Opus, o subagente sem model também está

Passo 4: Sobrescreva pontualmente pela ordem de resolução

A ordem que o Claude Code segue pra resolver o modelo de um subagente é essa:

1. variável de ambiente CLAUDE_CODE_SUBAGENT_MODEL
2. parâmetro model da invocação
3. campo model do frontmatter
4. modelo da conversa principal

CLAUDE_CODE_SUBAGENT_MODEL=haiku claude

A partir da versão 2.1.196, definir CLAUDE_CODE_SUBAGENT_MODEL como inherit equivale a não definir a variável: a resolução segue pro parâmetro por invocação e depois pro frontmatter

O erro comum deste passo é deixar essa variável exportada no shell e depois jurar que o frontmatter está quebrado

A variável ganha do arquivo, sempre

Passo 5: No Agent SDK, use AgentDefinition.model

A definição programática de subagente tem um campo model opcional, passado pelo parâmetro agents das opções de query()

query({
  prompt: "revisa o projeto",
  options: {
    agents: {
      revisor: {
        // demais campos da definição do subagente
        model: "haiku"
      }
    }
  }
})

O erro comum deste passo é supor que os aliases são idênticos aos do frontmatter

A documentação de subagentes no Agent SDK lista apenas sonnet, opus, haiku e inherit nesse campo

O que quebra quando o papel de apoio erra

Aqui é onde a maioria se perde, então vou por sintoma

O subagente rodou num modelo diferente do que eu configurei

Causa provável 1: o Claude Code confere os valores de modelo (variável de ambiente, parâmetro por invocação e frontmatter) contra a allowlist availableModels da organização

Se o valor resolver pra um modelo excluído, ele é ignorado e o subagente roda no modelo herdado

Causa provável 2: a variável de ambiente ganhando do frontmatter, como no passo 4

Como prevenir: antes de acusar o arquivo, cheque a variável de ambiente da sessão e a allowlist da organização

Editei o subagente e nada mudou

Causa: não existe file watching em .claude/agents/ dentro de diretórios adicionados com --add-dir ou /add-dir

Como prevenir: reinicie o Claude Code depois de mexer em subagente que mora nesses diretórios extras

O mesmo nome está definido em dois lugares

Causa: subagentes de projeto são descobertos subindo a partir do diretório de trabalho atual, varrendo todo .claude/agents/ até a raiz do repositório

Quando mais de um diretório define o mesmo nome, vale a definição mais próxima do diretório de trabalho

Como prevenir: em monorepo, saiba de qual pasta você abriu o Claude Code, porque isso decide qual definição vence

O Explore ficou mais caro do que era antes

Causa: a partir da versão 2.1.198, o subagente embutido Explore passou a herdar o modelo da conversa principal em vez de rodar sempre em Haiku

E na Claude API a herança do Explore é limitada ao Opus: conversa principal num tier superior roda o Explore em Opus, e conversa principal em Sonnet ou Haiku roda o Explore no mesmo modelo

Como prevenir: se o seu fluxo dependia do Explore barato por padrão, essa conta mudou de lugar e precisa ser reavaliada

O subagente está pensando demais

Causa: a partir da versão 2.1.198, os subagentes também herdam a configuração de extended thinking da conversa principal

Se o thinking está ligado na sessão, fica ligado no subagente

Como prevenir: lembre que thinking ligado num papel puramente mecânico é token gasto pra confirmar o óbvio

Todos esses comportamentos estão descritos na documentação de subagentes do Claude Code, vale a leitura

O que aconteceu quando troquei o modelo do papel de apoio

No vídeo abaixo eu mostro isso montado na prática, num fluxo de loop

Eu criei um subagente revisor dedicado ao projeto, com a instrução de não escrever e não consertar código: ele só roda os comandos de qualidade e responde aprovado ou reprovado

Deixei esse revisor no Haiku justamente por isso

Ele não julga se o código foi bem escrito, ele executa verificação mecânica

Configurei com escopo de projeto, não global, porque cada projeto tem regra de qualidade diferente

E configurei manualmente, já que eu tinha o prompt pronto, em vez de deixar a IA gerar a descrição

Detalhe que economiza mais do que parece: deixei o prompt de revisão dentro do subagente em vez de escrever as regras no arquivo de contexto do projeto

Aquele arquivo é relido a cada prompt, então tudo que mora nele você paga sempre

No arquivo de referência eu defini as condições de pronto (testes passam, checagem de tipos passa, lint passa, build roda sem erro) e os critérios de aceite do app

Aí amarrei o loop ao revisor: o subagente é chamado a cada iteração e o trabalho só é considerado feito com zero falhas

O modelo forte ficou no agente principal, o que constrói

E aqui entra o freio, que na minha opinião é a parte MAIS importante: guard rail de número máximo de turnos

Loop sem limite é loop infinito de programação, e você não quer descobrir isso pela fatura

Na primeira execução eu botei teto de 12 turnos

Só que o loop nem chegou perto disso: resolveu tudo de uma vez, concluiu num único turno e não iterou

Atribuí isso ao modelo muito forte no agente principal somado a um projeto simples demais

Pra forçar a iteração de verdade, montei uma segunda fase mais complexa (com autenticação e API) e troquei o modelo principal por um menor, com teto de 10 turnos

A aposta era essa: modelo menor com mais complexidade faz o loop repetir os ciclos

E é aí que a lição fica clara

Baixar o modelo no papel de apoio é barato e seguro, porque o papel é mecânico

Baixar o modelo no papel que constrói é o que faz o número de iterações subir, e iteração custa

O limite de turnos é exatamente o que segura o barato que sai caro

Uma coisa que eu comentei lá e mantenho: dá pra melhorar o acompanhamento do loop com avisos a cada iteração, mas isso é refinamento, não o mínimo

O mínimo é o par arquivo de especificação bem construído mais agente revisor

Abaixo disso o agente roda à toa e pode sair pior que prompt a prompt

Próximo passo: comece trocando um subagente só

A regra prática cabe numa linha: leve no apoio, forte na decisão

Não saia refazendo todos os seus subagentes hoje

Escolhe UM, o mais óbvio: aquele que só varre arquivo e resume o que achou

Coloca model: haiku no frontmatter dele

Deixa todos os outros sem o campo model, ou seja, em inherit, herdando o modelo da conversa principal

Roda o teu fluxo normal por alguns dias e compara duas coisas: o custo e a qualidade do que aquele papel devolve

Se o resultado se manteve, aí sim tu expande pro próximo papel de apoio

Se caiu, tu já sabe exatamente qual subagente reverter, porque só mexeu num…

É mais chato que trocar tudo de uma vez? É

Mas é assim que você descobre onde o barato resolve de verdade, em vez de adivinhar 😀

Até o próximo post!