AGENTS.md - Format Terbuka untuk Agen Coding AI
(agents.md)- AGENTS.md berfungsi sebagai pelengkap README dan merupakan file khusus yang berisi konteks serta panduan yang dibutuhkan agen coding AI saat bekerja di sebuah proyek
- Sudah digunakan di lebih dari 20.000 proyek open source untuk merangkum informasi seperti build/test/code style yang tidak terlalu diperlukan manusia tetapi penting bagi agen
- Menyediakan instruksi khusus agen di lokasi yang jelas dan dapat diprediksi, sehingga README tetap ringkas sambil meningkatkan efisiensi kolaborasi
- Satu AGENTS.md kompatibel dengan berbagai agen dan tool, dan pada monorepo skala besar dimungkinkan menggunakan AGENTS.md terpisah untuk tiap subproyek
- Merupakan standar terbuka yang dibuat lewat kolaborasi berbagai ekosistem seperti OpenAI Codex, Cursor, dan Google Jules
Why AGENTS.md?
- README.md adalah dokumentasi untuk manusia, menyediakan quick start, penjelasan proyek, dan panduan kontribusi
- AGENTS.md adalah dokumen pendamping untuk agen yang memuat konteks rinci seperti aturan build/test/kode tanpa membuat README menjadi rumit
- Alasan dipisahkan ke file tersendiri
- Memberikan lokasi instruksi yang dapat diprediksi untuk dirujuk agen
- README tetap ringkas dengan fokus pada kontributor manusia
- Menyediakan instruksi presisi khusus agen yang melengkapi dokumentasi yang sudah ada
- Mengadopsi nama standar terbuka yang bisa dipakai siapa saja, bukan format proprieter
- Satu AGENTS.md dapat kompatibel dengan banyak agen coding AI dan tool
How to use AGENTS.md?
- 1. Buat file AGENTS.md
- Letakkan di root repositori (banyak agen mendukung pembuatan otomatis)
- 2. Tulis poin-poin utama
- Ringkasan proyek
- Perintah build dan test
- Pedoman code style
- Cara melakukan pengujian
- Pertimbangan keamanan
- 3. Sertakan instruksi tambahan
- Hal-hal yang ingin disampaikan ke anggota tim seperti aturan commit/PR, perhatian keamanan, dataset besar, dan langkah deployment
- 4. Dukungan monorepo
- AGENTS.md dapat ditempatkan untuk setiap package
- Agen akan membaca file terdekat dan mengikuti instruksi yang sesuai untuk subproyek tersebut
- Contoh: repositori OpenAI memiliki 88 AGENTS.md
FAQ
- Item wajib: tidak ada, bebas menggunakan format Markdown umum
- Saat terjadi konflik: AGENTS.md terdekat diprioritaskan, prompt eksplisit dari pengguna diterapkan paling akhir
- Apakah dieksekusi otomatis: perintah test yang tertulis di file dapat dijalankan agen untuk mencoba memperbaiki error
- Kemungkinan pembaruan: bisa diubah kapan saja, dikelola sebagai dokumen hidup
- Migrasi dokumentasi yang ada: ganti nama file lalu pertahankan kompatibilitas dengan symbolic link
mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md
1 komentar
Opini Hacker News
Untuk proyek kecil, satu file .md saja sudah cukup, tetapi dari pengalaman saya, untuk proyek yang kompleks struktur folder hierarkis dengan index.md jauh lebih efektif.
Struktur yang terdiri dari index.md dan file-file di bawahnya seperti auth.md, performance.md mudah dirawat, dan memungkinkan LLM atau agen mengambil hanya konteks yang relevan tanpa memboroskan token yang tidak perlu.
File .docs menjadi cocok baik untuk manusia maupun LLM, dan index.md juga bisa memuat panduan singkat untuk tiap file serta panduan pengorganisasian.
Namun, saya rasa nama seperti ".codebots" atau ".context" lebih intuitif daripada ".agents".
Saya rasa file dan direktori penting tidak perlu disembunyikan.
Khususnya dokumentasi, jika disembunyikan justru menjadi kurang transparan; mungkin ini karena tradisi, tetapi cara seperti ini bukan pola yang baik.
Saya sempat berpikir nama seperti robot_docs.
Sebenarnya informasi seperti ini tumpang tindih dengan hal-hal yang ingin diketahui para kontributor, jadi saya rasa memang lebih tepat dimasukkan ke CONTRIBUTING.md.
Struktur ini terasa seperti dokumen panduan desain perangkat lunak/gaya coding untuk manusia sekaligus robot.
Saya menaruh file .md seperti ini di folder docs/, dan Claude Code menulisnya langsung.
AGENTS.md dan CLAUDE.md seharusnya dipakai hanya untuk keperluan robot, dan baik memecah satu file besar dengan header h2 maupun membaginya ke beberapa file masing-masing punya kelebihan dan kekurangan.
Ada juga format dokumentasi arsitektur seperti Arc42 yang mendukung keduanya.
Daripada merujuk ke bagian tertentu di dalam Markdown besar, lebih mudah dan lebih sedikit kesalahan jika dibuat sebagai file terpisah lalu di-@mention.
Saat perlu fokus pada bagian tertentu, memecahnya menjadi file-file kecil juga lebih baik untuk agen kode.
File kecil juga lebih nyaman saat review diff/PR.
Anda juga bisa punya beberapa file AGENTS.md di dalam codebase.
Tooling tinggal dibuat membaca AGENTS.md di direktori saat ini dan di direktori root, sehingga informasi bisa tetap dekat dengan kode dan tetap sejalan dengan pendekatan yang diinginkan.
Saya juga memakai struktur serupa, dan menambahkan panduan singkat per file di index.md memberi hasil yang cukup bagus.
Saya juga sedang bereksperimen dengan pendekatan menaruh file aturan perilaku yang diinginkan per direktori, seperti rules.md.
Misalnya, di direktori yang berisi berbagai service seperti realtime-service.ts dan queue-service.ts, saya menaruh rules.md di sampingnya.
Dengan menyebut file aturan ini di prompt, hal-hal baru bisa dibuat dengan mudah; untuk namanya, saya rasa masih perlu dipikirkan lagi.
Saat ini kita masih berada dalam masa transisi di mana manusia perlu menulis panduan khusus tambahan, melebihi yang dibutuhkan manusia, agar agen bisa memahami codebase.
Saya pikir sebentar lagi ini tidak akan diperlukan.
Kalau dokumentasi proyek kita sejak awal sudah cukup lengkap, saya rasa semua isi AGENTS.md juga bisa tercakup di dalamnya.
Kita harus selalu menulis dokumentasi untuk manusia, dan kelebihan LLM adalah mereka bisa membaca tulisan yang dibuat untuk manusia.
Saya rasa inilah perspektif desain yang tepat.
Ini berguna bukan hanya untuk memahami codebase, tetapi juga untuk menetapkan aturan gaya tertentu, misalnya library assert apa yang harus dipakai untuk menulis test, larangan komentar, penggunaan structured logging, dan sebagainya.
Bahkan bisa jadi lebih berguna untuk proyek baru yang hampir belum punya kode.
Saya memperkirakan aturan yang bisa dibaca mesin akan makin banyak diterapkan di berbagai aspek masyarakat.
Contohnya kendaraan otonom dan aturan lalu lintas; rambu yang sebenarnya juga sulit dipahami manusia tanpa konteks, seperti "dilarang belok kanan saat lampu merah, hari sekolah pukul 7–9", akan lebih sulit lagi bagi mesin.
Pada akhirnya, instansi pemerintah harus mengubahnya menjadi sinyal yang butuh lebih sedikit konteks atau punya keterbacaan mesin, seperti kode QR.
Tanpa perubahan seperti itu, mesin akan sering melanggar aturan.
Di area seperti business logic, saya rasa panduan khusus untuk agen tetap akan sangat diperlukan ke depannya.
Apa yang sedang dibuat, apa maksudnya, apa tujuan akhir proyek, hal-hal seperti ini tidak akan bisa dipahami mesin kecuali manusia menjelaskannya secara konkret.
Hal seperti arsitektur juga berbeda-beda menurut orang; perlu ada struktur mental agar saat melihat perubahan nyata bisa lebih mudah memahaminya, dan pada akhirnya bottleneck sebenarnya ada di sini.
Secara umum saya setuju, tetapi untuk informasi tertentu, misalnya hal yang ingin selalu dimasukkan ke konteks setiap saat, kadang muncul keinginan untuk memaksakan inclusion lewat file terpisah.
Jika kita tidak mendokumentasikan aturan dan asumsi yang kita anggap implisit, LLM tidak akan mengetahuinya.
Sebagian mungkin bisa diinferensikan dari kode, tetapi tidak mungkin 100%, jadi penting untuk menuliskan requirement secara eksplisit.
AGENTS.md pada akhirnya menjalankan peran yang mirip README.md sambil menunggangi hype, dan menarik bahwa orang-orang benar-benar mengisi isinya.
Orang biasanya malas menulis dokumentasi untuk orang lain, tetapi ternyata mau menulis dengan rajin untuk robot; itu menarik.
Fenomena ini mirip seperti desain ergonomis yang awalnya dibuat untuk kelompok kecil tetapi akhirnya justru lebih cocok untuk semua orang, seperti desain handle.
Malah kebalikannya: karena orang-orang tidak membaca dokumentasi, tidak ada yang termotivasi untuk menulisnya.
CLAUDE.md untuk agen, kalau sekali ditulis akan segera dibaca oleh 1000 agen, jadi jadi terasa ada motivasi untuk menulis.
Bukankah pada akhirnya cukup menaruh minimal saja di README.md?
Dalam praktiknya, bahkan agen pun tidak membaca dokumen ini, atau akan melupakan semuanya setelah diberi beberapa instruksi lagi.
Situasi sekarang adalah orang-orang sedang berusaha secara aktif menyingkirkan pengembang manusia, termasuk diri mereka sendiri, dari proses pengembangan, sehingga agen harus benar-benar dibekali panduan yang memadai.
Karena keinginan untuk menghapus semua keterlibatan manusia dalam pengembangan perangkat lunak makin besar.
Dengan nada bercanda, saya menyebut suasana akhir-akhir ini memang vibe coding.
Saya juga merasa pernah melihat pendapat sebelumnya bahwa menulis dokumentasi untuk bot pada dasarnya tidak berbeda dari menulis dokumentasi yang baik.
Pada akhirnya kesannya seperti hanya menulis, "Buat file AGENTS.md dan isilah dengan sihir," lalu mengarahkan orang ke situs terpisah.
Dalam kasus saya, saya sedang mengembangkan agen coding yang mengelola lebih dari 5.000 repositori.
Status agen disimpan di dalam direktori tersembunyi .agent, yang mencakup folder konfigurasi per peran agen dan instruksi yang jelas untuk masing-masing peran.
Di folder proyek saya membuat folder agents, lalu membagi banyak file berdasarkan peran dengan format <Role> <instruction>.
Agen hanya membaca file yang perannya sudah didefinisikan, dan state disimpan di folder dot<coding agent name>.
Inisialisasi dilakukan lewat /init, dan alih-alih sekadar mengindeks seluruh kode repo, sistem membuat high-level summary yang merangkum keseluruhan arsitektur dan logika.
Ringkasan ini disajikan sebagai "ghost comments" yang bisa ditoggle di editor, dan merupakan metadata yang tidak di-commit ke kode sebenarnya.
Dengan sistem mapping yang canggih, tiap ringkasan terhubung secara akurat ke baris-baris kode.
Awalnya saya mencoba memakai RAG langsung pada kode tetapi tidak mendapatkan hasil yang saya inginkan, jadi saya mengadopsi struktur ini.
Sekarang saya memakai model pencarian hybrid yang menggabungkan pencarian sintaktis cepat berbasis AST dan penelusuran semantik berbasis ringkasan (RAG).
Misalnya saat ditanya, "Bagaimana cara kerja autentikasi aplikasi ini?", pencarian sintaktis hanya menemukan fungsi-fungsi yang mengandung kata seperti login, tetapi pencarian semantik, melalui ringkasan, memahami keseluruhan alur autentikasi secara naratif dan menghubungkan bagian-bagian yang tersebar di berbagai file; rasanya seperti sihir.
Menambahkan ke sini, Anda juga bisa membuat hierarki ringkasan, dalam bentuk B-tree atau tree biasa.
Artinya, ada summary per method/class/module, dan tiap level dirancang untuk menunjuk ke level di bawahnya.
RAG bisa menelusuri sedalam yang diperlukan sesuai kueri semantik, dan tiap tahap merangkum isi di bawahnya agar jumlah informasi berkurang sambil tetap mempertahankan makna yang benar-benar diperlukan.
Pendekatan ini sangat efektif saat kode memiliki abstraksi yang baik.
Sebagai contoh, untuk fungsi seperti add(n1, n2), namanya saja sudah cukup menjelaskan maknanya sehingga implementasi nyatanya tidak perlu diketahui, tetapi fungsi di dunia nyata sering punya banyak peran seperti logging atau cache, jadi bergantung pada situasinya, kode sebenarnya mungkin tetap perlu dimasukkan ke konteks.
Saya ingin mendengar penjelasan yang lebih rinci.
Terasa seperti manusia perlahan-lahan sedang didorong untuk akhirnya menulis dokumentasi proyek dengan benar.
Ini memang setengah bercanda, tetapi sebenarnya saya menyampaikan poin seperti ini ke tim.
Bahkan kalau LLM ternyata tidak benar-benar menaikkan produktivitas secara besar, tetap ada efek samping bahwa dokumentasi jadi jauh lebih baik.
"Mission. Fucking. Accomplished." xkcd 810
Saya masih belum yakin apakah README.md dan AGENTS.md memang perlu dipisahkan.
Menurut ringkasan terkait,
alasan memisahkan adalah:
alasan untuk tidak memisahkan adalah:
README.md sekarang terasa seperti halaman marketing/landing page, sedangkan AGENTS.md dan CLAUDE.md adalah tempat untuk mendapatkan isi yang sebenarnya seperti kode/arsitektur/cara penggunaan.
Saat membaca contohnya saya juga berpikir sama, dan sejujurnya saya merasa satu README.md yang baik mungkin sudah cukup memuat semuanya.
README untuk manusia, AGENTS.md dan sejenisnya untuk LLM.
Cara penggunaan/instalasi ada di readme, sedangkan cara kompilasi/testing, keputusan arsitektur, standar coding, struktur repo, dan sebagainya dirangkum di dokumen agen.
Perlu juga mempertimbangkan masalah kapasitas context pada LLM.
README.md biasanya panjang sehingga sulit memasukkan semuanya ke context.
AGENT.md hanya memuat perintah penting yang benar-benar diperlukan LLM, seperti test dan build, secara ringkas.
Bisa jadi ada bagian yang tumpang tindih dengan README, tetapi saya tetap ingin menghindari pengiriman berulang konten yang tidak perlu ke context.
Bukankah janji AI justru kita tidak perlu terpaku pada format yang benar-benar presisi, cukup menulis dengan cara yang kita mau lalu mesin yang akan menyesuaikan?
Sebenarnya pilihan yang tepat memang hanya menstandarkan nama file, sementara isi tidak dipaksa ke format tertentu dan semua orang bebas menulis dengan cara apa pun yang mereka mau.
AGENTS.md adalah Markdown standar, jadi Anda bisa memakai heading apa pun, dan agen akan mem-parsing teksnya.
Meski begitu, tingkat struktur dan format tertentu tetap penting.
Hanya saja bukan setepat sintaks kode.
Pada akhirnya kesimpulannya tetap sama: isinya harus ditulis dengan jelas.
Semakin panjang dokumennya, pendekatan yang terstruktur makin menguntungkan dari sisi pemeliharaan bagi manusia.
Setiap agen yang dipakai, seperti Claude Code, Gemini, dan Aider, memakai nama file yang berbeda-beda.
Akan bagus jika bisa distandardisasi, tetapi untuk sekarang saya rela repot menggunakan ruler untuk menghasilkan beberapa format secara otomatis.
Terutama karena tiap agen juga punya cara berbeda dalam mengonsumsi file konfigurasi MCP, jadi saya rasa standarisasi tidak akan segera terjadi.
ruler
Kalau dilihat secara agak sinis, saya rasa ini karena upaya menciptakan vendor lock-in.
Standarisasi bisa berujung pada komoditisasi, jadi tampaknya para vendor enggan terhadapnya.
Jules memakai AGENTS.md, jadi itu menunjukkan Google ikut mendukung standar ini.
Jika Gemini Code Assist terus dipertahankan, saya perkirakan ia juga akan mendukung AGENTS.md.
Saya tidak melihat nama file tertentu disebut di dokumentasi Aider; kalau ada tautannya saya ingin tahu.
Anthropic tampaknya satu-satunya yang masih belum mendukung nama file standar.
Sedikit disayangkan bahwa alat seperti ruler memang benar-benar dibutuhkan.
Situs web ini terasa aneh.
Karena dibuat oleh OpenAI, saya sempat bertanya-tanya apakah tujuannya untuk menarik pengunjung dan positioning marketing.
Padahal pada praktiknya tidak ada format, hanya nama file yang ditentukan.
Absennya Anthropic/Claude juga menonjol; secara teknis orang bisa memakai symbolic link untuk menghubungkan CLAUDE.md ke AGENTS.md.
Sebenarnya ini dibuat oleh Sourcegraph dan sudah ada sejak Mei.
Sebelumnya namanya agent.md, lalu sekarang di-redirect 301 ke agents.md.
Lihat tautan lama.
Ada juga pengumuman resmi.
Sepertinya belakangan mereka menjalin kemitraan dengan OpenAI.
Menariknya, awalnya agent.md tetapi sekarang berubah menjadi agents.md.
Alasan Claude tidak ada di daftar adalah karena hanya Claude yang masih belum mendukung aturan nama file standar.