Codebase Berantakan Bikin AI Coding Agent Ikut Gampang Salah?
AI coding agent bukan mind reader. Artikel ini ngebahas kenapa clean code, test, AGENTS.md, dan boundary repo bisa bikin workflow AI lebih waras.
AI coding agent sering disalahin terlalu cepat. Padahal kadang masalahnya bukan modelnya doang, tapi codebase yang dia baca memang sudah bikin manusia ikut pusing.
Artikel ini ngebahas satu pertanyaan praktis: apakah codebase yang rapi bisa membantu AI coding agent bekerja lebih benar? Jawaban singkatnya: kemungkinan besar iya, walau risetnya masih perlu dibaca dengan hati-hati. Clean code di era AI bukan cuma urusan estetika senior engineer; dia mulai jadi interface kerja buat manusia, reviewer, dan agent yang membaca repo lu.
Apa maksudnya code cleanliness?
Code cleanliness adalah tingkat keterbacaan dan kerapian kode: nama variable jelas, function tidak terlalu panjang, struktur folder masuk akal, dependency tidak disembunyikan, dan test memberi sinyal yang bisa dipercaya. Ini bukan berarti semua kode harus “cantik” atau mengikuti selera satu orang. Maksudnya lebih sederhana: orang lain bisa masuk ke repo, memahami intent, lalu mengubah bagian kecil tanpa menebak-nebak terlalu banyak.
Di kerja harian, clean code sering dianggap sebagai urusan manusia. Kode rapi bikin onboarding lebih cepat, code review lebih ringan, dan debugging tidak terlalu melelahkan. Tapi setelah AI coding agent masuk workflow, definisinya ikut melebar. Codebase lu sekarang bukan cuma dibaca manusia; dia juga dibaca tool yang mencoba menyimpulkan intent dari nama file, test, error message, instruksi repo, dan pola kode yang sudah ada.
Riset SonarSource: codebase rapi vs codebase yang sengaja dibuat buruk
Paper arXiv berjudul Does Code Cleanliness Affect Coding Agents? A Controlled Minimal-Pair Study mencoba menguji efek kebersihan kode terhadap performa coding agent. Penulisnya, Priyansh Trivedi dan Olivier Schmitt dari SonarSource, membandingkan task pada pasangan codebase yang dibuat mirip, tetapi satu versi lebih clean dan satu versi dibuat lebih degraded.
Klaim menariknya: kualitas kode berpotensi memengaruhi kemampuan agent menyelesaikan task. Dengan kata lain, AI coding agent tidak bekerja di ruang kosong. Dia membaca lingkungan kerja yang lu kasih. Kalau lingkungan itu penuh nama ambigu, fungsi campur aduk, boundary kabur, dan test minim, agent punya lebih banyak ruang buat salah menafsirkan maksud.
Tapi bagian pentingnya: jangan baca paper ini sebagai vonis final. Diskusi Hacker News juga banyak yang skeptis terhadap desain eksperimen, terutama karena versi clean dan degraded dibuat secara sintetis. Itu kritik yang valid. Riset awal seperti ini lebih baik dibaca sebagai sinyal, bukan hukum alam. Namun buat builder, lesson praktisnya tetap kuat: kualitas codebase adalah input penting untuk kualitas output agent.
Kenapa AI agent gampang kejebak codebase berantakan?
AI coding agent menebak konteks dari banyak sinyal kecil. Nama function, struktur folder, README, test, pattern import, pesan error, bahkan komentar lama bisa jadi petunjuk. Kalau sinyal-sinyal itu saling bertabrakan, agent bisa terlihat “ngawur”, padahal dia cuma mengikuti petunjuk yang memang tidak konsisten.
Contoh sederhana: lu punya function bernama validateUser, tapi ternyata dia juga menulis ke database, mengirim email, dan mengubah status subscription. Buat manusia, ini code smell. Buat agent, ini jebakan intent. Saat diminta “ubah validasi user”, agent bisa menyentuh logic database atau email karena boundary-nya sudah tidak jelas dari awal.
Martin Fowler menjelaskan istilah code smell sebagai tanda bahwa ada sesuatu di kode yang mungkin perlu diperiksa lebih dalam. Code smell tidak selalu bug, tapi dia mengirim sinyal bahwa desainnya berisiko. Di era AI agent, smell seperti ini bukan cuma bikin manusia lambat; dia juga bisa bikin agent mengambil jalur yang salah dengan percaya diri.
Clean code sekarang juga jadi interface buat agent
Gua suka mikir codebase sebagai UI. Bedanya, UI ini bukan cuma untuk user aplikasi, tapi untuk manusia dan agent yang merawat software. Kalau UI produk berantakan, user salah klik. Kalau UI codebase berantakan, reviewer salah paham dan agent salah edit.
Interface codebase yang bagus biasanya punya beberapa ciri:
- Nama jelas: function dan file memberi petunjuk intent, bukan cuma implementasi.
- Boundary tegas: folder, module, dan service punya tanggung jawab yang tidak saling tumpang tindih.
- Test relevan: test menangkap perilaku penting, bukan cuma menaikkan angka coverage.
- Dokumentasi tipis tapi tepat: README, AGENTS.md, atau docs internal menjelaskan cara kerja repo tanpa jadi novel.
- Error message berguna: saat gagal, agent dan manusia tahu harus mulai debug dari mana.
GitHub sendiri mulai mendukung AGENTS.md untuk Copilot code review. Ini sinyal menarik: instruksi repo yang eksplisit mulai dianggap penting agar agent tidak cuma membaca kode mentah. Tapi AGENTS.md bukan pengganti codebase rapi. Dia lebih mirip papan petunjuk. Kalau jalannya tetap rusak, papan petunjuk tidak cukup menyelamatkan perjalanan.
Checklist praktis: rapihin repo sebelum nyalahin model
Sebelum buru-buru ganti model AI, coba cek lima hal ini dulu. Ini bukan checklist sakral, tapi cukup buat mengurangi area abu-abu yang bikin agent gampang salah jalan.
1. Tulis instruksi repo yang eksplisit
Buat file seperti AGENTS.md atau bagian khusus di README. Isi dengan cara menjalankan test, command build, struktur folder penting, aturan style, dan area yang tidak boleh disentuh sembarangan. Agent butuh context yang stabil, bukan instruksi panjang yang berubah tiap chat.
2. Pecah function yang punya terlalu banyak tanggung jawab
Kalau satu function melakukan validasi, transformasi data, akses database, dan kirim notifikasi, agent akan susah mengubah satu bagian tanpa menyenggol bagian lain. Pecah berdasarkan responsibility, bukan berdasarkan selera “biar kelihatan clean”.
3. Pastikan test mewakili perilaku penting
AI agent sangat bergantung pada feedback loop. Kalau test tidak ada, agent cuma menebak. Kalau test terlalu rapuh, agent mengejar test pass tanpa memahami perilaku. Minimal, punya test untuk alur utama, edge case berisiko, dan bug yang pernah kejadian.
4. Rapihin nama sebelum rapihin arsitektur besar
Refactor besar sering mahal. Tapi mengganti nama variable, function, dan file yang menipu bisa memberi dampak cepat. Nama yang jelas mengurangi kebutuhan komentar dan membantu agent menyimpulkan intent lebih akurat.
5. Buat boundary file untuk hal sensitif
Kalau ada area seperti auth, payment, migration, secret handling, atau data deletion, tandai dengan jelas. Bisa lewat folder convention, komentar singkat, docs, atau aturan di AGENTS.md. Agent boleh bantu, tapi area high-risk tetap perlu review manusia yang lebih ketat.
Yang sering dilupain: codebase rapi bukan berarti over-engineering
Ada jebakan lain: karena pengin “rapi”, tim malah bikin abstraction berlapis-lapis yang susah dipahami. Ini juga buruk buat agent. Clean code bukan berarti semua hal harus dibuat generic, reusable, dan enterprise-looking. Kadang duplikasi kecil lebih mudah dibaca daripada abstraction yang salah.
Patokan gua sederhana: rapi itu ketika intent lebih mudah dibaca dan perubahan kecil lebih aman dilakukan. Kalau refactor bikin manusia butuh lima file tambahan untuk paham satu alur, agent juga belum tentu lebih terbantu.
Takeaway buat developer yang pakai AI coding agent
- AI coding agent bukan mind reader. Dia membaca sinyal dari repo lu.
- Clean code adalah interface kerja, bukan cuma estetika.
- Instruksi seperti AGENTS.md membantu, tapi tidak bisa menambal arsitektur yang terlalu kabur.
- Test, naming, boundary, dan docs kecil sering lebih berguna daripada prompt super panjang.
- Jangan jadikan riset awal sebagai klaim final, tapi pakai sebagai alasan buat merapikan workflow hari ini.
FAQ singkat
Apakah clean code pasti bikin AI agent lebih akurat?
Belum bisa dibilang pasti untuk semua kasus. Riset SonarSource memberi sinyal kuat, tapi desain eksperimennya tetap perlu dibaca kritis. Yang aman: codebase rapi memberi sinyal lebih jelas untuk manusia dan agent.
Apakah AGENTS.md wajib?
Tidak wajib, tapi sangat berguna kalau lu rutin pakai AI agent. Anggap saja sebagai buku manual singkat repo: command penting, aturan kerja, boundary, dan hal yang harus diverifikasi.
Mana yang lebih penting: prompt bagus atau codebase rapi?
Dua-duanya penting, tapi prompt bagus tidak akan selalu menyelamatkan repo yang sinyalnya kacau. Kalau agent terus salah di area yang sama, cek struktur kode, test, dan dokumentasi repo sebelum menyalahkan model.
Penutup
Menurut gua, pelajaran paling praktis dari topik ini bukan “semua developer harus jadi clean code purist”. Pelajaran yang lebih berguna: kalau lu mau AI agent jadi multiplier, codebase lu harus cukup jelas untuk dibantu.
AI bisa mempercepat kerja, tapi dia juga memperbesar konsekuensi dari repo yang berantakan. Jadi sebelum nambah prompt, nambah tool, atau pindah model, coba rapihin interface yang paling dekat dulu: codebase lu sendiri.