Satu File AGENTS.md Belum Cukup: Memory Agent Saya Tiga Lapis
Repo dengan banyak coding agent butuh lebih dari satu file instruksi: AGENTS.md untuk prosedur, memory user untuk preferensi, fact store untuk fakta.
Ringkasan
AGENTS.md itu file instruksi sederhana di root repo yang dibaca berbagai coding agent lintas tool, jadi aturan nggak perlu diduplikat per vendor. Pelajaran utamanya: file instruksi yang kepanjangan justru diabaikan, jadi isi cuma hal yang kalau dihapus bikin salah. Sisanya pecah tiga lapis: prosedur project di AGENTS.md, preferensi developer di memory user, fakta referensi diambil on-demand.
Saya tulis AGENTS.md setelah agent-agent di repo saya ngulang kesalahan yang sama di tiap sesi baru.
Saya punya satu repo yang diisi beberapa coding agent. Claude Code, opencode, dan kawan-kawannya, semua kerja di tempat yang sama. Tiap kali dipanggil, mereka mulai dari nol. Konteks sesi kemarin nggak dibawa. Yang bikin kesal: yang dilupakan itu hal yang sama persis. Struktur folder yang udah disepakati diulang salah. Command testing yang udah dipilih diabaikan. Konvensi commit dilanggar lagi di commit berikutnya.
Solusi paling obvious saya coba dulu: kumpulkan semua aturan di satu file panjang. Semua keputusan desain, semua preferensi, semua gotcha, satu tempat. Nama file bebas, isinya yang penting lengkap. Beres, kan?
Ternyata nggak. File makin panjang, makin banyak aturan yang diabaikan. Agent tetap aja ngulang salah yang sama, dan sebagian instruksi lama ikut jadi korban. File panjang berubah jadi noise: semua baris diperlakukan sama pentingnya, padahal nggak.
Saya salah duga di sini. Saya kira makin lengkap instruksinya, makin akurat agentnya. Kebaliknya: instruksi yang nggak terseleksi malah menurunkan akurasi. Anthropic nulis ini eksplisit di halaman best practices Claude Code: file instruksi yang membengkak bikin instruksi aslinya malah diabaikan [3]. Soalnya sederhana, tiap baris harus lulus satu pertanyaan: kalau baris ini dihapus, agent bakal bikin kesalahan nggak? Kalau jawabannya nggak, buang.
AGENTS.md: satu file yang udah disepakati banyak orang
Pas nyari pola yang lebih sehat, saya nemu agents.md. Bukan framework, bukan SDK, cuma file markdown sederhana di root repo yang isinya instruksi buat coding agent. Situs resminya nyebutnya "README for agents": tempat yang dedicated dan predictable buat konteks yang dibutuhkan AI coding agent [1]. Proyek open source yang memakainya udah lebih dari 60 ribu [1].
Yang bikin saya kepaksa ngecek dulu (dan akhirnya ikut): format ini dijaga lintas tool. Codex, Jules, Cursor, sampai editor-editor besar nerima file yang sama. Satu file instruksi, dibaca banyak agent, nggak perlu duplikat per tool.
Tapi agents.md sendiri cuma nyelesain satu lapis masalah: instruksi project yang dibaca tiap sesi. Sisa masalah saya belum selesai. Preferensi saya sebagai developer itu lintas project, nggak enak ditulis ulang di tiap repo. Dan fakta-fakta yang sifatnya referensi nggak perlu dibaca tiap sesi, cukup dicari pas dibutuhkan.
Tiga lapis: prosedur, preferensi, fakta
Pola yang sekarang jalan di repo saya: pecah memory jadi tiga lapis beda urusan.
Lapis pertama, AGENTS.md di root repo. Isinya prosedur yang berlaku buat semua agent di repo itu: command build dan test, konvensi commit, batasan yang bikin kerusakan kalau dilanggar. Pendek, spesifik, bisa dijalankan. Kalo proyeknya monorepo, agents.md malah support nested: agent otomatis baca file terdekat di directory tree, yang paling dekat menang [1]. Jadi tiap subproyek bisa punya aturan sendiri tanpa mastahin satu file raksasa.
Lapis kedua, memory user. Ini preferensi lintas project, dan cara saya pakainya terinspirasi Claude Code. Claude Code punya dua mekanisme yang dibawa lintas sesi: file instruksi yang ditulis manusia, dan auto memory, catatan yang dia tulis sendiri dari koreksi saya [2]. Yang kedua ini yang bikin hemat: koreksi yang sama nggak perlu saya ketik ulang tiap sesi, dia nyatet sendiri. Catatan itu bisa direview dan dihapus pas udah nggak relevan.
Lapis ketiga, fact store. Fakta yang sifatnya referensi (konvensi panjang, jejak keputusan, hal yang dicari sesekali) disimpan terpisah dan diambil on-demand, bukan ditumpuk di file yang dibaca tiap sesi. Kenapa repot? Volatility-nya beda. Prosedur project jarang berubah. Preferensi developer bergeser per bulan. Fakta referensi berubah tiap minggu. Kalau ketiganya dicampur, update yang sering bikin file yang jarang berubah jadi berisik.
Bridging ke Claude Code
Satu hal yang bikin pola ini praktis: Claude Code nggak baca AGENTS.md, dia baca CLAUDE.md. Dokumen resminya bilang begini: kalau repo kamu udah pakai AGENTS.md, bikin CLAUDE.md yang meng-import AGENTS.md biar kedua tool baca instruksi yang sama tanpa duplikasi [2]. Satu baris @AGENTS.md di CLAUDE.md, selesai. Sisanya tinggal aturan khusus Claude kalau perlu.
Hasil akhirnya bukan cuma soal kerapian file. Beberapa agent yang beda vendor bisa kerja di repo yang sama, baca aturan yang sama, dan koreksi yang saya kasih ke satu agent nggak hilang buat agent lain. File instruksi tetap pendek karena udah nggak jadi tempat penampungan segalanya. Dan tiap sesi baru, yang dilupakan agent tinggal makin sedikit.