Pular para o conteúdo

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:

SeveridadeSignificadoExemplo
BloqueanteFluxo principal impossível, sem contornoNinguém consegue fazer login
GraveFuncionalidade importante quebrada ou dados errados, contorno trabalhosoFaturas mostram o total errado
MenorFuncionalidade funciona com um pequeno problema ou um contorno fácilA ordenação volta ao padrão depois de recarregar a página
CosméticoProblema visual, sem impacto funcionalTexto 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.