Proč váš AI kódovací agent halucinuje cesty k souborům

Poznávacím znamením není špatné tělo funkce. Je to sebejistá úprava souboru, který neexistuje, nebo souboru, který existuje, ale neimplementuje dané chování.

Požádali jste o opravu vypršení relace. Agent otevřel src/auth/session.ts. Ta cesta je věrohodná. Je taky špatná. Skutečný handler žije v apps/api/src/middleware/expiry.ts, přejmenovaném před dvěma refaktoringy. Agent vám nelhal. Doplnil řetězec ve tvaru cesty na základě tréninkových priorů plus toho, co už bylo v kontextovém okně.

Toto je běžný vzorec selhání na skutečném repozitáři. Model umí psát kód. Chyba spočívá ve výběru špatného místa, kam ho napsat.

Proč si agenti vymýšlejí cesty

Kódovací agent je model predikce dalšího tokenu vybavený nástroji. Když řeknete „oprav vypršení relace“, musí nejdřív pojmenovat soubor, než bude moct cokoli číst nebo patchovat. Pokud ještě nemá podloženou mapu, sestaví cestu z:

1. Konvencí pojmenování, které viděl v jiných repozitářích. src/auth/session.ts je častý tvar.
2. Souborů už přítomných v konverzaci, které možná jsou ty, co jste vložili minulý týden, ne ty, na kterých teď záleží.
3. Výpisů adresářů, které náhodou spustil, neúplných na velkém stromu.
4. Instrukčních souborů. CLAUDE.md a AGENTS.md říkají agentovi, jak se chovat. Nejsou to živý index symbolů, volajících ani aktuálních cest.

Žádný z těchto zdrojů není mapou tohoto repozitáře, dnes. Model vyplňuje mezeru stejným způsobem, jakým vyplňuje jakoukoli mezeru: pokračováním s vysokou pravděpodobností. Toto pokračování často vypadá jako skutečná cesta. Někdy soubor existuje a leží vedle toho správného. Někdy existoval na větvi sloučené minulý měsíc. Někdy nikdy neexistoval.

Grep vás tu nezachrání, pokud agent vůbec nehledá správný řetězec. Agent uhodl cestu, pak přečetl, co ta cesta vrátila, pak ji upravil. Prvním chybným krokem byla cesta, ne patch.

Čtení souborů také není totéž co nalezení těch správných. Claude Code, Cursor, Codex a podobné nástroje dokážou otevřít cokoli, na co je namíříte. Otázka zní, jestli spolehlivě najdou správné soubory, důležité symboly, závislosti, testy a rozsah dopadu dřív, než upravují. Přístup k souborům bez mapy stále začíná hádáním.

Úprava špatného souboru je problém vyhledávání

Berte vymyšlenou cestu jako omyl vyhledávání, ne jako povahovou vadu.

Kdyby agent musel vrátit path/file.ext:line dřív, než by mu bylo dovoleno editovat, staly by se dvě věci. Za prvé byste mohli otevřít citaci a odmítnout práci za deset sekund. Za druhé by se agent musel dotázat něčeho, co strom skutečně zná.

Toto je práce vrstvy kontextu kódové báze. Samotné sémantické vyhledávání nestačí. Útržek, který „zní jako vypršení relace“, může pořád přistát v zastaralém balíčku. Potřebujete taky přesný text, když znáte řetězec, vyhledávání symbolů, když znáte jméno, strukturální vyhledávání, když znáte tvar, a graf závislostí, když potřebujete volající a rozsah dopadu.

Maguyva je tato vrstva pro kódovací agenty kompatibilní s MCP. Není to editor. Claude Code, Cursor, Codex CLI, VS Code, Windsurf a další MCP klienti zůstávají tam, kde jsou. Agent se dotazuje seřazené mapy dřív, než se dotkne řádku.

Tvrzení je záměrně skromné: méně halucinovaných úprav. Maguyva modelu neubírá schopnost hádat. Mění výchozí první krok z „vymyslet věrohodnou cestu“ na „vyžádat si seřazená, citovaná místa“.

Jak vypadá podložená odpověď

Užitečná odpověď na otázku „kde se řeší vypršení relace“ není odstavec. Je to krátký seznam míst:

• apps/api/src/middleware/expiry.ts:48 - handler
• apps/web/src/lib/auth-client.ts:112 - volající
• apps/api/tests/expiry.test.ts:20 - test, který selže, pokud je změna špatná

Tyto řádky můžete otevřít. Pokud jsou špatné, zastavíte se. Pokud jsou správné, agent může editovat. Smysl je v ověření, ne v hesle.

Maguyva zpřístupňuje 11 zákaznických MCP nástrojů napříč vyhledáváním, symboly, analýzou závislostí, získáváním souborů, kontextem repozitáře a deterministickými servisními pracovními postupy. Čtyři režimy vyhledávání (sémantický, strukturální, grafový/závislostní a textový) se slévají do seřazených výsledků; vyhledávání symbolů je samostatný MCP nástroj (find_symbol). Podložené odpovědi se vracejí s cestami k souborům a čísly řádků, takže je můžete posuzovat vůči stromu před sebou.

Dokumentace popisuje nejkratší cestu: začít zdarma, naindexovat repozitář, který už znáte, připojit klienta, pak položit jednu otázku, kterou umíte ověřit.

Smyčka, která mění první úpravu

Nepotřebujete novou víru v pracovní postup. Potřebujete jeden krok navíc před prvním zápisem.

1. Položte otázku, kterou už dokážete posoudit. „Jaký kód řeší přihlášení a vypršení relace“ je lepší než „oprav autentizaci“.
2. Vyžadujte citace. Cestu k souboru a číslo řádku, ne shrnutí „modulu autentizace“.
3. Otevřete citované soubory. Sledujte symbol. Potvrďte závislost, které se chystáte dotknout.
4. Teprve pak nechte agenta patchovat.

Pokud krok 2 nevrátí nic užitečného, agent nemá právo cestu improvizovat. Buď hledá znovu, nebo mu ukážete cestu vy. Přesně tato jediná brána vytváří méně halucinovaných úprav. Model je stejný model. Změnila se mapa.

Instrukční soubory jsou pořád důležité. Zachovejte je. Používejte je pro konvence, revizní pravidla a to, čeho se nedotýkat. Nežádejte je, aby byly indexem. CLAUDE.md, který vyjmenovává tři důležité adresáře, zastará týden po rozdělení balíčku. Dotazovatelná mapa se aktualizuje, když se aktualizuje repozitář.

Příbuzné selhání je téměř správný soubor: agent otevře auth.ts, když chování žije v auth-client.ts, nebo patchuje vygenerovaný soubor místo zdroje, nebo edituje kopii v packages/legacy, protože se shodovalo jméno. Citace tyto chyby nedělají nemožnými. Dělají je viditelnými dřív, než diff přistane.

Co za vás mapa nevyřeší

Buďte střízliví ohledně toho, co dostáváte. Podložená mapa neudělá každou úpravu správnou — váš agent i tak může napsat špatný patch přesně do správného souboru. Pokud se vaše kódová báze opírá o dynamický dispatch, reflexi nebo monkey-patching, některá vyhledávání symbolů se vrátí chudší, než byste chtěli, protože přesně to dělá běhová nepřímost s jakýmkoli statickým indexem. A pokud doufáte v procento — „halucinované cesty snížené o X %“ — tady ho nenajdete, protože nikdo kromě vás nedokáže poctivě naměřit toto číslo pro váš repozitář.

Co můžete čekat, je užší a užitečnější: agent přestane začínat úpravy uhodnutou cestou. Tento první krok se podloží skutečnou mapou a odtud pochází méně halucinovaných úprav. Všechno po citaci — čtení diffu, posouzení patche — je pořád vaše práce, stejně jako vždycky byla.

Tento test vás nestojí skoro nic: naindexujte repozitář, který už znáte, a položte jednu otázku, kterou umíte ověřit. Začněte cestou, na které jste se už spálili. Pokud jsou citace špatné, uvidíte to hned. Pokud jsou správné, další úprava vašeho agenta dostane lepší místo k přistání.

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