Log de erro gigante: quanto do stack trace colar no Claude Code?

Fala aí, beleza? O erro estoura umas 400 linhas no terminal, tu dá aquele Ctrl+A, Ctrl+C, joga tudo no chat e espera mágica…

E volta uma resposta genérica, do tipo "verifique se o objeto existe antes de acessar a propriedade", que serve pra qualquer projeto do planeta

Só que o problema não é o Claude Code ser ruim de ler log

É o recorte

Um stack trace gigante é quase todo ruído: frames de biblioteca, frames de runtime, camadas de framework que tu nunca vai abrir pra editar. O sinal mora em três pedaços, e separar esses três é o assunto do post

E quando o log é tão grande que nem cabe no prompt (log de build, log de produção com milhares de linhas), também tem saída: em vez de transportar o texto pelo chat, tu dá acesso ao arquivo

Bora ver na prática?

Como recortar um log gigante em 4 passos

A documentação oficial descreve o fluxo de depuração do Claude Code assim: tu cola a mensagem de erro (ou descreve o sintoma) e ele rastreia o problema pelo código, identifica a causa raiz e implementa a correção

Se liga no detalhe: o trabalho dele é RASTREAR pelo teu codebase

Então o que tu cola não precisa conter o mundo, precisa conter os pontos de partida certos

Vale um aviso antes: esse recorte é pra erro que acontece dentro do teu projeto. Se o teu erro aparece antes disso, na hora de configurar a ferramenta, o caminho é outro e passa pelos erros comuns na instalação do Claude Code

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

1. Pegue a linha da exceção INTEIRA

É a linha que traz o tipo da exceção e a mensagem junto. Dependendo da linguagem ela fica no topo do rastro, em outras fica lá no fim, procura com calma

Essa linha é o que diferencia "alguma coisa está undefined" de "a propriedade id foi lida de algo undefined"

O erro comum deste passo: cortar a mensagem e deixar só o tipo. TypeError sozinho não diz nada, quem carrega a pista é o texto depois dos dois pontos

2. Varra o rastro e mantenha só os frames com caminho do teu repositório

Vai passando os frames e pergunta: esse arquivo é meu? Se o caminho tem node_modules, site-packages, vendor ou runtime da linguagem, corta

Normalmente sobram dois ou três frames, e são justamente os arquivos que tu pode editar

O erro comum deste passo: manter dezenas de frames de node_modules "pra dar contexto". Isso não é contexto, é volume, e volume tem custo (já chego lá)

3. Cole o comando exato que reproduziu o erro

npm run build, pytest tests/test_auth.py -k session, php artisan migrate, o que foi

Sem isso ele não sabe se o estouro veio de teste, de build, de servidor de dev ou de uma rota específica que tu abriu no navegador

O erro comum deste passo: achar que o comando é óbvio. Pra ti é, pra quem chegou agora na conversa não

4. Aponte os arquivos suspeitos com @

No Claude Code tu referencia arquivo com @ dentro do prompt, tipo @src/auth/login.ts, e dá pra referenciar vários arquivos na mesma mensagem

A recomendação da documentação é exatamente essa: colar o material bruto (erro, log, saída) ou apontar o arquivo com @, em vez de descrever a coisa com as tuas palavras. Ele lê a fonte, não a tua interpretação da fonte

O erro comum deste passo: escrever "o erro tá no arquivo de login da pasta auth" e deixar ele caçar. Referenciar com @ é mais barato pros dois lados

O recorte final fica com essa cara:

TypeError: Cannot read properties of undefined (reading 'id')
    at getUserSession (src/auth/login.ts:42:19)
    at handler (src/api/routes/user.ts:17:5)

Reproduzi com: npm run dev e depois POST /api/user/session
Suspeitos: @src/auth/login.ts @src/api/routes/user.ts

Três linhas de rastro, um comando, dois arquivos apontados

É isso, beleza? 🙂

Colei o log inteiro e o Claude Code respondeu genérico

Sintoma: a resposta vem vaga, as sugestões ignoram o teu código (parecem tiradas de tutorial genérico) e, pior, a qualidade vai caindo conforme a conversa segue

Causa: o log inteiro ocupa a janela de contexto. O Claude Code mostra um indicador ao vivo de quão cheia ela está, e quando enche o modelo deixa de enxergar com clareza as partes mais antigas da conversa, aí a qualidade cai

Ou seja: aquelas 400 linhas não foram "mais informação", foram informação empurrando informação

Solução: recortar ANTES de colar, usando os 4 passos ali de cima

E se tu já está no meio da bagunça, roda /context: ele mostra o que está ocupando a janela de contexto, por componente. Dá pra ver com os próprios olhos quem está comendo o espaço

Prevenção: manda o recorte de três partes (exceção + frames do teu projeto + comando) já na PRIMEIRA mensagem. É mais fácil acrescentar depois do que tirar

Colei só a última linha do erro e ele chutou a correção

Sintoma: o Claude Code propõe mudança num arquivo que não tem nada a ver com o teu problema, ou devolve a bola pedindo pra tu rodar de novo e mostrar mais

O oposto do problema anterior, e igualmente irritante

Causa: sem os frames do teu código e sem o comando que reproduziu, sobrou só o nome da exceção. O rastreio pelo codebase começa no escuro, e o que ele faz com pouca pista é o que qualquer um faria: chutar o suspeito mais comum

Solução: devolver os dois elementos que faltaram, o frame do teu projeto e o comando de reprodução

O fluxo documentado é colar o erro e deixar o Claude Code rastrear até a causa raiz. Ele só consegue rastrear se tiver de onde partir

Isso vale até fora do código, viu? Erro de terminal costuma trazer a pista na própria mensagem, e ler a mensagem do npm com calma resolve muita coisa antes de qualquer prompt

Prevenção: trate o comando de reprodução como parte obrigatória do prompt, tipo cinto de segurança. Exceção sem comando é metade do recado

O log é grande demais para colar no prompt

Sintoma: log de build ou de produção com milhares de linhas. Recortar no olho é inviável, e tu nem sabe onde o erro relevante começa

Causa: tu está tentando TRANSPORTAR o arquivo pelo chat, quando o que resolve é dar ACESSO ao arquivo

Solução: canalizar o conteúdo direto pro Claude Code, que é uma das práticas descritas no guia de boas práticas da Anthropic

cat error.log | claude

No modo headless dá pra já mandar a pergunta junto:

cat build-error.txt | claude -p 'concisely explain the root cause of this build error'

Tome cuidado com o teto aqui: o stdin canalizado é limitado a 10MB. Passando disso, o Claude Code encerra com erro e status diferente de zero, e a orientação oficial é gravar o conteúdo num arquivo e referenciar o caminho no prompt

E aí entra outra coisa que confunde bastante gente: arquivo grande não vem inteiro de uma vez

A ferramenta Read aceita file_path, offset (linha inicial) e limit (quantidade de linhas). Quando a leitura do arquivo todo estoura o limite de tokens, ela devolve a primeira página com um aviso de visão PARCIAL, dizendo como ler o resto com offset e limit

Se tu já sabe o que está procurando, melhor ainda: estreita com a Grep, que filtra por arquivo com o parâmetro glob (tipo **/*.tsx) ou por linguagem com type (tipo py ou rust). Detalhe que já me pegou: ela respeita o .gitignore, então se o teu log está ignorado, passa o caminho direto

Prevenção: salva a saída em arquivo desde o começo, em vez de tentar raspar o terminal depois. Log em arquivo tu lê, recorta e referencia quando quiser

A saída do comando veio cortada no meio

Sintoma: o Claude Code roda o comando, o resultado aparece truncado e justo a linha do erro some. Sensação de estar debugando com um olho fechado

Causa: existe uma variável, BASH_MAX_OUTPUT_LENGTH, que define quantos caracteres da saída voltam pro Claude Code no resultado de um comando. O padrão é 30.000 caracteres, com teto de 150.000

Comando verborrágico passa desse valor fácil, e o que passou não volta

Solução: dá pra trabalhar dentro desse teto de 150.000, mas nem o teto salva log de build gigante

O caminho mais tranquilo é redirecionar a saída pra arquivo e apontar o caminho:

npm run build > build-error.txt

Aí o arquivo vira a fonte, e tu volta pro esquema da seção anterior (canalizar, ou referenciar o caminho e deixar ele ler por páginas)

Prevenção: pra comando que cospe muito texto, grava em arquivo por padrão. Depender da saída direta é aposta

A sessão já está cheia de log antigo

Sintoma: tu colou log demais nas mensagens anteriores, resolveu dois erros no caminho e agora TODA resposta piora, mesmo as perguntas simples

Causa: janela de contexto ocupada por material que já cumpriu a função. Aquele log de meia hora atrás não serve mais pra nada e continua lá, atravessado

Solução: primeiro /context, pra ver o que está ocupando a janela

Depois escolhe a ferramenta certa:

• /compact reduz o histórico resumindo mensagens antigas e preservando o contexto importante
• e ele aceita instrução em texto livre, no formato /compact focus on the auth bug fix, então o resumo guarda o que TU escolheu em vez do que a passagem automática adivinha ser importante
• /clear zera a conversa pra um contexto vazio, quando o histórico antigo virou descartável de vez

Medo de perder tudo com o /clear? A conversa anterior continua salva em disco, relaxa 🙂

E tem mais: o Claude Code compacta automaticamente conforme tu se aproxima do limite da janela, e esse passo automático funciona igual ao /compact. Encher o contexto não encerra a sessão

O ponto é que compactação automática é adivinhação sobre o que importa. Quando TU sabe o que importa, /compact com instrução é bem melhor

Prevenção: limpa entre erros diferentes. Erro novo, contexto novo

O recorte muda conforme o tipo de erro

Não existe receita única, o material bruto é diferente em cada cenário. Se reconhece em um destes três:

Runtime em dev é onde o recorte de três partes brilha, porque tu tem o erro fresco e sabe o comando

Build e CI é onde canalizar o arquivo ganha, porque a pista costuma estar no meio de saída de compilador e não no fim

Produção é o caso em que tu nem sabe qual linha importa, então o jogo é buscar dentro do arquivo em vez de colar pedaço

Conclusão

Precisão vence volume, é isso que fica

Três partes bem escolhidas (a linha da exceção, os frames do TEU código e o comando que reproduziu) valem mais que o log inteiro despejado, porque log inteiro ocupa a janela de contexto e contexto cheio derruba a qualidade das respostas

No próximo erro que estourar, faz assim: cola a exceção completa, mantém só os frames do teu repositório, escreve o comando que reproduziu, referencia os arquivos suspeitos com @ e roda /context antes de jogar qualquer coisa grande na conversa

Se o log for monstruoso, nem tenta colar: cat error.log | claude ou arquivo no disco com o caminho no prompt

E quando a sessão ficar pesada de log velho, /compact com instrução ou /clear sem medo

Até o próximo post! =)