# Perché il tuo agente di coding AI allucina i percorsi dei file

Canonical source: https://maguyva.ai/it/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

> Gli agenti di coding AI inventano percorsi di file quando non hanno una mappa reale del repository. Ecco perché succede, e come la fondatezza porta a meno modifiche allucinate.

Il segnale non è un corpo di funzione sbagliato. È una modifica sicura di sé a un file che non esiste, o a un file che esiste ma non è quello che implementa il comportamento.

Hai chiesto una correzione della scadenza di sessione. L'agente ha aperto `src/auth/session.ts`. Quel percorso è plausibile. È anche sbagliato. L'handler vero vive in `apps/api/src/middleware/expiry.ts`, rinominato due refactoring fa. L'agente non ti ha mentito. Ha completato una stringa a forma di percorso a partire da priori di addestramento più qualsiasi cosa fosse già nella finestra di contesto.

Questo è il modello di fallimento comune su un repository reale. Il modello sa scrivere codice. L'errore sta nello scegliere il posto sbagliato in cui scriverlo.

## Perché gli agenti inventano percorsi

Un agente di coding è un modello di previsione del token successivo dotato di strumenti. Quando dici 'sistema la scadenza di sessione', deve nominare un file prima di poter leggere o applicare una patch a qualsiasi cosa. Se non ha già una mappa fondata, costruisce un percorso a partire da:

1. Convenzioni di denominazione che ha visto in altri repository. `src/auth/session.ts` è una forma frequente.
2. File già presenti nella conversazione, che potrebbero essere quelli che hai incollato la settimana scorsa, non quelli che contano ora.
3. Elenchi di directory che ha eseguito per caso, incompleti su un albero grande.
4. File di istruzioni. `CLAUDE.md` e `AGENTS.md` dicono all'agente come comportarsi. Non sono un indice vivo di simboli, chiamanti, o percorsi attuali.

Nessuna di queste fonti è una mappa di questo repository, oggi. Il modello riempie il vuoto nello stesso modo in cui riempie qualsiasi vuoto: con una continuazione ad alta probabilità. Quella continuazione spesso sembra un percorso reale. A volte il file esiste ed è vicino a quello giusto. A volte esisteva su un branch unito il mese scorso. A volte non è mai esistito.

Grep non ti salva qui se l'agente non cerca affatto la stringa giusta. L'agente ha indovinato un percorso, poi ha letto ciò che quel percorso restituiva, poi lo ha modificato. Il primo passo sbagliato è stato il percorso, non la patch.

Leggere i file non è nemmeno lo stesso che trovare quelli giusti. Claude Code, Cursor, Codex, e strumenti simili possono aprire qualsiasi cosa tu indichi loro. La domanda è se trovano in modo affidabile i file giusti, i simboli importanti, le dipendenze, i test, e il raggio d'impatto prima di modificare. L'accesso ai file senza una mappa inizia comunque con un'indovinello.

## La modifica del file sbagliato è un problema di recupero

Tratta il percorso inventato come un errore di recupero, non come un difetto di personalità.

Se l'agente dovesse restituire `path/file.ext:line` prima di poter modificare, accadrebbero due cose. Primo, potresti aprire la citazione e rifiutare il lavoro in dieci secondi. Secondo, l'agente dovrebbe interrogare qualcosa che conosce davvero l'albero.

Questo è il lavoro di un livello di contesto della codebase. La sola ricerca semantica non basta. Un frammento che 'suona come scadenza di sessione' può comunque atterrare in un pacchetto deprecato. Ti serve anche testo esatto quando conosci la stringa, ricerca di simboli quando conosci il nome, ricerca strutturale quando conosci la forma, e un grafo delle dipendenze quando ti servono i chiamanti e il raggio d'impatto.

Maguyva è quel livello per gli agenti di coding compatibili con MCP. Non è un editor. Claude Code, Cursor, Codex CLI, VS Code, Windsurf, e altri client MCP restano dove sono. L'agente interroga una mappa classificata prima di toccare una riga.

L'affermazione è deliberatamente modesta: meno modifiche allucinate. Maguyva non toglie al modello la capacità di indovinare. Cambia il primo passo predefinito da 'inventare un percorso plausibile' a 'chiedere posizioni classificate e citate'.

## Come appare una risposta fondata

Una risposta utile a 'dove viene gestita la scadenza di sessione' non è un paragrafo. È un breve elenco di posizioni:

- `apps/api/src/middleware/expiry.ts:48` - l'handler
- `apps/web/src/lib/auth-client.ts:112` - il chiamante
- `apps/api/tests/expiry.test.ts:20` - il test che fallirà se la modifica è sbagliata

Puoi aprire queste righe. Se sono sbagliate, ti fermi. Se sono corrette, l'agente può modificare. La verifica è il punto, non uno slogan.

Maguyva espone 11 strumenti MCP rivolti al cliente per ricerca, simboli, analisi delle dipendenze, recupero file, contesto del repository e workflow di utilità deterministici. Quattro modalità di recupero (semantica, strutturale, a grafo/dipendenze e testuale) vengono fuse in risultati classificati; la ricerca di simboli è uno strumento MCP separato (`find_symbol`). Le risposte fondate tornano con percorsi di file e numeri di riga, così puoi valutarle rispetto all'albero di fronte a te.

La [documentazione](/it/docs) descrive il percorso più breve: iniziare gratis, indicizzare un repository che già conosci, collegare il client, poi fare una domanda che puoi verificare.

## Un ciclo che cambia la prima modifica

Non ti serve una nuova religione del workflow. Ti serve un passo in più prima della prima scrittura.

1. Fai una domanda che già puoi valutare. 'Quale codice gestisce il login e la scadenza di sessione?' è meglio di 'sistema l'autenticazione'.
2. Esigi citazioni. Percorso del file e numero di riga, non un riassunto del 'modulo di autenticazione'.
3. Apri i file citati. Segui il simbolo. Conferma la dipendenza che stai per toccare.
4. Solo allora lascia che l'agente applichi la patch.

Se il passo 2 non restituisce nulla di utile, l'agente non ha il diritto di improvvisare un percorso. Cerca di nuovo, oppure glielo indichi tu. Proprio questo unico cancello produce meno modifiche allucinate. Il modello è lo stesso modello. È la mappa che è cambiata.

I file di istruzioni contano ancora. Mantienili. Usali per convenzioni, regole di revisione, e per ciò che non va toccato. Non chiedere loro di essere l'indice. Un `CLAUDE.md` che elenca tre directory importanti sarà obsoleto la settimana dopo una divisione di pacchetto. Una mappa interrogabile si aggiorna quando si aggiorna il repository.

Un fallimento correlato è il file quasi giusto: l'agente apre `auth.ts` quando il comportamento vive in `auth-client.ts`, oppure applica una patch a un file generato invece che alla sorgente, oppure modifica la copia in `packages/legacy` perché il nome corrispondeva. Le citazioni non rendono impossibili questi errori. Li rendono visibili prima che il diff atterri.

## Cosa non ti risolverà una mappa

Sii lucido su cosa ottieni. Una mappa fondata non renderà corretta ogni modifica — il tuo agente può comunque scrivere una patch sbagliata esattamente nel file giusto. Se la tua codebase si affida a dispatch dinamico, reflection, o monkey-patching, alcune ricerche di simboli torneranno più magre di quanto vorresti, perché è quello che l'indirezione a runtime fa a qualsiasi indice statico. E se speri in una percentuale — 'percorsi allucinati ridotti del X%' — non la troverai qui, perché nessuno può misurare onestamente quel numero per il tuo repository tranne te.

Ciò che puoi aspettarti è più stretto e più utile: l'agente smette di aprire le sue modifiche con un percorso indovinato. Quel primo passo diventa fondato in una mappa reale, ed è da lì che vengono le modifiche meno allucinate. Tutto ciò che viene dopo la citazione — leggere il diff, giudicare la patch — resta comunque il tuo lavoro, come è sempre stato.

Il test non ti costa quasi nulla: indicizza un repository che già conosci e fai una domanda che puoi verificare. Inizia con un percorso da cui sei già stato scottato. Se le citazioni sono sbagliate, lo vedrai subito. Se sono corrette, la prossima modifica del tuo agente avrà un posto migliore dove atterrare.

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