Vale a pena trocar para o Claude Sonnet 5.5 no meio de um projeto?

Fala aí, beleza? A Anthropic soltou o Claude Sonnet 5.5, e a pergunta que mais aparece não é "ele é bom?", e sim "eu troco AGORA, com o projeto rodando?" 🙂

E já adianto: trocar de modelo no meio do projeto não é só mudar o ID e sair correndo

O Sonnet 5.5 saiu em 28 de setembro de 2026, como o segundo modelo da família Claude 5.5

O Sonnet 5 continua ativo, mas virou legado (não recebe mais atualizações)

E o Sonnet 4.5 já tem data pra sair: a aposentadoria na Claude API está marcada pra 30/11/2026

Então a dúvida real é outra: quando a troca compensa e quando ela quebra o que já funciona?

Bora ver isso com calma, critério por critério 😀

Sonnet 5.5 vs Sonnet 5: o que muda na prática?

Antes de decidir qualquer coisa, se liga no que dá pra comparar com dado oficial ou índice público:

Um detalhe importante na linha do índice: o ganho depende do nível de esforço

No Low, o Sonnet 5.5 marca 36, abaixo dos 38 do Sonnet 5

Do Medium pra cima ele passa na frente, e no Max chega a 56

Ou seja, "o 5.5 é mais inteligente" é verdade dependendo de como tu configura ele

O que você ganha ao migrar para o Sonnet 5.5?

O ganho mais direto é no bolso, mas não do jeito que a maioria imagina

O preço por token é exatamente o mesmo do Sonnet 5

O que muda é quanto token cada tarefa consome: segundo a Anthropic, o Sonnet 5.5 custa até 30% menos na maior parte do trabalho, porque usa menos tokens e faz menos chamadas de ferramenta

E ainda gera saída mais de 30% mais rápido que o Sonnet 5

Mesma tabela de preço, menos consumo e mais velocidade… massa, né? 😀

Pra que tipo de tarefa ele foi pensado?

A Anthropic posiciona o Sonnet 5.5 como um complemento mais rápido e mais barato do Opus 5.5

O foco declarado são as tarefas do dia a dia bem delimitadas: correção de bugs, documentos, slides e planilhas

Então pensa assim: o Opus continua sendo o sênior pros problemas cabeludos, e o Sonnet 5.5 é quem resolve o volume do dia a dia rapidinho

Onde o Sonnet 5.5 está disponível?

Na Claude API, no Amazon Bedrock, no Google Cloud e no Microsoft Foundry

Se o teu projeto já roda em um desses, não tem troca de provedor envolvida

O fator tempo também conta

Esse é o ganho que pouca gente coloca na conta

O Sonnet 5 é legado: não recebe mais atualizações e pode ser descontinuado (a aposentadoria fica pra não antes de 30/06/2027)

Não é urgente, mas uma hora essa migração vai acontecer de qualquer jeito

Quem está no Sonnet 4.5 não tem esse luxo: a aposentadoria do claude-sonnet-4-5-20250929 na Claude API é em 30/11/2026, e o substituto recomendado é justamente o Sonnet 5.5

Se o teu código ainda aponta pra uma versão antiga, vale entender o que fazer com um modelo aposentado na API

O que pode quebrar no seu código ao trocar de versão?

Aqui é onde mora o perigo 😛

O guia de migração oficial lista mudanças que devolvem erro 400 pra quem só troca o ID

Erro 400 ao desligar o thinking:

Sintoma: a chamada que funcionava no modelo anterior começa a voltar erro 400

Causa: no Sonnet 5.5, thinking: {"type": "disabled"} não é aceito

O thinking roda por padrão, e os tipos aceitos são "adaptive" e "between_tools"

Solução: pra desligar o thinking inicial, mande o nível mais baixo:

"thinking": {"type": "between_tools"}

Como prevenir: se liga nas limitações do between_tools, porque elas pegam MUITA gente:

• só é aceito com esforço low, medium e high
• em xhigh ou max dá erro 400 (nesses casos, omita o campo thinking ou mande {"type": "adaptive"})
• com ele, o esforço não pode mudar no meio da conversa
• o campo não aceita display, budget_tokens nem block_binding

Se o teu código monta esse objeto com um budget_tokens herdado da versão antiga, tome cuidado!

Erro 400 ao forçar o uso de ferramenta:

Sintoma: as chamadas com ferramenta obrigatória passam a falhar com erro 400

Causa: o Sonnet 5.5 recusa tool_choice dos tipos "tool" e "any"

Solução: use o tool_choice automático e marque a ferramenta com strict: true:

"tool_choice": {"type": "auto"}

E, como o modelo não é mais obrigado a chamar a ferramenta, diga no prompt QUANDO ele deve usar

Como prevenir: no Amazon Bedrock só vale o auto, então nem adianta procurar outra opção por lá

Blocos de thinking presos à conversa:

Sintoma: o histórico de conversa que tu edita, filtra ou remonta passa a dar problema

Causa: cada bloco de thinking do Sonnet 5.5 é assinado sobre a conversa anterior

E se liga: a regra vale pela data de criação da CONTA, não pela data do modelo

Em contas criadas a partir de 31/08/2026 00:00 UTC, a API exige isso por padrão (Claude API, Bedrock e Google Cloud), então quem abriu a conta depois dessa data já cai nesse comportamento ao usar o Sonnet 5.5

Solução: ler os blocos de conteúdo pelo tipo e devolver os blocos de thinking sem alteração

Como prevenir: nada de pegar "o primeiro bloco da resposta" achando que é texto, nem de "limpar" o thinking antes de reenviar

Esse tipo de atalho funcionava por sorte, e é exatamente ele que quebra agora

Em que momento do projeto a migração dói menos?

Aqui não tem fórmula mágica, tem critério

A fase em que o projeto está diz MUITO mais sobre o risco do que o modelo em si

No início de uma feature:

É a melhor janela

O código novo já nasce compatível com os breaking changes (thinking, ferramentas e blocos assinados), então não tem retrabalho

E, se algo se comportar diferente, tu percebe enquanto ainda está construindo, e não com usuário reclamando

Antes de um release:

É o pior momento, sem dúvida

Trocar de modelo muda o comportamento, e isso obriga a revalidar todos os fluxos que usam thinking e ferramentas

Fazer isso com prazo apertado é receita pra surpresa em produção…

Depois do deploy:

É um bom momento, desde que exista tempo pra testar com calma

Esse é especialmente o caso de quem ainda depende do Sonnet 4.5: o prazo vai até 30/11/2026, então dá pra planejar, mas não dá pra empurrar pra sempre

O critério que pesa mais que a fase:

Se o teu código desliga o thinking ou força o uso de ferramenta, o projeto vai dar mais trabalho, seja qual for a fase

Se não usa nada disso, a troca tende a ser bem mais tranquila

Como migrar o projeto para o Sonnet 5.5 com o Claude Code:

O Claude Code tem uma migração assistida, e ela adianta bastante o serviço

Bora ver na prática? 😀

1. Garanta o Claude Code v2.1.284 ou mais recente

O Sonnet 5.5 exige no mínimo essa versão

O erro comum deste passo: tentar usar o modelo numa instalação antiga e achar que o problema está na conta

2. Rode a migração assistida

/claude-api migrate this project to claude-sonnet-5-5

Esse comando chama a skill Claude API, que já vem com o Claude Code

Ela troca o ID do modelo e, quando precisa, aplica as mudanças de parâmetros, a substituição de prefill e a calibração de esforço

Antes de editar qualquer coisa, ela pede pra confirmar o escopo: o diretório inteiro, um subdiretório ou uma lista de arquivos

Só depois dessa confirmação ela começa a mexer no código

Ela também detecta clientes do Bedrock e do Claude Platform on AWS

O erro comum deste passo: confirmar o diretório inteiro de primeira num projeto grande (começa por um subdiretório e mede o tamanho do ajuste)

3. Revise o checklist que a skill entrega

No fim, ela entrega um checklist pra conferência manual

Não pula isso! Fazer no esquema "next, next e finish" aqui é perigoso haha

O erro comum deste passo: confiar 100% na edição automática e não olhar o que ficou pra conferir

4. Confira o checklist oficial

• ID trocado para claude-sonnet-5-5
• blocos lidos pelo tipo, com os de thinking devolvidos sem alteração
• between_tools usado com esforço high ou menor, quando a ideia é rodar sem thinking inicial
• uso forçado de ferramenta trocado por auto + strict: true

O erro comum deste passo: esquecer alguma chamada com esforço xhigh ou max usando between_tools, o que dá erro 400

Pronto, com esses quatro passos feitos e o checklist conferido, o projeto já está rodando no Sonnet 5.5 🙂

Como trocar de modelo no Claude Code sem mudar o projeto inteiro?

Quer sentir o modelo antes de mexer no código? Faz todo o sentido

A documentação de configuração de modelos mostra três caminhos

1. Trocar na sessão atual

/model sonnet

Se preferir escolher numa lista, /model sem argumento abre o seletor

Se liga: o padrão do Claude Code continua sendo o Opus 5.5 nas contas Pro, Max, Team, Enterprise e Anthropic API

E o alias sonnet aponta para o Sonnet 5.5 na Anthropic API

2. Abrir uma sessão já com outro modelo

A flag --model e a variável de ambiente ANTHROPIC_MODEL fazem isso

Isso é útil, por exemplo, pra quem usa o Claude Code em dois projetos e quer cada sessão num modelo diferente

O erro comum deste passo: achar que a flag --model vale pras sessões futuras (ela vale só pra sessão iniciada com ela, e o mesmo acontece com o ANTHROPIC_MODEL)

3. Fixar a versão pra não mudar no meio do projeto

A variável ANTHROPIC_DEFAULT_SONNET_MODEL define qual modelo o alias sonnet usa:

export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5-5

Com isso, o alias fica preso a uma versão, e o projeto não troca de modelo sem tu perceber

Se a ideia é segurar o projeto no Sonnet 5 por enquanto, coloca nessa variável o ID do Sonnet 5 que consta na documentação

O erro comum deste passo: esquecer que essa variável também afeta o opusplan fora do Plan Mode

Vídeo: a última troca de versão do Sonnet

Pra começar do zero na pergunta "vale o upgrade?", este vídeo do canal mostra a chegada do Sonnet 5 e a discussão sobre trocar de versão, uma boa base pra pensar na decisão de agora

Veredito: trocar agora ou esperar?

Antes do veredito, um aviso honesto: os números de velocidade e custo por tarefa são os informados pela Anthropic, e os de qualidade vêm de índices públicos

Não são medição própria em projeto real, beleza?

Se o projeto está no Sonnet 4.5:

Migra já

A aposentadoria na Claude API é em 30/11/2026, e o substituto recomendado é o Sonnet 5.5

Quanto antes começar, mais tempo sobra pra testar sem pressa

Se está no Sonnet 5 com projeto estável e perto de release:

Fixa a versão e migra depois do deploy

O Sonnet 5 segue ativo, então não tem motivo pra arriscar o release por causa de uma troca de modelo

Se está no Sonnet 5 e vai começar uma feature nova:

Migra agora

O preço por token é o mesmo, a Anthropic informa mais velocidade e menor custo por tarefa, e o código novo já nasce no padrão do 5.5

Próximo passo:

Recapitulando: o Claude Sonnet 5.5 mantém o preço do Sonnet 5, promete mais velocidade e menos consumo por tarefa, mas tem breaking changes que dão erro 400

Então o próximo passo é bem concreto:

• identifica em que fase do ciclo o teu projeto está (início de feature, perto do release ou pós deploy)
• procura no código por thinking com "disabled" e por tool_choice com "tool" ou "any"
• se encontrar, roda a migração assistida do Claude Code em um subdiretório primeiro, pra medir o tamanho do ajuste antes de mexer no resto

Feito isso, tu decide com dado na mão, e não no hype 🙂

Até o próximo post!