O bug só acontece na máquina de outra pessoa: que contexto dar ao Claude Code?

Fala aí, beleza? Alguém do time te chama dizendo que "deu erro" na tela de login

Tu roda o mesmo fluxo na tua máquina e funciona redondo, nenhum log estranho, nenhum stack trace

Aí vem o pedido clássico: "Claude, conserta isso"

E o agente faz o que dá pra fazer com quase nada de contexto: chuta uma hipótese, mexe em três arquivos e o bug segue vivinho na máquina da outra pessoa

Correção no escuro é isso, e o problema quase nunca é o modelo: é o briefing

Esse post separa dois casos que vivem sendo confundidos: quando o bug está no SEU app e quem viu foi outra pessoa, e quando o bug está no Claude Code da máquina dela

E tem um terceiro assunto que aparece no meio da investigação e quase ninguém espera: o log que você pediu chegando com credencial junto

O que coletar muda bastante em cada um…

Sintoma: o relato chegou vago (só "deu erro") e você não consegue reproduzir

Formação Recomendada

Formação Claude Code

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

• 116 aulas
• 4 projetos
• 9h 23min

Conhecer formação

Causa: falta a sequência, os dados e o estado

O relato vago não é má vontade, é só a pessoa contando o FIM da história

O que falta é a sequência de passos até o erro, os dados que ela digitou e o estado da sessão dela naquele momento

Que estado da sessão? Coisas do tipo: já estava logada há horas, tinha trocado de conta, estava com o app aberto em duas abas, veio de um link antigo

Sem isso, o agente não tem como reconstruir o caminho, e um bug que não reproduz continua não reproduzindo

Solução: um roteiro fixo do que pedir

Em vez de perguntar "o que aconteceu?", manda o roteiro pronto pra pessoa preencher

1. O que você estava tentando fazer
2. Passo a passo do que clicou, na ordem
3. Quais dados usou (pode trocar por valores falsos do MESMO formato)
4. O que você esperava que acontecesse
5. O que apareceu na tela, mensagem COMPLETA, print inteiro
6. Data e horário aproximado
7. Deu uma vez só ou repete sempre?

O item 3 é o que mais salva: dado de entrada com formato diferente (acento, espaço no fim, CPF com máscara, e-mail em maiúscula) é campeão de bug que só aparece na máquina dos outros

E o item 7 separa condição de corrida de bug determinístico, o que muda completamente a hipótese

Prevenção: template fixo, não improviso

Deixa esse roteiro salvo em algum lugar que o time acessa fácil e cola sempre igual

Relato padronizado vira contexto padronizado, e contexto padronizado é o que o agente consegue usar

Sintoma: funciona na sua máquina e quebra na dela

Causa: a diferença não está no código

Se o mesmo commit roda aqui e quebra ali, o suspeito quase nunca é a linha de código: é ambiente ou dado

Sistema operacional diferente, versão de runtime diferente, variável de ambiente ausente, fuso horário, locale, banco com dados reais versus seed limpinho

É tipo culpar a receita quando o forno é que está com temperatura errada 😀

Solução: escrever a diferença, não descrever a sensação

Agente não adivinha ambiente, ele lê o que você escreveu

Então monta um bloco de contexto assim, com o que você conseguiu apurar:

Minha máquina: SO X, runtime versão A, banco local com seed
Máquina dela: SO Y, runtime versão B, banco de homologação
Variáveis que existem aqui e não sei se existem lá: LISTA
Dado de entrada real (anonimizado): "exemplo com o mesmo formato"
Erro exibido: mensagem completa

E aí muda o pedido: em vez de "corrige", pede hipóteses ranqueadas

Algo como "liste as causas mais prováveis pra esse comportamento dado esse ambiente, da mais pra menos provável, e diga que evidência confirmaria cada uma"

Isso transforma o agente em investigador em vez de chutador

A lógica é a mesma de dar contexto de negócio para uma skill: o que não está escrito, não existe pro modelo

Prevenção: registrar as variáveis no repositório

Se a cada relato você precisa lembrar de cabeça quais variáveis o projeto usa, você vai esquecer uma

Deixa isso versionado num arquivo do repositório, com nome das variáveis (nunca os valores) e as versões esperadas

Da próxima vez, é copiar e colar

Sintoma: o problema é o Claude Code na máquina da outra pessoa, não o seu código

Causa: instalação, configuração ou customização local

Tem uma categoria inteira de "bug" que não é do seu app: é do setup do Claude Code de quem está reclamando

CLAUDE.md antigo, skill que alguém instalou, plugin, hook, servidor MCP, comando ou agente personalizado

A boa notícia é que dá pra isolar isso com comando, sem palpite

Solução: os comandos que ordenam a investigação

Primeiro, o diagnóstico da instalação e das configurações:

/doctor

Depois, o teste que mais economiza discussão:

claude --safe-mode

O safe mode inicia a sessão com todas as customizações desligadas: CLAUDE.md, skills, plugins, hooks, servidores MCP e comandos e agentes personalizados

Autenticação, escolha de modelo, ferramentas nativas e permissões continuam funcionando normalmente

Se o problema SOME no safe mode, pronto: a causa está em uma dessas superfícies de customização, e agora é só ir religando

Se você desconfia de memória carregada, o /context mostra o uso real da janela de contexto por categoria, incluindo quais arquivos CLAUDE.md e de memória automática foram carregados

E pra log de execução tem a skill embutida /debug, que diagnostica problemas em tempo de execução e liga o log da sessão atual

Tome cuidado com uma pegadinha aqui: o log de debug fica desligado por padrão, a menos que a sessão tenha sido iniciada com claude –debug

Rodar /debug no meio da sessão passa a capturar dali em diante, ou seja: não recupera o que já passou

Os logs ficam gravados por sessão em ~/.claude/debug/, e só são escritos quando a sessão inicia com –debug ou quando se roda /debug

Outra pegadinha: existe a configuração disableBundledSkills, que desativa todas as skills embutidas exceto /doctor

Então se a pessoa disser "aqui não tem /debug", não é bug, pode ser config

E se depois de tudo isso sobrar um bug do PRÓPRIO Claude Code, o caminho é reportar:

/feedback

O /bug é apelido do mesmo comando, se você já tem o dedo viciado nele

Prevenção: /doctor e safe mode antes do palpite

Combina com o time que todo relato de "o Claude Code está estranho" já vem com o resultado do /doctor e com o teste no safe mode

Duas informações que custam um minuto e cortam metade das hipóteses

Sintoma: você pediu os logs e veio credencial junto

Causa: isso tudo está em texto puro no disco

Aqui é a parte que dá arrepio, então presta atenção

As transcrições de sessão do Claude Code ficam salvas localmente em JSONL, num caminho previsível: ~/.claude/projects/<projeto>/<session-id>.jsonl

O <projeto> é o caminho do diretório de trabalho com os caracteres não alfanuméricos trocados por hífen, ou seja: fácil de achar

Os prompts digitados ficam em ~/.claude/history.jsonl, com data e caminho do projeto

E não tem criptografia em repouso: a única proteção são as permissões de arquivo do sistema operacional

Agora o detalhe que pega gente boa: se uma ferramenta lê um arquivo .env ou um comando imprime uma credencial, esse valor vai parar dentro do arquivo de transcrição da sessão

As transcrições ficam armazenadas localmente em texto puro por 30 dias por padrão, em ~/.claude/projects/, pra permitir retomar sessões

Juntando as peças: pedir "me manda o log" pode significar pedir o segredo de produção por mensagem interna 😛

Solução: revisar antes de mandar, e limpar depois

Antes de circular qualquer arquivo, alguém abre e LÊ o que está lá dentro

E existe o comando pra apagar os dados locais de um projeto:

claude project purge

Ele apaga transcrições e memória automática em projects/, entradas por sessão em tasks/, debug/ e file-history/, as linhas de prompt correspondentes em history.jsonl e a entrada do projeto em ~/.claude.json

Prevenção: combinar o que pode circular

Define com o time o que pode ir pro canal interno e o que nunca sai da máquina

Essa conversa é irmã daquela de combinar regras em projeto de cliente: melhor alinhar antes do incidente do que depois do vazamento

Como montar o pedido ao Claude Code passo a passo, sem correção no escuro

Agora junta tudo num pedido só, na ordem que evita o chute

1. Descreva o comportamento relatado com a sequência de passos. Não é "está quebrado", é "usuário faz A, depois B, e na etapa C aparece esta mensagem". O erro comum aqui é resumir o relato e perder justamente o passo que só a outra pessoa fez

2. Aponte o caminho do código suspeito. A documentação de boas práticas usa exatamente esse espírito: em vez de "conserte o bug de login", dizer que usuários relatam falha de login após expirar a sessão, apontar o fluxo de auth em src/auth/ e especialmente o refresh de token. O erro comum é apontar o arquivo errado com confiança e o agente ir atrás da sua hipótese em vez do problema

3. Peça um teste que FALHE reproduzindo o problema, antes da correção. Essa é a virada de chave: enquanto não existe teste vermelho, você não reproduziu nada, só acreditou. O erro comum é aceitar um teste que passa de primeira, porque ele não está reproduzindo coisa nenhuma

4. Entregue uma verificação que o agente rode sozinho. Pode ser uma suíte de testes, o código de saída de um build, um linter, um script que compara a saída com um fixture ou um screenshot comparado ao design. O erro comum é deixar a verificação por sua conta e virar gargalo humano no meio do loop

5. Só então autorize a correção. Com passos, caminho, teste vermelho e verificação na mesa, o agente trabalha com evidência. O erro comum é liberar a correção junto com o diagnóstico e nunca saber qual mudança resolveu

6. Confira com a skill embutida /verify. Ela sobe o app e confere a mudança contra o app rodando, inferindo como subir pelo tipo de projeto (CLI, servidor, TUI, navegador) e pelo que está no README, no package.json ou no Makefile. Ela não roda sozinha, precisa ser invocada, e quando precisa descobrir do zero como subir e dirigir o app, grava a receita que funcionou em .claude/skills/verify/SKILL.md na raiz do repositório (ou no diretório do pacote alterado, em monorepo). O erro comum é esperar que ela dispare automática e concluir que "não fez nada"

7. Se a tentativa piorou o estado, volte com /rewind. Ele volta código e conversa para um checkpoint anterior, ou resume parte da conversa. O erro comum é seguir empilhando correção em cima de correção e perder a referência do que estava funcionando

Quatro cenários comuns e o que coletar em cada um

Nem sempre você tem acesso à máquina de quem viu o erro, e isso muda o que dá pra exigir

Repara no padrão: quanto menos acesso você tem, mais o peso cai na sequência de passos e nos dados de entrada

E quanto mais acesso você tem, mais rápido dá pra separar "é o app" de "é o setup dele"

Conclusão

Bug que não reproduz não se resolve com prompt esperto, se resolve com material

Contexto específico, mais um teste que falha reproduzindo o problema, mais uma verificação que o agente roda sozinho: essa trinca vale mais que qualquer frase mágica no prompt

Próximo passo prático, hoje mesmo: salva aquele roteiro de coleta como template fixo do time

E no próximo relato que chegar, segura a vontade de pedir a correção e começa pelo teste que reproduz

A correção vem depois, e vem certa 🙂

até o próximo post!