Ringkasan Utama
AGENTS.md dan CLAUDE.md sama-sama memberi agen coding AI instruksi tetap tentang proyek Anda, tetapi keduanya berasal dari ekosistem berbeda. CLAUDE.md adalah berkas memory yang dibaca Claude Code otomatis, sedangkan AGENTS.md adalah konvensi lintas-tool yang diadopsi banyak agen. Dalam praktik Anda bisa mendukung keduanya, dan sering satu berkas hanya menunjuk ke yang lain.
Buka repositori modern dan Anda makin sering menemukan berkas yang satu-satunya pembacanya adalah mesin. AGENTS.md dan CLAUDE.md sama-sama berkas itu: tempat memberi tahu agen coding AI bagaimana proyek Anda dibangun, diuji, dan ingin diperlakukan. Kebingungannya adalah kini ada dua konvensi yang bersaing untuk pekerjaan yang sama.
Keduanya lebih mirip daripada berbeda. Sama-sama Markdown biasa, sama-sama berada di root repositori, dan sama-sama ada karena menempelkan konteks yang sama ke setiap sesi itu pemborosan. Yang berbeda adalah siapa yang membacanya dan seberapa luas ia dipahami. Perbandingan ini membahas asal masing-masing, bagaimana tool memperlakukannya, dan cara menjalankan keduanya tanpa merawat dua salinan.
| Aspek | AGENTS.md | CLAUDE.md |
|---|---|---|
| Asal | Konvensi lintas-tool yang populer di banyak agen | Berkas memory Claude Code dari Anthropic |
| Pembaca utama | Codex, Cursor, dan agen lain yang mengadopsinya | Claude Code, dimuat otomatis setiap sesi |
| Lokasi | Root repo, dengan berkas bersarang opsional per direktori | Root repo, home pengguna, dan subdirektori bersarang |
| Format | Markdown biasa, tanpa skema wajib | Markdown biasa, mendukung impor berkas |
| Sinyal cakupan | Portabel di tool yang mengenali namanya | Khusus Claude, paling kaya di dalam Claude Code |
Pekerjaan sama, garis keturunan berbeda
CLAUDE.md adalah berkas memory Claude Code. Ketika sesi dimulai, Claude Code membacanya otomatis dan memperlakukan isinya sebagai konteks tetap: perintah build, konvensi, catatan arsitektur, dan aturan yang tidak ingin Anda ulang. Ia mendukung penyarangan, sehingga sebuah subdirektori bisa membawa berkasnya sendiri, dan bisa mengimpor berkas lain agar dokumen utama tetap ringkas.
AGENTS.md tumbuh dari keinginan akan nama netral yang bisa diadopsi agen mana pun, alih-alih satu berkas per vendor. Isinya jenis yang sama, tetapi janjinya adalah portabilitas. Beberapa poin menangkap perbedaannya:
- CLAUDE.md dijamin dibaca oleh Claude Code dan dipahami mendalam olehnya.
- AGENTS.md bertujuan dibaca banyak tool, sehingga kontributor yang memakai agen berbeda tetap mendapat konteks.
- Keduanya tidak punya skema kaku; keduanya hanya Markdown yang dilipat agen ke dalam konteksnya.
Apa yang masuk ke dalam berkas mana pun
Nama mana pun yang Anda pilih, konten yang baik itu identik. Buatlah singkat dan faktual: cara memasang, cara menjalankan tes, konvensi yang penting, dan hal-hal yang tidak boleh dilakukan agen. Esai panjang cuma dibaca sekilas dan encer, jadi utamakan baris yang ringkas dan bersinyal tinggi ketimbang prosa.
Sebuah berkas minimal untuk konvensi mana pun tampak seperti ini:
# AGENTS.md
## Build & test
- Install: npm install
- Run tests: npm test
- Lint: npm run lint
## Conventions
- TypeScript strict; no default exports
- Keep functions small and pure
## Do not
- Do not edit files under generated/Jangan merawat dua salinan penuh. Taruh konten sebenarnya di satu berkas dan jadikan yang lain penunjuk satu baris ke sana, atau symlink keduanya bila tooling Anda mengizinkan. Instruksi yang terduplikasi lambat laun menyimpang, dan berkas agen yang usang lebih buruk daripada tidak ada karena agen memercayainya.
Menjalankan keduanya tanpa beban perawatan
Sebagian besar tim tidak perlu memilih. Setup yang pragmatis menjaga satu sumber kebenaran dan memenuhi kedua konvensi:
- Tulis intinya sekali, lalu rujuk dari berkas kedua sehingga hanya ada satu tempat untuk mengedit.
- Jaga instruksi tetap ramping dan rapikan seiring proyek berubah; perlakukan berkas seperti kode, bukan tempat pembuangan.
- Pakai berkas bersarang untuk repositori besar agar tiap paket hanya membawa konteks yang relevan baginya.
Berkas konteks agen hanya sepercaya pembaruan terakhirnya. Karena agen mengikutinya secara harfiah, perintah build yang usang atau konvensi yang sudah dihapus justru menyesatkannya. Tinjau berkas ini dalam pull request seperti Anda meninjau kode, dan hapus panduan yang tidak lagi berlaku.
Yang mana yang sebaiknya Anda commit
Jika tim Anda menstandarkan Claude Code, dahulukan CLAUDE.md, karena Anda mendapat pemuatan otomatis, impor, dan pemahaman terdalam. Jika kontributor memakai campuran agen, tambahkan AGENTS.md agar tidak ada yang kehilangan konteks, dan arahkan ke konten yang sama.
Keputusannya bukan soal memilih pemenang melainkan soal jangkauan. CLAUDE.md memaksimalkan kedalaman di dalam satu tool; AGENTS.md memaksimalkan keluasan di banyak tool. Mendukung keduanya, didukung satu sumber, hampir tanpa biaya dan melindungi Anda dari konvensi mana pun yang diharapkan rekan berikutnya.
AGENTS.md dan CLAUDE.md adalah kebiasaan baik yang sama dengan dua label: tuliskan konteks proyek Anda agar agen berhenti menebak. Simpan satu berkas otoritatif, cerminkan ke nama satunya, dan perlakukan keduanya sebagai dokumentasi hidup yang layak selama tetap benar.