Software Development
AGENTS.md vs CLAUDE.md: Berkas Konteks Agen
Agustus 20269 menit baca
Keduanya berkas Markdown di root repositori yang memberi agen coding AI konteks tetap tentang proyek Anda. CLAUDE.md adalah berkas memory Claude Code, dibaca otomatis tiap sesi dan mendukung impor serta penyarangan. AGENTS.md adalah konvensi lintas-tool yang diadopsi banyak agen, sehingga kekuatannya adalah portabilitas ketimbang integrasi mendalam dengan satu tool.
Tidak. Sebagian besar tim menjaga satu sumber kebenaran dan mendukung keduanya, menjadikan satu berkas penunjuk tipis ke yang lain atau men-symlink keduanya bila tooling mengizinkan. Ini memberi Claude Code kedalaman CLAUDE.md sementara kontributor di agen lain tetap membaca berkas yang namanya mereka kenali, tanpa merawat dua salinan terpisah.
Buatlah singkat dan faktual: cara memasang, cara menjalankan tes, konvensi yang penting, dan hal yang tidak boleh dilakukan agen. Esai panjang cuma dibaca sekilas dan encer, jadi utamakan baris ringkas yang bersinyal tinggi. Kontennya sama entah Anda menamai berkas AGENTS.md atau CLAUDE.md.
Berkas memory khusus Claude Code adalah CLAUDE.md, yang dimuat otomatis. Jika Anda menstandarkan Claude Code, dahulukan CLAUDE.md untuk pemuatan otomatis dan impor, dan tambahkan AGENTS.md yang menunjuk ke konten yang sama hanya jika kontributor memakai agen lain yang mengharapkan nama itu.
Karena agen mengikuti berkas secara harfiah, perintah build yang usang atau konvensi yang sudah dihapus justru menyesatkannya alih-alih sekadar diabaikan. Berkas usang lebih buruk daripada tidak ada, jadi tinjau berkas ini dalam pull request seperti Anda meninjau kode dan hapus panduan yang tidak lagi berlaku.
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 |
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:
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.
Sebagian besar tim tidak perlu memilih. Setup yang pragmatis menjaga satu sumber kebenaran dan memenuhi kedua konvensi:
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.
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.