Por que o formato é mais negligenciado que o conteúdo
O formato de um relatório de bug são 10 campos fixos organizados em quatro blocos: identidade → ambiente → sintoma → evidências. Com a ordem fixada, o desenvolvedor sabe exatamente onde procurar, sem perguntar de novo. Abaixo estão a lista completa de campos, as regras de escrita com exemplos bons e ruins para cada campo e os 7 erros de formato que arruínam relatórios que, fora isso, estavam corretos.
A mesma informação escrita em outro formato custa o dobro de tempo para processar. Formato inconsistente causa três problemas:
O valor de um formato não está em parecer organizado, mas em o mesmo campo estar sempre no mesmo lugar.
O formato padrão de um relatório de bug: 10 campos
| # | Campo | Para que serve | Obrigatório? | Como escrever |
|---|---|---|---|---|
| 1 | Título | Permite ao desenvolvedor decidir se abre o ticket | Obrigatório | Componente + ação + resultado inesperado + condição (veja exemplos de título de bug) |
| 2 | ID | Permite que todos citem o mesmo registro | Obrigatório (automático) | BUG-0042, nunca «o de antes» |
| 3 | Gravidade / Prioridade | Base para o planejamento | Recomendado | Gravidade mede o dano, prioridade mede a urgência do negócio — mantenha separadas |
| 4 | Ambiente | Define se o relatório é reproduzível | Obrigatório | URL, versão do navegador, sistema operacional, dispositivo, resolução, conta |
| 5 | Pré-requisitos | O estado inicial para reproduzir | Recomendado | «Logado como conta enterprise, com 2 itens já no carrinho» |
| 6 | Passos para reproduzir | Leva outra pessoa à mesma tela | Obrigatório | Numerados, uma ação por passo (veja como escrever os passos) |
| 7 | Resultado esperado | Base para decidir «isso é um defeito?» | Obrigatório | Descreva o que deveria acontecer, nunca «não funciona direito» |
| 8 | Resultado real | Descrição factual | Obrigatório | Sintoma + números + texto exato do erro, sem suposições |
| 9 | Evidências | Evita que o desenvolvedor refaça tudo | Muito recomendado | Capturas anotadas, gravação de tela, logs de console, requisições com falha |
| 10 | Observações | Contexto adicional | Opcional | Frequência, contornos, tickets relacionados |
Como escrever cada campo
Identidade: título, ID, gravidade e prioridade
- Título: uma linha com onde, o que você fez, o que deu errado e em que condição. 40 exemplos bons e ruins lado a lado: exemplos de título de bug.
- ID: deixe o sistema gerar. Numeração manual sempre gera duplicidade.
- Gravidade vs prioridade: o par que mais acaba fundido em um único campo.
| Campo | Pergunta que responde | Quem decide | Exemplo |
|---|---|---|---|
| Gravidade | Quanto dano o próprio defeito causa? | QA / quem reporta | Perda de dados = crítica; um erro de digitação = leve |
| Prioridade | Quando vamos corrigir? | Produto / lead técnico | Erro de digitação no hero na semana de lançamento = prioridade alta |
Ambiente: ambiente e pré-requisitos
O campo de ambiente precisa cobrir os seis itens: URL, navegador e versão, sistema operacional, dispositivo, resolução ou viewport e tipo de conta. Escrever só «Chrome» equivale a não escrever nada — diferenças de comportamento entre versões de navegador são rotina na web.
O pré-requisito mais esquecido não é o estado de login, mas o estado dos dados: «2 itens no carrinho», «conta no 3º dia do teste», «esse pedido já teve um reembolso». É isso que trava a reprodução.
Sintoma: passos para reproduzir, resultado esperado e resultado real
- Passos para reproduzir: numerados, uma ação por passo, dados reais. O método completo está em como escrever os passos.
- Resultado esperado: descreva o que deveria acontecer e cite a fonte quando possível (um requisito, o ID de um critério de aceite ou simples lógica de negócio). «Deveria funcionar direito» devolve o julgamento ao desenvolvedor.
- Resultado real: apenas fatos, com números e o texto exato do erro. Sem suposições — hipóteses como «provavelmente é cache» vão para Observações, marcadas como «suspeita».
Evidências: capturas / gravações / logs, e observações
- As capturas devem ser anotadas: circule a área do problema e adicione setas ou texto, para ninguém varrer uma captura de tela inteira.
- As gravações devem ter de 10 a 30 segundos e manter só o momento relevante — uma gravação de cinco minutos não será assistida.
- Os logs devem conter apenas o útil: saída de console em nível de erro, requisições de rede com falha (HTTP ≥ 400) e os corpos de requisição e resposta do endpoint envolvido.
- As observações devem trazer duas coisas: a frequência (sempre / intermitente, com probabilidade) e o contorno, se existir.
Diferenças de formato em três canais
| Canal | Como os campos aparecem | A armadilha |
|---|---|---|
| Ferramenta de tickets (Jira / Linear / GitHub Issues) | Campos personalizados + template de descrição | Informações de ambiente no fim da descrição, afogadas no texto — o lugar delas são campos personalizados |
| E-mail ou mensagem (para cliente ou colaborador externo) | Blocos de texto simples | Sem TL;DR, e anexos com nomes aleatórios que obrigam a procurar entre uma dúzia de arquivos |
| Planilha (Excel / Google Sheets / Feishu Bitable) | Uma linha por bug, colunas = campos | A ordem das colunas não bate com os 10 campos e filtro e ordenação se perdem |
O canal muda, os campos não. Informação ausente não é relevada por ter sido enviada por e-mail.
7 erros de formato que arruínam um relatório
captura-1.png, que nem quem enviou consegue associar três dias depois.Checklist de formato
Confirme cada linha antes de enviar:
- Os 10 campos estão presentes, na mesma ordem da última vez?
- Os seis itens de ambiente (URL / navegador / SO / dispositivo / resolução / conta) estão preenchidos?
- Resultado esperado e resultado real escritos separadamente?
- Passos numerados, com uma ação por passo?
- Capturas anotadas e gravações com menos de 30 segundos?
- Nenhuma suposição não verificada no resultado real?
- Frequência informada com clareza (sempre / intermitente + probabilidade)?
FAQ
Existe um «formato padrão» de relatório de bug?
Não há norma setorial obrigatória, mas existe um consenso de fato: título, ambiente, passos para reproduzir, resultado esperado, resultado real e evidências aparecem em praticamente todos os frameworks (IEEE 829, ISTQB e a maioria dos templates comerciais de defeito). Os 10 campos aqui somam identidade e observações a esse núcleo.
Podemos mudar a ordem dos campos?
Sim, desde que se mantenha consistente e estável no time. O sentido de uma ordem fixa é a memória muscular: o desenvolvedor sabe onde olhar. Mudar com frequência atrapalha mais do que escolher uma ordem não ideal.
Qual é a diferença real entre gravidade e prioridade?
A gravidade descreve o dano objetivo do defeito (julgado por QA); a prioridade descreve a urgência da correção (julgada por produto). As duas podem divergir: um erro de digitação no hero tem gravidade baixa, mas se o lançamento é em três dias, a prioridade é alta.
Um bug simples precisa mesmo dos 10 campos?
Não. Um bug simples se resolve com título, ambiente e resultado real — mas nunca sem o ambiente, a principal causa de «não consegui reproduzir». Os campos são opcionais; as posições, não.
Qual é a diferença entre «formato» e «modelo»?
Formato é a especificação dos campos: quais existem, em que ordem e como cada um é escrito. Modelo é um arquivo esqueleto que se copia e preenche. Os dois trabalham juntos: defina os campos pelo formato e entregue-os como modelo. Se quiser o esqueleto pronto para preencher, veja modelo de relatório de bug (versões Word e Markdown).
O formato pode ser automatizado; o julgamento é seu
Para deixar o limite claro: o BugCapturer não decide o que é um defeito nem escreve o seu título — isso exige o seu entendimento do que foi observado. Mas o que se esquece e o que consome tempo pode se preencher sozinho:
- Contexto técnico automático: URL, navegador, sistema operacional, resolução de tela e tamanho do viewport são gravados no campo de ambiente, sem copiar à mão.
- Dados de diagnóstico: logs de console em nível de erro e requisições de rede com falha (HTTP ≥ 400) são coletados, com anonimização automática de parâmetros sensíveis (tokens, senhas, chaves de API).
- Capturas anotadas: selecione a área e adicione setas, caixas e texto, para que «onde está errado» fique fixado na imagem.
- Gravação de tela: grave a aba atual e corte o trecho, para entregar um vídeo curto que dá para verificar.
- Compartilhar ou sincronizar: gere um link que colaboradores externos abrem sem cadastro, ou envie o relatório para o Feishu Bitable ou um webhook genérico.
O julgamento continua sendo seu. Do resto, a ferramenta cuida.
Leia também
- Modelo de relatório de bug: todos os campos com esqueleto para copiar
- Exemplos de título de bug: 40 títulos bons e ruins comparados
- Como escrever os passos para reproduzir: 5 exemplos completos
- Como reportar bugs com eficácia
- Checklist de QA para sites