Por que seu agente de código com IA alucina caminhos de arquivo

O sinal revelador não é um corpo de função errado. É uma edição confiante em um arquivo que não existe, ou em um arquivo que existe mas não é o que implementa o comportamento.

Você pediu uma correção de expiração de sessão. O agente abriu src/auth/session.ts. Esse caminho é plausível. Também está errado. O handler de verdade vive em apps/api/src/middleware/expiry.ts, renomeado há duas refatorações. O agente não mentiu para você. Ele completou uma string em formato de caminho a partir de priors de treinamento mais o que já estivesse na janela de contexto.

Esse é o padrão de falha comum em um repositório real. O modelo sabe escrever código. O erro está em escolher o lugar errado para escrevê-lo.

Por que agentes inventam caminhos

Um agente de código é um modelo de previsão do próximo token com ferramentas. Quando você diz “conserta a expiração de sessão”, ele precisa nomear um arquivo antes de conseguir ler ou aplicar um patch em qualquer coisa. Se ainda não tem um mapa fundamentado, ele constrói um caminho a partir de:

1. Convenções de nomenclatura que já viu em outros repositórios. src/auth/session.ts é um formato frequente.
2. Arquivos que já estão na conversa, que talvez sejam os que você colou semana passada, não os que importam agora.
3. Listagens de diretório que ele acabou executando, incompletas em uma árvore grande.
4. Arquivos de instrução. CLAUDE.md e AGENTS.md dizem ao agente como se comportar. Não são um índice vivo de símbolos, chamadores ou caminhos atuais.

Nenhuma dessas fontes é um mapa deste repo, hoje. O modelo preenche a lacuna do jeito que preenche qualquer lacuna: com uma continuação de alta probabilidade. Essa continuação muitas vezes parece um caminho real. Às vezes o arquivo existe e fica ao lado do certo. Às vezes existiu em uma branch que foi mesclada mês passado. Às vezes nunca existiu.

O grep não te salva aqui se o agente nunca busca a string certa. O agente chutou um caminho, depois leu o que aquele caminho retornou, depois editou. O primeiro passo errado foi o caminho, não o patch.

Ler arquivos também não é a mesma coisa que encontrar os certos. Claude Code, Cursor, Codex e ferramentas parecidas conseguem abrir o que você apontar para eles. A pergunta é se conseguem encontrar de forma confiável os arquivos certos, os símbolos importantes, as dependências, os testes e o raio de impacto antes de editar. Acesso a arquivo sem um mapa ainda começa com um chute.

A edição do arquivo errado é um problema de recuperação

Trate o caminho inventado como um erro de recuperação, não como uma falha de caráter.

Se o agente tivesse que retornar path/file.ext:line antes de ter permissão para editar, duas coisas aconteceriam. Primeiro, você conseguiria abrir a citação e rejeitar o trabalho em dez segundos. Segundo, o agente teria que consultar algo que realmente conhece a árvore.

Esse é o trabalho de uma camada de contexto de código. Busca semântica sozinha não é suficiente. Um trecho que “soa como expiração de sessão” ainda pode pousar em um pacote obsoleto. Você também precisa de texto exato quando conhece a string, busca de símbolos quando conhece o nome, busca estrutural quando conhece a forma, e um grafo de dependências quando precisa de chamadores e raio de impacto.

O Maguyva é essa camada para agentes de código compatíveis com MCP. Não é um editor. Claude Code, Cursor, Codex CLI, VS Code, Windsurf e outros clientes MCP continuam onde estão. O agente consulta um mapa ranqueado antes de tocar em uma linha.

A afirmação é modesta de propósito: menos edições alucinadas. O Maguyva não tira do modelo a capacidade de chutar. Ele muda o primeiro passo padrão de “inventar um caminho plausível” para “pedir locais ranqueados e citados”.

Como é uma resposta fundamentada

Uma resposta útil para “onde a expiração de sessão é tratada” não é um parágrafo. É uma lista curta de locais:

• apps/api/src/middleware/expiry.ts:48 - o handler
• apps/web/src/lib/auth-client.ts:112 - o chamador
• apps/api/tests/expiry.test.ts:20 - o teste que vai falhar se a mudança estiver errada

Você pode abrir essas linhas. Se estiverem erradas, você para. Se estiverem certas, o agente pode editar. A verificação é o ponto, não um slogan.

O Maguyva expõe 11 ferramentas MCP voltadas ao cliente em busca, símbolos, análise de dependências, recuperação de arquivos, contexto de repositório e workflows utilitários determinísticos. Quatro modos de recuperação (semântico, estrutural, grafo/dependência e texto) são fundidos em resultados ranqueados; busca de símbolos é uma ferramenta MCP separada (find_symbol). Respostas fundamentadas voltam com caminhos de arquivo e números de linha, então você pode avaliá-las contra a árvore na sua frente.

Os docs descrevem o caminho mais curto: começar grátis, indexar um repo que você já conhece, conectar o cliente, depois fazer uma pergunta que você consiga verificar.

Um loop que muda a primeira edição

Você não precisa de uma nova religião de fluxo de trabalho. Precisa de um passo extra antes da primeira escrita.

1. Faça uma pergunta que você já consiga avaliar. “Que código trata login e expiração de sessão?” é melhor que “conserta a autenticação”.
2. Exija citações. Caminho de arquivo e número de linha, não um resumo de “o módulo de autenticação”.
3. Abra os arquivos citados. Siga o símbolo. Confirme a dependência que você está prestes a tocar.
4. Só então deixe o agente aplicar o patch.

Se o passo 2 não retorna nada útil, o agente não tem permissão para improvisar um caminho. Ele busca de novo, ou você aponta o caminho. Essa única barreira é o que produz menos edições alucinadas. O modelo é o mesmo modelo. O mapa é o que mudou.

Arquivos de instrução continuam importando. Mantenha-os. Use-os para convenções, regras de revisão e o que não deve ser tocado. Não peça a eles para serem o índice. Um CLAUDE.md que lista três diretórios importantes vai ficar desatualizado na semana seguinte a uma divisão de pacote. Um mapa consultável se atualiza quando o repo se atualiza.

Uma falha relacionada é o arquivo quase-certo: o agente abre auth.ts quando o comportamento vive em auth-client.ts, ou aplica patch em um arquivo gerado em vez da fonte, ou edita a cópia em packages/legacy porque o nome bateu. Citações não tornam esses erros impossíveis. Elas os tornam visíveis antes de o diff pousar.

O que um mapa não vai resolver para você

Seja realista sobre o que você está ganhando. Um mapa fundamentado não vai tornar toda edição correta — seu agente ainda pode escrever um patch ruim exatamente no arquivo certo. Se sua base de código se apoia em despacho dinâmico, reflexão ou monkey-patching, algumas buscas de símbolos vão voltar mais pobres do que você gostaria, porque é isso que a indireção em tempo de execução faz com qualquer índice estático. E se você está esperando uma porcentagem — “caminhos alucinados reduzidos em X%” — você não vai encontrar isso aqui, porque ninguém consegue medir essa cifra honestamente para o seu repo além de você mesmo.

O que você pode esperar é mais estreito e mais útil: o agente para de abrir suas edições com um caminho chutado. Esse primeiro passo fica fundamentado em um mapa real, e é daí que vêm as menos edições alucinadas. Tudo depois da citação — ler o diff, julgar o patch — continua sendo seu trabalho, do jeito que sempre foi.

O teste quase não custa nada: indexe um repo que você já conhece e faça uma pergunta que você consiga verificar. Comece com um caminho que já te queimou antes. Se as citações estiverem erradas, você vai ver na hora. Se estiverem certas, a próxima edição do seu agente tem um lugar melhor para pousar.

// it doesn't know the file. it knows how to find it.