Mengapa agen coding AI berhalusinasi jalur file

Tandanya bukan badan fungsi yang salah. Itu adalah perubahan yang percaya diri pada file yang tidak ada, atau file yang ada tetapi bukan yang mengimplementasikan perilaku itu.

Anda meminta perbaikan kedaluwarsa sesi. Agen membuka src/auth/session.ts. Jalur itu masuk akal. Itu juga salah. Handler sebenarnya hidup di apps/api/src/middleware/expiry.ts, diganti namanya dua refactor lalu. Agen tidak berbohong kepada Anda. Ia menyelesaikan string berbentuk jalur dari prior pelatihan ditambah apa pun yang sudah ada di jendela konteks.

Ini adalah pola kegagalan umum pada repo sungguhan. Model bisa menulis kode. Kesalahannya ada pada memilih tempat yang salah untuk menulisnya.

Mengapa agen mengarang jalur

Agen coding adalah model prediksi token berikutnya dengan alat-alat. Saat Anda bilang ‘perbaiki kedaluwarsa sesi’, ia harus menyebutkan file sebelum bisa membaca atau menambal apa pun. Jika belum punya peta yang berdasar, ia membangun jalur dari:

1. Konvensi penamaan yang pernah dilihatnya di repo lain. src/auth/session.ts adalah bentuk yang sering muncul.
2. File yang sudah ada dalam percakapan, yang mungkin adalah yang Anda tempel minggu lalu, bukan yang penting sekarang.
3. Daftar direktori yang kebetulan dijalankannya, tidak lengkap pada pohon yang besar.
4. File instruksi. CLAUDE.md dan AGENTS.md memberi tahu agen cara berperilaku. Itu bukan indeks yang hidup dari simbol, pemanggil, atau jalur terkini.

Tidak satu pun dari sumber ini adalah peta repo ini, hari ini. Model mengisi kekosongan dengan cara yang sama seperti mengisi kekosongan mana pun: dengan kelanjutan berprobabilitas tinggi. Kelanjutan itu sering terlihat seperti jalur sungguhan. Kadang filenya ada dan terletak di sebelah yang benar. Kadang ia pernah ada di branch yang di-merge bulan lalu. Kadang ia tidak pernah ada.

Grep tidak menyelamatkan Anda di sini jika agen tidak pernah mencari string yang benar. Agen menebak jalur, lalu membaca apa yang dikembalikan jalur itu, lalu mengeditnya. Langkah pertama yang salah adalah jalurnya, bukan patch-nya.

Membaca file juga bukan hal yang sama dengan menemukan yang benar. Claude Code, Cursor, Codex, dan alat serupa bisa membuka apa pun yang Anda arahkan. Pertanyaannya adalah apakah mereka secara andal menemukan file yang tepat, simbol yang penting, dependensi, tes, dan cakupan dampak sebelum mengedit. Akses file tanpa peta tetap dimulai dengan tebakan.

Mengedit file yang salah adalah masalah pengambilan

Perlakukan jalur yang dikarang sebagai kegagalan pengambilan, bukan sebagai cacat karakter.

Jika agen harus mengembalikan path/file.ext:line sebelum diizinkan mengedit, dua hal akan terjadi. Pertama, Anda bisa membuka kutipan itu dan menolak pekerjaan dalam sepuluh detik. Kedua, agen harus menanyakan sesuatu yang benar-benar mengenal pohon itu.

Itu adalah pekerjaan lapisan konteks codebase. Pencarian semantik saja tidak cukup. Sepotong yang ‘terdengar seperti kedaluwarsa sesi’ tetap bisa mendarat di paket yang sudah usang. Anda juga butuh teks yang tepat saat Anda tahu stringnya, pencarian simbol saat Anda tahu namanya, pencarian struktural saat Anda tahu bentuknya, dan graf dependensi saat Anda butuh pemanggil dan cakupan dampak.

Maguyva adalah lapisan itu untuk agen coding yang kompatibel MCP. Ini bukan editor. Claude Code, Cursor, Codex CLI, VS Code, Windsurf, dan klien MCP lainnya tetap di tempatnya. Agen menanyakan peta berperingkat sebelum menyentuh satu baris.

Klaimnya sengaja sederhana: lebih sedikit perubahan yang berhalusinasi. Maguyva tidak menghilangkan kemampuan model untuk menebak. Ia mengubah langkah pertama default dari ‘karang jalur yang masuk akal’ menjadi ‘minta lokasi berperingkat, terkutip’.

Seperti apa jawaban yang berdasar

Jawaban yang berguna untuk ‘di mana kedaluwarsa sesi ditangani’ bukanlah sebuah paragraf. Ini daftar singkat lokasi:

• apps/api/src/middleware/expiry.ts:48 - handler-nya
• apps/web/src/lib/auth-client.ts:112 - pemanggilnya
• apps/api/tests/expiry.test.ts:20 - tes yang akan gagal jika perubahan itu salah

Anda bisa membuka baris-baris ini. Jika salah, Anda berhenti. Jika benar, agen boleh mengedit. Verifikasi adalah intinya, bukan slogan.

Maguyva mengekspos 11 alat MCP yang menghadap klien di seluruh pencarian, simbol, analisis dependensi, pengambilan file, konteks repo, dan alur kerja alat bantu deterministik. Empat mode pengambilan (semantik, struktural, graf/dependensi, dan teks) digabung menjadi hasil berperingkat; pencarian simbol adalah alat MCP terpisah (find_symbol). Jawaban yang berdasar kembali dengan jalur file dan nomor baris, sehingga Anda bisa menilainya terhadap pohon di depan Anda.

Dokumentasi menjelaskan jalur terpendek: mulai gratis, indeks repo yang sudah Anda kenal, hubungkan klien, lalu ajukan satu pertanyaan yang bisa Anda verifikasi.

Loop yang mengubah perubahan pertama

Anda tidak butuh agama alur kerja baru. Anda butuh satu langkah ekstra sebelum tulisan pertama.

1. Ajukan pertanyaan yang sudah bisa Anda nilai. ‘Kode mana yang menangani login dan kedaluwarsa sesi?’ lebih baik daripada ‘perbaiki auth’.
2. Tuntut kutipan. Jalur file dan nomor baris, bukan ringkasan ‘modul auth’.
3. Buka file yang dikutip. Ikuti simbolnya. Konfirmasikan dependensi yang akan Anda sentuh.
4. Baru setelah itu biarkan agen menambal.

Jika langkah 2 tidak mengembalikan apa pun yang berguna, agen tidak punya hak untuk mengimprovisasi jalur. Ia mencari lagi, atau Anda menunjukkannya. Justru satu gerbang inilah yang menghasilkan lebih sedikit perubahan yang berhalusinasi. Modelnya adalah model yang sama. Yang berubah adalah petanya.

File instruksi masih penting. Simpan itu. Gunakan untuk konvensi, aturan review, dan apa yang tidak boleh disentuh. Jangan minta mereka menjadi indeks. CLAUDE.md yang mendaftar tiga direktori penting akan basi seminggu setelah pemecahan paket. Peta yang bisa ditanyakan diperbarui saat repo diperbarui.

Kegagalan terkait adalah file yang hampir benar: agen membuka auth.ts padahal perilakunya hidup di auth-client.ts, atau menambal file yang dihasilkan alih-alih sumbernya, atau mengedit salinan di packages/legacy karena namanya cocok. Kutipan tidak membuat kesalahan-kesalahan ini mustahil. Kutipan membuatnya terlihat sebelum diff mendarat.

Apa yang tidak akan diperbaiki peta untuk Anda

Bersikaplah realistis tentang apa yang Anda dapatkan. Peta yang berdasar tidak akan membuat setiap perubahan benar — agen Anda tetap bisa menulis patch yang buruk di file yang persis benar. Jika codebase Anda bersandar pada dispatch dinamis, refleksi, atau monkey-patching, beberapa pencarian simbol akan kembali lebih tipis daripada yang Anda inginkan, karena itulah yang dilakukan indireksi runtime pada indeks statis mana pun. Dan jika Anda mengharapkan persentase — ‘jalur yang berhalusinasi berkurang X%’ — Anda tidak akan menemukannya di sini, karena tidak ada yang bisa secara jujur mengukur angka itu untuk repo Anda selain diri Anda sendiri.

Yang bisa Anda harapkan lebih sempit dan lebih berguna: agen berhenti memulai perubahannya dengan jalur yang ditebak. Langkah pertama itu menjadi berdasar pada peta sungguhan, dan dari situlah lebih sedikit perubahan yang berhalusinasi berasal. Semua yang setelah kutipan — membaca diff, menilai patch — tetap menjadi pekerjaan Anda, seperti selalu.

Tes ini hampir tidak membebani Anda apa pun: indeks satu repo yang sudah Anda kenal dan ajukan satu pertanyaan yang bisa Anda verifikasi. Mulai dengan jalur yang pernah membuat Anda kapok. Jika kutipannya salah, Anda akan langsung melihatnya. Jika benar, perubahan berikutnya dari agen Anda punya tempat yang lebih baik untuk mendarat.

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