Claude Code usou uma função que não existe na biblioteca: por que acontece e como cortar esse erro

Fala aí, beleza? O código veio bonito, indentado, com tratamento de erro e tudo, o nome da função faz TODO sentido pra aquela biblioteca… e aí a primeira execução estoura dizendo que aquilo nunca existiu 😅

Isso não é um bug do Claude Code

O modelo completa padrão: ele viu um monte de biblioteca parecida, aprendeu a convenção de nomes daquele ecossistema e, quando não tem a assinatura real na frente dele, preenche a lacuna com o que é estatisticamente plausível

E plausível não é a mesma coisa que existente

A boa notícia é que esse erro é previsível, e o que é previsível dá pra cortar mudando duas coisas: o que você pede e o fluxo que você deixa o agente seguir

Neste post eu separo os três sintomas que aparecem na prática (função inexistente, função de outra versão e pacote inexistente), o que fazer em cada um deles e como montar um setup que continua valendo depois que a sessão compacta

Sintoma 1: a função não existe na biblioteca (mas o nome faz todo sentido)

O que você vê:

Um AttributeError no Python, um TypeError no JavaScript, aquele clássico is not a function

A biblioteca existe, está instalada, o import até funciona

O que não existe é o método que ele chamou

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Por que acontece:

O nome segue a convenção da lib, então ele é coerente com tudo que o modelo já viu

Se a biblioteca tem create(), update() e delete(), um upsert() parece a coisa mais natural do mundo de existir ali

O agente escreveu sem abrir o código instalado pra conferir a assinatura, e é aí que mora o problema

Como resolver agora:

Inverte a ordem do trabalho: primeiro leitura, depois escrita

Em vez de pedir a implementação direto, peça a assinatura real antes

Antes de propor qualquer código:
1. abra o arquivo da dependência instalada neste projeto
2. cole aqui a assinatura real da função que você pretende usar
3. só depois escreva a implementação
Se a função não existir, diga que não existe, não sugira uma alternativa parecida sem confirmar

E tem um jeito de garantir que ele não vai sair editando enquanto investiga: o plan mode

O Shift+Tab cicla os modos de permissão da sessão, do modo normal pro auto-accept (⏵⏵ accept edits on) e, apertando de novo, pro plan mode (⏸ plan mode on)

Se você já quer abrir a sessão assim:

claude --permission-mode plan

No plan mode ele analisa o código e monta o plano, mas não aplica mudança, o que é exatamente o que você quer numa investigação de dependência

Como prevenir:

Essa regra não pode viver só no chat, senão ela some

Coloca ela na memória do projeto, no CLAUDE.md ou no .claude/CLAUDE.md do diretório de trabalho:

## Regras de dependência
- Não use função, método ou atributo de biblioteca sem antes abrir o código instalado e confirmar a assinatura
- Se não der pra confirmar, pare e pergunte, não invente uma alternativa parecida

Se a regra vale pra todo projeto seu, ela sobe um nível e vai pro ~/.claude/CLAUDE.md, que é o arquivo de memória do usuário

Sintoma 2: a função existia, mas em outra versão da biblioteca

O que você vê:

Esse é mais cruel, porque você joga o nome do método no Google e ACHA a documentação

A chamada é real, está lá na doc, com exemplo e tudo

Só que ela quebra no seu projeto

Por que acontece:

O treino do modelo mistura versões diferentes da mesma biblioteca

Ele sabe que aquela função existe, ele só não sabe em qual versão, e principalmente não sabe qual versão está no seu lock file

Como resolver agora:

Diz a versão exata no prompt, sempre

"usando a versão X.Y.Z instalada neste projeto" muda o comportamento dele mais do que qualquer instrução genérica de "seja preciso"

E dá pra ir além: plugar documentação versionada direto na sessão

O Context7 é um servidor MCP mantido pela Upstash que entrega documentação de código atualizada e específica por versão pra clientes MCP, entre eles o Claude Code

Pra adicionar via HTTP:

claude mcp add --transport http context7 https://mcp.context7.com/mcp

Ou pelo pacote npm:

claude mcp add context7 -- npx -y @upstash/context7-mcp@latest

Ele expõe duas ferramentas principais: resolve-library-id, que converte o nome da biblioteca num ID compatível, e query-docs, que busca a documentação da versão

Dá pra usar sem chave de API, com limites de requisição básicos, e tem chave gratuita no dashboard se você quiser limites maiores

Se o servidor não aparecer depois de adicionar, o caminho é o mesmo tipo de investigação de quando o Claude Code não reconhece uma instalação, não adianta seguir programando e torcer

Como prevenir:

Versão fixada é memória de projeto, não recado solto no chat

Escreve as versões das dependências críticas no CLAUDE.md e para de repetir isso na mão toda sessão 🙂

Sintoma 3: o pacote inteiro não existe (e por que isso é risco de segurança)

O que você vê:

Aqui nem chega a rodar: o install falha porque o pacote sugerido não está no registry

É a mesma mecânica do sintoma 1, só que agora no nome do pacote em vez do nome da função

Por que isso é mais sério:

Função inventada quebra na sua cara, e erro que quebra é erro barato

Pacote inventado abre uma porta

Existe um nome pra isso: slopsquatting, a prática de registrar um nome de pacote inexistente que um LLM pode alucinar na saída, pra que o dev instale o pacote falso sem perceber

E isso não é teoria de internet, tem medição

Um estudo independente reavaliou a taxa de alucinação de pacotes em modelos de fronteira de 2026 e mediu uma faixa de 4,62% a 6,10%, contra os 5,2% a 21,7% que pesquisas anteriores relatavam

Pra chegar nisso, foram geradas 199.845 respostas de geração de código entre 22 e 28 de abril de 2026

Os cinco modelos avaliados foram Claude Sonnet 4.6, Claude Haiku 4.5, GPT-5.4-mini, Gemini 2.5 Pro e DeepSeek V3.2

O dado que mais me chamou atenção: os cinco modelos geraram 127 nomes de pacotes inexistentes EM COMUM, e desses, 53 ainda estavam disponíveis para registro em abril de 2026 (41 no PyPI e 12 no npm)

Ou seja, é um alvo previsível e compartilhado, não um chute aleatório de cada modelo

Importante ser honesto com o recorte: o estudo aponta alvos potenciais, não um ataque em andamento, não há evidência ali de que algum desses 53 nomes tenha sido registrado com má intenção

Como prevenir:

Nunca instalar pacote sugerido sem conferir no registry oficial antes

É um passo de cinco segundos: abre o npm ou o PyPI, procura o nome exato, olha se tem histórico de versões e quem publica

Se o nome só aparece na resposta da IA e em lugar nenhum do ecossistema, você tem sua resposta

Como blindar seu fluxo no Claude Code para o erro não voltar

Os prompts acima resolvem a sessão de hoje

O que resolve amanhã é setup, e ele é rápido de montar

1. Escreva a regra no CLAUDE.md do projeto

O Claude Code lê esses arquivos como memória persistente, nos caminhos CLAUDE.md ou .claude/CLAUDE.md no diretório de trabalho, e a leitura é recursiva: ele parte do diretório atual e sobe até a raiz, carregando o que encontrar no caminho

O detalhe que faz diferença: o CLAUDE.md da raiz do projeto sobrevive à compactação, depois do /compact o Claude Code relê o arquivo do disco e reinjeta o conteúdo na sessão

O erro comum deste passo: escrever a regra no chat

Instrução dita no meio da conversa é a primeira coisa que evapora quando o contexto aperta

2. Registre a versão exata das dependências críticas nesse mesmo arquivo

Não precisa listar as 60 dependências do projeto, só as que o agente encosta toda hora

O erro comum deste passo: escrever "use a versão mais recente"

Isso não é informação, é permissão pra ele chutar

3. Ligue o Context7 pra documentação versionada

É o claude mcp add que mostrei ali em cima

O erro comum deste passo: se o comando falhar por causa do ambiente (Node, permissão do npm, WSL), o problema não é o MCP, é a base, e aí vale olhar os erros comuns ao instalar o Claude Code antes de seguir tentando

4. Use plan mode antes de deixar ele editar

Tarefa que mexe em biblioteca que você não domina começa em plan mode, sem exceção

O erro comum deste passo: passar a sessão inteira em auto-accept porque é mais confortável

Aí ele escreve, aplica e quebra tudo antes de você ler uma linha

5. Exija que a chamada tenha rodado antes de considerar pronto

Esse é o passo que quase todo mundo pula

O erro comum, e o mais caro de todos: aceitar um "pronto, implementado!" sem que o código tenha sido EXECUTADO nenhuma vez

Código que compila não prova que a função existe em runtime, e num projeto grande você só descobre isso três features depois

O que mudou aqui quando o fluxo passou a exigir verificação

Esse assunto conversa direto com uma dor que eu já vinha sentindo programando com IA, seja no Claude Code ou em outra ferramenta: conforme a sessão anda, a IA vai esquecendo detalhe do projeto e começa a criar coisa sem relação com o que foi pedido

Na prática isso aparece como código repetido, ela não lembrar que já tinha criado aquela função, e instrução que está no arquivo de instruções sendo simplesmente ignorada

A qualidade cai conforme o contexto enche, e piora depois da compactação

E aumentar o contexto não resolve, na minha visão até piora, porque é mais informação pra ela se perder

Foi por isso que eu fui testar um framework que força planejamento antes da implementação, e no vídeo eu mostro esse fluxo do começo

O que me chamou atenção não foi a parte de escrever código, foi a fase que vem ANTES

Quando testei, na fase de pesquisa foram disparados 4 agentes em paralelo pra investigar stack, funcionalidades, arquitetura e armadilhas do projeto, e eu acompanhei cada um deles por um atalho do Claude Code, vendo em que passo estavam e quais modelos usaram

Detalhe engraçado: o terminal parecia parado e devolvido, mas o processo continuava rodando de forma assíncrona

Depois eu abri a pasta de planejamento gerada e ali estavam as informações que eu tinha selecionado na entrevista, escritas de forma bem mais detalhada

O ponto que interessa pra este post é o comportamento: o agente lê e investiga ANTES de escrever

A fase de planejamento é rigorosa e às vezes sofrida, tem mais burocracia mesmo, mas é exatamente essa burocracia que tira o agente do modo "completa o padrão e segue"

E ela ajuda muito quem entende pouco de programação ou não vem da área técnica, porque o plano vira uma coisa legível antes de virar código

Veja o fluxo funcionando na prática

No vídeo abaixo eu mostro a instalação, a entrevista de planejamento e os agentes de pesquisa rodando em paralelo dentro do Claude Code

Se o seu problema é chamada inventada, olha com atenção pra fase de pesquisa: é ali que o agente troca o palpite pela leitura

Conclusão

Alucinação de função não se resolve com prompt mágico, e desconfia de quem te vende um 🙂

Se resolve com verificação obrigatória dentro do fluxo: o agente abre a dependência instalada, confirma a assinatura, respeita a versão que está no seu projeto e só considera pronto o que rodou de verdade

As três camadas do post trabalham juntas: memória de projeto pra regra sobreviver à compactação, documentação versionada pra ele não misturar versões e plan mode pra ele pensar antes de aplicar

Próximo passo concreto pra hoje: abre o CLAUDE.md do seu projeto e escreve duas regras, a versão fixada das dependências críticas e a proibição de chamada não verificada

Depois disso, pluga o Context7 e testa a mesma tarefa que te quebrou na semana passada

Bora ver na prática? 😀

até o próximo post!