AGENTS.md: Satu File Konteks untuk Semua Coding Agent (Codex, Gemini, Claude)

Kamu habiskan satu sore untuk menulis CLAUDE.md yang rapi. Agen-mu akhirnya berhenti menebak-nebak stack-mu dan mulai menjalankan perintah test yang benar. Lalu seorang rekan tim membuka repo yang sama pakai Codex, kamu coba Gemini CLI di sebuah branch, dan semua konteks yang susah payah kamu bangun itu tidak ikut terbawa. Tiap tool maunya punya file sendiri, di tempatnya sendiri.

AGENTS.md adalah jawaban dari kekacauan itu: satu file Markdown biasa, di root repo-mu, yang dibaca coding agent apa pun sebelum menyentuh kodemu.

AGENTS.md itu sebenarnya apa

Tidak ada sihir. Ini cuma file Markdown bernama AGENTS.md, biasanya di root repositori, yang dimuat sebuah agen sebagai instruksi tetap sebelum mulai bekerja. Anggap saja seperti README yang kamu tulis untuk rekan tim AI-mu alih-alih untuk rekan manusiamu: apa proyek ini, cara build dan test-nya, konvensi yang harus dihormati, dan jebakan yang harus dihindari.

Ini konvensi terbuka, sudah dibaca Codex dan daftar tool agen yang terus bertambah, dengan tujuan eksplisit agar portabel di antara semuanya. Satu file, banyak agen, bukan satu file khusus per tool.

AGENTS.md vs CLAUDE.md vs GEMINI.md

Saat ini lanskapnya terbagi-bagi per tool:

• CLAUDE.md adalah yang dicari Claude Code.
• GEMINI.md adalah konvensi milik Gemini CLI.
• AGENTS.md adalah standar lintas-tool, dibaca Codex dan lainnya, dirancang sebagai file yang netral.

Isinya hampir identik di ketiganya: konteks proyek, perintah, konvensi. Satu-satunya perbedaan nyata adalah nama file yang dibaca tiap tool secara default. Justru karena itulah menduplikasi aturan yang sama ke tiga file secara manual adalah pertarungan yang sudah pasti kalah (soal cara menjaganya tetap sinkron dibahas di bawah).

Kalau kamu kebanyakan bekerja di Claude Code, panduan CLAUDE.md kami membahas tuntas struktur yang khusus Claude. AGENTS.md adalah saudara dari file itu yang netral terhadap provider.

Apa saja yang perlu ditaruh di dalamnya

Buat ringkas dan berbobot. Seorang agen membacanya di setiap tugas, jadi tiap baris berebut perhatian. Yang esensial:

• Stack, dalam satu tarikan napas. "Next.js 16, TypeScript, Prisma, MariaDB." Tanpa sejarah, tanpa marketing.
• Perintah yang penting. Cara install, run, build, test, dan lint. Perintah persis: npm test, bukan "jalankan test-nya."
• Konvensi. Penamaan, tata letak file, penanganan error, pola-pola yang benar-benar kamu tegakkan saat review.
• Peta direktori. Dua baris soal di mana segala sesuatu berada, supaya agen berhenti nge-grep secara buta.
• Aturan baca-sebelum-sentuh. "Baca docs/payments.md sebelum mengubah apa pun di bawah billing/." Kebiasaan tunggal ini mencegah banyak kerusakan.
• Larangan keras. "Jangan pernah membuat branch tanpa diminta." "Tidak ada path absolut milik mesin di file yang di-commit."

Kesalahan yang membuat agen mengabaikannya

File konteks gagal secara diam-diam. Agen tidak melempar error, dia cuma melenceng. Penyebab umumnya:

1. Terlalu panjang. File 600 baris mengubur lima aturan yang benar-benar penting. Buang semua yang bisa disimpulkan agen dari kode itu sendiri.
2. Kontradiksi. "Selalu tulis test" di satu bagian, "lewati test untuk prototipe" di bagian lain. Agen memilih salah satunya secara acak.
3. Path spesifik mesin. /Users/you/project/... di file yang di-commit akan rusak untuk tiap rekan tim, dan untuk tiap agen di setiap mesin lain. Pakai path relatif.
4. Perintah basi. Perintah test berubah enam bulan lalu, file-nya tidak. Sekarang agen menjalankan hal yang salah dengan penuh percaya diri.
5. Tanpa prioritas. Semuanya "penting," jadi tidak ada yang penting. Taruh hal yang tidak bisa ditawar di paling depan dan beri label.
6. Membuang dokumentasi. Ini instruksi, bukan wiki. Tautkan ke dokumentasimu, jangan ditempel di dalam.

Menjaga satu konteks di seluruh provider

Inilah bagian praktis yang dilewatkan kebanyakan panduan. Kalau kamu, atau timmu, menjalankan lebih dari satu agen CLI, kamu tidak mau punya tiga salinan aturan yang sama yang saling melenceng.

Dua pendekatan yang bersih:

• Satu file kanonis, penunjuk tipis. Taruh semuanya di AGENTS.md dan jadikan CLAUDE.md dan GEMINI.md file satu baris yang berbunyi "lihat AGENTS.md," atau buat symlink. Satu sumber kebenaran, semua tool kebagian.
• Satu file, dipakai bersama lewat konvensi. Kalau tool-mu bisa diarahkan ke path kustom, arahkan semuanya ke AGENTS.md dan hapus sisanya.

Cara mana pun, aturannya sama: tulis konteksnya sekali, bukan sekali per provider. Itu juga satu-satunya cara agar tetap benar, karena file tunggal adalah satu-satunya file yang benar-benar dirawat orang.

Saat kamu menjalankan beberapa agen sekaligus

AGENTS.md level repo menjawab "apa proyek ini." Dia tidak menjawab "siapa agen ini." Saat kamu menjalankan agen Backend, agen Frontend, dan agen QA secara paralel pada kode yang sama, masing-masing butuh konteks proyek bersama plus perannya sendiri.

Itulah lapisan yang ditambahkan AgentsRoom di atas AGENTS.md-mu. Tiap agen mendapat peran khusus dengan system prompt-nya sendiri (DevOps, Frontend, Security, dan lainnya), supaya file bersama tetap ramping sementara tiap agen tetap tahu tugasnya. Ini agnostik terhadap provider secara rancangan, jadi setup yang sama bisa menjalankan Claude, Codex, atau Gemini berdampingan, dan instruksimu yang bisa dipakai ulang hidup di sebuah Prompt Library alih-alih diketik ulang ke tiap sesi.

Begitu sampai di titik itu, metode untuk menjalankan beberapa agen secara paralel tanpa kehilangan kendali adalah bacaan lanjutan yang paling pas.

Intinya

Tulis satu AGENTS.md. Buat ringkas, jaga tetap mutakhir, jaga tetap portabel. Arahkan tiap tool ke sana alih-alih merawat satu file per agen. Konteksmu berhenti terikat pada CLI mana pun yang kebetulan kamu pakai pertama, dan agen-mu, mana pun yang kamu jalankan, berangkat dari halaman yang sama.

Mau semua agen di satu layar, masing-masing dengan perannya sendiri dan konteks bersamamu? Download AgentsRoom, hubungkan provider-mu, dan suruh armadamu bekerja.