Varför din AI-kodande agent hallucinerar filsökvägar

Tecknet är inte en felaktig funktionskropp. Det är en självsäker ändring i en fil som inte finns, eller i en fil som finns men inte är den som implementerar beteendet.

Du bad om en fix för sessionsutgång. Agenten öppnade src/auth/session.ts. Den sökvägen är trolig. Den är också fel. Den verkliga handlern lever i apps/api/src/middleware/expiry.ts, omdöpt för två refaktoreringar sedan. Agenten ljög inte för dig. Den kompletterade en sökvägsformad sträng utifrån träningspriors plus vad som redan fanns i kontextfönstret.

Det här är det vanliga misslyckandemönstret på ett verkligt repo. Modellen kan skriva kod. Missen är att välja fel plats att skriva den på.

Varför agenter hittar på sökvägar

En kodande agent är en modell för nästa-token-förutsägelse med verktyg. När du säger ‘fixa sessionsutgång’ måste den namnge en fil innan den kan läsa eller patcha något. Om den inte redan har en förankrad karta konstruerar den en sökväg från:

1. Namngivningskonventioner den sett i andra repon. src/auth/session.ts är en vanlig form.
2. Filer redan i konversationen, som kanske är de du klistrade in förra veckan, inte de som spelar roll nu.
3. Kataloglistningar den råkade köra, ofullständiga på ett stort träd.
4. Instruktionsfiler. CLAUDE.md och AGENTS.md berättar för agenten hur den ska bete sig. De är inget levande index över symboler, anropare, eller aktuella sökvägar.

Ingen av dessa källor är en karta över det här repot, idag. Modellen fyller luckan på samma sätt som den fyller varje lucka: med en fortsättning med hög sannolikhet. Den fortsättningen ser ofta ut som en verklig sökväg. Ibland finns filen och ligger bredvid den rätta. Ibland fanns den på en gren som slogs samman förra månaden. Ibland har den aldrig funnits.

Grep räddar dig inte här om agenten aldrig söker efter rätt sträng. Agenten gissade en sökväg, läste sedan vad den sökvägen returnerade, och redigerade den sedan. Det första felsteget var sökvägen, inte patchen.

Att läsa filer är inte heller detsamma som att hitta de rätta. Claude Code, Cursor, Codex, och liknande verktyg kan öppna vad du än pekar dem mot. Frågan är om de tillförlitligt hittar rätt filer, de viktiga symbolerna, beroendena, testerna, och påverkansradien innan de redigerar. Filåtkomst utan en karta börjar fortfarande med en gissning.

Redigering av fel fil är ett hämtningsproblem

Behandla den påhittade sökvägen som en hämtningsmiss, inte som en karaktärsbrist.

Om agenten var tvungen att returnera path/file.ext:line innan den fick lov att redigera skulle två saker hända. För det första skulle du kunna öppna citatet och avvisa arbetet på tio sekunder. För det andra skulle agenten behöva fråga något som verkligen känner till trädet.

Det är jobbet för ett kodbaskontextlager. Enbart semantisk sökning räcker inte. Ett fragment som ‘låter som sessionsutgång’ kan ändå landa i ett avvecklat paket. Du behöver också exakt text när du känner till strängen, symbolsökning när du känner till namnet, strukturell sökning när du känner till formen, och en beroendegraf när du behöver anropare och påverkansradie.

Maguyva är det lagret för MCP-kompatibla kodande agenter. Det är ingen editor. Claude Code, Cursor, Codex CLI, VS Code, Windsurf, och andra MCP-klienter stannar där de är. Agenten frågar en rankad karta innan den rör en rad.

Påståendet är medvetet blygsamt: färre hallucinerade ändringar. Maguyva tar inte bort modellens förmåga att gissa. Det ändrar standardens första steg från ‘hitta på en trolig sökväg’ till ‘be om rankade, citerade platser’.

Hur ett underbyggt svar ser ut

Ett användbart svar på ‘var hanteras sessionsutgång’ är inte ett stycke. Det är en kort lista med platser:

• apps/api/src/middleware/expiry.ts:48 - handlern
• apps/web/src/lib/auth-client.ts:112 - anroparen
• apps/api/tests/expiry.test.ts:20 - testet som misslyckas om ändringen är fel

Du kan öppna de här raderna. Om de är fel stannar du. Om de är rätt kan agenten redigera. Verifieringen är poängen, inte en slogan.

Maguyva exponerar 11 kundvända MCP-verktyg för sökning, symboler, beroendeanalys, filhämtning, repo-kontext och deterministiska hjälpverktygsflöden. Fyra hämtningslägen (semantiskt, strukturellt, graf/beroende, och text) smälts samman till rankade resultat; symbolsökning är ett separat MCP-verktyg (find_symbol). Underbyggda svar kommer tillbaka med filsökvägar och radnummer, så att du kan bedöma dem mot trädet framför dig.

Dokumentationen beskriver den kortaste vägen: börja gratis, indexera ett repo du redan känner till, anslut klienten, ställ sedan en fråga du kan verifiera.

En loop som förändrar den första ändringen

Du behöver ingen ny arbetsflödesreligion. Du behöver ett extra steg innan den första skrivningen.

1. Ställ en fråga du redan kan bedöma. ‘Vilken kod hanterar inloggning och sessionsutgång?’ är bättre än ‘fixa auth’.
2. Kräv citat. Filsökväg och radnummer, inte en sammanfattning av ‘auth-modulen’.
3. Öppna de citerade filerna. Följ symbolen. Bekräfta beroendet du är på väg att röra.
4. Först då låter du agenten patcha.

Om steg 2 inte returnerar något användbart har agenten inte rätt att improvisera en sökväg. Den söker igen, eller så pekar du åt den. Precis den enda grinden är vad som ger färre hallucinerade ändringar. Modellen är samma modell. Kartan är vad som har förändrats.

Instruktionsfiler spelar fortfarande roll. Behåll dem. Använd dem för konventioner, granskningsregler, och det som inte ska röras. Be dem inte vara indexet. En CLAUDE.md som listar tre viktiga kataloger blir föråldrad veckan efter en paketuppdelning. En sökbar karta uppdateras när repot uppdateras.

Ett besläktat misslyckande är nästan-rätt-filen: agenten öppnar auth.ts när beteendet lever i auth-client.ts, eller patchar en genererad fil istället för källan, eller redigerar kopian i packages/legacy eftersom namnet stämde. Citat gör inte de här misstagen omöjliga. De gör dem synliga innan diffet landar.

Vad en karta inte fixar åt dig

Var nykter om vad du får. En underbyggd karta gör inte varje ändring korrekt — din agent kan fortfarande skriva en dålig patch i exakt rätt fil. Om din kodbas lutar sig mot dynamisk dispatch, reflektion, eller monkey-patching kommer vissa symbolsökningar att returnera magrare än du skulle vilja, eftersom det är vad körtidsindirektion gör med varje statiskt index. Och om du hoppas på en procentandel — ‘hallucinerade sökvägar minskade med X%’ — hittar du den inte här, eftersom ingen ärligt kan mäta det talet för ditt repo förutom du själv.

Det du kan förvänta dig är smalare och mer användbart: agenten slutar öppna sina ändringar med en gissad sökväg. Det första steget blir förankrat i en verklig karta, och det är därifrån färre hallucinerade ändringar kommer. Allt efter citatet — att läsa diffet, bedöma patchen — är fortfarande ditt jobb, precis som det alltid varit.

Testet kostar dig nästan ingenting: indexera ett repo du redan känner till och ställ en fråga du kan verifiera. Börja med en sökväg du redan blivit bränd av. Om citaten är fel ser du det omedelbart. Om de är rätt har din agents nästa ändring en bättre plats att landa på.

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