Quando o Claude inventa código: como evitar alucinações

Acontece mais ou menos assim: você pede uma função, o Claude te devolve um código limpo, bem comentado, com cara de quem sabe o que está fazendo. Você cola, roda, e o terminal cospe um erro — a biblioteca que ele importou não existe. Ou a função que ele chamou nunca esteve naquele pacote. Ou ele afirmou, com toda a convicção, que "a versão 3.2 adicionou esse parâmetro" quando a 3.2 nunca existiu.

Isso tem nome: alucinação. E é uma das maiores dores de quem usa IA pra programar, porque o erro vem embrulhado em confiança. Não é um "talvez seja assim" — é uma afirmação firme, do jeito que um colega experiente falaria. A boa notícia: depois que você entende por que acontece, dá pra reduzir muito. Vou te mostrar como.

Por que o Claude inventa coisas

Primeiro, tira da cabeça a ideia de que o Claude "consulta um manual" antes de responder. Ele não faz isso. Um modelo de linguagem prevê a próxima palavra mais provável com base em tudo que viu no treino. Quase sempre o mais provável é também o correto — por isso ele acerta tanto. Mas quando há uma lacuna (uma biblioteca obscura, uma API que mudou, um detalhe que ele não tem como saber), ele preenche com o que parece certo em vez de parar.

É como pedir pra alguém muito lido completar uma frase sobre um assunto que ele quase domina: na dúvida, ele arrisca o palpite mais plausível — e plausível não é a mesma coisa que verdadeiro. O nome getUserById soa como um método que deveria existir naquela biblioteca. Então ele escreve. Sem te avisar que chutou.

Três situações disparam alucinação com mais força:

• Falta de contexto. Ele não conhece seu projeto, sua stack, suas versões — então adivinha.
• Conhecimento de fronteira. Bibliotecas muito novas, muito de nicho, ou que mudaram depois do corte de treino.
• Pedido vago. "Faz a integração com o gateway de pagamento" obriga ele a inventar metade dos detalhes.

Repare que os três têm a mesma raiz: informação faltando. Alucinação é, no fundo, o modelo tapando um buraco. Quanto menos buraco, menos invenção.

Os tipos de alucinação que mais aparecem

Pra você reconhecer no susto, os formatos clássicos:

• Pacote fantasma — um import ou npm install de algo que não existe (ou existe com outro nome).
• Método inexistente — a biblioteca é real, mas o método/parâmetro que ele usou não está nela.
• Fato inventado — "esse recurso saiu na versão X", "o limite é Y", uma data, um número exato que ele não leu de lugar nenhum.
• Citação falsa — um link, uma seção de doc ou um nome de arquivo do seu projeto que não bate com a realidade.

O perigoso é que todos eles passam no teste do olho. O código compila na sua cabeça. Por isso a verificação não pode ser visual — tem que ser executada.

Como cortar as alucinações na prática

Aqui está o que realmente move o ponteiro. São hábitos, não mágica.

1. Dê contexto real do projeto

A maior parte das invenções some quando o Claude lê seu projeto em vez de adivinhar. No Claude Code, isso significa duas coisas: ter um CLAUDE.md descrevendo sua stack e convenções, e deixar ele abrir os arquivos certos. Um Claude que enxerga seu package.json não precisa chutar qual biblioteca você usa — ele vê.

# cria o CLAUDE.md com a cara do seu projeto
/init

Esse passo sozinho derruba boa parte das alucinações de "pacote fantasma". Falo mais sobre ele (e os outros tropeços de iniciante) em 7 erros comuns no Claude Code.

2. Dê permissão pra ele dizer "não sei"

Modelo treinado pra ser prestativo tem viés de sempre responder. Vire isso a seu favor: diga, explicitamente, que não saber é uma resposta aceitável.

"Se você não tiver certeza se essa função existe nessa biblioteca, diga que não sabe em vez de chutar. Prefiro um 'não sei' a um nome inventado."

Parece bobo, mas funciona. Você está dando ao modelo uma saída honesta para a lacuna — em vez de empurrá-lo a preencher.

3. Peça a evidência antes da resposta

Essa é a técnica que a própria Anthropic ensina pra reduzir alucinação: faça o Claude citar o trecho real antes de afirmar. Em vez de "essa API aceita o parâmetro X?", peça: "abra o arquivo da biblioteca (ou a doc) e me mostre a assinatura da função antes de usar". Forçar ele a buscar a prova primeiro corta o chute pela raiz — ele não consegue inventar um trecho que precisa colar na sua frente.

4. Sempre rode o código

Repita comigo: alucinação morre na execução. Pacote fantasma quebra no install. Método inexistente quebra no teste. Por isso o melhor antídoto é fechar o ciclo — peça pra ele rodar e corrigir:

"Roda esse código (ou os testes) e me mostra a saída. Se quebrar, conserta e roda de novo até passar."

Quando o Claude executa o que escreveu, ele vê o erro real e se corrige sozinho. É a diferença entre um código que "parece certo" e um que comprovadamente funciona.

5. Planeje antes de deixar ele escrever

Quanto mais o Claude pensa no caminho antes de sair codando, menos ele improvisa. O Plan Mode do Claude Code é feito pra isso: ele monta o plano, você revisa, e só então ele edita. Erros (e invenções) aparecem no plano em texto, onde custam zero — não no código já espalhado por cinco arquivos.

O hábito que resume tudo: confie, mas verifique

Não trate o Claude como um oráculo nem como um estagiário desastrado. Trate como um par muito rápido e muito confiante — que acerta a maior parte do tempo, mas precisa de revisão nos detalhes que ele não tinha como saber.

Na prática, isso é uma regra só: nada de "fato" do Claude entra no seu projeto sem passar por execução ou por uma fonte real. Código, você roda. Afirmação sobre versão, limite ou API, você confere na doc. Faça isso virar reflexo e a alucinação deixa de ser um susto — vira só mais um erro que o ciclo pega.

E como bônus, hábitos que reduzem invenção (contexto enxuto, pedidos específicos, rodar o código) também gastam menos tokens — porque você corta o vai-e-volta de conserto. Se a conta te preocupa, juntei os ajustes em como gastar menos tokens no Claude.

Resumindo

• Alucinação é o modelo preenchendo uma lacuna com o que parece certo — vem sempre embrulhado em confiança.
• A raiz é quase sempre informação faltando: pouco contexto, conhecimento de fronteira ou pedido vago.
• Reduza dando contexto real (CLAUDE.md, os arquivos certos), permitindo o "não sei" e pedindo evidência antes da afirmação.
• Sempre rode o código — alucinação morre na execução.
• Planeje antes de codar (Plan Mode) pra os erros aparecerem em texto, não no projeto.
• Regra de ouro: nenhum "fato" entra sem passar por execução ou fonte real.

Tá começando agora e quer pegar esses hábitos desde o primeiro dia? Comece pelo guia do Claude Code no terminal — é onde tudo isso vira rotina.

Fonte/inspiração: as técnicas de reduzir alucinação (deixar o modelo dizer "não sei", pedir evidência/citação antes da resposta) seguem o material oficial da Anthropic — Avoiding Hallucinations · Anthropic Prompt Engineering Tutorial. Os fatos vieram de lá; os exemplos, a redação e os recortes pro Claude Code são deste blog.