Triage de Alucinações e Causa Raiz

1. Visão geral do conceito e problema sistêmico

Quando um agente invoca um método inexistente ou utiliza uma biblioteca que não está presente no projeto, a reação típica de um vibe coder inexperiente é a raiva e exclamações emocionais no chat: "Você é burro?! Eu disse para usar Drizzle, não Prisma!".

• Isso leva ao acúmulo de "lixo emocional" no contexto da conversa.
• O modelo começa a pedir desculpas, mas continua cometendo erros, pois a causa raiz não foi eliminada.

Hallucination Triage é uma abordagem fria e de engenharia: tratar as alucinações do modelo não como "burrice da IA", mas como um defeito no sistema de entrega de contexto (Context Delivery Bug), passível de classificação e correção sistemática.

2. Taxonomia arquitetural e modelo mental

┌─────────────────────────────────────────────────────────────┐
│                 MATRIZ DE TRIAGEM DE ALUCINAÇÕES            │
├─────────────────────────────────────────────────────────────┤
│ 1. DETECÇÃO: O modelo gerou um método ou tipo inexistente   │
│    • Exemplo: `db.user.findFirstOrThrow()` no Drizzle ORM   │
├─────────────────────────────────────────────────────────────┤
│                          │                                  │
│                          ▼ DIAGNÓSTICO DA CAUSA RAIZ        │
│    ┌───────────────────────────────────────────────────┐    │
│    │ Tipo A: Arquivo ausente? ➔ O modelo não viu o schema │  │
│    │ Tipo B: Conflito de regras? ➔ As regras mencionam Prisma│ │
│    │ Tipo C: Conhecimento desatualizado? ➔ Treinamento do modelo é de 2023 │ │
│    └───────────────────────────────────────────────────┘    │
│                          │                                  │
│                          ▼ CORREÇÃO SISTEMÁTICA             │
│ 1. Adicionar o arquivo exato de tipos ao prompt             │
│ 2. Fixar a proibição nas rules: "NEVER use Prisma syntax"   │
│ 3. Adicionar validação via compilador `tsc --noEmit`        │
└─────────────────────────────────────────────────────────────┘

3. Cenários práticos de engenharia em produção

01. Eliminação de alucinações via arquivos de declaração

O agente inventava constantemente props para um componente interno de botão. Em vez de dar explicações, o desenvolvedor criou um arquivo src/components/ui/button.d.ts com tipos TypeScript explícitos e o adicionou à lista de contexto automático. Os erros desapareceram 100%.

02. Protocolo "Post-Mortem para bugs de IA"

Após resolver um bug complexo, o engenheiro gasta 2 minutos atualizando .agents/rules/learnings.md: "Neste projeto, o router Next.js usa Server Actions sem chamadas manuais de fetch. Não gere rotas-handler desnecessárias para mutações simples.".

4. Armadilhas, erros comuns e segurança

• Over-Correction (Hipercompensação): Ao tentar corrigir uma pequena alucinação, o engenheiro escreve uma regra gigante de 50 linhas em caixa alta, proibindo o modelo de usar padrões auxiliares úteis. As regras devem ser cirurgicamente precisas.
• Ignorar versões dos modelos: Se o modelo tiver capacidade de raciocínio muito baixa (por exemplo, um modelo antigo de 3B parâmetros), nenhum triage ajudará a resolver tarefas complexas. Às vezes, a única cura é trocar por um modelo mais potente.

5. Conclusão estratégica para o engenheiro de 2026

A alucinação é um espelho da qualidade da sua documentação de engenharia. Se o modelo alucina, significa que seu sistema era insuficientemente determinístico. O triage sistemático transforma cada erro em um tijolo na fundação da confiabilidade do seu repositório.