AGENTS.md: Satu File Konteks untuk Semua Coding Agent (Codex, Antigravity, 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 Antigravity 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

Waktu panduan ini pertama kali ditulis, tiap tool mencari file-nya sendiri. Sejak itu, sebagian besar sudah menyatu ke AGENTS.md:

• Codex membaca AGENTS.md, begitu juga GitHub Copilot CLI, Cursor, Amp, dan sebagian besar CLI agen yang lebih baru.
• Claude Code membaca CLAUDE.md, dan sejak versi 2.1.277 dia juga membaca AGENTS.md dengan sendirinya saat direktori kerjamu dan direktori di atasnya tidak punya CLAUDE.md atau CLAUDE.local.md. Kalau ada CLAUDE.md, Claude hanya membaca file itu, kecuali kamu mengubah pengaturan Project instructions di /config.
• Antigravity CLI membaca AGENTS.md atau GEMINI.md, di root repositori atau di subdirektori mana pun, ditambah folder .agents/rules/ dan aturan global di ~/.gemini/.

Isinya hampir identik di ketiganya: konteks proyek, perintah, konvensi. Yang masih berbeda adalah file mana yang dipilih sebuah tool saat ada beberapa sekaligus. 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). Kami memeriksa perilaku ini pada 10 Oktober 2026 dengan mencocokkannya ke dokumentasi memori Claude Code dan dokumentasi aturan Antigravity.

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 AGENTS.md, tidak ada yang lain. Kalau tidak ada yang butuh aturan khusus Claude, simpan satu AGENTS.md saja: Codex, Antigravity CLI, dan Claude Code 2.1.277 ke atas semuanya membacanya. Jebakannya terjadi diam-diam: CLAUDE.md, atau CLAUDE.local.md pribadi, yang ditambahkan belakangan membuat Claude Code berhenti membaca AGENTS.md.
• Satu file kanonis, satu import. Taruh semuanya di AGENTS.md dan awali CLAUDE.md dengan baris @AGENTS.md, lalu tulis aturan khusus Claude di bawahnya. Claude membaca file yang di-import lebih dulu. Repositori kami sendiri bekerja seperti itu: CLAUDE.md-nya hanya berisi satu baris itu. Symlink (ln -s AGENTS.md CLAUDE.md) juga bisa, tapi kurang mulus di Windows, karena membuatnya butuh hak Administrator atau Mode Pengembang, dan clone tanpa core.symlinks mendapat file teks satu baris alih-alih instruksimu.

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 Antigravity 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.

Pertanyaan yang sering diajukan

Apa itu AGENTS.md?

File Markdown, biasanya di root repositori, yang dimuat coding agent sebagai instruksi tetap sebelum mulai bekerja: apa proyek ini, cara build dan test-nya, konvensi yang harus dihormati, dan jebakan yang harus dihindari. Ini konvensi terbuka yang dipakai bersama lintas tool, bukan file milik satu tool saja, dan dibaca oleh Codex, Antigravity CLI, GitHub Copilot CLI, Cursor, Amp, serta, sejak versi 2.1.277, Claude Code.

Apakah Claude Code membaca AGENTS.md?

Ya, sejak Claude Code 2.1.277, tapi hanya kalau tidak ada CLAUDE.md, .claude/CLAUDE.md, atau CLAUDE.local.md di direktori kerjamu atau di atasnya. Dia lalu memuat setiap AGENTS.md dari direktori kerja ke atas, dan AGENTS.md milik sebuah subdirektori saat dia membuka file di sana. Kalau ada CLAUDE.md, Claude hanya membaca file itu, kecuali kamu mengatur Project instructions ke claude-md-and-agents-md di /config. Di versi yang lebih lama, taruh baris @AGENTS.md di paling atas sebuah CLAUDE.md.

Antigravity memakai AGENTS.md atau GEMINI.md?

Dua-duanya. Antigravity membaca AGENTS.md, GEMINI.md, atau folder .agents/rules/ di root repositori atau di subdirektori mana pun, plus aturan global dari ~/.gemini/. Aturan-aturan itu saling menambah, bukan saling menggantikan, dan saat dua aturan bertentangan, aturan dari direktori yang lebih spesifik yang menang.

Sebaiknya simpan AGENTS.md atau CLAUDE.md?

Jadikan AGENTS.md satu-satunya file yang kamu rawat. Kalau kamu juga butuh aturan khusus Claude, tambahkan CLAUDE.md yang baris pertamanya @AGENTS.md lalu tulis aturan itu di bawahnya: Claude membaca file yang di-import lebih dulu. Kalau tidak butuh, AGENTS.md saja sudah cukup untuk Claude Code 2.1.277 ke atas. Hindari dua salinan lengkap dari aturan yang sama: salinan yang tidak pernah diedit siapa pun akan basi.

Di mana sebaiknya menaruh AGENTS.md?

Di root repositori untuk aturan yang berlaku di mana saja. Claude Code dan Antigravity juga membaca file AGENTS.md di subdirektori, jadi sebuah package atau service dengan perintahnya sendiri bisa punya file sendiri, yang dibaca saat agen bekerja di folder itu.