Como pedir correção de bug ao Claude Sonnet 5.5 sem ele reescrever meio projeto

O bug é de uma linha

Mas a resposta volta mexendo em cinco arquivos, renomeando variável, criando helper novo e ainda enfiando comentário em função que nem tinha nada a ver com a história 😅

Fala aí, beleza? A Anthropic soltou o Claude Sonnet 5.5 em 28/09/2026, e segundo ela o modelo rende mais justamente em tarefas do dia a dia com escopo claro… e corrigir bug é uma delas

Só que "escopo claro" não aparece do nada: quem define é o seu pedido

Então bora ver como montar esse pedido pra aproveitar o modelo sem perder o controle do projeto 🙂

Quando o Sonnet 5.5 é a escolha certa para corrigir bug?

Segundo a Anthropic, o Sonnet 5.5 é o segundo modelo da família Claude 5.5, depois do Opus 5.5

E a própria empresa é bem direta: ele não avança a fronteira, mas é melhor que o Sonnet 5 em programação e trabalho de conhecimento

Onde ele brilha? Em tarefas cotidianas bem delimitadas, e a correção de bugs está na lista junto com criação de documentos, slides e planilhas

Faz sentido, né? Bug com escopo fechado é o cenário perfeito: tem um erro, tem um lugar, tem um comportamento esperado

Os números oficiais que interessam pra esse uso:

O preço de API é o mesmo do Sonnet 5 e metade do Opus 5.5

E quando NÃO ir direto pra correção?

Se o bug é incerto, mexe em vários arquivos ou está num código que tu não conhece, a doc do Claude Code recomenda começar pelo plan mode

Que plan mode? É o modo que separa a exploração da execução: o Claude investiga e propõe um plano antes de sair editando. Pra sair dele, você aprova o plano ou pressiona Shift+Tab

Agora, se dá pra descrever o diff em uma frase (tipo "trocar o <= por < no loop"), pode pular o plano sem medo

O que ter em mãos antes de abrir o chat?

Antes de digitar qualquer coisa, junta isso aqui:

• O log de erro ou a saída do CI completos, do jeito que saíram
• O arquivo e o trecho onde o problema aparece
• Uma frase com o comportamento atual e outra com o comportamento esperado
• O comando de verificação: teste, build ou lint que prova que o bug sumiu

E tão importante quanto o que entra é o que fica de fora:

• A sua interpretação do erro no lugar do log: ela adiciona abstração e costuma perder o detalhe que leva à causa raiz
• Arquivos sem relação com o bug: mais contexto irrelevante é mais chance de ele "aproveitar" e mexer onde não devia
• Pedidos paralelos de melhoria: "e aproveita e organiza esse arquivo" é o convite oficial pra reescrever meio projeto haha

Passo a passo: como montar o prompt de correção de bug

Bora ver na prática? Cada passo vira um pedaço do template final

1. Cole o erro direto, sem parafrasear

A doc do Claude Code é clara: cole o log, a saída do CI ou a thread direto

No Claude Code dá pra mandar o log via pipe:

cat error.log | claude

Erro comum deste passo: resumir o erro com as suas palavras ("deu um erro de null lá no checkout"). Nesse resumo some justamente a linha, o arquivo ou o valor que o modelo precisava pra achar a causa

2. Referencie o arquivo com @ em vez de descrever onde fica o código

No Claude Code, use @ pra apontar o arquivo, e o Claude lê o arquivo antes de responder

Nada de "é naquela função de pagamento que fica na pasta de serviços, sabe?" kkk

Erro comum deste passo: colar o projeto inteiro achando que mais contexto é sempre melhor. Não é: aponta só o que tem relação com o bug

3. Descreva o comportamento atual e o esperado

Duas frases resolvem:

Atual: ao aplicar um cupom de 100%, o total fica negativo
Esperado: o total deve parar em zero

Erro comum deste passo: escrever só "não funciona". Não funciona COMO? O modelo vai chutar, e chute vira mudança fora do lugar

4. Delimite o escopo da correção

Aqui é o coração do post 🙂

O guia oficial de prompting da Anthropic avisa que os modelos Claude tendem a fazer overengineering: arquivos extras, abstrações desnecessárias, flexibilidade que ninguém pediu

A solução? Pedir explicitamente uma solução mínima, algo assim:

Faça só as mudanças necessárias para corrigir este bug
Não refatore, não adicione features e não faça melhorias além do pedido
Não limpe o código ao redor
Não adicione docstrings, comentários nem anotações de tipo em código que você não alterou

Erro comum deste passo: esperar que o modelo adivinhe o limite. Ele não adivinha, tu precisa escrever

5. Peça a correção da causa raiz, não a supressão do erro

Uma instrução curta já muda o jogo:

Corrija a causa raiz. Não suprima o erro

Isso evita que o Claude mascare o problema com exceção genérica ou dados de fallback falsos

Erro comum deste passo: aceitar um try/catch genérico só porque o erro parou de aparecer. Tome cuidado! O erro sumiu da tela, mas o bug continua lá dentro

6. Informe a verificação que ele deve rodar

Pode ser teste, build, lint ou um screenshot pra comparar

Sem uma verificação executável, "parece pronto" vira o único sinal, e quem passa a ser o loop de verificação é você

Erro comum deste passo: não passar comando nenhum e ficar testando na mão a cada resposta

7. Junte tudo em um template com tags XML

O guia oficial recomenda tags XML pra separar as partes do prompt, e isso casa MUITO bem com correção de bug, porque cada pedaço fica no seu lugar:

<erro>
[cole aqui o log completo, sem editar]
</erro>

<codigo>
@caminho/do/arquivo
(fora do Claude Code, cole só o trecho onde o problema aparece)
</codigo>

<esperado>
Atual: (descreva o que acontece hoje)
Esperado: (descreva o que deveria acontecer)
</esperado>

<escopo>
Faça só as mudanças necessárias para corrigir este bug
Não refatore, não adicione features e não faça melhorias além do pedido
Não adicione docstrings, comentários nem anotações de tipo em código que você não alterou
Mantenha a solução mínima: sem arquivos novos, abstrações ou flexibilidade que eu não pedi
Se criar arquivos temporários, scripts ou helpers durante a tarefa, remova no final
Corrija a causa raiz, não suprima o erro com exceção genérica nem com dados de fallback falsos
</escopo>

<verificacao>
Rode [seu comando de teste, build ou lint] e só considere pronto quando passar
</verificacao>

Copia, salva e troca só os colchetes a cada bug 😀

Como validar a resposta antes de aceitar a correção?

A resposta chegou. Antes de aceitar, olha o diff procurando estes sinais de que a correção passou do escopo:

E a pergunta final, a que decide tudo: a verificação passou?

Se não passou, não tem "parece certo" que salve… volta pro chat com a saída da verificação colada, do mesmo jeito que você colou o erro

Como prevenir:

Deixa a instrução de solução mínima e a de causa raiz fixas no template, dentro de <escopo>

Assim tu não depende de lembrar delas no meio da pressa de corrigir bug em produção (e é justamente nessa hora que a gente esquece hehe)

Vídeo: o que mudou na linha Sonnet

Pra começar do zero com a linha Sonnet, este vídeo do canal apresenta o Sonnet 5 e discute se vale o upgrade, um bom contexto sobre o modelo anterior ao 5.5

E se quiser voltar ainda mais na história da linha, tem o post sobre o raciocínio estendido do Claude 3.7 Sonnet

Resumo e próximo passo

A ideia central é essa: o que limita o estrago é o pedido bem delimitado, não o modelo

O Sonnet 5.5 é mais forte em tarefa de escopo claro, então o seu trabalho é entregar esse escopo: erro colado, arquivo referenciado, atual e esperado, limite explícito, causa raiz e verificação

Próximo passo? Salva o template com as tags XML e usa no próximo bug que aparecer

Se a correção envolver vários arquivos ou código que você não conhece, começa pelo plan mode e só depois parte pra execução

Faça o teste e me conta se o diff veio mais enxuto =)

Até o próximo post!