# Bakit nagha-hallucinate ng mga file path ang AI coding agent mo

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

> Gumagawa-gawa ng mga file path ang AI coding agent kapag wala silang tunay na mapa ng repo. Ito ang dahilan kung bakit nangyayari ito, at kung paano nagreresulta ang naka-ground na mapa sa mas kaunting hallucinated na pagbabago.

Hindi ang maling function body ang senyales. Ito ay isang kumpiyanteng pagbabago sa isang file na hindi umiiral, o sa isang file na umiiral ngunit hindi ang file na nagpapatupad sa asal na iyon.

Hiningi mo ang pag-aayos ng session expiry. Binubuksan ng agent ang `src/auth/session.ts`. Plausible ang path. Mali rin ito. Ang tunay na handler ay naninirahan sa `apps/api/src/middleware/expiry.ts`, na binago ang pangalan dalawang refactor na ang nakalipas. Hindi nagsisinungaling sa iyo ang agent. Kinukumpleto nito ang isang path-shaped na string batay sa training bias kasama ang anumang nasa context window na.

Ito ay karaniwang failure pattern sa mga tunay na repository. Kayang magsulat ng code ang modelo. Ang pagkakamali nito ay ang pagpili ng maling lugar para isulat ito.

## Bakit gumagawa-gawa ng path ang mga agent

Ang mga coding agent ay mga next-token prediction model na may sangkap na mga tool. Kapag sinabi mong 'ayusin ang session expiry', kailangan nitong pangalanan ang isang file bago ito makabasa o makapag-patch ng anuman. Kung wala pa itong naka-ground na mapa, bumubuo ito ng path mula sa:

1. Naming convention na nakita nito sa ibang repository. Ang `src/auth/session.ts` ay isang karaniwang anyo.
2. Mga file na nasa usapan na, na maaaring iyong file na na-paste mo noong nakaraang linggo, hindi ang mahalaga ngayon.
3. Directory listing na natakbo nito nang aksidente, hindi kumpleto sa isang malaking tree.
4. Instruction file. Sinasabi ng `CLAUDE.md` at `AGENTS.md` sa agent kung paano kumilos. Hindi ito buhay na index ng mga symbol, tumatawag, o kasalukuyang path.

Wala sa mga pinagmulang ito ang mapa ng repo na ito, ngayon. Pinupunan ng modelo ang puwang sa parehong paraan na pinupunan nito ang alinmang puwang: gamit ang high-probability na continuation. Madalas mukhang tunay na path ang continuation na iyon. Minsan umiiral ang file at nasa tamang neighborhood ito. Minsan umiiral ito sa isang branch na na-merge noong nakaraang buwan. Minsan hindi ito kailanman umiral.

Hindi ka mase-save ng grep dito kung hindi man naghanap ang agent ng tamang string mula sa simula. Nagha-hula ang agent ng path, saka binabasa kung ano ang ibinabalik ng path na iyon, saka ie-edit ito. Ang unang maling hakbang ay ang path, hindi ang patch.

Hindi rin pareho ang pagbasa ng mga file sa paghahanap ng tama. Maaaring buksan ng Claude Code, Cursor, Codex, at kahalintulad na tool ang anumang itinuro mo dito. Ang tanong ay kung maaasahan nila mahanap ang tamang file, ang mahalagang symbol, mga dependency, test, at saklaw ng epekto bago mag-edit. Ang file access nang walang mapa ay nagsisimula pa rin sa panghuhula.

## Ang pag-edit ng maling file ay problema sa retrieval

Isipin ang na-gawa-gawang path bilang isang pagkakamali sa retrieval, hindi kapintasan sa karakter.

Kung kailangang ibalik ng agent ang `path/file.ext:line` bago ito pahintulutang mag-edit, may mangyayaring dalawang bagay. Una, maaari mong buksan ang cited at tanggihan ang gawain sa loob ng sampung segundo. Ikalawa, kailangang magtanong ang agent ng isang bagay na tunay na kilala ang tree na iyon.

Iyan ang gawain ng codebase context layer. Hindi sapat ang semantic search lang. Isang cited na 'parang session expiry' ay maaari pa ring dumapo sa isang deprecated na package. Kailangan mo rin ng eksaktong text kapag alam mo ang string, symbol search kapag alam mo ang pangalan, structural search kapag alam mo ang hugis, at dependency graph kapag kailangan mo ng mga tumatawag at saklaw ng epekto.

Ang Maguyva ang layer na iyon para sa mga MCP-compatible na coding agent. Hindi ito editor. Nananatili sa kanilang mga lugar ang Claude Code, Cursor, Codex CLI, VS Code, Windsurf, at ibang MCP client. Itinatanong ng agent ang ranked na mapa bago galawin ang isang linya.

Ang inaangkin ay sadyang katamtaman: mas kaunting hallucinated na pagbabago. Hindi inaalis ng Maguyva ang kakayahang manghula ng modelo. Binabago nito ang default na unang hakbang mula sa 'gumawa-gawa ng plausible na path' patungo sa 'humingi ng ranked, cited na lokasyon'.

## Ano ang hitsura ng naka-ground na sagot

Hindi isang talata ang kapaki-pakinabang na sagot sa 'saan hinahawakan ang session expiry'. Ito ay isang maikling listahan ng mga lokasyon:

- `apps/api/src/middleware/expiry.ts:48` - handler
- `apps/web/src/lib/auth-client.ts:112` - tumatawag
- `apps/api/tests/expiry.test.ts:20` - test na mabibigo kung mali ang pagbabago

Maaari mong buksan ang mga linyang ito. Kung mali, huminto ka. Kung tama, maaaring mag-edit ang agent. Ang pag-verify ang punto, hindi ang slogan.

Inilalantad ng Maguyva ang 11 customer-facing MCP tool sa search, symbol, dependency analysis, file retrieval, repository context, at deterministic utility-tool workflow. Ang apat na retrieval mode (semantic, structural, graph/dependency, at text) ay nagsasama sa isang ranked na resulta; ang symbol search ay hiwalay na MCP tool (`find_symbol`). Bumabalik ang mga naka-ground na sagot na may file path at line number, para mapa-evaluate mo ang mga ito laban sa tree na nasa harap mo.

Inilalarawan ng [dokumentasyon](/fil/docs) ang pinakamaikling daan: magsimula nang libre, i-index ang repo na kilala mo na, ikonekta ang client, pagkatapos ay magtanong ng isang tanong na kaya mong ma-verify.

## Ang loop na nagbabago sa unang pagbabago

Hindi mo kailangan ng bagong relihiyon sa workflow. Kailangan mo ng isang dagdag na hakbang bago ang unang pagsulat.

1. Magtanong ng isang tanong na kaya mo nang husgahan. Mas mahusay ang 'aling code ang humahawak sa login at session expiry?' kaysa 'ayusin ang auth'.
2. Humingi ng mga cited. File path at line number, hindi buod ng 'auth module'.
3. Buksan ang cited na file. Sundan ang symbol. I-verify ang mga dependency na gagalawin mo.
4. Pahintulutan lang mag-patch ang agent pagkatapos.

Kung walang ibinalik na kapaki-pakinabang ang hakbang 2, walang karapatan ang agent na mag-improvise ng path. Naghahanap ito ulit, o ipinapakita mo dito. Ang solong gate na iyon ang gumagawa ng mas kaunting hallucinated na pagbabago. Parehong modelo ang modelo. Ang mapa ang nagbabago.

Mahalaga pa rin ang mga instruction file. Panatilihin ang mga ito. Gamitin para sa mga convention, panuntunan sa review, at kung ano ang hindi dapat galawin. Huwag hilingin sa mga ito na maging index. Ang `CLAUDE.md` na naglilista ng tatlong mahahalagang directory ay lipas na sa loob ng isang linggo matapos ang paghahati ng package. Ang naitatanong na mapa ay nag-a-update kapag nag-update ang repo.

Ang may kaugnayang pagkabigo ay ang halos-tamang file: binubuksan ng agent ang `auth.ts` habang naninirahan ang asal sa `auth-client.ts`, o pina-patch ang isang na-generate na file sa halip na ang source, o ine-edit ang isang kopya sa `packages/legacy` dahil tumugma ang pangalan. Hindi ginagawang imposible ng cited ang mga pagkakamaling ito. Ginagawa nitong nakikita ang mga ito bago dumapo ang diff.

## Ano ang hindi aayusin ng mapa para sa iyo

Maging tapat tungkol sa nakukuha mo. Hindi gagawing tama ng naka-ground na mapa ang bawat pagbabago — maaari pa ring sumulat ang agent mo ng masamang patch sa mismong tamang file. Kung umaasa ang codebase mo sa dynamic dispatch, reflection, o monkey-patching, magbabalik ng mas manipis na resulta ang ilang symbol search kaysa sa gusto mo, dahil iyan ang ginagawa ng runtime indirection sa anumang static index. At kung umaasa ka ng porsyento — 'bumaba ang mga hallucinated path nang X%' — hindi mo ito matatagpuan dito, dahil walang sinuman ang makasusukat ng numerong iyon nang tapat para sa repo mo maliban sa iyo mismo.

Ang maaasahan mo ay mas makitid at mas kapaki-pakinabang: hihinto ang agent sa pagsisimula ng pagbabago nito gamit ang isang hinulaang path. Ang unang hakbang na iyon ay nagiging naka-ground sa tunay na mapa, at mula doon nanggagaling ang mas kaunting hallucinated na pagbabago. Lahat ng bagay matapos ang cited — pagbasa ng diff, pag-evaluate ng patch — gawain mo pa rin, gaya ng dati.

Halos walang kabuluhan ang pagsubok na ito: i-index ang repo na kilala mo na at magtanong ng isang tanong na kaya mong ma-verify. Magsimula sa path na nakapaso na sa iyo dati. Kung mali ang cited, makikita mo agad. Kung tama, may mas mahusay na lugar dadapuan ang susunod na pagbabago ng agent mo.

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