Como Escrever um Bom Relatório de Erro (para uma IA ou um Programador)

Um bom relatório de erro permite que outra pessoa — um programador ou uma IA — veja o mesmo problema que você viu, sem lhe ter de perguntar nada. Precisa de um título específico, dos passos exatos para o reproduzir, do que esperava, do que aconteceu realmente, de qualquer mensagem de erro copiada palavra por palavra e de onde aconteceu: que página, navegador, dispositivo e utilizador. Um erro por relatório, com uma captura de ecrã se ajudar.

A maioria dos erros demora mais a perceber do que a corrigir. Um relatório claro elimina a parte de perceção. Isto é ainda mais importante com ferramentas de IA: uma IA não consegue fazer uma pergunta de seguimento sobre o que queria dizer com "o checkout está estranho", por isso adivinha — e uma adivinhação errada pode estragar outra coisa.

O modelo

Copie isto e preencha:

Título: [O que está errado, onde] — p. ex. "O formulário de marcações rejeita horas depois das 18h"

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

Esperado: [o que deveria acontecer]
Real: [o que aconteceu em vez disso]

Mensagem de erro: [texto exato, se existir]
Onde: [página/URL, navegador, dispositivo, com sessão iniciada como que utilizador]
Com que frequência: [sempre / às vezes / uma vez]
Captura de ecrã ou gravação: [anexada]

O resto deste guia explica cada parte.

Passo 1: Reproduza primeiro

Antes de escrever, tente voltar a fazer acontecer o erro. Vai perceber quais os passos que importam e se acontece sempre.

• Comece num estado limpo: atualize a página, ou termine e inicie sessão de novo.
• Anote cada clique e cada coisa que escreveu.
• Tente encontrar o caminho mais curto que desencadeia o erro.
• Experimente outro navegador ou outra conta. Se só acontecer com um utilizador, é uma pista importante.

Para mais detalhes, veja como depurar uma app criada com IA.

Passo 2: Escreva um título específico

O título deve dizer o que está errado e onde, para que quem percorre uma lista saiba de que erro se trata.

Passo 3: Liste os passos exatos

Numere-os. Seja literal: que página, que botão, o que escreveu.

1. Inicie sessão como cliente (conta de teste: customer@example.com).
2. Adicione o "Kit inicial" ao carrinho.
3. Introduza o código de desconto WELCOME10 e clique em Aplicar.
4. Clique em Checkout.

"Tente fazer checkout com um código" deixa de fora os detalhes que muitas vezes importam: que utilizador, que produto, que código, se foi aplicado primeiro.

Passo 4: Esperado vs. real

Esta é a essência do relatório. Diga as duas coisas, porque a diferença é o erro.

• Esperado: A página de checkout abre com o desconto de 10% visível no total.
• Real: O botão mostra um indicador de carregamento durante um segundo e depois não acontece nada. 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

As mensagens de erro são o caminho mais rápido para a causa. Copie-as como texto, palavra por palavra — não as parafraseie.

Onde as encontrar:

• No ecrã: qualquer mensagem que a app mostre.
• Consola do navegador: abra as ferramentas de programador (F12, ou clique com o botão direito → Inspecionar) e veja o separador Consola para linhas a vermelho.
• Separador Rede: nas ferramentas de programador, encontre o pedido que falhou e anote o URL e o código de estado (por exemplo POST /api/checkout → 500).
• Registos do servidor, se tiver acesso.

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

Passo 6: Acrescente contexto

• Onde: o URL da página, o ambiente (pré-visualização, pré-produção ou produção).
• Quem: que utilizador ou função — administrador, membro, sem sessão iniciada.
• Dispositivo e navegador: "Safari no iPhone" vs. "Chrome no Windows" pode ser importante.
• Dados: qualquer coisa invulgar no registo — texto muito longo, carateres especiais, um grande número de itens.
• Quando começou: "depois da alteração de ontem aos códigos de desconto" é ouro.
• Com que frequência: sempre, ou uma em cada dez tentativas.

Passo 7: Mostre-o

Uma captura de ecrã com o problema assinalado, ou uma pequena gravação de ecrã, elimina ambiguidades — sobretudo em erros de layout. Se a sua ferramenta de IA aceitar imagens, anexe uma. Recorte tudo o que for privado, incluindo chaves e dados de outras pessoas.

Escrever relatórios de erro para um criador de IA

A mesma estrutura funciona como prompt. Duas adições ajudam:

• Diga o que não pode mudar, para que a correção não crie um novo problema.
• Peça que verifique a correção, não apenas que a escreva.

Com sessão iniciada como cliente, com o "Kit inicial" no carrinho e o código WELCOME10 aplicado, clicar em Checkout não faz nada. Esperado: a página de checkout abre com 10% de desconto no total. Real: um breve indicador de carregamento, depois nada. O separador Rede mostra que POST /api/checkout devolveu 500. O checkout sem código funciona. Encontre a causa e corrija-a sem alterar a forma como os preços são calculados para encomendas sem código. Depois verifique o checkout com um código percentual, um código de valor fixo e sem código.

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

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

Erros comuns

• "Está avariado." Sem passos, sem resultado esperado, nada em que agir.
• Vários erros no mesmo relatório. Alguns são corrigidos, outros perdem-se.
• Erros parafraseados. "Uma coisa undefined" esconde a parte útil.
• Não indicar o utilizador ou a função. Muitos erros afetam apenas administradores ou apenas novos utilizadores.
• Descrever apenas a correção que quer ("adicionar uma verificação de null") em vez do problema.
• Partilhar segredos em capturas de ecrã ou registos colados.

Lista de verificação

• Reproduzi o erro 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.
• Estão indicados o esperado e o real.
• As mensagens de erro estão copiadas exatamente, com qualquer pedido falhado e código de estado.
• Estão incluídos página, ambiente, utilizador, dispositivo e navegador.
• Indiquei com que frequência acontece e quando começou.
• Uma captura de ecrã ou gravação está anexada, sem dados privados.
• Um erro por relatório.

Reportar erros ao agente do Mythex

Num projeto do Mythex, o relatório é o prompt. Algumas funcionalidades ajudam:

• Anexe uma captura de ecrã da pré-visualização ou do ecrã de erro — até 5 ficheiros por mensagem.
• /fix foca o agente em corrigir um erro; o modo Plano permite-lhe investigar antes de editar.
• /test pede ao agente que reproduza os fluxos na própria pré-visualização e que relate o que vê.
• Reverter para este ponto desfaz uma correção que piorou as coisas.

A página de 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 torno disto, veja como iterar numa app criada com IA.

Perguntas