Como Escrever um Bom Relatório de Bug (para IA ou um Desenvolvedor)

Um bom relatório de bug permite que outra pessoa, seja um desenvolvedor ou uma IA, veja o mesmo problema que você viu, sem precisar fazer perguntas. Ele precisa de um título específico, dos passos exatos para reproduzi-lo, do que você esperava, do que realmente aconteceu, de qualquer mensagem de erro copiada palavra por palavra e de onde aconteceu: qual página, navegador, dispositivo e usuário. Um bug por relatório, com uma captura de tela se ajudar.

A maioria dos bugs leva mais tempo para ser entendida do que para ser corrigida. Um relatório claro elimina a parte de entender. Isso importa ainda mais com ferramentas de IA: uma IA não consegue fazer uma pergunta de acompanhamento sobre o que você quis dizer com "o checkout está estranho", então ela chuta, e um palpite errado pode quebrar outra coisa.

O modelo

Copie e preencha:

Título: [O que está errado, onde] — ex.: "Formulário de agendamento rejeita horários após as 18h"

Passos para reproduzir:
1. ...
2. ...
3. ...

Esperado: [o que deveria acontecer]
Real: [o que aconteceu no lugar]

Mensagem de erro: [texto exato, se houver]
Onde: [página/URL, navegador, dispositivo, logado com qual usuário]
Frequência: [sempre / às vezes / uma vez]
Captura de tela ou gravação: [anexada]

O restante deste guia explica cada parte.

Passo 1: reproduza primeiro

Antes de escrever, tente fazer o bug acontecer de novo. Você vai descobrir quais passos importam e se ele acontece sempre.

Comece de um estado limpo: atualize a página, ou saia e entre de novo.
Anote cada clique e cada coisa que digitar.
Tente encontrar o caminho mais curto que dispara o bug.
Teste outro navegador ou outra conta. Se acontece só para um usuário, isso é uma pista importante.

Para mais sobre isso, veja como depurar um app criado com IA.

Passo 2: escreva um título específico

O título deve dizer o que está errado e onde, para que quem olha uma lista saiba qual bug é.

Fraco	Forte
Checkout quebrado	O botão de checkout não faz nada quando o carrinho tem um código de desconto
Problema no celular	Os cards de preço ultrapassam a tela em celulares com menos de 400px de largura
Erro ao salvar	Salvar um perfil com emoji no nome mostra "500 Internal Server Error"

Passo 3: liste os passos exatos

Numere-os. Seja literal: qual página, qual botão, o que você digitou.

Entre como cliente (conta de teste: cliente@exemplo.com).
Adicione o "Kit inicial" ao carrinho.
Digite o código de desconto BEMVINDO10 e clique em Aplicar.
Clique em Checkout.

"Tente finalizar a compra com um código" deixa de fora os detalhes que muitas vezes importam: qual usuário, qual produto, qual código, se ele foi aplicado antes.

Passo 4: esperado vs. real

Este é o núcleo do relatório. Diga os dois, porque a diferença é o bug.

Esperado: a página de checkout abre com o desconto de 10% mostrado no total.
Real: o botão mostra um spinner por um segundo e depois nada acontece. Sem código de desconto, o checkout funciona.

Sem o "esperado", quem lê pode não saber que o comportamento está errado. Sem o "real", não sabe o que procurar.

Passo 5: copie os erros exatamente

Mensagens de erro são o caminho mais rápido até a causa. Copie-as como texto, palavra por palavra; não parafraseie.

Onde encontrá-las:

Na tela: qualquer mensagem que o app mostre.
Console do navegador: abra as ferramentas do desenvolvedor (F12, ou clique com o botão direito → Inspecionar) e olhe a aba Console para linhas em vermelho.
Aba Rede: nas ferramentas do desenvolvedor, encontre a requisição que falhou e anote a URL e o código de status (por exemplo POST /api/checkout → 500).
Logs do servidor, se você tiver acesso.

Uma linha como TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48 costuma apontar direto para o problema.

Passo 6: adicione contexto

Onde: a URL da página, o ambiente (prévia, staging ou produção).
Quem: qual usuário ou papel: administrador, membro, sem login.
Dispositivo e navegador: "Safari no iPhone" e "Chrome no Windows" podem fazer diferença.
Dados: qualquer coisa incomum no registro: textos muito longos, caracteres especiais, uma grande quantidade de itens.
Quando começou: "depois da mudança de ontem nos códigos de desconto" vale ouro.
Com que frequência: sempre, ou uma vez em dez tentativas.

Passo 7: mostre o problema

Uma captura de tela com o problema destacado, ou uma gravação curta da tela, elimina ambiguidades, especialmente em bugs de layout. Se a sua ferramenta de IA aceita imagens, anexe uma. Corte qualquer coisa privada, incluindo chaves e dados de outras pessoas.

Escrevendo relatórios de bug para um criador com IA

A mesma estrutura funciona como um prompt. Dois acréscimos ajudam:

Diga o que não deve mudar, para que a correção não cause um novo problema.
Peça para verificar a correção, e não apenas para escrevê-la.

Logado como cliente, com o "Kit inicial" no carrinho e o código BEMVINDO10 aplicado, clicar em Checkout não faz nada. Esperado: a página de checkout abre com 10% de desconto no total. Real: um breve spinner, e depois nada. A aba de rede mostra que POST /api/checkout retornou 500. Checkout sem código funciona. Encontre a causa e corrija sem alterar como os preços são calculados para pedidos sem código. Depois teste o checkout com um código percentual, um código de valor fixo e sem código.

Se você não tiver certeza da causa, peça um diagnóstico primeiro:

Não altere o código ainda. Com base neste relatório, quais são as causas prováveis e o que confirmaria cada uma?

Erros comuns

"Está quebrado." Sem passos, sem resultado esperado, nada para agir.
Vários bugs em um relatório. Alguns são corrigidos, outros se perdem.
Erros parafraseados. "Alguma coisa undefined" esconde a parte útil.
Esquecer o usuário ou o papel. Muitos bugs afetam só administradores ou só usuários novos.
Descrever só a correção que você quer ("adicione uma verificação de null") em vez do problema.
Compartilhar segredos em capturas de tela ou logs colados.

Checklist

Reproduzi o bug e encontrei os passos mais curtos.
O título diz o que está errado e onde.
Os passos estão numerados e são literais.
Esperado e real estão ambos descritos.
Mensagens de erro foram copiadas exatamente, com qualquer requisição que falhou e o código de status.
Página, ambiente, usuário, dispositivo e navegador estão incluídos.
Disse com que frequência acontece e quando começou.
Uma captura de tela ou gravação está anexada, com dados privados removidos.
Um bug por relatório.

Relatando bugs ao agente do Mythex

Num projeto do Mythex, o relatório é o prompt. Alguns recursos ajudam:

Anexe uma captura de tela da prévia ou da tela de erro: até 5 arquivos por mensagem.
/fix foca o agente em corrigir um bug; o modo Plano permite que ele investigue antes de editar.
/test faz o agente reproduzir os fluxos na própria prévia e relatar o que vê.
Reverter para este ponto desfaz uma correção que piorou as coisas.

A página depuração com prompts da documentação usa a mesma estrutura de passos / esperado / real. Para o ciclo de correção e verificação em volta disso, veja como iterar em um app criado com IA.

Perguntas

O que um relatório de bug deve incluir?

Um título específico, os passos exatos para reproduzir o problema, o que você esperava, o que aconteceu de fato, qualquer mensagem de erro copiada palavra por palavra, onde aconteceu (página, navegador, dispositivo, usuário) e uma captura de tela ou gravação, se ajudar.

Como escrever um relatório de bug para um criador de apps com IA?

Use a mesma estrutura de um relatório para um desenvolvedor: passos, resultado esperado, resultado real e o erro exato. Acrescente o que não pode mudar, e peça para corrigir e depois verificar a correção. Pedidos vagos como "está quebrado" levam a palpites.

E se eu não conseguir reproduzir o bug?

Relate mesmo assim, mas diga isso. Inclua o que você estava fazendo, o horário, a conta do usuário e qualquer erro que viu. Anote com que frequência acontece, por exemplo, uma em cada dez tentativas, já que bugs intermitentes costumam apontar para problemas de tempo ou de dados.

Devo juntar vários bugs em um único relatório?

Não. Um bug por relatório, para que cada um possa ser corrigido, testado e fechado sozinho. Se você acha que dois problemas estão relacionados, diga isso em cada relatório.