Modelo de relatório de bug que funciona (e como automatizar a maior parte)

QADenis Povarov25 de agosto de 2026

Pesquise «modelo de relatório de bug» e você vai encontrar cem variações do mesmo formulário. Título, ambiente, passos para reproduzir, resultado esperado, resultado real, severidade, capturas de tela. Copie para o seu issue tracker e, em um mês, praticamente ninguém mais o preenche.

Isso costuma ser diagnosticado como falta de disciplina. Não é. É um problema de design: o modelo pede a uma pessoa que transcreva informações que uma máquina já tem, e as pessoas, com razão, se recusam a fazer um trabalho tedioso sem retorno visível.

Por isso este post tem duas metades. Primeiro, um modelo para copiar que vale a pena manter. Depois, o argumento mais útil — quais campos apagar, porque outra coisa deveria preenchê-los.

O modelo

## Resumo
Uma frase. O que está quebrado, do ponto de vista do usuário.

## Passos para reproduzir
1.
2.
3.

## Resultado esperado
O que você achou que ia acontecer.

## Resultado real
O que aconteceu em vez disso.

## Impacto
Quem é afetado, com que frequência e se existe alguma alternativa.

## Ambiente
Navegador / sistema operacional / dispositivo / versão do app / URL / tipo de conta logada

## Evidências
Captura de tela, gravação, saída do console, requisição que falhou, ID da requisição

É isso. Nada aqui é novidade — o valor está no propósito real de cada campo, e é aí que a maioria dos modelos erra.

Resumo

O campo mais mal preenchido. Um bom resumo é escrito de fora: «O botão de finalizar compra não faz nada na etapa de pagamento com cartões salvos.» Um ruim é escrito de dentro de um palpite: «Condição de corrida no token do Stripe.»

Palpites no título são corrosivos porque ancoram todo mundo que lê o relatório depois. Metade do tempo de triagem de bugs com títulos ruins vai para derrubar um diagnóstico que quem reportou inventou e ninguém questionou.

Peça a observação. O diagnóstico é trabalho de quem corrige.

Passos para reproduzir

O campo que todo mundo sabe que importa e quase todo mundo preenche mal, de um jeito específico: quem reporta escreve os passos que acredita serem relevantes, e não os passos que seguiu.

A pessoa pula «eu estava com duas abas abertas». Pula «eu estava na página fazia uma hora». Pula «entrei pelo link do e-mail, não pelo menu». Essas omissões costumam ser o bug.

A instrução que ajuda: escreva o que você fez, a partir do momento em que abriu a página, incluindo as partes chatas.

O estado inicial importa tanto quanto as ações. Logado como quem? Com que dados já na conta? Em qual plano? Uma reprodução que começa numa conta nova muitas vezes não reproduz.

Resultado esperado e resultado real

Ao lado do resumo, parecem redundantes. Mantenha os dois mesmo assim.

Separá-los pega toda uma classe de relatórios que não são bugs: casos em que o software se comporta exatamente como foi projetado e o usuário esperava outra coisa. Isso é real e vale saber — é um bug de documentação, ou de UX, ou do discurso de vendas —, mas não é um defeito de código, e identificar isso na triagem custa muito menos do que depois de dois dias de investigação.

O par também força precisão. «Não funciona» não sobrevive à divisão em esperado e real. Deixar uma das duas caixas vaga fica constrangedor.

Impacto

O campo que a maioria dos modelos deixa de fora, e o que mais determina o que acontece em seguida.

Dropdowns de severidade não funcionam. Todo mundo que reporta escolhe «Alta», porque, para quem está com a tarefa travada, tudo parece grave. Em vez disso, peça as três coisas que a severidade tenta medir:

Quem — só eu, todo mundo da minha equipe, todo cliente no Safari?
Com que frequência — uma vez, toda vez, mais ou menos uma em dez?
Alternativa — existe outro jeito de fazer o trabalho?

«Toda vez, todos os usuários de celular, sem alternativa» e «uma vez, só eu, atualizar resolve» se ordenam sozinhos, sem ninguém mexer num dropdown. E «uma em dez» diz mais do que parece: intermitente significa condição de corrida, cache ou dependência de carga, e isso define onde o desenvolvedor vai procurar antes mesmo de começar a procurar.

Ambiente

Necessário, e o pior uso do tempo de uma pessoa desta lista inteira. Guarde essa ideia.

Evidências

Capturas de tela são o padrão, e são a forma de evidência mais fraca entre as comuns. Uma captura de tela prova que a página parecia errada. Não diz nada sobre o porquê.

Em ordem do que de fato resolve bugs:

A requisição que falhou — método, URL, status, corpo da resposta e um ID de requisição ou de trace, se houver. Um ID de requisição transforma um relatório do lado do cliente numa busca nos logs do servidor, que é o caminho mais curto que existe do relatório até a causa raiz.
O erro do console com o stack — aponta para uma linha de código.
Uma gravação de tela — mostra o timing e a sequência, o que capturas de tela não conseguem.
Uma captura de tela — mostra o estado final.

A maioria dos modelos pede a quarta e nunca menciona as três primeiras, porque as três primeiras exigem o DevTools, e quem reporta não está com o DevTools aberto.

Agora apague a maior parte

Volte ao modelo e separe os campos por quem consegue preenchê-los.

Só uma pessoa consegue preencher: resumo, passos para reproduzir, esperado e a parte de «quem e com que frequência» do impacto. Esses campos exigem intenção. Nenhuma instrumentação sabe o que alguém estava tentando fazer ou o que esperava ver.

Uma máquina preenche melhor: ambiente, comportamento real e os quatro tipos de evidência.

Cada campo do segundo grupo é um campo em que você pede a uma pessoa para fazer um trabalho pior do que um script faria, e paga por isso em relatórios abandonados.

Pense no que «Ambiente» realmente pede. Navegador e versão exata — a maioria das pessoas não sabe onde achar. Versão do sistema operacional — idem. Tamanho da viewport — ninguém sabe, e é justamente o campo que explicaria o bug de layout. URL da página — a pessoa vai colar a URL da página em que está agora, que é o seu formulário de suporte. Versão do app ou hash do build — invisível para ela, de propósito.

Seis dados, cada um trivial de ler no navegador, cada um exigindo uma ida e volta com o suporte quando se pede a uma pessoa que os informe.

O mesmo argumento vale ainda mais para as evidências. Você está pedindo a um usuário não técnico que abra o DevTools, encontre a aba de rede, reproduza o bug, descubra qual de duzentas requisições é a relevante e copie a resposta dela. É um pedido que ele não vai atender. E é uma linha de instrumentação.

Como o formulário deveria ser

Reduza-o ao que só uma pessoa sabe:

## O que deu errado?
[texto livre]

## O que você esperava que acontecesse?
[texto livre]

## Isso já aconteceu antes?
( ) Primeira vez  ( ) Às vezes  ( ) Toda vez

Três campos. Trinta segundos. Enquanto isso, o relatório chega com o navegador, o sistema operacional, a viewport, a URL, o console com tudo o que foi registrado antes de o relatório ser aberto, o log de rede com status e tempos, um replay de sessão dos últimos minutos e os cliques e entradas do usuário em ordem.

Essa é a troca de que trata todo o exercício: a pessoa escreve a frase que só ela pode escrever, e a máquina anexa todo o resto.

É isso que o BugDump faz. Uma tag de script coloca um botão de relatório na página; o usuário digita o que deu errado; o relatório chega com a telemetria já anexada, junto com uma captura de tela anotada que ele pode desfocar antes que ela saia do navegador. O plano Grátis tem 500 relatórios por projeto.

Duas coisas para continuar fazendo à mão

Automatizar a captura não automatiza tudo, e vale deixar claros os limites.

A triagem ainda precisa de uma pessoa. Doze relatórios do mesmo checkout quebrado devem virar uma tarefa com doze evidências, e só uma pessoa reconhece que são o mesmo bug. É nesse agrupamento que relatórios duplicados deixam de ser ruído e viram dados — doze relatórios em cinco navegadores e dois sistemas operacionais formam uma matriz, e o padrão nela costuma apontar a causa. O BugDump modela isso diretamente: relatórios são evidências, tarefas são o que você corrige, e muitos relatórios se ligam a uma tarefa.

Fechar o ciclo ainda precisa de uma pessoa. Um relatório enviado para o vazio ensina alguém a não reportar de novo. Seja qual for a ferramenta, quem reportou precisa ver que aquilo que enviou andou. Dê a essa pessoa uma página de status, ou mande uma mensagem quando a correção for lançada — um portal público em que ela acompanhe a tarefa ir de Confirmado para Concluído é a versão mais barata disso que funciona.

Modelos são um substituto para o objetivo real, que é um relatório com que um desenvolvedor consiga agir sem fazer mais perguntas. Se um formulário leva você até lá, use o modelo acima. Se a instrumentação leva você até lá sem formulário, isso é estritamente melhor — o melhor modelo de relatório de bug é aquele que ninguém precisa preencher.