# Warum dein KI-Coding-Agent Dateipfade halluziniert

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

> KI-Coding-Agenten erfinden Dateipfade, wenn sie keine echte Karte des Repos haben. Hier ist, warum das passiert, und wie Verankerung zu weniger halluzinierten Änderungen führt.

Das Verräterische ist nicht ein falscher Funktionskörper. Es ist eine selbstsichere Änderung an einer Datei, die nicht existiert, oder an einer Datei, die zwar existiert, aber nicht diejenige ist, die das Verhalten implementiert.

Du hast um eine Reparatur des Sitzungsablaufs gebeten. Der Agent hat `src/auth/session.ts` geöffnet. Dieser Pfad ist plausibel. Er ist auch falsch. Der echte Handler lebt in `apps/api/src/middleware/expiry.ts`, umbenannt vor zwei Refactorings. Der Agent hat dich nicht angelogen. Er hat einen pfadförmigen String aus Trainingspriors plus was auch immer schon im Kontextfenster war vervollständigt.

Das ist das übliche Versagensmuster auf einem echten Repository. Das Modell kann Code schreiben. Der Fehler liegt darin, den falschen Ort zum Schreiben zu wählen.

## Warum Agenten Pfade erfinden

Ein Coding-Agent ist ein Next-Token-Modell mit Werkzeugen. Wenn du sagst „repariere den Sitzungsablauf“, muss er eine Datei benennen, bevor er irgendetwas lesen oder patchen kann. Wenn er noch keine verankerte Karte hat, konstruiert er einen Pfad aus:

1. Namenskonventionen, die er in anderen Repositories gesehen hat. `src/auth/session.ts` ist eine häufige Form.
2. Dateien, die schon im Gespräch sind, die vielleicht die sind, die du letzte Woche eingefügt hast, nicht die, die jetzt zählen.
3. Verzeichnislistings, die er zufällig ausgeführt hat, die auf einem großen Baum unvollständig sind.
4. Instruktionsdateien. `CLAUDE.md` und `AGENTS.md` sagen dem Agenten, wie er sich verhalten soll. Sie sind kein lebendiger Index von Symbolen, Aufrufern oder aktuellen Pfaden.

Keine dieser Quellen ist eine Karte dieses Repos, heute. Das Modell füllt die Lücke so, wie es jede Lücke füllt: mit einer hochwahrscheinlichen Fortsetzung. Diese Fortsetzung sieht oft wie ein echter Pfad aus. Manchmal existiert die Datei und liegt neben der richtigen. Manchmal existierte sie auf einem Branch, der letzten Monat gemergt wurde. Manchmal hat sie nie existiert.

Grep rettet dich hier nicht, wenn der Agent nie nach dem richtigen String sucht. Der Agent hat einen Pfad geraten, dann gelesen, was dieser Pfad zurückgab, dann editiert. Der erste falsche Schritt war der Pfad, nicht der Patch.

Dateien zu lesen ist auch nicht dasselbe wie die richtigen zu finden. Claude Code, Cursor, Codex und ähnliche Werkzeuge können öffnen, worauf du sie zeigst. Die Frage ist, ob sie zuverlässig die richtigen Dateien finden, die wichtigen Symbole, die Abhängigkeiten, die Tests und den Auswirkungsradius, bevor sie editieren. Dateizugriff ohne Karte fängt immer noch mit einem Raten an.

## Die Falsche-Datei-Änderung ist ein Retrieval-Problem

Behandle den erfundenen Pfad als Retrieval-Fehltreffer, nicht als Charakterfehler.

Wenn der Agent `path/file.ext:line` zurückgeben müsste, bevor er editieren darf, würden zwei Dinge passieren. Erstens könntest du das Zitat öffnen und die Arbeit in zehn Sekunden ablehnen. Zweitens müsste der Agent etwas abfragen, das den Baum tatsächlich kennt.

Das ist der Job einer Codebase-Context-Schicht. Semantische Suche allein reicht nicht. Ein Chunk, der „nach Sitzungsablauf klingt“, kann trotzdem in einem veralteten Paket landen. Du brauchst auch exakten Text, wenn du den String kennst, Symbol-Lookup, wenn du den Namen kennst, strukturelle Suche, wenn du die Form kennst, und einen Dependency-Graphen, wenn du Aufrufer und Auswirkungsradius brauchst.

Maguyva ist diese Schicht für MCP-kompatible Coding-Agenten. Es ist kein Editor. Claude Code, Cursor, Codex CLI, VS Code, Windsurf und andere MCP-Clients bleiben, wo sie sind. Der Agent fragt eine gerankte Karte ab, bevor er eine Zeile anfasst.

Das Versprechen ist absichtlich bescheiden: weniger halluzinierte Änderungen. Maguyva nimmt dem Modell nicht die Fähigkeit zu raten. Es ändert den Standard-ersten-Schritt von „einen plausiblen Pfad erfinden“ zu „nach gerankten, zitierten Orten fragen“.

## Wie eine fundierte Antwort aussieht

Eine nützliche Antwort auf „wo wird der Sitzungsablauf behandelt“ ist kein Absatz. Es ist eine kurze Liste von Orten:

- `apps/api/src/middleware/expiry.ts:48` - der Handler
- `apps/web/src/lib/auth-client.ts:112` - der Aufrufer
- `apps/api/tests/expiry.test.ts:20` - der Test, der fehlschlägt, wenn die Änderung falsch ist

Du kannst diese Zeilen öffnen. Wenn sie falsch sind, stoppst du. Wenn sie richtig sind, darf der Agent editieren. Die Verifikation ist der Punkt, kein Slogan.

Maguyva stellt 11 kundenseitige MCP-Tools über Suche, Symbole, Abhängigkeitsanalyse, Dateiabruf, Repository-Kontext und deterministische Utility-Workflows bereit. Vier Retrieval-Modi (semantisch, strukturell, Graph/Abhängigkeit und Text) werden zu gerankten Ergebnissen fusioniert; Symbol-Lookup ist ein separates MCP-Tool (`find_symbol`). Fundierte Antworten kommen mit Dateipfaden und Zeilennummern zurück, sodass du sie gegen den Baum vor dir beurteilen kannst.

Die [Docs](/de/docs) beschreiben den kürzesten Weg: kostenlos starten, ein Repo indizieren, das du schon kennst, den Client verbinden, dann eine Frage stellen, die du prüfen kannst.

## Eine Schleife, die die erste Änderung ändert

Du brauchst keine neue Workflow-Religion. Du brauchst einen zusätzlichen Schritt vor dem ersten Schreiben.

1. Stell eine Frage, die du schon beurteilen kannst. „Welcher Code behandelt Login und Sitzungsablauf?“ ist besser als „repariere die Auth“.
2. Verlange Zitate. Dateipfad und Zeilennummer, keine Zusammenfassung von „dem Auth-Modul“.
3. Öffne die zitierten Dateien. Folge dem Symbol. Bestätige die Abhängigkeit, die du gleich anfasst.
4. Erst dann lass den Agenten patchen.

Wenn Schritt 2 nichts Nützliches liefert, darf der Agent keinen Pfad improvisieren. Er sucht erneut, oder du zeigst ihm den Weg. Dieses eine Gate ist es, was weniger halluzinierte Änderungen erzeugt. Das Modell ist dasselbe Modell. Die Karte ist, was sich geändert hat.

Instruktionsdateien zählen weiterhin. Behalte sie. Nutze sie für Konventionen, Review-Regeln und was nicht angefasst werden soll. Bitte sie nicht, der Index zu sein. Ein `CLAUDE.md`, das drei wichtige Verzeichnisse auflistet, ist die Woche nach einem Paket-Split veraltet. Eine abfragbare Karte aktualisiert sich, wenn sich das Repo aktualisiert.

Ein verwandtes Versagen ist die Beinahe-Treffer-Datei: Der Agent öffnet `auth.ts`, wenn das Verhalten in `auth-client.ts` lebt, oder patcht eine generierte Datei statt der Quelle, oder editiert die Kopie in `packages/legacy`, weil der Name gepasst hat. Zitate machen diese Fehler nicht unmöglich. Sie machen sie sichtbar, bevor der Diff landet.

## Was eine Karte nicht für dich löst

Sei ehrlich zu dir selbst, was du bekommst. Eine fundierte Karte macht nicht jede Änderung korrekt – dein Agent kann trotzdem einen schlechten Patch in genau der richtigen Datei schreiben. Wenn dein Codebase auf dynamischem Dispatch, Reflection oder Monkey-Patching aufbaut, kommen manche Symbol-Lookups dünner zurück, als dir lieb ist, weil das nun mal ist, was Laufzeit-Indirektion mit jedem statischen Index macht. Und wenn du auf eine Prozentzahl hoffst – „halluzinierte Pfade um X% reduziert“ – wirst du sie hier nicht finden, weil niemand diese Zahl für dein Repo ehrlich messen kann außer dir selbst.

Was du erwarten kannst, ist enger gefasst und nützlicher: Der Agent hört auf, seine Änderungen mit einem geratenen Pfad zu beginnen. Dieser erste Schritt ist in einer echten Karte verankert, und daher kommen weniger halluzinierte Änderungen. Alles nach dem Zitat – den Diff lesen, den Patch beurteilen – ist immer noch dein Job, genau wie es immer war.

Der Test kostet dich fast nichts: ein Repo indizieren, das du schon kennst, und eine Frage stellen, die du prüfen kannst. Fang mit einem Pfad an, mit dem du schon einmal auf die Nase gefallen bist. Wenn die Zitate falsch sind, siehst du es sofort. Wenn sie richtig sind, hat die nächste Änderung deines Agenten einen besseren Ort zum Landen.

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