AGENTS.md: Standar Terbuka Instruksi buat AI Coding Agent

Tiap kali kamu buka sesi baru sama coding agent, dia lupa semuanya. Nama kolom yang kemarin udah disepakati, cara nulis test di repo ini, perintah build yang bener — semua balik jadi tebakan. AGENTS.md ada buat itu: satu berkas Markdown yang kamu commit ke repo, isinya konteks yang agent butuhin, dan dia baca tiap kali mulai.

Bedanya dengan file rules yang lain: AGENTS.md bukan format milik satu perkakas. Dia diformalkan jadi spesifikasi terbuka pada Agustus 2025, digagas OpenAI bersama Google, Cursor, dan Factory, dan sejak Desember 2025 pengelolaannya dipegang Agentic AI Foundation di bawah Linux Foundation — jadi standarnya nggak lagi bergantung pada satu vendor. Sampai Desember 2025 tercatat lebih dari 60.000 proyek open source memakainya dan lebih dari dua puluh perkakas AI mendukungnya. Perbandingannya dengan .cursorrules dan CLAUDE.md kami tulis terpisah di file rules untuk AI coding.

Cara kerjanya sederhana banget

• Formatnya Markdown biasa. Nggak ada sintaks khusus, nggak ada bagian wajib. Agent cuma membaca teksnya.
• Letaknya di root repo, dan dia masuk ke konteks percakapan di posisi paling atas, tepat di bawah system prompt.
• Kamu bisa punya AGENTS.md di subfolder. Agent memakai berkas yang PALING DEKAT dengan kode yang lagi diedit, jadi tiap bagian repo bisa punya aturan sendiri.
• Perubahannya langsung berlaku. Kamu edit sekarang, percakapan berikutnya udah ikut aturan barunya.

Isi yang bikin AGENTS.md beneran kepakai

Yang berguna itu hal yang nggak bisa disimpulkan agent dari membaca kode. Kode udah nunjukkin apa yang ada; AGENTS.md nunjukkin apa yang diharapkan.

• Perintah build, test, dan lint yang benar — termasuk kalau ada urutan yang wajib.
• Konvensi penamaan yang dipakai tim, terutama yang nggak konsisten di kode lama.
• Struktur folder dan di mana file baru seharusnya diletakkan.
• Hal yang TIDAK boleh disentuh: berkas hasil generate, migrasi lama, direktori vendor.
• Keputusan teknis yang pernah diambil beserta alasannya, supaya agent nggak mengulang perdebatan yang sudah selesai.
• Cara nulis pesan commit dan syarat sebelum sebuah perubahan dianggap selesai.

# AGENTS.md

Sumber konteks tunggal untuk semua AI agent di repo ini.

## Perintah
- Pasang dependensi: pnpm install
- Jalankan test: pnpm test (WAJIB lulus sebelum bilang selesai)
- Cek tipe: pnpm typecheck

## Konvensi
- Nama kolom database pakai snake_case. Kode lama yang camelCase JANGAN diseragamkan sekarang.
- Komponen baru masuk ke src/components, satu file satu komponen.

## Jangan disentuh
- drizzle/ (hasil generate)
- src/lib/legacy/ (dijadwalkan dihapus, biarkan)

## Selesai artinya
Test lulus, typecheck bersih, dan tidak ada console.log tersisa.

Tiga kesalahan yang bikin dia diabaikan

1. Kepanjangan

Ini yang paling sering. AGENTS.md tumbuh jadi ribuan baris berisi seluruh dokumentasi proyek, dan begitu isinya terlalu banyak, bagian yang penting tenggelam di antara yang nggak penting. Aturan praktisnya: kalau sebuah kalimat nggak akan mengubah keputusan agent, buang.

2. Berisi hal yang sudah jelas dari kode

Nulis "proyek ini pakai React dan TypeScript" itu buang tempat — agent bisa lihat sendiri dari package.json. Yang berguna justru yang nggak kelihatan: kenapa kalian nolak satu pendekatan, atau folder mana yang tampak aktif padahal sudah mati.

3. Nggak pernah diperbarui

AGENTS.md yang isinya sudah nggak cocok sama kenyataan lebih buruk daripada nggak ada sama sekali, karena agent menurutinya dengan patuh. Perlakukan dia seperti kode: kalau konvensinya berubah, berkasnya ikut berubah di pull request yang sama.

Dari mana isinya sebaiknya diturunkan

Kalau kamu memakai lebih dari satu perkakas, kamu bakal ketemu masalah lama: aturan yang sama ditulis ulang di beberapa berkas, lalu ketiganya pelan-pelan beda isi. Cara yang lebih tahan lama adalah punya satu sumber kebenaran, lalu berkas-berkas itu diturunkan darinya.

Buat keputusan produk — siapa penggunanya, apa yang dihitung selesai, apa yang di luar lingkup — sumber yang paling masuk akal adalah PRD, karena di sana keputusannya memang sudah diambil. Buat keputusan teknis, sumbernya biasanya catatan arsitektur. Yang penting kamu tahu mana yang asli dan mana yang salinan, supaya waktu ada yang berubah kamu tahu harus mengubah yang mana lebih dulu. Kalau alur kerjamu memakai spesifikasi bertahap, lihat juga panduan GitHub Spec Kit.

Ringkasnya

1. Bikin AGENTS.md di root repo, isinya Markdown biasa.
2. Isi cuma hal yang nggak bisa disimpulkan agent dari membaca kode.
3. Taruh berkas terpisah di subfolder kalau tiap bagian repo punya aturan berbeda.
4. Jaga tetap pendek — kalau satu kalimat nggak mengubah keputusan agent, buang.
5. Perbarui bareng kodenya, jangan dibiarkan jadi dokumen basi.