Use o Haiku 5.5 como subagente somente leitura no Claude Code e verifique o modelo

A abordagem mais segura não é mover toda a sessão do Claude Code para um modelo pequeno. Entregue ao Haiku 5.5 apenas tarefas delimitadas, somente leitura e fáceis de conferir: localizar referências a símbolos, seguir imports, encontrar configurações ou resumir um conjunto definido de arquivos. Mantenha Sonnet ou Opus na conversa principal para decisões, edições, testes e aprovação final.

Uma configuração não está comprovada apenas porque o prompt diz “use Haiku” ou porque um arquivo contém model: haiku. Você precisa de três camadas de evidência: o modelo explícito na definição do agent, o modelo exibido pelo Claude Code durante a execução e o Model ID real no registro de solicitações do provedor. Considere a troca verificada somente quando as três camadas coincidirem.

Decida o que pode ser delegado

A Anthropic posiciona o Haiku 5.5 para trabalhos rápidos e repetitivos, como resumos, compaction, consultas a bancos de dados e classificação. O anúncio oficial também o descreve como subagente de programação ao lado do Sonnet 5.5 ou do Opus 5.5, enquanto modelos maiores continuam recomendados para agentic coding complexo. Consulte o anúncio do Haiku 5.5.

Comece com esta divisão:

Tarefa	Responsável recomendado	Por quê
Encontrar todas as referências a uma classe, função ou configuração	Subagente somente leitura em modelo pequeno	Entrada, saída e condição de parada são claras
Resumir a função dos arquivos de um diretório	Subagente somente leitura	Exige leitura e síntese, não alterações
Rastrear uma requisição da entrada até o banco de dados	Subagente somente leitura	O resultado pode ser validado por caminhos e linhas
Escolher arquitetura, estratégia de migração ou limite de segurança	Agente principal Sonnet/Opus	Exige ponderação ampla e decisão de maior risco
Alterar código, executar migrações, atualizar dependências ou permissões	Agente principal Sonnet/Opus	Modifica o workspace e requer revisão rigorosa
Decidir e implementar a correção final	Agente principal Sonnet/Opus	Precisa combinar evidências e responder pelo resultado

Uma regra útil: você consegue dizer em uma frase o que procurar, o que devolver e quando parar, sem gravar arquivos? Caso contrário, deixe a tarefa na conversa principal.

Entenda quatro controles diferentes de modelo

No Claude Code, vários mecanismos podem ser confundidos:

1. Modelo da conversa principal: selecionado com /model, parâmetro de inicialização ou settings.
2. Campo model no frontmatter do subagente: vale para aquela definição específica.
3. Alias versus Model ID completo: haiku é um alias que pode resolver de forma diferente por provedor e versão; claude-haiku-5-5 é o ID completo publicado pela Anthropic.
4. Substituição de uma função versus imposição global: um agent personalizado chamado Explore substitui apenas o Explore integrado; CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 afeta quase todos os subagentes.

A documentação oficial atual resolve o modelo nesta ordem: modelo passado para a invocação, model da definição do agent, CLAUDE_CODE_SUBAGENT_MODEL e, por último, o modelo da conversa principal. Portanto, CLAUDE_CODE_SUBAGENT_MODEL sozinho é apenas um padrão; não garante que irá prevalecer sobre o frontmatter ou a chamada. Consulte a documentação de subagentes do Claude Code.

Para este fluxo, comece com um único agent somente leitura, claramente nomeado. Não ative primeiro uma imposição global, pois isso também pode mover Plan, general-purpose, teammates ou workflow agents para o modelo pequeno.

Etapa 1: confira a versão do Claude Code e os IDs do provedor

Primeiro veja a versão:

claude --version

A versão altera a interface e o caminho de verificação:

• No Claude Code v2.1.198 ou posterior, /agents não abre mais o assistente de criação. O comando orienta você a pedir que Claude crie o arquivo ou a editar .claude/agents/ e ~/.claude/agents/ diretamente.
• No v2.1.197 ou anterior, /agents abre o assistente interativo com as abas Running e Library.
• No v2.1.242 ou posterior, /tasks mostra o modelo na linha do subagente em execução. Em versões mais antigas, dê mais peso ao registro do provedor.
• Use CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 somente quando quiser deliberadamente aplicar um modelo a todos os subagentes. O recurso exige v2.1.257 ou posterior.

Depois confirme quais IDs exatos o seu provedor aceita:

• Na API Anthropic Claude, o Model ID oficial do Haiku 5.5 é claude-haiku-5-5. Consulte a página oficial do modelo.
• Em uma plataforma de nuvem ou gateway de terceiros, não presuma que o mesmo ID já esteja disponível. O provedor pode usar um nome de deployment, um alias próprio ou um catálogo selecionado.
• Quando este guia foi verificado, em 10 de outubro de 2026, o catálogo público da BetterToken listava claude-haiku-4-5-20251001, claude-sonnet-5-5 e claude-opus-5-5, mas não claude-haiku-5-5. Ao usar BetterToken, escolha um ID que realmente conste no catálogo atual. Consulte o catálogo atual da BetterToken.

“A Anthropic lançou o modelo” e “meu gateway oferece o modelo” são fatos diferentes. Se o ID não está no catálogo do provedor, uma instrução no prompt ou um alias de família não comprovam suporte.

Etapa 2: crie um subagente de projeto somente leitura

Agents de projeto ficam em .claude/agents/ e podem ser mantidos junto com o repositório. Agents do usuário em ~/.claude/agents/ ficam disponíveis em todos os projetos.

Na raiz do repositório, crie o diretório:

mkdir -p .claude/agents

Crie .claude/agents/repo-researcher.md. Com a API Anthropic Claude, use esta definição:

---
name: repo-researcher
description: Finds symbols, traces call paths, and summarizes selected files before code changes. Use only for bounded read-only repository research.
tools: Read, Grep, Glob
model: claude-haiku-5-5
---

You are a read-only repository researcher.

For each task:
1. Search only the scope named by the caller.
2. Do not edit, create, delete, or rename files.
3. Return file paths and line numbers for every important finding.
4. Separate direct evidence from inference.
5. Stop when the requested question is answered; do not propose unrelated refactors.

Return:
- Findings
- Evidence: file:line
- Uncertainties
- Suggested next check for the main agent

Três detalhes são importantes:

• tools permite apenas Read, Grep e Glob; não concede Write, Edit nem Bash.
• description explica quando delegar, reduzindo o risco de o agente principal enviar uma alteração para o subagente.
• model usa um ID completo aceito pelo provedor, não apenas uma frase solicitando Haiku.

Se o Claude Code estiver conectado por BetterToken, o pequeno modelo Claude presente no catálogo verificado era:

model: claude-haiku-4-5-20251001

Esse é um exemplo do catálogo atual, não uma promessa permanente. Confira novamente o catálogo ou o Model Plaza antes de mudar o mapping. A documentação da BetterToken para Claude Code orienta a usar um Model ID exato e definir ANTHROPIC_BASE_URL como https://bettertoken.ai, sem acrescentar /v1. Consulte o guia de Claude Code da BetterToken.

Se .claude/agents/ não existia quando a sessão atual começou e o Claude Code não localizar o novo agent, reinicie o Claude Code uma vez. A documentação oficial explica que o watcher em execução não detecta o primeiro diretório agents se ele não existia na inicialização.

Etapa 3: mantenha o agente principal em Sonnet ou Opus

Escolha o modelo da conversa principal separadamente. Por exemplo:

/model sonnet

ou:

/model opus

Com um gateway, o modelo final atrás de um alias depende do gateway e de seu mapping. Use um ID completo do provedor quando precisar fixar uma versão e confirme-o no registro da solicitação.

Não ative uma imposição global apenas para colocar um agent de pesquisa em um modelo pequeno. Esta configuração tem alcance muito maior:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

Use-a somente quando quiser conscientemente que Plan, subagentes general-purpose, teammates e workflow agents sigam o mesmo modelo. Se quiser alterar apenas a exploração automática de código, defina um agent de projeto ou usuário chamado Explore e atribua um model próprio. Isso substitui o Explore integrado sem mudar todos os demais.

Etapa 4: acione o agent com um teste auditável

Não comece com “entenda todo o repositório”. Escolha uma tarefa estreita cuja resposta possa ser verificada manualmente:

Use the repo-researcher agent to find every call site of PaymentService.createCharge.
Return file:line, the caller's purpose, and the path from the public entry point.
Do not edit files. Stop after covering this symbol and its direct callers.

Depois da execução, confira quatro pontos:

1. O transcript principal contém uma linha de delegação para repo-researcher; o agente principal não fez a busca silenciosamente.
2. O subagente devolveu caminhos e números de linha, separando evidência de inferência.
3. A árvore de trabalho não mudou:

git status --short

4. A decisão seguinte e qualquer alteração continuam sob responsabilidade do agente principal.

Se a pesquisa precisar ser preservada, revise-a primeiro na conversa principal. Depois permita que o agente principal grave o resultado aceito na documentação ou em uma issue. Não dê permissão de escrita ao subagente apenas para salvar a saída.

Etapa 5: verifique o modelo realmente executado

1. Inspecione a definição do agent, mas não pare nela

Confirme que .claude/agents/repo-researcher.md contém o ID completo pretendido. Isso comprova apenas a configuração estática. Um modelo passado na invocação, uma política da organização ou um mapping do gateway ainda podem alterar a solicitação.

2. Inspecione /tasks durante a execução

Execute:

/tasks

O Claude Code v2.1.242 ou posterior mostra o modelo na linha do subagente. Se ele for diferente do arquivo, verifique se:

• Claude passou outro modelo nessa invocação;
• CLAUDE_CODE_SUBAGENT_MODEL_FORCE está ativado;
• uma política availableModels da organização substituiu o modelo;
• sua versão segue uma ordem de precedência anterior.

3. Relacione o registro de solicitação do provedor

Encontre a solicitação na mesma janela de tempo e confira o Model ID real. Isso é especialmente importante com gateways de terceiros, porque um alias mostrado pelo cliente pode ser mapeado novamente pelo gateway.

A BetterToken mostra modelo, contagens de tokens, cobrança final e status em um único registro. Neste fluxo, use apenas os campos de modelo e status como prova; não transforme o registro em uma alegação de economia sem evidência. Primeiro relacione o horário da solicitação com o período de execução do subagente.

Use uma tabela de aceitação simples:

Ponto de controle	Evidência esperada	O que fazer se houver diferença
Arquivo do agent	Model ID exato	Corrija o ID e aguarde a recarga ou reinicie, se necessário
/tasks	Subagente alvo e modelo em execução	Confira parâmetros da chamada, variáveis force e política da organização
Registro do provedor	Model ID real e status de sucesso na mesma janela	Confira catálogo, mapping de alias, routing e acesso da conta
git status --short	Nenhuma alteração inesperada	Restrinja tools, reverta mudanças e repita o teste

Registre “troca de modelo verificada” apenas quando os três primeiros pontos coincidirem. Um prompt que menciona Haiku, o nome do agent na interface ou a existência de uma resposta não bastam isoladamente.

Solução de problemas

O agent não é chamado

Confirme que o arquivo está em .claude/agents/ ou ~/.claude/agents/, que o frontmatter contém name e description e que o YAML é válido. Reinicie o Claude Code se o primeiro diretório agents foi criado depois do início da sessão. Se ainda não carregar, inicie com --debug e examine o erro.

/agents não mostra o assistente

Normalmente isso não é falha. No v2.1.198 ou posterior, /agents orienta a editar os arquivos diretamente. O assistente interativo pertence ao v2.1.197 ou anterior. Siga a documentação da versão instalada, não uma captura antiga.

model: haiku não prova Haiku 5.5

haiku é um alias, não uma versão fixada. O destino pode mudar com a versão do Claude Code, o provedor ou o mapping do gateway. Para routing auditável, use um ID completo do catálogo atual e verifique /tasks e o registro do provedor.

O gateway retorna model not found, 403 ou aplica fallback

Primeiro confira se o ID aparece no catálogo ativo e se a conta tem acesso. Se claude-haiku-5-5 não está listado, não repita indefinidamente o mesmo valor: escolha um modelo adequado que conste no catálogo ou aguarde o gateway adicioná-lo. Uma allowlist da organização também pode substituir o modelo sem interromper a tarefa.

Todos os subagentes foram para o modelo pequeno

Procure e remova CLAUDE_CODE_SUBAGENT_MODEL_FORCE. Para fixar apenas um agent, coloque o ID completo no frontmatter desse agent. Para mudar apenas a exploração automática, substitua Explore.

O subagente alterou arquivos

Use git status --short para identificar o escopo e reverta mudanças não desejadas. Depois limite tools a Read, Grep, Glob e repita a restrição de somente leitura no system prompt. Remover ferramentas de escrita é mais confiável do que apenas pedir “não edite”.

Implantação mínima

Comece com cinco passos:

1. Atualize o Claude Code e execute claude --version.
2. Copie um Model ID completo e realmente disponível no catálogo do seu provedor.
3. Crie um único repo-researcher limitado a Read, Grep e Glob.
4. Acione-o com uma tarefa limitada a um símbolo ou diretório.
5. Compare /tasks, o registro do provedor e git status --short.

O objetivo não é enviar tudo ao menor modelo. É estabelecer uma divisão de trabalho auditável: o modelo pequeno reúne evidências somente leitura e verificáveis; o agente principal Sonnet ou Opus mantém as decisões e alterações de maior impacto. Valide primeiro uma tarefa estreita e expanda o padrão somente onde os mesmos critérios de aceitação continuarem válidos.