Mexer até funcionar não é entender: depure com hipótese e registro

Quinta, 17h, o upload de imagens parou de funcionar no painel. Em duas horas, a Paula atualizou três bibliotecas, mudou o limite de tamanho no servidor, trocou o formato da requisição e limpou o cache. O upload voltou. Ninguém sabe qual das seis mudanças resolveu, e cinco delas continuam no código. A resposta curta: antes de cada mudança, escreva o que você espera que aconteça e como vai verificar; mude uma coisa por vez; e desfaça o que não fez diferença. Tentativa sem hipótese até resolve, mas deixa um sistema que ninguém consegue explicar.

Jogos de combinar elementos, em que você junta dois ícones e nasce um terceiro, são divertidos justamente porque o feedback é imediato e não há custo em errar. No software, cada combinação deixa rastro: dependência nova, configuração alterada, comportamento escondido.

Por que combinar até dar certo cobra juros

Quando várias mudanças acontecem juntas e o problema some, você não tem como saber a causa. Talvez uma resolveu e as outras são neutras. Talvez uma resolveu e outra criou um problema que só aparece com outro tipo de arquivo. Talvez o problema era intermitente e sumiu sozinho.

O resultado aparece semanas depois. Alguém pergunta por que aquela biblioteca está numa versão específica, ou por que o limite do servidor é 50 MB, e a resposta é "estava assim quando funcionou". Isso é superstição técnica: ninguém mexe com medo de quebrar, e o sistema acumula peças que ninguém entende.

Há também o custo imediato. Mudar várias coisas ao mesmo tempo torna cada tentativa mais lenta de avaliar e mais difícil de desfazer. Uma mudança por vez parece mais lenta, mas converge mais rápido, porque cada passo elimina uma possibilidade.

O ciclo hipótese, mudança, verificação

1. Reproduza o problema de forma confiável. Descubra o menor passo a passo que faz o erro aparecer sempre. Sem isso, você não sabe se resolveu.
2. Colete fatos antes de mexer: mensagem de erro completa, log do servidor, código de status, o que mudou recentemente.
3. Escreva uma hipótese no formato "acho que X causa o erro; se eu mudar Y, espero ver Z".
4. Faça uma única mudança que testa essa hipótese.
5. Verifique o resultado com o mesmo passo a passo da reprodução.
6. Se não mudou nada, desfaça antes da próxima hipótese.
7. Registre em uma linha o que tentou e o que viu.

Exemplo trabalhado: o upload da Paula, do jeito certo

Refazendo a tarde com o ciclo, a Paula começa reproduzindo: imagem de 3 MB falha, imagem de 500 KB funciona. Já é um fato importante. O log do servidor mostra status 413, que significa corpo da requisição grande demais. O registro dela fica assim:

Problema: upload de imagem falha no painel (desde terça)
Reprodução: enviar foto-teste-3mb.jpg -> falha; foto-500kb.jpg -> ok
Fato: proxy responde 413 Request Entity Too Large

H1: o limite de corpo no proxy reverso é menor que 3 MB.
    Mudança: subir o limite do proxy para 10 MB.
    Esperado: 3 MB passa.
    Resultado: passou. 8 MB também passa; 12 MB falha com 413.
    Conclusão: CONFIRMADA.

Pergunta seguinte: por que começou na terça?
Fato: deploy de terça trocou a configuração do proxy pelo
      modelo padrão, que tem limite menor.
Ação: limite de 10 MB versionado junto com a configuração do proxy,
      com comentário explicando que o painel aceita fotos até 10 MB.

Uma hipótese, uma mudança, um resultado claro. Nenhuma biblioteca foi atualizada sem necessidade, e a causa raiz (o deploy de terça) foi encontrada, o que evita que o problema volte no próximo deploy. Para entender o código 413 e os vizinhos dele, veja o guia de códigos de status HTTP.

Quando você não sabe o que mudou: git bisect

Se o problema apareceu em algum momento e você não sabe em qual commit, o Git consegue fazer a busca binária por você. Você marca um commit bom e um ruim, e ele vai testando o meio até achar o primeiro commit ruim.

git bisect start
git bisect bad                 # o commit atual tem o erro
git bisect good v2.3.0         # esta versão funcionava

# O Git faz checkout de um commit no meio. Teste e responda:
git bisect good                # ou: git bisect bad

# Repita até ele mostrar "is the first bad commit".
# Se existir um teste automatizado que falha com o erro:
git bisect run npm test

git bisect reset               # volta para onde você estava

Com centenas de commits entre o bom e o ruim, a busca leva poucos passos, porque cada teste corta as possibilidades pela metade. O git bisect run aceita qualquer comando que termine com código zero quando está bom e diferente de zero quando está ruim.

Como limpar o que ficou da tentativa e erro

Se você já está na situação da Paula original, com seis mudanças e o problema resolvido, ainda dá para recuperar o entendimento. Crie um branch, desfaça as mudanças uma de cada vez e teste depois de cada uma. A que trouxer o erro de volta é a necessária; as outras podem sair. Se precisar desfazer um commit inteiro, o guia sobre desfazer o último commit mostra o caminho seguro.

Ao terminar, transforme o registro de tentativas numa mensagem de commit ou num comentário curto ao lado da configuração. Duas frases bastam: qual era o sintoma e por que esta mudança o resolve. Quem abrir aquele arquivo daqui a seis meses, inclusive você, vai saber que a linha tem motivo e o que esperar se ela for removida.

Erros comuns

• Mudar várias coisas de uma vez: quando funciona, você não sabe por quê; quando piora, não sabe o que desfazer.
• Começar sem reprodução confiável: o erro some por acaso e você acredita que a última mudança resolveu.
• Atualizar dependência como primeira tentativa: traz mudanças não relacionadas e pode criar problemas novos.
• Deixar no código as mudanças que não ajudaram: o sistema acumula configuração sem motivo, que ninguém ousa remover.
• Não registrar as tentativas: você ou um colega repete a mesma hipótese descartada no dia seguinte.
• Parar no sintoma: resolver o 413 sem descobrir que o deploy trocou a configuração garante a volta do erro.

Checklist

• Tenho um passo a passo que reproduz o erro sempre.
• Coletei mensagem de erro, log e o que mudou recentemente antes de mexer.
• Cada tentativa tem uma hipótese escrita e um resultado esperado.
• Fiz uma mudança por vez e desfiz as que não tiveram efeito.
• Usei git bisect quando não sabia em que momento o erro começou.
• A correção final está versionada com uma frase explicando o motivo.
• Encontrei a causa raiz, não só o sintoma.

Curiosidade e experimentação são ótimas; sem registro, viram superstição. Olhe o último componente ou configuração que você adicionou ao projeto: existe, no commit ou no código, uma frase dizendo por que ele está lá e o que quebra se for removido?