Jangan buat AGENTS.md otomatis dengan /init — malah cuma menaikkan biaya 20%

Klaim utama

• Jika file konteks untuk agen coding AI (AGENTS.md) dibuat otomatis dengan perintah /init, performa agen justru menurun dan biaya naik lebih dari 20%
• Masalah utamanya adalah pemberian informasi yang duplikatif, padahal agen bisa menemukannya sendiri
• AGENTS.md seharusnya hanya berisi informasi yang tidak bisa diketahui agen hanya dengan membaca kode

Hasil riset: AGENTS.md membantu atau malah merugikan

• Lulla et al. (ICSE JAWs 2026): eksperimen berpasangan pada 124 GitHub PR dengan hanya membandingkan ada atau tidaknya AGENTS.md
  • Saat AGENTS.md ada, waktu eksekusi turun 28.64%, token output turun 16.58%
  • File yang digunakan dalam riset ini benar-benar dipelihara oleh developer dan berisi pengetahuan yang spesifik untuk proyek tersebut
• Riset ETH Zurich: menguji 4 agen pada SWE-bench dan lainnya, sambil membedakan file yang dibuat otomatis oleh LLM dan file yang ditulis developer
  • Konteks yang dibuat otomatis oleh LLM: tingkat keberhasilan tugas turun 2~3%, biaya naik 20%+
    • Dalam lingkungan yang seluruh dokumen yang ada seperti README dihapus, file buatan LLM justru menaikkan performa sebesar 2.7%
  • File yang ditulis langsung oleh developer: tingkat keberhasilan naik sekitar 4%, biaya naik hingga 19%
• Kesimpulan: bukan konten otomatisnya yang buruk, tetapi duplikasi informasinya
  • Jika informasi yang sama diberikan dua kali, hasilnya hanya menambah noise; yang benar-benar membantu hanyalah pengetahuan yang tidak bisa ditemukan sendiri dan ditulis developer

Mengapa pembuatan otomatis itu merugikan

• AGENTS.md yang dibuat otomatis umumnya berisi informasi yang sebenarnya sudah bisa ditemukan agen sendiri
  • Gambaran codebase (100% output Sonnet 4.5, 99% output GPT-5.2 menyertakan ini)
  • Struktur direktori, tech stack, penjelasan modul
• Jika informasi yang sudah diketahui diberikan lagi, itu hanya menghabiskan token tanpa nilai tambah
• Efek anchoring: jika pola lama disebutkan, agen akan terpaku pada pola itu meskipun ada alternatif yang lebih baik
  • Ini selaras dengan riset "Lost in the Middle" (Liu et al., 2024) — konteks yang panjang memecah perhatian dan menurunkan performa

Apa yang harus dimasukkan ke AGENTS.md vs yang tidak boleh dimasukkan

• Yang harus dimasukkan (informasi yang tidak bisa ditemukan agen)
  • Penetapan tool: "gunakan uv untuk manajemen paket"
  • Aturan yang tidak intuitif: "test wajib dijalankan dengan --no-cache, kalau tidak fixture akan memicu false positive"
  • Batasan sistem: "modul auth memakai middleware kustom, jangan refactor ke Express standar"
  • Jika tool disebut dalam dokumen, agen memakainya 1.6~2.5 kali per tugas; jika tidak didokumentasikan, angkanya turun drastis menjadi kurang dari 0.05 kali
• Yang tidak boleh dimasukkan (bisa ditemukan agen sendiri)
  • Struktur direktori, layout monorepo
  • Ringkasan tech stack, pola arsitektur standar

Keterbatasan struktural file statis

• Bahkan AGENTS.md yang ditulis dengan baik pun punya kelemahan mendasar — file bersifat statis, sedangkan tugas bersifat dinamis
• Instruksi dalam satu file tidak bisa bercabang berdasarkan jenis tugas
  • Pada tugas edit dokumentasi pun, instruksi seperti "jalankan seluruh test sebelum commit" tetap diterapkan sehingga token dan waktu terbuang
  • Saat refactor CSS, peringatan migrasi DB ikut dimuat; saat memperbaiki keamanan, petunjuk optimasi performa ikut terbawa
• Framework ACE (ICLR 2026): alih-alih file statis, pendekatan Agentic Context Engineering yang mengembangkan konteks secara dinamis lewat pipeline generator/reflector/curator mencatat performa 12.3% lebih tinggi dibanding metode statis

Struktur yang lebih baik, tapi belum benar-benar ada

• Terkait AGENTS.md, banyak orang secara independen sampai pada kesimpulan yang sama
  • Struktur yang tepat bukan satu file tunggal, melainkan lapisan routing + konteks terfokus yang dimuat saat diperlukan
• Layer 1 - file protokol: bukan gambaran umum codebase atau style guide, tetapi dokumen routing
  • Mendefinisikan persona yang tersedia dan kapan dipanggil, skill dan jenis tugas yang ditangani, koneksi MCP dan kegunaannya
  • Hanya berisi fakta repo minimum yang tidak bisa ditemukan agen, dan tidak memuat hal lain
• Layer 2 - file persona/skill: dimuat secara selektif sesuai jenis tugas
  • Agen UX dan agen backend memuat konteks yang berbeda, dan tidak memuat konteks milik pihak lain
• Layer 3 - sub-agen pemeliharaan: agen khusus untuk menjaga akurasi file protokol
  • Dokumentasi membusuk — bahkan riset ETH Zurich pun melihat penurunan performa meski pengujiannya memakai file yang baru dibuat
  • Jika AGENTS.md dibiarkan 6 bulan, lalu masih menjelaskan dependency yang sudah diganti atau struktur direktori yang sudah berubah, dampaknya akan jauh lebih parah
• Saat ini belum ada agen coding utama yang menyediakan lifecycle hook untuk menerapkan arsitektur ini dengan mudah — bisa didekati dengan sub-agen dan scoped context, tetapi masih ada celah tool yang belum terisi

Optimasi otomatis

• Arize AI memakai loop optimasi otomatis alih-alih menulis instruksi CLAUDE.md secara manual
  • Menjalankan agen pada tugas pelatihan → mengevaluasi hasil → membuat umpan balik LLM tentang penyebab kegagalan → memperbaiki instruksi lewat meta-prompting → mengulang
  • Pada pengujian cross-repo, akurasi naik +5.19%; pada pengujian in-repo, naik +10.87%
• Fakta tidak nyaman yang diungkap optimizer: hal yang membantu manusia memahami codebase berbeda dari hal yang dibutuhkan LLM untuk bernavigasi
  • Informasi seperti "service ini memakai pola repository" terlihat jelas berguna bagi developer, tetapi bisa menjadi noise bagi model
  • Sebaliknya, hal yang benar-benar dibutuhkan model (pembedaan import path tertentu, aturan penamaan file yang tidak intuitif, dan sebagainya) sering kali sudah terlalu terinternalisasi oleh developer sampai-sampai tidak terpikir untuk ditulis
• Menulis AGENTS.md secara manual berarti mengasumsikan developer tahu apa yang dibutuhkan agen
  • Bukti empiris mengisyaratkan kemungkinan besar tidak
  • Optimizer menemukan perbedaan antara "apa yang dianggap penting" dan "apa yang benar-benar mengubah hasil"
• Namun ini bukan berarti penulisan harus ditinggalkan — 5% itu bermakna, tapi tidak revolusioner. Artinya, jangan terlalu bergantung pada intuisi; uji secara nyata

Mindset yang tepat dalam memandang AGENTS.md

• Lihat AGENTS.md sebagai catatan dari proses yang belum sempat diperbaiki
• Setiap baris yang ditambahkan adalah sinyal bahwa ada bagian codebase yang cukup ambigu hingga bisa membingungkan agen AI, dan sangat mungkin juga akan membingungkan kontributor manusia baru
• Respons yang tepat bukan memperbesar file konteks, melainkan memperbaiki akar masalahnya
  • Agen menaruh utility di direktori yang salah → berarti struktur direktori itu sendiri membingungkan, jadi tata ulang
  • Agen terus memakai dependency yang sudah deprecated → berarti struktur import terlalu memudahkan dependency lama itu terambil, jadi perbaiki
  • Agen melewatkan type checking → jangan bergantung pada instruksi, tangkap otomatis di build pipeline
• AGENTS.md adalah alat diagnostik, bukan konfigurasi permanen — tambahkan satu baris, telusuri mengapa agen terus mengulang kesalahan itu, perbaiki akar masalahnya, lalu hapus baris tersebut
• Teknik yang bisa dicoba: mulai dengan AGENTS.md yang hampir kosong dan hanya tambahkan satu instruksi, "kalau menemukan sesuatu yang terasa mengejutkan atau membingungkan di proyek ini, tinggalkan komentar". Sebagian besar tambahan yang diusulkan agen bukan untuk disimpan permanen, melainkan penanda titik-titik codebase yang tidak jelas

Rekomendasi praktis

• Berhenti menjalankan /init — kecuali repo benar-benar tidak punya dokumentasi sama sekali, hasil pembuatan otomatis hanya akan menduplikasi dokumen yang sudah ada
• Sebelum menambahkan satu baris ke AGENTS.md, tanyakan: "apakah agen bisa mengetahui ini hanya dengan membaca kode?" Kalau ya, jangan ditulis
• Jika agen berulang kali gagal, perbaiki codebase-nya terlebih dahulu sebelum memperbesar file konteks
  • Perbaiki struktur kode, tambahkan aturan linter, perluas cakupan test — dan hanya sentuh AGENTS.md jika itu pun masih belum cukup
• Jika agen dijalankan dalam skala besar di pipeline CI/CD atau auto-review, sadari bahwa overhead biaya 15~20% akan terakumulasi secara majemuk di ribuan eksekusi
• Naluri untuk melakukan onboarding agen seperti karyawan baru (tur kantor, bagan organisasi, penjelasan arsitektur) memang wajar, tetapi agen coding bukan karyawan baru — bahkan sebelum prompt selesai diketik, ia sudah bisa grep seluruh codebase. Yang dibutuhkan agen bukan peta, melainkan lokasi ranjau

[lloydkwon]

Katanya pada akhirnya ini pertarungan soal context...
Sepertinya perlu dibuat terpisah antara file md untuk agent dan file md untuk pengguna.

[lukeio]

Saya sangat setuju. Struktur yang mudah dibaca manusia (README) dan struktur yang mudah diparse LLM (AGENTS.md) memang benar-benar berbeda. Jika seluruh konteks dibuat otomatis lalu dilempar begitu saja, yang terbuang hanya biaya token API, dan saya juga sering mengalami hal itu justru memperparah halusinasi. Pada akhirnya, meski merepotkan, sepertinya yang paling efisien adalah instruksi untuk agen diringkas dan dipoles langsung oleh manusia.

[sonnet]

Pada awalnya ada README, dan AGENTS.md pada dasarnya adalah README yang dibuat untuk agen.

[jaehar16]

Tapi bukankah itu sudah ada di README?

[armila]

Tapi modelnya sendiri berubah hanya dalam beberapa bulan,
sementara agents harus disesuaikan lagi dengan model itu...
Bukankah perubahan model berlangsung lebih cepat daripada waktu yang dibutuhkan untuk membuat struktur agents yang tepat?
Sebelum orang sempat terbiasa dengan alatnya, alatnya sudah keburu berubah...

[jjw9512151]

Pada akhirnya, sepertinya yang terpenting adalah menjaga context tetap murni dan dengan token sesedikit mungkin.. Dari sudut pandang ini, rasanya karakter Tionghoa juga cukup berguna ya. wkwk

[aliveornot]

Bagi model, bahasa Inggris itu sekarang hampir seperti 1 kata = 1 huruf (token), jadi bukankah pada dasarnya sudah seperti hanzi?

[eususu]

Oh, saya belum kepikiran pendekatan seperti ini, tapi sepertinya memang masuk akal!

[t7vonn]

Oh ..