Bug que só acontece em produção: como conduzir a investigação com o Claude Opus 5.5

Funciona na sua máquina, passa no CI, você dá deploy e dez minutos depois o suporte manda print do erro

Clássico, né?

O bug que só acontece em produção é o mais chato de todos porque ele te tira a ferramenta principal do dev: reproduzir na mão até entender. Sobra log, stack trace e hipótese

Em 22 de setembro de 2026 a Anthropic lançou o Claude Opus 5.5, primeiro modelo da família 5.5, descrito oficialmente como o Opus mais forte para coding agêntico e trabalho longo em bases de código grandes, incluindo debugging, refatoração e code review

Só que modelo bom não conserta método ruim

Se você chegar e digitar "tá dando erro em produção, arruma", vai receber um chute educado e vai passar a tarde mexendo em código que não era o problema. O que muda o jogo é a ordem: evidência primeiro, hipóteses ordenadas depois, validação antes do fix. É a mesma lógica de investigar bug sem sair chutando correção, agora com um modelo que aguenta contexto muito maior

Bora montar o processo?

O que ter em mãos antes de abrir o Claude Code

Esse é o passo que todo mundo pula e depois reclama que a IA "inventou"

O modelo só enxerga o que você mostra. Investigação com evidência pobre gera hipótese pobre, e aí a culpa não é do Opus 5.5

Do lado da evidência:

• Log do momento da falha, com timestamp, não o log inteiro do dia e não o print recortado no celular
• Stack trace completo, do topo até a linha mais funda, sem cortar as linhas "que não importam" (elas importam)
• Condições em que reproduziu: horário, volume de requisição, qual usuário ou tipo de conta, região, versão do deploy
• Diferenças conhecidas entre ambientes: versão de runtime, variável de ambiente, banco, quantidade de instância, proxy na frente
• O commit ou deploy suspeito, e de preferência o que estava rodando antes dele
• Frequência: acontece sempre, 1 em cada 10, ou só uma vez e nunca mais?

Esse último item é o que separa "bug determinístico com condição escondida" de "race condition". Anota mesmo que pareça óbvio

Do lado da ferramenta:

Na versão 2.1.280 do Claude Code CLI o claude-opus-5-5 foi adicionado e passou a ser o modelo Opus padrão, com janela de 1M de contexto

O Opus 5.5 está disponível para usuários Pro, Max, Team e Enterprise, e também via Claude API, Amazon Bedrock, Google Cloud, Microsoft Foundry e Claude Platform na AWS

Na API o identificador do modelo é claude-opus-5-5

Tome cuidado! Se você vem do Opus 5 com código que desativava thinking ou que forçava ferramenta, vai tomar erro. Tem uma lista de quebras de compatibilidade no fim do post, dá uma olhada antes de migrar pipeline

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Passo a passo: conduzindo a investigação com o Opus 5.5

A regra do processo todo é uma: nada de editar arquivo até existir hipótese confirmada

1. Escolha o modelo antes de começar a conversa

Rodar /model sem argumento abre o seletor, e /model <alias|nome> troca direto. Na inicialização também dá pra passar na hora de subir

claude --model claude-opus-5-5

No VS Code dá pra clicar no nome do modelo embaixo da caixa de prompt, que abre o mesmo seletor

O erro comum deste passo: começar a investigação num modelo, trocar no meio e achar que o raciocínio continua igual. Blocos de thinking ficam atrelados ao modelo e à conversa, então troca de modelo no meio de uma investigação longa não é de graça. Define no começo

2. Entre em plan mode antes de despejar qualquer coisa

Aperta Shift+Tab até a barra de status mostrar ⏸ plan mode on, ou digita /plan

Em plan mode o Claude explora o código e propõe um plano sem editar os arquivos, e edição de arquivo nunca é auto-aprovada ali, mesmo que você tenha regra de allow configurada. Um conjunto embutido de comandos read-only (ls, cat, git status e afins) roda sem ficar te perguntando

É exatamente o modo que você quer numa investigação: leitura liberada, escrita travada

O erro comum deste passo: confiar que "eu não vou deixar ele editar" e ir no fluxo normal. Na terceira hipótese você aprova um diff no automático e agora tem duas variáveis mudando ao mesmo tempo, a do bug e a da sua edição. Trava por configuração, não por força de vontade 🙂

3. Despeje a evidência bruta, não o seu resumo do bug

Seu resumo já é uma hipótese disfarçada. Quando você escreve "acho que é timeout do banco", você acabou de podar metade da árvore de investigação

Cola o stack trace inteiro, o log com timestamp, o diff do deploy suspeito e as condições. Texto cru

A janela de contexto do Opus 5.5 é de 1M de tokens por padrão, então log grande e stack trace longo não são mais o problema que eram

O erro comum deste passo: mandar print ou trecho "da parte importante". A parte importante do stack trace costuma ser justamente a que você achou irrelevante

4. Ajuste o esforço com /effort

O comando /effort aceita low, medium, high, xhigh ou max, ou um orçamento numérico de tokens. A mudança vale a partir da próxima requisição do turno

/effort high

Detalhe importante: no Opus 5.5 o default caiu para medium (no Opus 5, requisição sem effort rodava em high). E segundo a documentação, no medium padrão o modelo igualou ou superou o Opus 5 em high em tarefas multistep, com menos passos e menos tokens

Ou seja: não sai metendo max em tudo por reflexo. Investigação longa com effort alto em cima de contexto gigante estica a sessão, e aí vale saber o que acontece quando você estoura o limite do Opus no meio do raciocínio

O erro comum deste passo: achar que effort controla o tamanho da resposta. Não controla. A orientação oficial é clara: o effort controla quanto o modelo pensa, e o tamanho da resposta você pede explicitamente no prompt

5. Peça hipóteses ORDENADAS, não um palpite

Esse é o coração do método

Um palpite te dá uma coisa pra testar. Uma lista rankeada te dá um plano de investigação, e ainda te mostra o que o modelo está considerando e por quê

O prompt precisa exigir quatro coisas de cada hipótese: a evidência que a sustenta, a evidência que a contradiz, o teste mais barato que a confirma e o que você esperaria ver se ela fosse falsa

Não proponha correção ainda.

Com base só na evidência acima, liste 5 hipóteses de causa raiz,
ordenadas da mais provável para a menos provável.

Para cada hipótese:
- evidência no log/stack trace que a sustenta (cite a linha)
- evidência que a contradiz ou que falta pra sustentá-la
- o teste mais barato que a confirma ou descarta
- o que eu deveria observar se ela fosse FALSA

Seja conciso: no máximo 4 linhas por hipótese.
Se a evidência não permite ranquear, diga isso em vez de adivinhar.

Repara no "seja conciso" e no "diga isso em vez de adivinhar". O primeiro é porque tamanho de resposta se pede no prompt. O segundo é pra abrir a porta do "não sei", que numa investigação vale muito mais que um chute confiante

O erro comum deste passo: pedir hipóteses e já emendar "e corrige". Aí o modelo entra em modo solução, escolhe a hipótese 1 e você perde as outras quatro

6. Use subagentes pra caminhos independentes

O Claude Code tem subagentes embutidos de pesquisa (Explore e Plan) que mantêm a exploração numa janela de contexto separada. O subagente Plan é o usado no plan mode pra reunir contexto antes do plano, e dá pra disparar vários subagentes pra investigações independentes em paralelo

Na prática: hipótese de pool de conexão e hipótese de fuso horário não têm nada a ver uma com a outra. São duas buscas separadas no código. Mandar as duas na mesma janela só polui o contexto

O erro comum deste passo: usar paralelo pra hipóteses que dependem uma da outra. Se a hipótese B só faz sentido caso a A seja verdadeira, é sequencial, não paralelo

7. Valide hipótese por hipótese, ainda sem tocar no código

Validar aqui é procurar no código e nos dados a condição que a hipótese exige

Se a hipótese é "o pool de conexão satura acima de X requisições simultâneas", a validação é achar onde o pool é configurado, qual o tamanho, e se o log mostra a fila crescendo antes do erro

Não é aplicar a correção e ver se para de dar erro. Isso não é validação, é loteria com deploy

Vamos validar só a hipótese 2.

Me mostre, citando arquivo e linha:
1. onde essa condição é configurada no código
2. o que no log confirma ou nega que a condição aconteceu
3. o que ficou sem resposta e que evidência eu precisaria coletar

Se a evidência atual não fecha, diga "não confirmada" e pare.
Não proponha fix.

O erro comum deste passo: aceitar validação por plausibilidade. "Faz sentido" não é confirmação. Confirmação é linha de código mais linha de log

8. Só então saia do plan mode, e só para a hipótese confirmada

Uma hipótese confirmada, um fix, um teste que falha antes e passa depois

Deixa o /rewind à mão: o menu oferece restaurar conversa, restaurar código ou os dois. É a rede de segurança quando o fix piora as coisas

O erro comum deste passo: confiar no checkpoint pra tudo. O checkpointing só rastreia arquivos editados dentro da sessão atual e não captura mudança manual feita fora do Claude Code. Se você editou no editor, no vim ou rodou um script, o /rewind não sabe disso

Padrões de bug que só aparecem em produção (e como pedir a investigação certa)

Bug de produção quase sempre cai em um punhado de famílias. Reconhecer a família encurta a investigação em horas

Falha intermitente sob carga

Sintoma: erro aparece em horário de pico, some fora dele, e o mesmo request repetido na mão funciona

Causa provável: concorrência. Race condition em estado compartilhado, pool de conexão saturando, lock esperando mais que o timeout, cache sendo escrito por dois caminhos ao mesmo tempo

Como investigar:

Este erro só aparece sob concorrência e não reproduz em request único.\Mapeie todo estado compartilhado no caminho de código do stack trace:
- variável de módulo, singleton, cache em memória, conexão reusada
- operações de leitura seguidas de escrita sem atomicidade
- pontos onde duas requisições podem ver o mesmo valor antes da escrita

Para cada ponto, diga qual ordem de execução produziria o erro do log.
Não sugira correção.

Como prevenir: correlation ID em todo log de request, porque sem ele você não consegue separar duas execuções entrelaçadas. E teste de carga no ambiente de staging, mesmo que simples

Erro que só acontece numa região ou num horário

Sintoma: falha concentrada em um fuso, ou sempre perto da meia-noite, ou só para usuário de um país

Causa provável: timezone e data. Servidor em UTC, usuário em outro fuso, cálculo de "hoje" que muda de dia no meio, horário de verão, ou dado real com formato que não existia no seed local

Como investigar:

A falha se concentra em um fuso/horário específico.

Liste todos os pontos do caminho de código que:
- criam data/hora sem fuso explícito
- comparam datas de origens diferentes
- derivam "hoje", "início do dia" ou "último mês"
- assumem formato ou locale do dado de entrada

Para cada um, diga em que fuso o valor seria diferente e por quê.

Como prevenir: fuso explícito em toda fronteira (entrada, banco, exibição) e dado de teste que inclua os casos chatos de verdade, não só o caminho felizinho

Quebrou depois de um deploy específico

Sintoma: funcionava, deployou, quebrou. Rollback resolve

Causa provável: o que mudou fora do código. Variável de ambiente que não existe no ambiente novo, migração aplicada parcialmente, dependência que subiu de versão no lockfile, config de build diferente

Como investigar: aqui o diff é a evidência principal. Leva o diff do deploy junto com o log

Este é o diff do deploy que introduziu a falha e este é o stack trace.

Me diga, em ordem de risco:
1. o que nesse diff depende de configuração externa ao código
2. o que muda comportamento apenas quando algum dado ou env var já existe
3. o que assume estado de banco pós-migração

Para cada item, o teste mais barato que confirma se é a causa.

Como prevenir: feature flag pra separar "deploy" de "ativação", e paridade de ambiente checada por script, não por memória. Já me ferrei uma vez por causa de uma env var que existia só no meu .env local, e o pior é que é sempre a mesma lição

Não reproduz localmente de jeito nenhum

Sintoma: você tenta de tudo na sua máquina e o código insiste em funcionar

Causa provável: volume e forma dos dados. Produção tem registro com campo nulo que "nunca é nulo", string com emoji, array com 40 mil itens, usuário sem relacionamento obrigatório

Como investigar:

Esta falha não reproduz com dado local.

A partir do stack trace, liste as premissas que o código faz sobre os dados:
campo não nulo, lista não vazia, relacionamento existente, tamanho máximo,
encoding, tipo.

Para cada premissa, escreva a query que verifica se ela é violada em produção.
Não altere o código.

Repara que a saída aqui é uma query de verificação, não um fix. Você continua investigando

Como prevenir: validação na fronteira de entrada e log que registre a forma do dado quando a validação falha, não só a mensagem genérica

Prompts prontos para cada fase da investigação

Guarda esses num arquivo e reusa. Prompt de investigação boa é ativo, não é improviso de cada dia

E lembra da orientação oficial: prompts do Opus 5 funcionam sem alteração no Opus 5.5, e o effort controla quanto o modelo pensa, não o tamanho da resposta. Se você quer resposta curta, pede resposta curta

Experimento de menor custo entre duas hipóteses

Quando sobram duas hipóteses e as duas explicam o log, você não precisa testar as duas

Duas hipóteses ainda estão de pé: A e B.

Proponha UM experimento que discrimina as duas, ou seja: cujo resultado
aponte para A ou para B, nunca para ambas.

Me diga:
- o que rodar/observar
- o resultado esperado se A for verdadeira
- o resultado esperado se B for verdadeira
- o custo e o risco de rodar isso em produção

Se nenhum experimento único discrimina, diga isso.
Máximo 10 linhas.

Leitura de stack trace longo, linha por linha

Leia este stack trace de baixo pra cima, linha por linha.

Para cada frame:
- o que essa camada estava tentando fazer
- que estado ela precisava receber pra chegar ali
- se o frame é código nosso, de dependência ou de runtime

No fim, aponte o frame mais profundo que ainda é código NOSSO
e diga que premissa dele foi violada.

Esse prompt é bom justamente porque o Opus 5.5 coloca a informação mais importante no começo da resposta e segue as regras de escrita que recebe, o que ajuda bastante em sessão longa onde você já leu muita saída

Code review focado em risco de concorrência

Revise este arquivo procurando SÓ risco de concorrência:
estado compartilhado, leitura-seguida-de-escrita não atômica,
ordem de lock, reuso de conexão, cache sem invalidação segura.

Ignore estilo, naming e performance.
Para cada achado: linha, cenário concreto de duas execuções simultâneas
que produz erro, e severidade.
Se não houver risco, diga que não há.

Esse tipo de uso é o que aparece no depoimento de cliente citado pela Anthropic: Carl Bennett, CIO da Deloitte Consulting, relatou que mesmo no menor nível de effort o Opus 5.5 pegou 72% dos bugs conhecidos em code reviews, contra 56% do Opus 5 em high effort, com menos falsos alarmes

Menos falso alarme importa mais do que parece numa investigação. Review que aponta trinta coisas te faz ignorar as trinta

Post-mortem

Depois que fechou, aproveita o contexto que já está na sessão

Escreva um post-mortem curto desta investigação:

1. sintoma observado
2. causa raiz confirmada (e a evidência que confirmou)
3. hipóteses que foram descartadas e por quê
4. por que não pegamos isso antes do deploy
5. o que instrumentar pra detectar em minutos na próxima vez

Sem elogio, sem preenchimento. Máximo 300 palavras.

O item 3 é o que ninguém escreve e é o mais valioso. Hipótese descartada com motivo economiza a investigação do mês que vem 😀

Vale usar o Opus 5.5 nesse tipo de investigação?

Veredito honesto: pro caso específico de bug de produção com muita evidência bruta, é o cenário em que os números do Opus 5.5 mais ajudam

O que pesa a favor:

• Contexto de 1M de tokens por padrão e 128k de saída máxima. Log grande, stack trace inteiro e diff no mesmo prompt, sem você recortar evidência (e recortar evidência é como se perde investigação)
• Adaptive thinking sempre ligado. Você não esquece de habilitar raciocínio na hora que precisa dele
• Velocidade. Gera tokens de saída mais de 30% mais rápido que o Opus 5 e tende a terminar a mesma tarefa com menos tokens. Numa investigação de oito passos, isso muda a sensação de uso
• Custo de releitura. A leitura de cache sai a US$ 0,20 por milhão de tokens (60% menos que o Opus 5), e investigação longa é justamente relê o mesmo contexto várias vezes
• Preço de API: US$ 4 por milhão de tokens de entrada e US$ 20 por milhão de saída, sendo a saída 20% abaixo do Opus 5. No geral, a Anthropic descreve o Opus 5.5 como cerca de 40% mais barato de rodar que o Opus 5 em carga típica, com desempenho no nível do Claude Fable 5.1 na maior parte do trabalho

No Artificial Analysis Intelligence Index, o Opus 5.5 lidera o índice entre 173 modelos avaliados, e o score varia por nível de effort:

A mesma análise aponta melhores scores em 6 das 10 avaliações do índice, incluindo Humanity’s Last Exam com 61,4% (recorde anterior de 59,1%, do Claude Fable 5.1) e SciCode com 66,9% (anterior 63,1%, também Fable 5.1)

Vale registrar o que esses números NÃO dizem: nenhum deles é benchmark de "achar bug intermitente em produção". São proxy de capacidade geral. Trate como indicação, não como promessa

O contraponto, e ele é importante:

Modelo não substitui evidência ruim. Se você entrega print de celular e um "tá dando erro 500", nenhum score de índice vai salvar a investigação. O gargalo continua sendo instrumentação

E tem as quebras de compatibilidade pra quem vem do Opus 5:

• Thinking não pode ser desativado
• Uso forçado de ferramenta (forced tool_choice) retorna erro
• Blocos de thinking ficam atrelados ao modelo e à conversa
• A ferramenta computer_20251124 não é aceita na Claude API e no Google Cloud

Se você tem agente próprio em produção que dependia de qualquer um desses comportamentos, lê o guia de migração antes de trocar o identificador do modelo e sair correndo

Na conta de sanidade: o Opus 5.5 está posicionado oficialmente como melhor Opus para agentes, coding e trabalho de conhecimento, com orquestração confiável de tarefa multi-ferramenta. Investigação de bug é exatamente tarefa multi-ferramenta e multi-passo. Combina

Conclusão

O que separa investigação de chute não é o modelo, é a ordem

Evidência bruta primeiro

Hipóteses rankeadas com evidência a favor e contra depois

Validação hipótese por hipótese

E só no fim, código

Inverte qualquer um desses e você volta pro ciclo de "muda uma coisa, dá deploy, reza", que é o jeito mais caro de descobrir que a causa era outra

Próximo passo prático: atualiza o Claude Code, confirma o modelo com /model, e roda a próxima investigação inteira em plan mode do começo ao fim, sem deixar editar nada. Salva o prompt de hipóteses rankeadas num arquivo e reusa sempre, ele é o que mais rende

E tem mais vindo: a Anthropic anunciou Claude Sonnet 5.5 e Claude Haiku 5.5 para as semanas seguintes, com os mesmos ganhos de desempenho, eficiência e segurança. Pra investigação onde nem precisa de Opus, deve ficar interessante…

Até o próximo post! 🙂