Kenapa ejen pengekodan AI anda berhalusinasi laluan fail

Tandanya bukan badan fungsi yang salah. Ia adalah perubahan yang yakin pada fail yang tidak wujud, atau pada fail yang wujud tetapi bukan fail yang melaksanakan tingkah laku itu.

Anda meminta pembetulan tamat tempoh sesi. Ejen membuka src/auth/session.ts. Laluan itu munasabah. Ia juga salah. Pengendali sebenar hidup dalam apps/api/src/middleware/expiry.ts, dinamakan semula dua penstrukturan semula yang lalu. Ejen itu tidak menipu anda. Ia melengkapkan rentetan berbentuk laluan berdasarkan prasyarat latihan ditambah apa sahaja yang sudah berada dalam tetingkap konteks.

Ini ialah corak kegagalan biasa pada repositori sebenar. Model boleh menulis kod. Kesilapannya ialah memilih tempat yang salah untuk menulisnya.

Kenapa ejen mereka-reka laluan

Ejen pengekodan ialah model ramalan token seterusnya yang dilengkapi alat. Apabila anda berkata ‘betulkan tamat tempoh sesi’, ia mesti menamakan satu fail sebelum ia boleh membaca atau menampal apa-apa. Jika ia belum mempunyai peta yang berasas, ia membina laluan daripada:

1. Konvensyen penamaan yang pernah dilihatnya dalam repositori lain. src/auth/session.ts adalah bentuk yang kerap.
2. Fail yang sudah berada dalam perbualan, yang mungkin adalah fail yang anda tampal minggu lepas, bukan yang penting sekarang.
3. Penyenaraian direktori yang secara kebetulan dijalankannya, tidak lengkap pada pokok yang besar.
4. Fail arahan. CLAUDE.md dan AGENTS.md memberitahu ejen cara berkelakuan. Ia bukan indeks hidup bagi simbol, pemanggil, atau laluan semasa.

Tiada satu pun sumber ini adalah peta repo ini, hari ini. Model itu mengisi jurang dengan cara yang sama ia mengisi mana-mana jurang: dengan kesinambungan berkebarangkalian tinggi. Kesinambungan itu selalunya kelihatan seperti laluan sebenar. Kadangkala fail itu wujud dan terletak di sebelah yang betul. Kadangkala ia wujud pada cabang yang digabungkan bulan lepas. Kadangkala ia tidak pernah wujud.

Grep tidak menyelamatkan anda di sini jika ejen langsung tidak mencari rentetan yang betul. Ejen meneka satu laluan, kemudian membaca apa yang dikembalikan laluan itu, kemudian mengeditnya. Langkah salah pertama ialah laluan itu, bukan tampalan itu.

Membaca fail juga bukan perkara yang sama dengan mencari yang betul. Claude Code, Cursor, Codex, dan alat serupa boleh membuka apa sahaja yang anda tunjukkan kepadanya. Persoalannya ialah sama ada mereka secara boleh dipercayai menemui fail yang betul, simbol yang penting, kebergantungan, ujian, dan lingkungan impak sebelum mengedit. Akses fail tanpa peta masih bermula dengan tekaan.

Mengedit fail yang salah adalah masalah pengambilan semula

Anggap laluan yang direka-reka itu sebagai kesilapan pengambilan semula, bukan kecacatan watak.

Jika ejen perlu mengembalikan path/file.ext:line sebelum ia dibenarkan mengedit, dua perkara akan berlaku. Pertama, anda boleh membuka petikan itu dan menolak kerja itu dalam sepuluh saat. Kedua, ejen perlu menyoal sesuatu yang benar-benar mengenali pokok itu.

Itulah kerja lapisan konteks pangkalan kod. Carian semantik sahaja tidak mencukupi. Petikan yang ‘kedengaran seperti tamat tempoh sesi’ masih boleh mendarat dalam pakej yang sudah luput. Anda juga memerlukan teks tepat apabila anda mengetahui rentetan itu, carian simbol apabila anda tahu namanya, carian struktur apabila anda tahu bentuknya, dan graf kebergantungan apabila anda memerlukan pemanggil dan lingkungan impak.

Maguyva ialah lapisan itu untuk ejen pengekodan yang serasi MCP. Ia bukan editor. Claude Code, Cursor, Codex CLI, VS Code, Windsurf, dan klien MCP lain kekal di tempatnya. Ejen menyoal peta berperingkat sebelum menyentuh satu baris.

Dakwaan itu sengaja sederhana: perubahan berhalusinasi yang lebih sedikit. Maguyva tidak mengambil daripada model keupayaan untuk meneka. Ia mengubah langkah pertama lalai daripada ‘reka-reka laluan yang munasabah’ kepada ‘minta lokasi berperingkat, yang dipetik’.

Bagaimana rupa jawapan yang berasas

Jawapan yang berguna kepada ‘di manakah tamat tempoh sesi dikendalikan’ bukanlah satu perenggan. Ia adalah senarai lokasi yang ringkas:

• apps/api/src/middleware/expiry.ts:48 - pengendali
• apps/web/src/lib/auth-client.ts:112 - pemanggil
• apps/api/tests/expiry.test.ts:20 - ujian yang akan gagal jika perubahan itu salah

Anda boleh membuka baris-baris ini. Jika salah, anda berhenti. Jika betul, ejen boleh mengedit. Pengesahan itulah intinya, bukan slogan.

Maguyva mendedahkan 11 alat MCP yang berorientasikan pelanggan merentasi carian, simbol, analisis kebergantungan, pengambilan fail, konteks repositori dan aliran kerja alat utiliti deterministik. Empat mod pengambilan semula (semantik, struktur, graf/kebergantungan, dan teks) digabungkan menjadi hasil berperingkat; carian simbol ialah alat MCP yang berasingan (find_symbol). Jawapan yang berasas kembali dengan laluan fail dan nombor baris, supaya anda boleh menilainya berbanding pokok di hadapan anda.

Dokumentasi menerangkan laluan terpendek: mula secara percuma, indeks repo yang sudah anda kenali, sambungkan klien, kemudian tanya satu soalan yang boleh anda sahkan.

Gelung yang mengubah perubahan pertama

Anda tidak memerlukan agama aliran kerja baharu. Anda memerlukan satu langkah tambahan sebelum tulisan pertama.

1. Tanya satu soalan yang sudah boleh anda nilai. ‘Kod mana yang mengendalikan log masuk dan tamat tempoh sesi?’ lebih baik daripada ‘betulkan auth’.
2. Tuntut petikan. Laluan fail dan nombor baris, bukan ringkasan ‘modul auth’.
3. Buka fail yang dipetik. Ikuti simbol itu. Sahkan kebergantungan yang bakal anda sentuh.
4. Hanya kemudian benarkan ejen menampal.

Jika langkah 2 tidak mengembalikan apa-apa yang berguna, ejen tiada hak untuk mengimprovisasi laluan. Ia mencari semula, atau anda menunjukkannya. Justeru satu pintu gerbang itulah yang menghasilkan perubahan berhalusinasi yang lebih sedikit. Model itu adalah model yang sama. Peta itulah yang berubah.

Fail arahan masih penting. Kekalkan ia. Gunakan untuk konvensyen, peraturan semakan, dan apa yang tidak sepatutnya disentuh. Jangan minta ia menjadi indeks. CLAUDE.md yang menyenaraikan tiga direktori penting akan lapuk seminggu selepas pembahagian pakej. Peta yang boleh disoal dikemas kini apabila repo dikemas kini.

Kegagalan yang berkaitan ialah fail yang hampir betul: ejen membuka auth.ts sedangkan tingkah laku hidup dalam auth-client.ts, atau menampal fail yang dijana berbanding sumber, atau mengedit salinan dalam packages/legacy kerana nama itu sepadan. Petikan tidak menjadikan kesilapan ini mustahil. Ia menjadikan kesilapan ini kelihatan sebelum diff itu mendarat.

Apa yang tidak akan dibetulkan peta untuk anda

Bersikap tenang tentang apa yang anda perolehi. Peta yang berasas tidak akan menjadikan setiap perubahan betul — ejen anda masih boleh menulis tampalan yang buruk tepat pada fail yang betul. Jika pangkalan kod anda bersandar pada dispatch dinamik, refleksi, atau monkey-patching, sesetengah carian simbol akan kembali lebih nipis daripada yang anda mahu, kerana itulah yang dilakukan ketaklangsungan masa jalan kepada mana-mana indeks statik. Dan jika anda mengharapkan peratusan — ‘laluan berhalusinasi berkurangan X%’ — anda tidak akan menemuinya di sini, kerana tiada sesiapa boleh mengukur angka itu secara jujur untuk repo anda selain diri anda sendiri.

Apa yang boleh anda jangkakan adalah lebih sempit dan lebih berguna: ejen berhenti memulakan perubahannya dengan laluan yang diteka. Langkah pertama itu menjadi berasas dalam peta sebenar, dan dari situlah datangnya perubahan berhalusinasi yang lebih sedikit. Segala-galanya selepas petikan itu — membaca diff, menilai tampalan itu — masih kerja anda, sebagaimana ia selalu berlaku.

Ujian ini hampir tidak membebankan anda apa-apa: indeks repo yang sudah anda kenali dan tanya satu soalan yang boleh anda sahkan. Mulakan dengan laluan yang pernah membakar anda. Jika petikan itu salah, anda akan melihatnya serta-merta. Jika betul, perubahan seterusnya ejen anda mempunyai tempat yang lebih baik untuk mendarat.

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