# Pourquoi votre agent de code IA hallucine des chemins de fichiers

Canonical source: https://maguyva.ai/fr/blog/why-ai-coding-agents-hallucinate-file-paths

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Date: 2026-08-14 · Author: Maguyva Team

> Les agents de code IA inventent des chemins de fichiers quand ils n'ont pas de vraie carte du dépôt. Voici pourquoi cela arrive, et comment l'ancrage mène à moins de modifications hallucinées.

Le signe révélateur n'est pas un corps de fonction erroné. C'est une modification assurée d'un fichier qui n'existe pas, ou d'un fichier qui existe mais n'est pas celui qui implémente le comportement.

Vous avez demandé une correction d'expiration de session. L'agent a ouvert `src/auth/session.ts`. Ce chemin est plausible. Il est aussi faux. Le vrai gestionnaire vit dans `apps/api/src/middleware/expiry.ts`, renommé il y a deux refactorisations. L'agent ne vous a pas menti. Il a complété une chaîne en forme de chemin à partir de priors d'entraînement plus tout ce qui se trouvait déjà dans la fenêtre de contexte.

C'est le mode d'échec courant sur un dépôt réel. Le modèle sait écrire du code. L'erreur est de choisir le mauvais endroit où l'écrire.

## Pourquoi les agents inventent des chemins

Un agent de code est un modèle de prédiction de token suivant, doté d'outils. Quand vous dites « corrige l'expiration de session » , il doit nommer un fichier avant de pouvoir lire ou corriger quoi que ce soit. S'il n'a pas déjà une carte fondée, il construit un chemin à partir de :

1. Conventions de nommage qu'il a vues dans d'autres dépôts. `src/auth/session.ts` est une forme fréquente.
2. Fichiers déjà présents dans la conversation, qui sont peut-être ceux que vous avez collés la semaine dernière, pas ceux qui comptent maintenant.
3. Listes de répertoires qu'il a exécutées par hasard, incomplètes sur un grand arbre.
4. Fichiers d'instructions. `CLAUDE.md` et `AGENTS.md` disent à l'agent comment se comporter. Ce ne sont pas un index vivant des symboles, des appelants ou des chemins actuels.

Aucune de ces sources n'est une carte de ce dépôt, aujourd'hui. Le modèle comble le vide comme il comble tout vide : avec une continuation hautement probable. Cette continuation ressemble souvent à un vrai chemin. Parfois le fichier existe et se trouve à côté du bon. Parfois il existait sur une branche fusionnée le mois dernier. Parfois il n'a jamais existé.

Grep ne vous sauve pas ici si l'agent ne recherche jamais la bonne chaîne. L'agent a deviné un chemin, puis a lu ce que ce chemin retournait, puis l'a modifié. La première étape erronée était le chemin, pas le correctif.

Lire des fichiers n'est pas non plus la même chose que trouver les bons. Claude Code, Cursor, Codex et des outils similaires peuvent ouvrir tout ce vers quoi vous les pointez. La question est de savoir s'ils trouvent de façon fiable les bons fichiers, les symboles importants, les dépendances, les tests, et le rayon d'impact avant de modifier. L'accès aux fichiers sans carte commence toujours par une supposition.

## La modification du mauvais fichier est un problème de récupération

Traitez le chemin inventé comme un échec de récupération, pas comme un défaut de caractère.

Si l'agent devait renvoyer `path/file.ext:line` avant d'être autorisé à modifier, deux choses se produiraient. D'abord, vous pourriez ouvrir la citation et rejeter le travail en dix secondes. Ensuite, l'agent devrait interroger quelque chose qui connaît réellement l'arbre.

C'est le travail d'une couche de contexte de code. La recherche sémantique seule ne suffit pas. Un fragment qui « sonne comme l'expiration de session » peut quand même atterrir dans un paquet obsolète. Vous avez aussi besoin de texte exact quand vous connaissez la chaîne, de recherche de symboles quand vous connaissez le nom, de recherche structurelle quand vous connaissez la forme, et d'un graphe de dépendances quand vous avez besoin des appelants et du rayon d'impact.

Maguyva est cette couche pour les agents de code compatibles MCP. Ce n'est pas un éditeur. Claude Code, Cursor, Codex CLI, VS Code, Windsurf et les autres clients MCP restent où ils sont. L'agent interroge une carte classée avant de toucher une ligne.

L'affirmation est délibérément modeste : moins de modifications hallucinées. Maguyva ne retire pas au modèle sa capacité à deviner. Il change la première étape par défaut, qui passe d' « inventer un chemin plausible » à « demander des emplacements classés et cités » .

## À quoi ressemble une réponse fondée

Une réponse utile à « où l'expiration de session est-elle gérée » n'est pas un paragraphe. C'est une courte liste d'emplacements :

- `apps/api/src/middleware/expiry.ts:48` - le gestionnaire
- `apps/web/src/lib/auth-client.ts:112` - l'appelant
- `apps/api/tests/expiry.test.ts:20` - le test qui échouera si le changement est faux

Vous pouvez ouvrir ces lignes. Si elles sont fausses, vous vous arrêtez. Si elles sont justes, l'agent peut modifier. La vérification est le but, pas un slogan.

Maguyva expose 11 outils MCP orientés client à travers la recherche, les symboles, l'analyse de dépendances, la récupération de fichiers, le contexte de dépôt et des workflows utilitaires déterministes. Quatre modes de récupération (sémantique, structurel, graphe/dépendance et texte) sont fusionnés en résultats classés ; la recherche de symboles est un outil MCP séparé (`find_symbol`). Les réponses fondées reviennent avec des chemins de fichiers et des numéros de ligne, afin que vous puissiez les évaluer contre l'arbre devant vous.

La [documentation](/fr/docs) décrit le chemin le plus court : commencer gratuitement, indexer un dépôt que vous connaissez déjà, connecter le client, puis poser une question que vous pouvez vérifier.

## Une boucle qui change la première modification

Vous n'avez pas besoin d'une nouvelle religion de workflow. Vous avez besoin d'une étape supplémentaire avant la première écriture.

1. Posez une question que vous pouvez déjà évaluer. « Quel code gère la connexion et l'expiration de session ? » vaut mieux que « corrige l'authentification » .
2. Exigez des citations. Chemin de fichier et numéro de ligne, pas un résumé du « module d'authentification » .
3. Ouvrez les fichiers cités. Suivez le symbole. Confirmez la dépendance que vous êtes sur le point de toucher.
4. Ce n'est qu'ensuite que vous laissez l'agent corriger.

Si l'étape 2 ne renvoie rien d'utile, l'agent n'a pas le droit d'improviser un chemin. Il recherche à nouveau, ou vous l'orientez. Cette seule barrière est ce qui produit moins de modifications hallucinées. Le modèle est le même modèle. La carte est ce qui a changé.

Les fichiers d'instructions comptent toujours. Gardez-les. Utilisez-les pour les conventions, les règles de revue et ce qu'il ne faut pas toucher. Ne leur demandez pas d'être l'index. Un `CLAUDE.md` qui liste trois répertoires importants sera obsolète la semaine suivant une scission de paquet. Une carte interrogeable se met à jour quand le dépôt se met à jour.

Un échec apparenté est le fichier presque-bon : l'agent ouvre `auth.ts` alors que le comportement vit dans `auth-client.ts`, ou modifie un fichier généré au lieu de la source, ou modifie la copie dans `packages/legacy` parce que le nom correspondait. Les citations ne rendent pas ces erreurs impossibles. Elles les rendent visibles avant que le diff n'atterrisse.

## Ce qu'une carte ne résoudra pas pour vous

Soyez lucide sur ce que vous obtenez. Une carte fondée ne rendra pas chaque modification correcte — votre agent peut toujours écrire un mauvais correctif dans exactement le bon fichier. Si votre base de code s'appuie sur le dispatch dynamique, la réflexion ou le monkey-patching, certaines recherches de symboles reviendront plus maigres que vous ne le souhaiteriez, parce que c'est ce que l'indirection à l'exécution fait à tout index statique. Et si vous espérez un pourcentage — « chemins hallucinés réduits de X % » — vous ne le trouverez pas ici, parce que personne ne peut honnêtement mesurer ce chiffre pour votre dépôt, sauf vous.

Ce que vous pouvez attendre est plus étroit et plus utile : l'agent cesse d'ouvrir ses modifications avec un chemin deviné. Cette première étape est ancrée dans une vraie carte, et c'est de là que viennent moins de modifications hallucinées. Tout ce qui suit la citation — lire le diff, juger le correctif — reste votre travail, comme cela l'a toujours été.

Le test ne vous coûte presque rien : indexez un dépôt que vous connaissez déjà et posez une question que vous pouvez vérifier. Commencez par un chemin qui vous a déjà brûlé. Si les citations sont fausses, vous le verrez immédiatement. Si elles sont justes, la prochaine modification de votre agent a un meilleur endroit où atterrir.

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