# Miksi AI-koodausagenttisi hallusinoi tiedostopolkuja

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

> AI-koodausagentit keksivät tiedostopolkuja, kun niillä ei ole aitoa karttaa repositoriosta. Tässä miksi se tapahtuu, ja miten ankkurointi johtaa vähemmän hallusinoituihin muutoksiin.

Merkki ei ole väärä funktion runko. Se on itsevarma muutos tiedostoon, jota ei ole olemassa, tai tiedostoon, joka on olemassa mutta ei ole se, joka toteuttaa käyttäytymisen.

Pyysit korjausta istunnon vanhentumiseen. Agentti avasi `src/auth/session.ts`. Se polku on uskottava. Se on myös väärä. Aito käsittelijä elää kohteessa `apps/api/src/middleware/expiry.ts`, uudelleennimetty kaksi refaktorointia sitten. Agentti ei valehdellut sinulle. Se täydensi polun muotoisen merkkijonon koulutuksen ennakko-oletusten ja kontekstiikkunassa jo olleen perusteella.

Tämä on tavallinen epäonnistumismalli oikealla repositoriolla. Malli osaa kirjoittaa koodia. Virhe on väärän paikan valitsemisessa sen kirjoittamiseen.

## Miksi agentit keksivät polkuja

Koodausagentti on seuraavan tokenin ennustemalli työkaluineen. Kun sanot 'korjaa istunnon vanhentuminen', sen täytyy nimetä tiedosto ennen kuin se voi lukea tai korjata mitään. Jos sillä ei jo ole ankkuroitua karttaa, se rakentaa polun:

1. Nimeämiskäytännöistä, joita se on nähnyt muissa repositorioissa. `src/auth/session.ts` on yleinen muoto.
2. Tiedostoista, jotka ovat jo keskustelussa, jotka saattavat olla niitä, jotka liitit viime viikolla, eivät niitä, jotka ovat tärkeitä nyt.
3. Hakemistolistauksista, jotka se sattui ajamaan, epätäydellisiä suurella puulla.
4. Ohjetiedostoista. `CLAUDE.md` ja `AGENTS.md` kertovat agentille, miten käyttäytyä. Ne eivät ole elävä indeksi symboleista, kutsujista, tai nykyisistä poluista.

Mikään näistä lähteistä ei ole kartta tästä repositoriosta, tänään. Malli täyttää aukon samalla tavalla kuin se täyttää minkä tahansa aukon: korkean todennäköisyyden jatkumolla. Se jatkumo näyttää usein aidolta polulta. Joskus tiedosto on olemassa ja sijaitsee oikean vieressä. Joskus se oli olemassa haarassa, joka yhdistettiin viime kuussa. Joskus sitä ei ole koskaan ollut.

Grep ei pelasta sinua tässä, jos agentti ei koskaan etsi oikeaa merkkijonoa. Agentti arvasi polun, luki sitten mitä se polku palautti, muokkasi sitten sitä. Ensimmäinen väärä askel oli polku, ei korjaus.

Tiedostojen lukeminen ei myöskään ole sama asia kuin oikeiden löytäminen. Claude Code, Cursor, Codex, ja vastaavat työkalut voivat avata mitä tahansa, mihin osoitat ne. Kysymys on, löytävätkö ne luotettavasti oikeat tiedostot, tärkeät symbolit, riippuvuudet, testit, ja vaikutusalueen ennen muokkaamista. Tiedostoihin pääsy ilman karttaa alkaa silti arvauksella.

## Väärän tiedoston muokkaaminen on hakuongelma

Kohtele keksittyä polkua hakuosumana, ei luonteen puutteena.

Jos agentin pitäisi palauttaa `path/file.ext:line` ennen kuin sen sallitaan muokata, kaksi asiaa tapahtuisi. Ensinnäkin voisit avata lainauksen ja hylätä työn kymmenessä sekunnissa. Toiseksi agentin pitäisi kysyä jotain, joka todella tuntee puun.

Se on koodikannan kontekstikerroksen työ. Pelkkä semanttinen haku ei riitä. Katkelma, joka 'kuulostaa istunnon vanhentumiselta', voi silti laskeutua vanhentuneeseen pakettiin. Tarvitset myös tarkan tekstin, kun tiedät merkkijonon, symbolihaun, kun tiedät nimen, rakenteellisen haun, kun tiedät muodon, ja riippuvuusgraafin, kun tarvitset kutsujia ja vaikutusalueen.

Maguyva on se kerros MCP-yhteensopiville koodausagenteille. Se ei ole editori. Claude Code, Cursor, Codex CLI, VS Code, Windsurf, ja muut MCP-asiakasohjelmat pysyvät siellä, missä ne ovat. Agentti kysyy järjestettyä karttaa ennen kuin se koskee riviä.

Väite on tarkoituksella vaatimaton: vähemmän hallusinoituja muutoksia. Maguyva ei riistä mallilta kykyä arvata. Se muuttaa oletusarvoisen ensimmäisen askeleen 'keksi uskottava polku' -askeleesta 'pyydä järjestettyjä, lainattuja sijainteja' -askeleeksi.

## Miltä perusteltu vastaus näyttää

Hyödyllinen vastaus kysymykseen 'missä istunnon vanhentuminen käsitellään' ei ole kappale. Se on lyhyt lista sijainneista:

- `apps/api/src/middleware/expiry.ts:48` - käsittelijä
- `apps/web/src/lib/auth-client.ts:112` - kutsuja
- `apps/api/tests/expiry.test.ts:20` - testi, joka epäonnistuu, jos muutos on väärä

Voit avata nämä rivit. Jos ne ovat väärin, pysähdyt. Jos ne ovat oikein, agentti voi muokata. Varmennus on pointti, ei iskulause.

Maguyva paljastaa 11 asiakaskäyttöistä MCP-työkalua haulle, symboleille, riippuvuusanalyysille, tiedostojen haulle, repo-kontekstille ja deterministisille apuohjelmatyönkuluille. Neljä hakutilaa (semanttinen, rakenteellinen, graafi/riippuvuus, ja teksti) sulautuvat järjestetyiksi tuloksiksi; symbolihaku on erillinen MCP-työkalu (`find_symbol`). Perustellut vastaukset palaavat tiedostopolkuineen ja rivinumeroineen, joten voit arvioida niitä edessäsi olevaa puuta vasten.

[Dokumentaatio](/fi/docs) kuvaa lyhimmän polun: aloita ilmaiseksi, indeksoi repo, jonka jo tunnet, yhdistä asiakasohjelma, esitä sitten yksi kysymys, jonka voit varmistaa.

## Silmukka, joka muuttaa ensimmäisen muutoksen

Et tarvitse uutta työnkulun uskontoa. Tarvitset yhden ylimääräisen askeleen ennen ensimmäistä kirjoitusta.

1. Esitä kysymys, jonka jo voit arvioida. 'Mikä koodi käsittelee kirjautumisen ja istunnon vanhentumisen?' on parempi kuin 'korjaa autentikointi'.
2. Vaadi lainauksia. Tiedostopolku ja rivinumero, ei yhteenvetoa 'autentikointimoduulista'.
3. Avaa lainatut tiedostot. Seuraa symbolia. Vahvista riippuvuus, jota olet koskettamassa.
4. Vasta silloin annat agentin korjata.

Jos vaihe 2 ei palauta mitään hyödyllistä, agentilla ei ole oikeutta improvisoida polkua. Se etsii uudelleen, tai sinä osoitat sen. Juuri tämä yksi portti on se, mikä tuottaa vähemmän hallusinoituja muutoksia. Malli on sama malli. Kartta on se, mikä on muuttunut.

Ohjetiedostot ovat yhä tärkeitä. Säilytä ne. Käytä niitä käytännöille, katselmointisäännöille, ja sille, mitä ei pidä koskea. Älä pyydä niitä olemaan indeksi. `CLAUDE.md`, joka listaa kolme tärkeää hakemistoa, vanhenee viikko paketin jakamisen jälkeen. Kyseltävä kartta päivittyy, kun repo päivittyy.

Sukua oleva epäonnistuminen on lähes oikea tiedosto: agentti avaa `auth.ts`, kun käyttäytyminen elää kohteessa `auth-client.ts`, tai korjaa generoidun tiedoston lähteen sijaan, tai muokkaa kopiota kohteessa `packages/legacy`, koska nimi täsmäsi. Lainaukset eivät tee näistä virheistä mahdottomia. Ne tekevät ne näkyviksi ennen kuin diffi laskeutuu.

## Mitä kartta ei ratkaise puolestasi

Ole selväpäinen siitä, mitä saat. Perusteltu kartta ei tee jokaisesta muutoksesta oikeaa — agenttisi voi silti kirjoittaa huonon korjauksen täsmälleen oikeaan tiedostoon. Jos koodikantasi nojaa dynaamiseen lähetykseen, refleksioon, tai monkey-patchingiin, jotkin symbolihaut palaavat laihempina kuin toivoisit, koska sitä ajonaikainen epäsuoruus tekee mille tahansa staattiselle indeksille. Ja jos toivot prosenttilukua — 'hallusinoidut polut vähentyneet X%' — et löydä sitä täältä, koska kukaan ei voi rehellisesti mitata sitä lukua repollesi paitsi sinä itse.

Mitä voit odottaa, on kapeampaa ja hyödyllisempää: agentti lakkaa aloittamasta muutoksiaan arvatulla polulla. Tuo ensimmäinen askel ankkuroituu aitoon karttaan, ja siitä vähemmän hallusinoidut muutokset tulevat. Kaikki lainauksen jälkeen — diffin lukeminen, korjauksen arvioiminen — on yhä sinun työtäsi, niin kuin se aina on ollut.

Testi ei maksa sinulle juuri mitään: indeksoi repo, jonka jo tunnet, ja esitä yksi kysymys, jonka voit varmistaa. Aloita polulla, jonka takia sinua on jo poltettu. Jos lainaukset ovat väärin, näet sen heti. Jos ne ovat oikein, agenttisi seuraavalla muutoksella on parempi paikka laskeutua.

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