Como você descreve um bug para um assistente de IA para que ele possa diagnosticá-lo com precisão?

Question

Accepted Answer

Um bom relatório de bug para uma IA é o mesmo que um bom relatório de bug para um humano: forneça **contexto suficiente para reproduzir o problema mentalmente** e elimine o ruído. A IA só pode raciocinar sobre o que você colar — descrições vagas produzem suposições vagas.

## O que incluir

- **A mensagem de erro exata e o rastreamento de pilha completo** — copie literalmente, não parafraseie. O arquivo e a linha no rastreamento são a pista mais útil.
- **O código relevante** — a função que lança o erro mais seus chamadores imediatos, não o repositório inteiro.
- **Comportamento esperado vs atual** — "Espero X, mas obtenho Y" é o cerne de qualquer relatório de bug.
- **Etapas de reprodução** — a entrada exata ou sequência que o dispara.
- **Ambiente/versões** — versões de linguagem, framework e biblioteca (um bug pode ser específico da versão).
- **Schema de banco de dados ou dados de amostra** — quando o bug afeta uma consulta ou formato de dados.

## O que omitir

Arquivos não relacionados, toda sua configuração, segredos/chaves de API e teorias do tipo "acho que pode ser X" que enviesam o diagnóstico. Forneça fatos, não palpites.

## Relatório fraco vs forte

```text
❌ WEAK: "My login is broken, it throws an error. Why?"
   → no error text, no code, no repro → the AI can only guess

✅ STRONG:
   Error (verbatim):
     TypeError: Cannot read properties of undefined (reading 'id')
       at getUser (auth.js:42)
   Code (auth.js:40-43):
```

```js
function getUser(token) {
  const session = sessions.find(s => s.token === token); // returns undefined if not found
  return session.user.id; // line 42: crashes when session is undefined
}
```

```text
   Expected: return null for an unknown token.
   Actual:   throws TypeError above.
   Repro:    call getUser('expired-token').
   Env:      Node 20, no framework.
```

Com a versão forte, a IA pode apontar direto para a verificação `undefined` ausente e propor um guard, porque cada fato necessário está na página.

## Por que isso importa

Um assistente de IA **não tem acesso ao seu sistema em execução** — ele raciocina apenas a partir do que você fornece. Um relatório fraco força-o a adivinhar o erro, o código e o ambiente simultaneamente, e uma suposição errada desperdiça uma rodada. Um relatório forte (rastreamento exato + código relevante + esperado/atual + reprodução + versões) transforma o diagnóstico em uma tarefa focada e geralmente obtém a correção certa na primeira tentativa. Aprender a escrever relatórios de bug concisos também o torna um melhor depurador, porque força você a isolar os fatos antes de perguntar.