AGENTS.md: Panduan Sederhana untuk Coding Agents yang Digunakan 20K+ Proyek Open-Source

AGENTS.md adalah format terbuka dan sederhana yang dirancang khusus untuk memberikan panduan bagi coding agents atau agen pengkodean berbasis AI. Melalui informasi di website resminya https://agents.md Format ini sudah digunakan lebih dari 20 ribu proyek open-source sebagai cara standar untuk menyampaikan konteks dan instruksi agar agen AI dapat bekerja efektif pada sebuah proyek.

Apa Itu AGENTS.md?

AGENTS.md bisa dianggap sebagai semacam README khusus untuk agen pengkodean. Biasanya README.md berisi informasi yang ditujukan untuk manusia, seperti cara cepat memulai, deskripsi proyek, dan panduan kontribusi. Namun, AGENTS.md melengkapi README dengan memberikan informasi tambahan yang lebih teknis dan detail, seperti langkah build, pengujian, dan konvensi coding yang dibutuhkan AI, tanpa membuat README menjadi penuh dengan detail teknis.

Manfaat Menggunakan AGENTS.md

Memberikan tempat yang jelas dan terstruktur untuk instruksi yang ditujukan kepada coding agents.
Mempermudah pemeliharaan dokumentasi dengan menjaga README tetap ringkas dan fokus pada kontributor manusia.
Memberikan panduan spesifik dan terfokus untuk kebutuhan AI yang melengkapi dokumentasi utama.

Kompatibilitas dengan Berbagai Coding Agents

Satu file AGENTS.md dapat digunakan oleh berbagai macam coding agent populer, seperti:

Codex dari OpenAI
Amp dan Jules dari Google
Cursor, Factory, RooCode, Aider
Gemini CLI dari Google
Kilo Code, OpenCode, Phoenix, Zed

Contoh Isi AGENTS.md

Berikut contoh isi file AGENTS.md yang umum digunakan pada proyek pengembangan perangkat lunak:

Perintah Setup

Instalasi dependensi: pnpm install
Jalankan server pengembangan: pnpm dev
Jalankan pengujian: pnpm test

Gaya Kode

Gunakan mode strict TypeScript.
Gunakan tanda kutip tunggal dan hindari titik koma.
Utamakan pola programming fungsional.

Tips Lingkungan Pengembangan

Gunakan perintah pnpm dlx turbo run where <project_name> untuk langsung masuk ke package yang diinginkan tanpa perlu cek manual.
Untuk menambahkan package ke workspace agar dikenali oleh Vite, ESLint, dan TypeScript, gunakan pnpm install --filter <project_name>.
Buat project React + Vite dengan TypeScript menggunakan perintah pnpm create vite@latest <project_name> -- --template react-ts.
Selalu cek nama package di file package.json masing-masing package, jangan gunakan nama di level root.

Instruksi Pengujian

Cek rencana Continuous Integration (CI) di folder .github/workflows.
Jalankan pengujian dengan perintah pnpm turbo run test --filter <project_name> untuk menjalankan semua tes yang ditentukan.
Dari root package, cukup jalankan pnpm test. Pastikan semua tes berhasil sebelum melakukan merge.
Untuk menjalankan tes tertentu, pakai pola Vitest: pnpm vitest run -t "<test name>".
Perbaiki error pengujian atau tipe sampai semua hijau.
Setelah memindahkan file atau mengubah impor, jalankan pnpm lint --filter <project_name> untuk memastikan aturan ESLint dan TypeScript masih valid.
Tambahkan atau perbarui pengujian untuk kode yang diubah walaupun belum diminta.

Panduan Pull Request (PR)

Gunakan format judul PR: [] .
Selalu jalankan pnpm lint dan pnpm test sebelum commit.

Panduan Memulai dengan AGENTS.md

Tambahkan file AGENTS.md di root repository. Beberapa agen pengkodean dapat membuatkan file ini secara otomatis jika diminta.
Isi dengan bagian-bagian penting agar agen AI dapat bekerja efektif, seperti ikhtisar proyek, perintah build dan tes, gaya kode, instruksi pengujian, dan keamanan.
Tambahkan instruksi tambahan seperti panduan commit, PR, catatan keamanan, dataset besar, atau langkah deployment.
Jika proyek besar atau monorepo, gunakan AGENTS.md nested (bertingkat) pada subproject agar agen dapat menggunakan instruksi yang paling relevan di tiap folder.

FAQ Seputar AGENTS.md

Apakah format AGENTS.md memiliki field yang wajib diisi? – Tidak, AGENTS.md tetap menggunakan standar Markdown, dan pengisian header bersifat fleksibel sesuai kebutuhan.
Bagaimana jika ada instruksi yang bertentangan? – Instruksi dari AGENTS.md terdekat dengan file yang sedang diedit diutamakan, dan perintah eksplisit dari pengguna selalu menimpa.
Apakah agen menjalankan perintah uji dari AGENTS.md secara otomatis? – Ya, apabila Anda mencantumkannya, agen akan menjalankan dan mencoba memperbaiki kesalahan sebelum menyelesaikan tugas.
Bisakah AGENTS.md diperbarui seiring waktu? – Tentu, anggaplah sebagai dokumentasi hidup yang bisa terus diperbaiki dan disesuaikan.
Bagaimana migrasi dokumen lama ke AGENTS.md? – Ganti nama file lama menjadi AGENTS.md dan buat symbolic link agar tidak mengganggu kompatibilitas.
Bagaimana konfigurasi AGENTS.md di beberapa coding agents seperti Aider dan Gemini CLI? – Set konfigurasi seperti mengarahkan ke AGENTS.md di berkas pengaturan masing-masing.

Kesimpulan

AGENTS.md merupakan inovasi penting bagi komunitas pengembang software yang memanfaatkan AI. Dengan memberikan panduan yang jelas dan terstruktur, AGENTS.md membantu coding agents memahami dan bekerja dengan proyek Anda lebih efisien. Format ini terus dikembangkan dan didukung oleh berbagai pihak termasuk OpenAI dan Google, serta sangat direkomendasikan untuk diadopsi oleh semua pengembang yang menggunakan AI dalam workflow mereka.