Agent Operable Codebase

Image: AI generated

Satu Pertanyaan

Buka file terpanjang di proyek Anda. Berapa banyak fungsi di dalamnya?

Suruh agen AI memodifikasi satu fungsi di file itu. Agen akan membaca seluruh file. Ia membuka file karena butuh satu fungsi, tapi 19 fungsi yang tidak diperlukan ikut terbawa.

Di sinilah masalah dimulai.

Kode yang Dibaca Manusia, Kode yang Dikerjakan Agen

Selama ini, kode ditulis untuk dibaca manusia. Penamaan variabel yang baik, komentar, dan dokumentasi – semuanya untuk mengurangi beban kognitif manusia.

Di era agen, pertanyaannya berubah. Apakah kode yang mudah dibaca manusia sama dengan kode yang mudah dikerjakan agen?

Tidak sama.

Manusia bisa scroll file 2.000 baris sambil intuisi bekerja: “bagian ini jangan disentuh.” Agen tidak punya intuisi seperti itu. Membaca 2.000 baris berarti 1.950 baris menjadi polusi konteks.

Penelitian mengonfirmasi ini. Ketika informasi yang tidak relevan tercampur, performa AI turun 30~85%. Bahkan token yang tidak relevan berupa spasi pun menurunkan performa. Konteks yang lebih pendek lebih baik – ini bukan intuisi, melainkan hasil eksperimen.

Jangan masukkan robot ke kantor manusia. Buatlah pabrik tempat robot bisa bekerja.

Tiga Hal yang Dibutuhkan Agen

Agar agen dapat bekerja secara stabil di codebase, tiga hal harus terpenuhi.

1. Harus Bisa Dibaca – Tanpa Noise

Satu file, satu konsep. Nama file adalah nama konsep.

before: read utils.go → 20 fungsi, 19 tidak diperlukan
after:  read check_one_file_one_func.go → 1 fungsi, tepat yang dibutuhkan

filefunc menyelesaikan masalah ini. Dengan 22 aturan struktur, kode dipisahkan per unit makna. Di framework Hono (star 23k+), 186 file dipecah menjadi 626 file. 4.419 tes, tidak ada yang gagal. File bertambah 3,4 kali lipat, tapi logika tidak berubah satu baris pun.

“Bukankah filenya jadi terlalu banyak?” – Agen tidak membuka direktori. Mereka mencari. Entah 500 atau 1.000 file, satu grep saja cukup. Mengambil 5 yang diperlukan lebih mudah daripada tidak membuka 295 yang tidak diperlukan.

2. Harus Bisa Diverifikasi – Secara Mekanis

Jika fungsi tanpa tes dimodifikasi, tidak ada yang tahu apa yang rusak. Agen pun tidak tahu. Terjebak dalam doom loop.

before: 0 tes, tidak tahu apa yang rusak saat dimodifikasi
after:  527 fungsi dengan tes, perubahan perilaku langsung terdeteksi

tsma menyelesaikan masalah ini. Mengindeks semua fungsi di proyek, mendeteksi ada tidaknya tes, mengukur cakupan, dan memberikan umpan balik berupa nomor baris untuk cabang yang belum tercakup.

Tanpa umpan balik, jika LLM diminta menulis tes, cakupan berhenti di 60~70%. Jika diberi tahu “line 41, 44, 70 belum tercakup”, cakupan mencapai 100%. Model yang sama. Perbedaannya hanya resolusi umpan balik.

Dalam eksperimen proyek 527 fungsi: TODO 0 tercapai. Agen otonom berhenti di 40 dan menyatakan “sudah selesai.” Dengan ratchet, 527 selesai semua.

3. Spesifikasi Harus Bisa Diverifikasi Silang

Skema API, skema DB, kebijakan keamanan, dan transisi state harus bisa diperiksa kecocokannya secara mekanis. Ketika satu diubah, harus bisa diketahui sebelum kompilasi apakah terjadi ketidakcocokan.

before: 200 endpoint, konsistensi antar spesifikasi diperiksa manusia
after:  satu operationId menghubungkan semua layer, mesin mendeteksi drift

yongol menyelesaikan masalah ini. 10 SSOT (OpenAPI, DDL, sqlc, SSaC, Rego, Hurl, dll.) dihubungkan dengan satu operationId dan diverifikasi silang dengan ~287 aturan. user_id bertipe string di OpenAPI tapi BIGINT di DDL – kontradiksi antar layer seperti ini tidak bisa ditangkap alat yang ada.

Satu Struktur yang Menembus Tiga Alat

filefunc, tsma, yongol adalah alat independen, tapi memiliki struktur yang sama.

filefunc:  22 aturan struktur → validate → perbaiki → ulangi
tsma:      ukur cakupan → umpan balik cabang belum tercakup → perbaiki → ulangi
yongol:    verifikasi silang → deteksi drift → perbaiki → ulangi

Semuanya loop yang sama.

LLM menghasilkan → alat deterministik menilai → hasilnya dikembalikan ke LLM → ulangi

Symbolic Feedback Loop. Struktur siklis di mana alat deterministik mengoreksi generasi probabilistik LLM. Bukan AI yang memverifikasi AI, melainkan mesin yang memverifikasi AI.

Berikan opini, ia akan menyanjung. Berikan fakta, ia akan memperbaiki. Tanya “kodenya oke?” dan ia menjawab “ya, bagus.” Beri tahu “line 41: field name mismatch” dan ia langsung memperbaiki. Umpan balik tanpa objek sanjungan – karena angka dan lokasi bukan emosi.

Dari Legacy ke Agent-Operable

Tidak perlu mengubah codebase yang ada sekaligus. Ini bukan pondasi baru, melainkan perkuatan gempa. Memperkuat bangunan tanpa menutup toko yang sedang beroperasi.

Tahap 1 – Buat agar bisa dibaca

Pecah file terpanjang terlebih dahulu. Jalankan filefunc validate dan buat pelanggaran menjadi 0. Semua tes yang ada harus tetap lulus.

Tahap 2 – Buat agar bisa diverifikasi

Ulangi tsma next. Tambahkan tes untuk fungsi tanpa tes, isi cabang yang belum tercakup. Jika agen mati di tengah jalan, progres tetap tersimpan. Agen baru menjalankan tsma next dan melanjutkan.

Tahap 3 – Verifikasi silang

Terapkan SSOT dan jalankan yongol validate. Mesin menangkap kontradiksi antar layer.

Setiap tahap independen. Bisa melakukan tahap 2 tanpa tahap 1, atau tahap 1 tanpa tahap 2. Tapi ketika ketiganya digabungkan, jangkauan kerja otonom agen meluas secara dramatis.

Mengubah Sistem Operasi

Agent-operable codebase bukan sekadar lint atau tooling. Ini mengubah sistem operasi codebase.

Banyak orang membuat kereta lebih cepat. Model lebih besar, agen lebih pintar, prompt lebih baik.

Semakin cepat kereta, semakin penting relnya. Orang yang memasang rel masih hampir tidak ada.

Artikel Terkait

• filefunc – Satu File, Satu Konsep – Konvensi struktur kode yang menghilangkan polusi konteks LLM dengan 22 aturan struktur
• tsma – Garis Pertahanan Regresi untuk Kode Legacy – Otomasi tes berbasis ratchet yang menyelesaikan 527 fungsi hingga TODO 0
• Mengapa Agen Coding Bekerja dan Mengapa Gagal – Analisis struktural Symbolic Feedback Loop
• Topologi Umpan Balik Lebih Penting dari IQ Model – Mengapa model yang sama bisa berhenti di 40 atau menyelesaikan 527
• whyso – Yang Tidak Ditunjukkan git blame – Ekstraksi otomatis riwayat perubahan per file

Referensi

• Stanford, “Lost in the Middle: How Language Models Use Long Contexts” (2024) – Performa turun 30%+ ketika informasi relevan terkubur di tengah konteks
• Amazon, “Context Length Alone Hurts LLM Performance” (2025) – Performa turun 13.9~85% meski token yang tidak relevan berupa spasi
• Bukti empiris framework Hono – 186 file → 626 file, 4.419 tes semuanya lulus
• Bukti empiris 527 fungsi tsma – PASS 246 (46,7%), DONE 281 (53,3%), TODO 0
• Eksperimen Ratchet Pattern – Agen otonom 40/527 (7,6%) vs ratchet CLI 527/527 (100%)