Anda terbangun dengan lima laporan bug kritis pada Senin pagi. Alat pemantauan tinjauan Anda telah menjalankan tugasnya. Ia menangkap setiap laporan crash, setiap ulasan bintang satu yang marah, setiap "aplikasi membeku saat saya mengetuk simpan." Anda tahu persis apa yang rusak. Namun, yang tidak Anda ketahui adalah di mana harus mencarinya.

Itulah tembok yang saya hadapi setelah membangun pipeline pertama saya. Pipeline tersebut memantau ulasan aplikasi dan log crash yang masuk tanpa masalah, menyortir setiap potongan umpan balik ke dalam kategori yang rapi: bug, crash, atau permintaan fitur. Dashboard terlihat sehat. Namun, proses debugging yang sebenarnya tidak.

Mengetahui adanya bug hanyalah langkah awal yang sangat kecil. Saya masih harus membuka IDE, melakukan grep melalui modul, melakukan referensi silang stack trace terhadap codebase saat ini, dan merekonstruksi jalur kegagalan di dalam kepala saya. Ketika tiket-tiket menumpuk dan kopi masih panas, proses arkeologi manual tersebut membuang waktu yang tidak Anda miliki. Saya butuh pipeline yang melakukan lebih dari sekadar menandai masalah. Saya butuh pipeline yang menginvestigasinya.

Jadi, saya membangun kembali sistem tersebut dengan satu tujuan tunggal: mengambil laporan bug mentah dan mengembalikan diagnosis yang tervalidasi. Bukan sekadar paragraf renungan LLM. Melainkan temuan terstruktur yang menyebutkan nama file, menunjukkan barisnya, memperkirakan risikonya, dan menyarankan perbaikan. Berikut adalah cara saya mewujudkannya.

Mengapa Struktur Lebih Baik daripada Log Chat

Saya membangun agen investigasi ini dengan PydanticAI. Alasannya sederhana. Ketika Anda meminta model bahasa untuk menalar tentang kode, output standarnya adalah aliran teks yang ramah. Itu mungkin membantu pembaca manusia, tetapi tidak berguna bagi skrip downstream. Saya membutuhkan kontrak yang dapat dibaca oleh mesin.

Agen tersebut mengembalikan model data yang divalidasi dengan empat bidang spesifik: penyebab utama (root cause), file yang terdampak, usulan perubahan, serta penilaian kompleksitas dan risiko. Jika model kehilangan satu bidang atau berhalusinasi tentang jalur file, validasi akan gagal dan saya dapat langsung mengetahuinya. Ketegasan tersebut menjaga integritas pipeline.

Untuk melakukan pekerjaan detektif yang sebenarnya, agen tersebut mendapatkan empat alat read-only dan tidak ada yang lain. Ia dapat mencari kode melalui grep, membaca rentang baris tertentu dari sebuah file, mencantumkan isi direktori, dan menemukan simbol seperti kelas atau fungsi. Read-only adalah bagian yang penting. Saya tidak ingin agen dengan akses tulis berkeliaran di repositori saya pada jam 2 pagi. Pahami dulu, baru edit.

Repo Map: Konteks Sebelum Alat

Versi pertama agen ini akurat tetapi sangat mahal. Ia menghabiskan token seperti turis yang berjalan berputar-putar. Model tersebut akan memanggil list-dir, lalu grep, lalu membaca file, lalu list-dir lagi, secara perlahan menyusun model mental struktur proyek satu per satu token yang mahal.

Solusinya adalah dengan menghasilkan repo map yang ringkas sebelum agen mulai bekerja. Peta ini adalah ringkasan distilasi dari repositori: file-file kunci, fungsi atau kelas utamanya, dan bagaimana modul-modul utama terhubung. Anggap saja seperti memberikan GPS kepada agen alih-alih memintanya menemukan jalan melalui coba-coba.

Dengan peta tersebut di dalam context window-nya, agen tidak membuang-buang panggilan untuk mencari tahu apakah src/utils/parser.ts ada. Ia sudah mengetahui medannya. Ia langsung menuju ke puncak bukit tempat asap mengepul. Perubahan tunggal tersebut sepenuhnya menghilangkan fase "berkeliling tanpa arah".

Tool Funnel: Memaksa Sebuah Kesimpulan

Bahkan dengan adanya peta, agen bisa saja ragu-ragu. Ia akan menemukan file yang mencurigakan, lalu meragukan dirinya sendiri, lalu mencari lagi, lalu membaca file lain, terjebak dalam loop tanpa akhir dari sekadar "satu pengecekan lagi". Saya butuh cara untuk memaksakan momentum.

Saya menerapkan tool funnel tiga fase yang membatasi apa yang dapat dilakukan agen seiring kemajuannya.

Fase pertama adalah eksplorasi. Agen memiliki akses penuh ke keempat alat. Ia dapat mencari, menelusuri, dan membaca apa pun yang dibutuhkannya untuk mereplikasi bug dalam penalaran-nya.

Fase kedua adalah deep-dive. Setelah agen mengidentifikasi garis kesalahan yang mungkin, ia kehilangan alat penemuan. Ia hanya dapat membaca file. Tidak ada lagi grep, tidak ada lagi daftar direktori. Pada tahap ini, ia harus mempelajari kode yang telah ditemukan dan membangun rantai buktinya.

Fase ketiga adalah output. Semua alat dikunci. Agen tidak dapat lagi melakukan kueri ke codebase. Ia harus duduk dan menulis laporan. Ini mencegah spiral "biarkan saya memeriksa satu hal lagi" yang tidak ada habisnya.

Funnel tersebut menurunkan rata-rata jumlah panggilan alat dari lebih dari empat puluh per analisis menjadi sekitar sepuluh. Agen menjadi lebih cepat, lebih murah, dan secara paradoks menjadi lebih percaya diri karena ia harus berkomitmen pada sebuah kesimpulan.

Menjaga Backend agar Tetap Swappable

Saya tidak ingin mengunci sistem pada satu penyedia model saja. Saya menggunakan mesin yang berbeda tergantung pada tugasnya. Terkadang Claude Code, terkadang Grok Build, terkadang apa pun yang paling murah saat itu. Untuk menjaga logika inti tetap agnostik terhadap penyedia, saya membagi pekerjaan menjadi dua tahap.

Tahap pertama adalah eksplorasi. Agen pengkodean, yang bisa berupa model mumpuni apa pun, membaca peta repo, menggunakan alat, dan menghasilkan laporan markdown mentah. Ini adalah bagian pemikiran yang mahal.

Tahap kedua adalah penstrukturan. LLM yang murah dan cepat mengambil markdown tersebut dan memformat ulang ke dalam model Pydantic yang ketat. Tahap ini hampir tidak memerlukan penalaran. Ini hanyalah ekstraksi dan pemformatan, sehingga dapat berjalan pada perangkat keras ringan.

Karena batasannya jelas, saya dapat menukar backend tanpa menyentuh logika validasi. Laporan markdown bertindak sebagai adaptor universal antara otak eksploratif dan output terstruktur yang sebenarnya saya gunakan.

Apa yang Benar-benar Berhasil

Pengaturan ini mengubah cara saya menangani issue yang masuk. Lapisan klasifikasi masih memisahkan bug dari permintaan fitur, tetapi sekarang lapisan analisis langsung mengambil alih segera setelahnya. Pada saat saya membuka editor, saya sudah memiliki jalur file, rentang baris, dan usulan perubahan yang menunggu saya. Saya tetap meninjau semuanya secara manual. Ini adalah bantuan, bukan autopilot. Namun pengumpulan konteks yang dulu