Reprodução mínima de bugs: isole o erro antes de consultar uma IA

Quando um erro aparece em um projeto real, a primeira reação costuma ser enviar para a IA uma pasta inteira, um log enorme e a pergunta “por que não funciona?”. Isso entrega contexto demais e, ao mesmo tempo, esconde o que realmente importa. Dependências, dados antigos, extensões, variáveis de ambiente e efeitos de uma execução anterior passam a competir com o sintoma.

Uma reprodução mínima faz o movimento contrário. Ela preserva apenas o menor conjunto de código, configuração, entrada e passos que ainda produz o mesmo erro. O objetivo não é deixar o caso curto a qualquer custo, mas torná-lo executável, comparável e seguro para outra pessoa ou ferramenta analisar.

Resultado esperado

Ao final, você terá uma pasta separada do projeto principal com um caso pequeno que reproduz o bug, instruções curtas, versões relevantes, entrada sintética e saída observada. Esse pacote poderá ser usado em uma conversa com IA, em uma revisão interna ou em um relatório de bug sem expor o repositório completo.

O método melhora a qualidade do diagnóstico, mas não garante que a IA encontrará a causa. Problemas de concorrência, desempenho, rede, hardware, permissões ou dados de produção podem resistir à redução. Nesses casos, o caso mínimo ajuda a registrar exatamente onde a reprodução deixa de funcionar.

Pré-requisitos

• permissão para analisar o código e compartilhar o trecho escolhido;
• uma cópia de trabalho ou branch descartável, nunca a única cópia do projeto;
• um ambiente em que seja seguro repetir o erro;
• o comando, ação ou requisição que aciona o problema;
• tempo para testar cada redução, em vez de remover vários elementos de uma vez;
• um editor de texto para criar o arquivo README.md do caso.

Não reproduza falhas destrutivas com dados reais, credenciais válidas ou integrações de produção. Se o sintoma envolve pagamento, envio de mensagens, exclusão, infraestrutura ou dados pessoais, troque os destinos por ambientes de teste antes de começar.

Passo 1: escreva o contrato do bug

Antes de mexer no código, registre quatro itens em frases separadas:

• entrada: o dado ou ação que inicia o fluxo;
• resultado esperado: o comportamento definido por requisito, documentação ou teste;
• resultado observado: o que realmente ocorreu, sem interpretação;
• frequência: sempre, às vezes ou somente sob uma condição conhecida.

“A tela quebra” não basta. Prefira algo como: “Ao enviar um formulário com o campo nome vazio, a API deveria responder 400 com uma mensagem de validação. Ela responde 500 e registra TypeError na função normalizarNome”. Essa descrição delimita uma diferença testável.

Separe fatos de hipóteses. “A resposta foi 500” é fato observado. “A biblioteca de validação está com defeito” ainda é hipótese. Se você misturar os dois, a IA tende a aceitar a explicação sugerida e explorar menos alternativas.

Passo 2: preserve o estado antes de reduzir

Salve o identificador do commit, o estado dos arquivos modificados e as versões relevantes. Em um projeto Git, estes comandos ajudam a registrar o ponto de partida sem alterar arquivos:

git rev-parse HEAD
git status --short
git diff --stat

Se houver mudanças ainda não registradas, não as descarte para “limpar” o ambiente. Faça uma cópia autorizada ou crie uma branch de investigação conforme o fluxo da equipe. A reprodução mínima deve ser reversível e não pode colocar o trabalho original em risco.

Anote também data, sistema operacional, arquitetura, runtime e versão das dependências diretamente ligadas ao erro. Não despeje a lista inteira no primeiro momento. Um problema em uma requisição HTTP pode precisar da versão do runtime e do cliente usado, mas não de cada pacote de interface do projeto.

Passo 3: comece de fora do projeto principal

Crie uma pasta nova e copie somente o primeiro arquivo que parece necessário. Adicione o comando de execução e tente reproduzir. Se faltou configuração, função ou dado, acrescente apenas esse elemento e teste novamente.

Essa abordagem, construída do zero, costuma funcionar bem quando o fluxo pode ser representado por poucas funções. Em sistemas maiores, use a rota inversa: copie o trecho relevante para uma área de teste e remova uma camada por vez. Depois de cada remoção, execute exatamente o mesmo caso.

Quando o bug desaparece, restaure o último elemento removido. Ele pode não ser a causa, mas marca uma dependência necessária para o sintoma. Registre essa transição no README, porque “sem este middleware o erro não ocorre” vale mais do que um palpite sobre o middleware.

Passo 4: reduza código, configuração e entrada separadamente

Há três dimensões diferentes para simplificar:

1. Código: remova telas, rotas, funções, estilos e integrações não percorridos pelo caso.
2. Configuração: conserve somente opções necessárias para iniciar e alcançar o erro.
3. Entrada: diminua o arquivo, payload ou sequência de ações até restar o menor exemplo que mantém o comportamento.

Altere uma dimensão por vez. Se você troca a entrada, atualiza dependências e remove duas funções na mesma rodada, não saberá qual mudança eliminou o bug. O ganho vem da comparação controlada entre uma execução e a seguinte.

Minimalidade não significa código ilegível. Use nomes simples, mantenha indentação e deixe comentários apenas onde explicam uma condição indispensável. Imagens de código impedem a execução e dificultam busca e cópia; compartilhe o texto do código.

Passo 5: substitua dados reais por dados sintéticos

Se o erro depende de uma planilha, JSON, imagem ou registro de banco, não envie a base original por conveniência. Construa uma amostra falsa que preserve somente a forma necessária: mesmos tipos, campos obrigatórios, codificação e condição de borda.

Por exemplo, um problema causado por um sobrenome com apóstrofo não precisa do cadastro verdadeiro. Use um nome fictício com o mesmo caractere. Um erro em um identificador longo pode ser reproduzido com um valor sintético de igual comprimento. Se a troca fizer o problema desaparecer, registre quais características do dado parecem necessárias e mantenha o original fora da conversa.

Revise também logs, URLs e cabeçalhos. Tokens, chaves de API, cookies, strings de conexão, e-mails, caminhos internos e identificadores de clientes podem aparecer em mensagens de erro. A orientação de segurança não é ocultar apenas o campo chamado “senha”; é remover qualquer dado que conceda acesso ou identifique pessoas e ambientes.

Para um roteiro específico, use o guia do Bastidores sobre como minimizar e mascarar logs antes de pedir diagnóstico à IA.

Passo 6: fixe o ambiente relevante

O caso deve informar as versões que mudam o comportamento. Inclua runtime, framework, dependência envolvida, sistema operacional quando pertinente e qualquer opção não padrão. Prefira arquivos de lock ou comandos de instalação determinísticos, sem publicar credenciais de repositórios privados.

Não afirme que o bug “só acontece na versão X” sem comparação. Se possível, execute o mesmo caso na última versão conhecida como funcional e na primeira versão em que falha. Registre os dois resultados. Essa fronteira reduz o espaço de investigação sem transformar correlação em causa.

Extensões de editor, plugins, cache e variáveis de ambiente também contam. A Microsoft recomenda recriar problemas após desabilitar extensões quando isso for aplicável. Faça esse teste em cópia segura e registre a diferença, sem desmontar o ambiente principal.

Passo 7: registre um único caminho de reprodução

Escreva passos numerados que outra pessoa consiga seguir sem conhecer o projeto. Comece pelo estado inicial e termine no sintoma:

1. instale as dependências com o comando informado;
2. inicie o exemplo;
3. envie a entrada sintética incluída;
4. observe o código de resposta e a mensagem indicada.

Copie a mensagem de erro completa como texto e destaque a primeira linha relevante da pilha, sem apagar o contexto técnico necessário. Se a saída muda a cada execução, marque as partes variáveis. Uma captura pode complementar o relatório, mas não substitui passos nem texto copiável.

Passo 8: confirme que o caso ainda é reproduzível

Feche processos, limpe apenas artefatos descartáveis documentados e execute o roteiro a partir do estado inicial. Depois, repita. Se o erro ocorre uma vez em dez, diga isso e registre as dez tentativas. Não descreva uma falha intermitente como determinística.

Quando possível, mova a pasta para outro caminho ou use um ambiente limpo. Se o caso só funciona na sua máquina, verifique dependências implícitas: arquivo fora da pasta, variável global, serviço já iniciado, cache, permissão ou configuração do usuário.

Para código desconhecido ou sugerido por IA, use um ambiente isolado e sem dados reais. O guia sobre teste no Windows Sandbox com rede desligada e arquivos somente leitura explica como limitar o impacto, mas não transforma código não revisado em seguro.

Passo 9: monte o pacote mínimo

Uma estrutura simples pode conter:

reproducao-bug/
  README.md
  entrada-exemplo.json
  codigo-minimo.ext
  arquivo-de-dependencias

No README, inclua objetivo, ambiente, instalação, comando exato, entrada, resultado esperado, resultado observado e frequência. Liste também o que foi removido durante a redução e qualquer condição sem a qual o bug desaparece.

Abra cada arquivo antes de compartilhar. Faça uma busca por padrões de segredo e confirme que a pasta não contém .env, chave privada, histórico Git, banco local, cache, dump ou arquivo gerado desnecessário. O GitHub oferece proteção contra envio de segredos conhecidos, mas um bloqueio automático não substitui a revisão humana e não detecta todo dado sensível.

Passo 10: peça análise à IA sem entregar a conclusão

Apresente o material em ordem. Um pedido útil pode seguir este modelo:

Objetivo: explicar a causa provável deste erro.
Esperado: [comportamento verificável].
Observado: [comportamento e erro exato].
Reprodução: [comando e passos].
Ambiente: [versões relevantes].
Arquivos: [lista curta].

Separe fatos de hipóteses. Liste até três causas em ordem de probabilidade,
indique qual evidência favorece cada uma e proponha primeiro testes
reversíveis que não alterem produção nem apaguem dados.

Evite começar com “a causa é a biblioteca X”. Peça que a ferramenta mostre quais linhas e evidências sustentam cada hipótese. Se uma informação estiver ausente, a resposta correta pode ser solicitar um teste adicional, não completar a lacuna com suposição.

Passo 11: teste uma sugestão por vez

Não aplique de uma só vez todas as mudanças propostas pela IA. Escolha o teste mais seguro e discriminatório, registre o estado anterior, execute e anote o resultado. Uma correção aparente pode apenas esconder o sintoma ou introduzir outro problema.

Depois de encontrar uma alteração candidata, volte ao projeto real e confirme com testes proporcionais ao risco. Revise o diff, verifique casos vizinhos e preserve uma forma de reversão. O caso mínimo ajuda a explicar a falha, mas o sistema completo ainda pode ter regras que o exemplo não representa.

Erros comuns

Enviar o repositório inteiro como “contexto”

Mais arquivos aumentam ruído e superfície de exposição. Comece pelo caminho mínimo e acrescente uma dependência somente quando ela for necessária para executar ou explicar o erro.

Remover tanto que o erro some

Volte uma etapa e restaure o último elemento. Um exemplo curto que não falha não reproduz o problema.

Compartilhar somente uma captura

A imagem pode mostrar a interface, mas não é executável nem pesquisável. Inclua código, mensagem de erro e passos como texto.

Mascarar o dado e mudar sua forma

Trocar uma string de 200 caracteres por “X” pode eliminar a condição de borda. Preserve tipo, comprimento e caracteres relevantes com valores sintéticos.

Atualizar tudo antes de reproduzir

A atualização pode fazer o sintoma desaparecer sem revelar qual componente mudou. Primeiro registre e reproduza, depois compare versões deliberadamente.

Aceitar a primeira explicação plausível

Uma resposta convincente não é evidência. Exija um teste que diferencie hipóteses e mude uma variável por rodada.

Solução de problemas

O erro desaparece na pasta mínima

Liste diferenças entre o projeto real e o caso: configuração, permissões, cache, serviço externo, extensão, volume de dados e ordem de execução. Reintroduza uma diferença por vez.

O caso funciona somente com dados reais

Não publique a base. Identifique propriedades estruturais do menor registro que falha e crie uma amostra sintética equivalente. Se isso não for possível, mantenha o diagnóstico em ambiente autorizado e restrito.

Outra pessoa não consegue reproduzir

Peça a ela o primeiro ponto de divergência, não apenas “funcionou aqui”. Compare comando, versão, diretório atual, variáveis necessárias e saída de instalação.

A IA pede mais arquivos

Solicite a justificativa de cada arquivo. Revise conteúdo e permissões antes de acrescentá-lo. Nunca envie segredo ou dado pessoal para satisfazer uma suposição do modelo.

O problema é intermitente

Registre número de tentativas, intervalo, carga, concorrência e timestamps. Não force uma narrativa determinística. Talvez o artefato mínimo seja um teste repetível que mede frequência, não uma execução que falha sempre.

O que este método não garante

Uma reprodução mínima não prova sozinha a causa raiz, não valida a correção no sistema completo e não autoriza compartilhar código proprietário. Também pode não capturar falhas ligadas a produção, integrações de terceiros, dados regulados, hardware específico ou temporização.

Se a redução exigir abrir arquivos desconhecidos, executar scripts externos ou expor rede e credenciais, interrompa o processo e envolva a equipe responsável. O caso deve diminuir o risco do diagnóstico, não criar um incidente novo.

Checklist antes de enviar

• O esperado e o observado estão descritos separadamente?
• Existe um comando ou sequência exata de reprodução?
• O exemplo contém todos os arquivos necessários e nenhum arquivo irrelevante?
• O erro foi reproduzido novamente após a última redução?
• Versões e condições relevantes foram registradas?
• Dados reais foram substituídos por amostras sintéticas equivalentes?
• Segredos, credenciais, dados pessoais e caminhos internos foram removidos?
• Fatos estão separados de hipóteses?
• A IA foi orientada a propor testes reversíveis antes de mudanças?
• A correção candidata será validada também no projeto completo?

Ilustração editorial exclusiva do Bastidores da IA. Não é captura de tela de produto ou sistema real.

Fontes consultadas em 7 de setembro de 2026

• Stack Overflow Help Center: como criar um exemplo mínimo e reproduzível
• Microsoft Learn: orientações para um bom relatório de bug
• Microsoft Learn: como relatar um problema e registrar passos de reprodução
• GitHub Docs: proteção contra envio de segredos
• OWASP Cheat Sheet Series: codificação segura com IA