Seus prompts pararam de funcionar igual no Claude Sonnet 5.5? O que revisar primeiro

Fala aí, beleza? Teu prompt que rodava lisinho começou a devolver coisa estranha?

Calma, muito provavelmente o prompt não ficou ruim, o modelo é que mudou por baixo dele

A Anthropic lançou o Claude Sonnet 5.5 em 28/09/2026, e ele custa na API exatamente o mesmo que o Sonnet 5: US$ 2 por milhão de tokens de entrada e US$ 10 por milhão de tokens de saída

Mesmo preço, mas não o mesmo comportamento!

Várias configurações passaram a dar erro, o thinking mudou e o jeito como ele toma decisões também mudou

Aí um prompt que rendia bem na versão anterior pode voltar com erro, com formato diferente ou com iniciativa demais 😛

Se tu já passou por isso na migração de prompts do Fable 5.1, a lógica aqui é parecida: diagnóstico por sintoma, na ordem em que vale a pena revisar

Bora lá?

O que mudou do Sonnet 5 para o Sonnet 5.5 que afeta seus prompts

Antes do como, o porquê 🙂

O Sonnet 5.5 é o segundo modelo da família Claude 5.5 e está disponível na Claude API, no Amazon Bedrock, no Google Cloud e no Microsoft Foundry

Também dá pra usar no Claude.ai (web, iOS e Android) e no app desktop

Segundo a Anthropic, o que muda por dentro é isso aqui:

E aqui está o ponto central, se liga:

Um modelo que decide sozinho em menos passos reage de outro jeito a instruções implícitas e a regras que tu escreveu pensando no modelo anterior

Aquela gambiarra que corrigia uma mania do Sonnet 5 pode simplesmente não fazer mais sentido… ou pior, atrapalhar

Neste vídeo do canal tem a chegada do Claude Sonnet 5 e a discussão sobre se vale o upgrade 🙂

Erro 400 em chamada que funcionava no Sonnet 5: o que corrigir

Esse é o mais fácil de perceber: a requisição nem chega a responder

Sintoma: a chamada da API que rodava antes agora retorna 400

Causa: segundo o guia oficial de migração, cinco configurações passaram a retornar erro no Sonnet 5.5:

• thinking budgets
• parâmetros de amostragem fora do padrão (temperature, top_p e top_k)
• prefill do assistente
• forced tool choice
• thinking {"type": "disabled"}

Ou seja, se tu tinha um temperature customizado lá no código desde a época do modelo anterior, ele é um forte candidato a culpado haha

Solução: remova esses campos da requisição

E se tu usava o disabled pra rodar sem thinking prévio? Aí entra uma configuração nova:

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

Essa é a configuração mais baixa de thinking do modelo, e ela só é aceita com effort high ou abaixo

Com xhigh ou max, use adaptive: ou omita o campo, ou envie assim:

"thinking": {"type": "adaptive"}

Tome cuidado! Mandar between_tools junto com xhigh ou max não é a combinação aceita, então confira os dois campos juntos

Como prevenir: o guia oficial de migração tem um checklist para cada modelo de origem, use o do modelo de onde tu está vindo

O Sonnet 5.5 pensa mais (ou menos) do que antes: ajuste o effort, não o prompt

Sintoma: com o mesmo prompt, as respostas vêm mais longas ou mais rasas, ou aquela frase "pense menos" no system prompt não muda nada

Causa: são cinco níveis de effort (low, medium, high, xhigh e max), e eles foram recalibrados

Traduzindo: o mesmo nível NÃO gera a mesma quantidade de thinking que gerava no Sonnet 5

E tem mais um detalhe, o guia de prompting do Sonnet 5.5 diz que pedir no system prompt para o modelo pensar menos não reduz o thinking de forma confiável

Solução: controle isso pelo parâmetro effort, e não pelo texto do prompt

Lembra também que o padrão muda conforme o lugar:

Então o mesmo prompt pode se comportar diferente na tua aplicação e no Claude Code, e isso não é bug 😀

Como prevenir: tire do prompt as instruções sobre quanto pensar e defina o effort explicitamente

A saída em JSON mudou de formato ou quebrou

Sintoma: o JSON que saía certinho agora dá erro ou vem fora do esperado

Causa: as duas técnicas clássicas pra forçar formato eram o prefill do assistente e o forced tool choice

As duas agora retornam 400 no Sonnet 5.5

Solução: use structured outputs, ou seja, output_config com um JSON schema

Essa é a alternativa indicada no guia de migração pra quem precisa de saída em JSON, e a saída JSON também é um dos padrões cobertos no guia de prompting específico do modelo

Como prevenir: descreva o formato no schema, e não em instruções implícitas espalhadas pelo prompt ("responda em JSON", "não coloque texto antes", "use aspas duplas" e por aí vai)

O schema é a fonte da verdade, o prompt fica pra explicar a tarefa

O modelo começa a construir quando você só pediu ideias ou um plano

Esse aqui assusta, né?

Sintoma: tu pede opções e ele já sai alterando arquivo ou executando coisa

Causa: iniciativa e escopo são um dos padrões tratados no guia oficial de prompting do Sonnet 5.5

Uma instrução implícita tipo "só me dá umas ideias" pode não bastar pra segurar o modelo

Solução: inclua o texto do guia oficial, em inglês e literal:

When the user asks for ideas, options, or a plan, give them that and stop. Don't start building or changing anything until they say to go ahead.

Ele deixa claro que pedir plano é pedir plano, e que construir só depois do teu "pode ir"

Isso pesa MUITO quando o agente mexe em coisa sensível, tipo alterações no banco de dados, onde executar antes da hora é o caminho mais curto pro desastre

Como prevenir: torne explícito no prompt o limite entre planejar e executar

Ferramentas sendo chamadas demais: corte a linguagem enfática

Sintoma: o modelo aciona uma ferramenta em situações em que não deveria

Causa: pelas boas práticas oficiais da Anthropic (o guia geral, não o específico do 5.5), linguagem enfática exagerada provoca acionamento em excesso nos modelos Claude recentes

E regras do tipo "na dúvida, use a ferramenta" pioram o quadro

Sabe aquele prompt cheio de CRITICAL, MUST e NEVER em caixa alta, escrito pra fazer o modelo antigo prestar atenção? Pois é…

Solução: troque a versão gritada pela versão direta

Antes:
CRITICAL: You MUST use this tool when...

Depois:
Use this tool when...

E remova as regras de "na dúvida, use"

Como prevenir: revise as regras que tu escreveu pra compensar o modelo anterior, porque muitas viraram redundantes ou passaram a atrapalhar

Instrução aplicada só em parte e exemplos antigos atrapalhando

Sintoma: a regra vale só na primeira seção, ou o modelo copia exemplos que não representam mais o que você quer

Causa: instruções com escopo implícito e exemplos misturados com o material de apoio

Solução: as boas práticas oficiais indicam duas coisas

Primeiro, declare o escopo de forma explícita, algo como "aplique em todas as seções, não só na primeira"

Segundo, separe instrução, contexto e exemplos com tags XML:

<instructions>
Revise o texto abaixo e aplique as regras em todas as seções, não só na primeira
</instructions>

<context>
Material de apoio aqui
</context>

<examples>
Exemplos atuais do que você espera
</examples>

Assim o modelo não confunde o que é ordem com o que é referência

Como prevenir: revise os exemplos sempre que trocar de modelo e descarte os que só existiam pra corrigir manias da versão anterior

App ficou em silêncio entre as chamadas de ferramenta

Sintoma: tua aplicação mostrava uma narração enquanto o modelo usava ferramentas, e agora não aparece nada

Causa: o texto que vinha em streaming entre as chamadas de ferramenta agora chega como blocos de thinking do tipo progress update

E esses blocos, por padrão, vêm vazios (display em "omitted")

O prompt está ok, o conteúdo só mudou de lugar 🙂

Solução: configure o display explicitamente pra voltar a exibir a narração

Como prevenir: teste o fluxo de streaming de ponta a ponta antes de trocar o modelo em produção

No Claude.ai, a resposta veio de outro modelo

Sintoma: no app, em pedidos de cibersegurança ofensiva de maior risco (geração de exploit, pentest e etc), a resposta não parece do Sonnet 5.5

Causa: os classificadores de cibersegurança podem fazer a resposta cair para o Sonnet 5

Eles leem também memória, conectores, resultados de busca e arquivos, não só a tua mensagem

E depois do fallback, a conversa continua no Sonnet 5

Solução: entenda que o teu prompt não falhou, a resposta é que veio do modelo anterior

Como prevenir: lembre que o conteúdo de memória, arquivos e conectores também entra nessa avaliação, então o contexto da conversa conta tanto quanto o pedido

Próximo passo: migre com o guia oficial em mãos

Recapitulando a ordem de revisão:

1. Erros 400: remova thinking budgets, amostragem fora do padrão, prefill, forced tool choice e thinking disabled
2. Effort: tire do prompt as instruções sobre quanto pensar e defina o nível explicitamente
3. Formato: troque prefill e forced tool choice por structured outputs com JSON schema
4. Iniciativa: deixe explícito o limite entre planejar e executar
5. Linguagem enfática: corte os CRITICAL, os MUST e os "na dúvida, use"
6. Exemplos e escopo: declare o escopo e separe tudo com tags XML

O próximo passo concreto é abrir o guia de migração, que tem checklist para quem vem do Sonnet 5, Sonnet 4.6, Sonnet 4.5, Sonnet 4, Claude 3.7 Sonnet e Haiku 4.5

E junto com ele o guia de prompting do Sonnet 5.5, que cobre effort, iniciativa e escopo, saída JSON, progress updates, uso de ferramentas e mais

Ah, e tem um bônus pra quem migra: o prompt mínimo cacheável caiu pra 512 tokens (no Sonnet 5, Sonnet 4.6 e Sonnet 4.5 era 1.024)

Ou seja, prompts menores passam a aproveitar o cache, legal né? 😀

No fim das contas, revisar os prompts do Claude Sonnet 5.5 é mais limpar do que reescrever: muita regra que existia pra segurar o modelo antigo pode simplesmente sair

Até o próximo post!