O problema é o modelo ou o seu prompt? Quando trocar para o Claude Sonnet 5.5 não resolve

Trocar de modelo não conserta um pedido mal feito

Dói um pouco ouvir isso, né? haha

Fala aí, beleza? A Anthropic anunciou o Claude Sonnet 5.5 em 28/09/2026, o segundo modelo da família Claude 5.5 (o Opus 5.5 saiu antes)

Muita gente vai migrar esperando que aquela tarefa que sempre dava errado finalmente funcione

Às vezes funciona mesmo

Mas se a falha estava no contexto que você entrega, ela vai junto pra versão nova, igualzinha…

Neste post te mostro os sinais de que o problema é o seu prompt e não o modelo, e um teste simples pra separar as duas coisas 🙂

O que o Sonnet 5.5 promete (e o que ele não promete)

Segundo a Anthropic, o Sonnet 5.5 é mais forte em tarefas do dia a dia bem delimitadas (o termo em inglês é well-scoped), em correção de bugs e na criação de documentos, slides e planilhas

Sobre o Sonnet 5, o anúncio fala em geração mais de 30% mais rápida e até 30% menos custo por tarefa na maior parte do trabalho

O preço por token continua o mesmo do Sonnet 5: US$ 2 por milhão de tokens de entrada e US$ 10 por milhão de tokens de saída

No Terminal-Bench 4.0, o anúncio mostra 70,6% do Sonnet 5.5 contra 10,3% do Sonnet 5

Tome cuidado com esse número: é dado do dia do lançamento, divulgado pela própria Anthropic, e não posição em ranking

Se liga no ponto central: o ganho está em tarefa bem delimitada

Ou seja, depende do que VOCÊ entrega

Pra requisito ambíguo, pesquisa exploratória, definição de arquitetura e julgamento de longo prazo, o Opus 5.5 segue sendo o indicado

Sintoma 1: a resposta é genérica ou resolve outra coisa

Você pede uma coisa e recebe algo meio morno, que até funciona, mas não era bem aquilo

Causa: tarefa vaga, sem cenário e sem preferência

O modelo preenche os buracos com o palpite mais provável, e o palpite mais provável é o genérico

Solução: a própria documentação de boas práticas do Claude Code dá um exemplo perfeito disso

Em vez de:

add tests for foo.py

Escreva:

write a test for foo.py covering the edge case where the user is logged out. avoid mocks.

Repara que a segunda versão diz QUAL cenário cobrir e COMO você prefere que seja feito

Agora aplica o teste do colega, que é a regra de ouro da Anthropic pra prompts: mostre o pedido pra um colega com pouco contexto da tarefa

Se ele ficar confuso, o Claude também vai ficar

Como prevenir: trate o Claude como um funcionário brilhante, mas novo, que não conhece as normas da sua equipe

É como contratar um dev fodão no primeiro dia: ele sabe programar muiiito bem, mas não sabe que vocês odeiam mock no projeto 😛

Se isso apareceu depois de uma troca de versão, vale ler também o que revisar no prompt antes de culpar o modelo

Sintoma 2: o Claude mexe no arquivo errado ou inventa onde está o código

Você fala "ajusta o middleware de autenticação" e ele edita outro arquivo, ou cria um novo do zero

Causa: você descreveu a localização em vez de apontar

Solução: no Claude Code, referencie o arquivo com @

Ajuste a validação de token em @src/auth/middleware.ts para rejeitar tokens expirados

Com o @, o Claude lê o arquivo antes de responder, então ele não precisa adivinhar onde o código mora

Como prevenir: sempre que a tarefa depender de um arquivo específico, aponte o arquivo exato

Descrever "aquele arquivo de auth lá" é pedir pra dar errado haha

Sintoma 3: ele diz que terminou, mas não está pronto

Esse é clássico

O agente fala "pronto, implementado!" e quando tu roda, quebra

Causa: não existe critério de sucesso e não existe forma de verificar

A documentação do Claude Code é bem direta aqui: sem checagem, o agente tende a parar quando o trabalho parece pronto, o que não é o mesmo que estar pronto

Solução: dê ao Claude uma checagem que retorne um sinal legível, por exemplo:

• suíte de testes
• exit code do build
• linter
• script de diff
• screenshot comparado ao design

Assim ele tem como saber se acertou, em vez de achar que acertou

Como prevenir: defina o critério de sucesso antes do primeiro prompt

É assim que a Anthropic descreve o começo da engenharia de prompt: critérios de sucesso definidos, uma forma de testar contra eles e um primeiro rascunho de prompt pra iterar

Sintoma 4: ele segue a regra ao pé da letra e erra no caso que ela não previa

Você escreveu uma regra, ele obedeceu, e mesmo assim o resultado ficou estranho num caso que você não tinha imaginado

Causa: instrução sem o porquê

Regra solta não diz pro modelo o que você queria proteger, então ele não consegue estender a ideia pros casos novos

Solução: explique a motivação junto com a regra, porque isso generaliza melhor que a instrução sozinha

O exemplo da própria Anthropic:

A resposta será lida por um sistema de text-to-speech, então evite reticências

Com o motivo, o modelo entende que o problema é a leitura em voz alta, e passa a evitar outras coisas que também atrapalhariam ali

Como prevenir: acompanhe cada regra importante com o motivo dela

E quando a regra é tão rígida que nem deveria depender da interpretação de um modelo, talvez faça sentido trocar o prompt por uma decisão tipada no código

Sintoma 5: a sessão começou bem e foi piorando

Nas primeiras mensagens tava tudo massa, e depois de um tempo o Claude começa a esquecer coisa, repetir erro e ignorar o que tu pediu…

Causa: pode ser a janela de contexto cheia

Que janela? É tudo que o Claude está "vendo" na sessão: a conversa inteira, cada arquivo lido e cada saída de comando

No Claude Code ela enche rápido, e o desempenho cai conforme ela enche

Outra causa possível é o CLAUDE.md inchado

Ele é carregado em toda sessão, e quando tem coisa demais o Claude acaba ignorando instruções

Solução:

• use /clear pra recomeçar limpo
• enxugue o CLAUDE.md perguntando, pra cada linha, se removê-la faria o Claude errar (se não faria, corta!)
• use /context pra confirmar se o arquivo foi carregado

Como prevenir: mantenha no CLAUDE.md só o que vale de forma ampla pro projeto

Instrução de uma tarefa específica vai no prompt da tarefa, não no arquivo que roda sempre

Teste simples para separar falha do modelo de falha do prompt

Bora ver na prática?

A ideia é mudar UMA variável por vez: primeiro o contexto, com o mesmo modelo, e só depois pensar em modelo

1. Escreva o critério de sucesso e a checagem

Antes de mexer em qualquer coisa, define o que é "deu certo" e como verificar (teste, build, linter, diff ou screenshot)

Critério: usuário deslogado recebe 401 em /api/orders
Checagem: npm test passa sem falhas

O erro comum deste passo: usar "ficou bom" como critério, o que não dá pra checar

2. Aplique o teste do colega no prompt

Lê o seu prompt como se fosse alguém que caiu de paraquedas no projeto

O erro comum deste passo: ler com o contexto que está na SUA cabeça, e não no texto

3. Reescreva com arquivo apontado, cenário e preferência

write a test for @src/orders/controller.ts covering the edge case where the user is logged out. avoid mocks.

O erro comum deste passo: apontar o arquivo e esquecer o cenário, ou o contrário

4. Recomece com /clear e confira o CLAUDE.md com /context

Sessão limpa elimina a dúvida de contexto cheio, e o /context mostra se o arquivo foi carregado

O erro comum deste passo: continuar na mesma sessão longa e atribuir ao prompt novo um resultado que veio do contexto acumulado

5. Rode de novo contra a mesma checagem

Mesmo modelo, mesma checagem, só o contexto mudou

O erro comum deste passo: mudar prompt e modelo ao mesmo tempo, e aí não dá pra saber o que resolveu

Se passou, o problema era o contexto 😀

Se continua falhando, olha pra natureza da tarefa: se ela é ambígua, exploratória ou de arquitetura, é sinal de que ela pede o Opus 5.5, e não um Sonnet mais novo

Quando o Sonnet 5.5 é a escolha certa e quando não é

Com base no posicionamento oficial, dá pra separar assim:

E tem mais um ajuste além do prompt: o nível de esforço (effort) do modelo

O guia de migração do Sonnet 5.5 recomenda escolher o nível de esforço (effort) conforme a tarefa:

• high na maior parte do trabalho
• medium pra coding agêntico bem especificado e uso de ferramentas em várias etapas
• medium ou low pra chat e tarefas sensíveis a latência

E se tu vai usar via API: segundo o anúncio oficial da Anthropic, o ID do modelo é claude-sonnet-5-5, e ele está disponível na Claude Platform, AWS, Google Cloud e Microsoft Azure

Antes de trocar de modelo, troque o pedido

Recapitulando: o Sonnet 5.5 rende mais em tarefa bem delimitada, e quem delimita a tarefa é você

Resposta genérica, arquivo errado, "terminei" sem estar pronto, regra seguida ao pé da letra e sessão que vai piorando têm causa no contexto, e nenhuma versão nova corrige isso sozinha

Modelo novo amplifica um bom contexto, não substitui

O próximo passo é simples: pega a última tarefa que falhou, escreve o critério de sucesso e roda o teste das cinco etapas antes de culpar o modelo

Se mesmo assim não sair, aí sim é hora de olhar pra outro modelo =)

Até o próximo post!