Modelo de bug report: grátis, para Jira, GitHub e Linear
Um modelo de bug report grátis para copiar e colar, versões prontas para GitHub, Linear e Jira, um formulário de issue do GitHub e um exemplo preenchido.
Um modelo de bug report é um conjunto fixo de campos que faz todo report responder às mesmas perguntas: o que deu errado, onde, como reproduzir, o que deveria ter acontecido e qual evidência mostra isso. O modelo abaixo cobre título, resumo, ambiente, passos para reproduzir, resultado esperado e resultado obtido, frequência, severidade, anexos e logs. Copie-o para o seu rastreador de issues, um formulário de suporte ou uma mensagem de chat e preencha os espaços. Mais abaixo há versões prontas para GitHub, Linear e Jira, incluindo um formulário de issue do GitHub.
Modelos existem porque os devs perdem a maior parte do tempo com detalhes que faltam, não com a correção. Um report com os passos exatos, a versão do navegador e o erro de console muitas vezes é corrigido no mesmo dia. Um report que diz "o checkout está quebrado" vira uma longa thread de perguntas.
O modelo
Título: [O que está quebrado] ao [ação] em [página ou funcionalidade]
Resumo
Uma ou duas frases em linguagem simples. O que aconteceu e quem é afetado.
Ambiente
- URL:
- Navegador e versão:
- Sistema operacional:
- Dispositivo / tamanho da tela:
- Versão ou build do app (se souber):
- Conta / papel / usuário de teste:
- Data e hora em que aconteceu (com fuso horário):
Passos para reproduzir
1.
2.
3.
Resultado esperado
O que deveria ter acontecido.
Resultado obtido
O que aconteceu no lugar. Inclua a mensagem de erro exata, copiada como texto.
Frequência
Sempre / Às vezes (cerca de X de Y tentativas) / Aconteceu uma vez
Severidade
Bloqueante / Grave / Menor / Cosmético
Contorno
Algum jeito de contornar o problema, ou "Nenhum encontrado".
Anexos
- Screenshot ou gravação de tela:
- Erros de console:
- Requisição de rede que falhou (URL, status, resposta):
- Arquivo HAR (sanitizado), se pedido:
Notas
Qualquer outra coisa: quando começou, o que mudou recentemente, tickets relacionados.
Como preencher cada campo
Título
O título é o que as pessoas leem de relance numa lista de cinquenta tickets, então seja específico. Um padrão útil é "o que está quebrado" mais "quando" mais "onde". "Botão Pagar continua desativado depois de inserir um cartão válido no checkout" é melhor que "Bug no checkout". Evite palavras como "urgente" ou "quebrado" sozinhas; o campo de severidade já carrega isso.
Resumo
Uma ou duas frases que um colega não técnico consiga entender. Diga quem é afetado, se você souber: todos os usuários, só admins, só quem usa Safari, só um cliente.
Ambiente
Muitos bugs dependem do navegador, do dispositivo, da conta ou dos dados. Anote a URL exata, o nome e a versão do navegador, o sistema operacional e a conta ou o papel que você usou. Se o app mostra um número de versão ou de build, inclua. O horário da falha, com o seu fuso horário, permite que o dev encontre as entradas correspondentes nos logs do servidor.
Passos para reproduzir
Este é o campo mais importante. Numere os passos, comece de um estado conhecido ("logado como um usuário com o carrinho vazio") e inclua os dados exatos que você usou. Escreva uma ação por passo. Se não conseguiu reproduzir uma segunda vez, diga isso e descreva o que fez da primeira vez da forma mais fiel possível.
Resultado esperado e resultado obtido
Coloque os dois lado a lado para que a diferença fique óbvia. Copie as mensagens de erro como texto em vez de parafraseá-las; o dev vai procurar exatamente essa string no código. "Nada acontece" é um resultado obtido válido, mas acrescente o que você verificou, como "nenhuma mensagem de erro, o botão continua ativo".
Frequência
Bugs que acontecem "sempre" são os mais fáceis de corrigir. Bugs que acontecem "às vezes" precisam de mais dados, então estime a taxa ("3 de 10 tentativas") e anote o que parece importar, como uma conexão lenta ou um arquivo grande.
Severidade
Severidade fala de impacto, não do quanto você está irritado. Uma escala comum:
| Severidade | Significado | Exemplo |
|---|---|---|
| Bloqueante | Fluxo principal impossível, sem contorno | Ninguém consegue fazer login |
| Grave | Funcionalidade importante quebrada ou dados errados, contorno trabalhoso | Faturas mostram o total errado |
| Menor | Funcionalidade funciona com um pequeno problema ou um contorno fácil | A ordenação volta ao padrão depois de recarregar a página |
| Cosmético | Problema visual, sem impacto funcional | Texto do botão se sobrepõe em telas pequenas |
A prioridade, que decide quando o bug é corrigido, normalmente é definida pelo time dono do backlog, não por quem reporta.
Contorno
Um contorno (workaround) diz ao time o quanto a correção é urgente e ajuda o suporte a responder aos clientes enquanto isso.
Anexos e logs
Evidências são o que mais economiza tempo. Anexe um screenshot com a área do problema marcada, ou uma gravação de tela curta que mostre os passos. Para apps web, acrescente os erros de console e a requisição de rede que falhou. Os nossos guias sobre como exportar logs de console no Chrome e como capturar o tráfego de rede no Chrome mostram como. Se alguém pedir um arquivo HAR, siga como obter um arquivo HAR e limpe-o antes com o sanitizador de HAR, porque arquivos HAR contêm cookies e tokens.
Um exemplo preenchido
Título: Botão Pagar continua desativado depois de inserir um cartão válido no checkout
Resumo
Na página de checkout, o botão Pagar nunca fica clicável depois que um cartão
de teste válido é inserido, então o pedido não pode ser feito. Visto no Chrome e no Edge.
Ambiente
- URL: https://staging.example.com/checkout
- Navegador e versão: Chrome 154 no Windows 11; também Edge 154
- Dispositivo / tamanho da tela: Notebook, 1920x1080
- Versão ou build do app: web 4.18.0 (rodapé)
- Conta / papel / usuário de teste: [email protected], cliente padrão
- Data e hora: 2026-11-10 14:32 CET
Passos para reproduzir
1. Faça login como [email protected].
2. Adicione "Starter plan, annual" ao carrinho.
3. Vá para /checkout.
4. Insira o cartão de teste 4242 4242 4242 4242, validade 12/30, CVC 123.
5. Clique fora do campo do cartão.
Resultado esperado
O botão Pagar fica ativo e mostra "Pagar US$ 120,00".
Resultado obtido
O botão Pagar continua cinza e desativado. Nenhuma mensagem de erro aparece.
O console mostra: Uncaught TypeError: Cannot read properties of
undefined (reading 'postalCode') at validateCard (checkout.js:214)
Frequência
Sempre (5 de 5 tentativas)
Severidade
Bloqueante: os clientes não conseguem pagar
Contorno
Nenhum encontrado. Funciona na build de produção 4.17.2.
Anexos
- Gravação de tela: link nos comentários
- Erros de console: checkout-console.log
- Rede: POST /api/cart/validate retornou 200; nenhuma outra falha
Notas
Começou depois do deploy em staging de hoje de manhã.
Repare no que faz este exemplo funcionar. Os passos começam de uma conta conhecida. O cartão de teste está identificado. O erro de console está citado exatamente. Quem reportou testou outro navegador e a build anterior, o que já restringe a causa à última mudança.
Versões mais curtas
Nem todo bug precisa de todos os campos. Para uma mensagem rápida no chat do time, uma versão compacta basta:
Bug: [título]
Onde: [URL], [navegador/SO]
Passos: 1) ... 2) ... 3) ...
Esperado: ...
Obtido: ...
Evidência: [screenshot / gravação / erro de console]
Para times de suporte que encaminham o report de um usuário, acrescente o ID da conta do cliente, o link do ticket e as palavras do próprio cliente, e marque quais partes você mesmo reproduziu.
Para rodadas de teste de QA, acrescente o ID do caso de teste e a build testada, para que o bug aponte de volta para o teste que o encontrou.
Modelos para GitHub, Linear e Jira
O modelo em texto puro funciona em qualquer lugar. Se o seu rastreador renderiza Markdown, esta versão mantém os títulos e os checklists legíveis:
## Resumo
<!-- Uma ou duas frases: o que aconteceu e quem é afetado. -->
## Ambiente
- URL:
- Navegador e versão:
- Sistema operacional:
- Versão ou build do app:
- Conta / papel:
## Passos para reproduzir
1.
2.
3.
## Resultado esperado
## Resultado obtido
<!-- Cole a mensagem de erro exata como texto. -->
## Frequência
<!-- Sempre / Às vezes (X de Y) / Uma vez -->
## Severidade
<!-- Bloqueante / Grave / Menor / Cosmético -->
## Evidências
- [ ] Screenshot ou gravação de tela
- [ ] Erros de console
- [ ] Requisição de rede que falhou
GitHub Issues
Salve a versão em Markdown como .github/ISSUE_TEMPLATE/bug_report.md no seu repositório, com um cabeçalho curto para que o GitHub a ofereça no seletor de "New issue":
---
name: Bug report
about: Algo está quebrado
labels: bug
---
O GitHub também suporta formulários de issue (issue forms), que transformam o modelo em campos com rótulo que ninguém consegue pular. Salve isto como .github/ISSUE_TEMPLATE/bug_report.yml:
name: Bug report
description: Algo está quebrado
labels: ["bug"]
body:
- type: textarea
id: summary
attributes:
label: Resumo
description: O que aconteceu e quem é afetado?
validations:
required: true
- type: input
id: url
attributes:
label: URL
- type: input
id: environment
attributes:
label: Navegador, sistema operacional e versão do app
placeholder: Chrome 154 no macOS 26, web 4.18.0
- type: textarea
id: steps
attributes:
label: Passos para reproduzir
value: |
1.
2.
3.
validations:
required: true
- type: textarea
id: expected
attributes:
label: Resultado esperado
validations:
required: true
- type: textarea
id: actual
attributes:
label: Resultado obtido
description: Cole a mensagem de erro exata como texto.
validations:
required: true
- type: dropdown
id: severity
attributes:
label: Severidade
options:
- Bloqueante
- Grave
- Menor
- Cosmético
- type: textarea
id: evidence
attributes:
label: Screenshots, gravação e logs
description: Arraste arquivos para cá ou cole o link de uma gravação.
Linear
O Linear tem modelos de issue nas configurações de cada time. Crie um chamado "Bug", cole a versão em Markdown na descrição dele e defina o label Bug e o estado de triagem do time, para que todo report comece com os mesmos campos.
Jira
No Jira, cole a versão em texto puro ou em Markdown na descrição de um novo Bug. O Jira Cloud não tem uma descrição padrão nativa para cada tipo de issue, então os times que querem o modelo já preenchido usam um app de modelos de issue do Atlassian Marketplace. O link para uma gravação de tela com logs de console e de rede vai na descrição ou num comentário.
Erros que o modelo evita
Um modelo é, acima de tudo, um checklist contra os mesmos poucos erros:
- Vários bugs num só report. Um ticket por problema, para que cada um possa ser corrigido, testado e fechado por conta própria.
- Erros parafraseados. "Falou alguma coisa sobre permissões" não dá para pesquisar. A mensagem exata dá.
- Ponto de partida ausente. Passos que começam no meio de um fluxo só funcionam para quem os escreveu.
- Opiniões em vez de observações. "A API está quebrada" é um palpite. "POST /api/orders retornou 500" é um fato que o dev pode verificar.
- Segredos nos anexos. Screenshots de painéis de admin, arquivos HAR e logs de console podem conter tokens e dados de clientes. Recorte, desfoque ou sanitize antes de anexar.
Torne-o o padrão do seu time
A maioria dos rastreadores de issues permite salvar uma descrição padrão ou um modelo de issue, então todo bug novo já começa com esses títulos. Mantenha o modelo curto o bastante para que as pessoas o preencham de fato. Se um campo fica vazio na maioria dos reports, remova-o. Se os devs vivem fazendo a mesma pergunta de acompanhamento, acrescente um campo para ela.
Deixe a ferramenta preencher os campos técnicos
Os campos que as pessoas mais pulam são os técnicos: versão do navegador, erros de console, a requisição que falhou. O Midge, uma extensão grátis do Chrome, os anexa automaticamente a uma gravação de tela ou a um screenshot, então quem reporta só escreve o título, os passos e o resultado esperado. Toda gravação inclui logs de console, requisições de rede, ações do usuário e informações do dispositivo. Senhas, números de cartão, tokens e cookies são ocultados no seu navegador antes que qualquer coisa saia do seu dispositivo. Um report vai direto para Jira, Linear, GitHub Issues ou Slack, ou é compartilhado como um link que você pode colar em qualquer lugar.
Guias relacionados
Perguntas frequentes
O que um modelo de bug report deve incluir?
Um título claro, o ambiente (URL, navegador, sistema operacional, versão do app, conta), passos numerados para reproduzir, o resultado esperado, o resultado obtido, com que frequência acontece, a severidade e evidências como screenshots, um vídeo, logs de console e requisições de rede.
Posso usar este modelo no Jira, no Linear ou no GitHub Issues?
Sim. É texto puro com títulos compatíveis com Markdown, então você pode colá-lo em qualquer rastreador. O GitHub e o Linear também permitem salvá-lo como modelo de issue, e o Jira permite com um app do Marketplace.
Onde ficam os modelos de issue do GitHub?
Na pasta .github/ISSUE_TEMPLATE do repositório. Um arquivo .md adiciona um modelo em Markdown, e um arquivo .yml adiciona um formulário de issue com campos obrigatórios. O GitHub os lista quando alguém abre uma nova issue.
Qual é a diferença entre severidade e prioridade?
A severidade descreve o quanto o bug afeta o produto ou os usuários. A prioridade descreve quando o time vai corrigi-lo. Um bug grave numa tela de admin pouco usada pode ter prioridade menor que um bug cosmético na página de preços.
Preciso preencher todos os campos?
Não. Título, passos, resultado esperado e resultado obtido são essenciais. Preencha o resto quando souber, e escreva "desconhecido" em vez de chutar.