agent.md: File Instruksi yang Meningkatkan Kualitas Kode Bantuan LLM

Tools berbasis AI seperti GitHub Copilot, Claude Code, dan berbagai coding assistant lain semakin menjadi bagian dari workflow developer. Tapi ada satu keluhan yang terus berulang: hasil yang diberikan AI sering tidak konsisten dengan konvensi proyek, mengikuti gaya yang berbeda, atau bahkan memperkenalkan pola yang seharusnya tidak dipakai. Salah satu solusi yang mulai banyak diadopsi adalah file agent.md — file instruksi khusus yang memberi tahu AI bagaimana seharusnya menulis kode di dalam proyek tersebut.

Artikel ini membahas apa itu agent.md, kenapa file ini penting, bagaimana strukturnya, dan bagaimana developer bisa memanfaatkannya untuk meningkatkan kualitas kode yang dihasilkan AI.

Apa Itu agent.md

agent.md adalah file markdown yang berisi instruksi, konvensi, dan pedoman untuk AI coding assistant yang bekerja di dalam repository. Idenya sederhana: sebelum AI mulai menulis atau mengedit kode, ia membaca file ini untuk memahami bagaimana proyek tersebut seharusnya dikerjakan.

Bayangkan AI sebagai developer baru yang bergabung ke tim. Developer baru itu perlu tahu konvensi penamaan, struktur folder, gaya kode, dan aturan yang berlaku di proyek. Tanpa panduan, ia akan menebak-nebak dan hasilnya sering tidak konsisten. agent.md berperan seperti onboarding document yang ringkas untuk AI.

Konsep ini sebenarnya bukan hal baru — banyak proyek sudah punya README atau CONTRIBUTING.md. Tapi file-file itu ditulis untuk manusia, panjang, dan berisi banyak konteks yang tidak relevan untuk tugas menulis kode. agent.md dirancang lebih fokus dan langsung pada instruksi yang dibutuhkan AI untuk bekerja dengan benar.

Kenapa agent.md Makin Populer

Ada beberapa alasan kenapa developer dan tim mulai mengadopsi agent.md:

• Konsistensi kode. Tanpa panduan, AI cenderung menghasilkan kode dengan gaya yang berbeda-beda setiap kali diminta. agent.md memastikan AI mengikuti satu set konvensi yang sama.
• Mengurangi iterasi. Developer tidak perlu berkali-kali mengoreksi hasil AI karena kesalahan konvensi yang seharusnya bisa dihindari sejak awal.
• Menghemat konteks. Alih-alih menulis ulang instruksi di setiap prompt, developer cukup sekali menuliskannya di agent.md dan AI membacanya saat dibutuhkan.
• Onboarding lebih mulus. Developer baru dan AI sama-sama membaca panduan yang sama, sehingga tidak ada perbedaan pemahaman.
• Mendorong standar proyek. Keberadaan agent.md memaksa tim untuk mendokumentasikan konvensi yang selama ini hanya ada di kepala masing-masing.

Yang menarik, file ini juga membantu manusia. Ketika tim menuliskan konvensi untuk AI, mereka sekaligus mendokumentasikan praktik yang selama ini tidak tertulis — nilai yang tetap berguna bahkan jika AI tidak dipakai sama sekali.

Isi yang Umum Ada di agent.md

Isi agent.md sangat bergantung pada proyek, tapi ada beberapa bagian yang hampir selalu muncul:

• Konvensi penamaan — aturan penamaan variabel, fungsi, file, dan komponen.
• Struktur proyek — penjelasan singkat tentang letak file, misalnya di mana komponen, utility, test, dan asset seharusnya ditempatkan.
• Gaya kode — preferensi seperti TypeScript ketat, functional vs OOP, atau penggunaan library tertentu.
• Pola yang harus dihindari — praktik yang dilarang di proyek, misalnya menggunakan any di TypeScript atau menaruh logika di template.
• Instruksi testing — framework test yang dipakai dan bagaimana test seharusnya ditulis.
• Perintah build dan lint — command yang harus dijalankan sebelum kode dianggap selesai.
• Batasan — hal yang tidak boleh dilakukan AI, seperti mengubah file tertentu atau menambah dependency tanpa izin.

Kunci dari agent.md yang baik adalah ringkas dan spesifik. Instruksi yang terlalu panjang justru mengurangi efektivitasnya, karena AI mungkin mengabaikan bagian yang penting atau konteksnya terpotong.

Cara Membuat agent.md yang Efektif

Membuat agent.md yang baik butuh sedikit strategi. Berikut langkah-langkah yang bisa diikuti:

1. Mulai dari masalah nyata. Perhatikan pola kesalahan yang sering dibuat AI di proyek lo. Setiap pola itu adalah kandidat instruksi untuk agent.md. Misalnya, jika AI sering menaruh semua komponen di satu file, tulis aturan tentang pemisahan file.

2. Tulis singkat dan jelas. Gunakan kalimat langsung dan spesifik. Hindari kata-kata ambigu seperti "usahakan" atau "sebaiknya" — gunakan aturan yang tegas seperti "wajib" atau "jangan".

3. Sertakan contoh. Contoh kode pendek yang benar dan yang salah jauh lebih efektif daripada penjelasan panjang. AI sangat baik dalam meniru pola, jadi berikan pola yang tepat.

4. Perbarui secara berkala. agent.md bukan dokumen sekali jadi. Seiring proyek berkembang, konvensi juga berubah. Jadikan pembaruan agent.md bagian dari rutinitas tim.

5. Uji dengan prompt nyata. Setelah menulis agent.md, coba berikan beberapa task nyata ke AI dan perhatikan apakah hasilnya lebih sesuai. Iterasi berdasarkan hasil itu.

Perbedaan agent.md dengan File Instruksi Lain

Saat ini ada beberapa konvensi file instruksi untuk AI, dan penting untuk tidak tertukar:

• CLAUDE.md — konvensi yang dipakai oleh Claude Code, biasanya berisi instruksi umum untuk asisten Claude.
• AGENTS.md — konvensi yang diadopsi lintas tool AI, sering dianggap sebagai standar bersama untuk instruksi agen.
• .cursorrules — file instruksi spesifik untuk editor Cursor.
• agent.md — file instruksi untuk AI coding assistant secara umum, dengan fokus pada cara bekerja di dalam proyek tertentu.

Penting untuk dicatat bahwa ekosistem ini masih berkembang dan setiap tool punya cara baca yang sedikit berbeda. Sebelum membuat file, sebaiknya cek dokumentasi tool AI yang dipakai tim untuk tahu file mana yang dikenali dan bagaimana format yang diharapkan.

Apakah agent.md Layak Diadopsi

Bagi tim yang sudah rutin memakai AI coding assistant, jawabannya hampir pasti ya. agent.md adalah investasi kecil dengan dampak yang langsung terasa: hasil kode AI yang lebih konsisten, review yang lebih cepat, dan lebih sedikit koreksi berulang.

Untuk developer individu, file ini juga berguna, terutama jika sering berpindah-pindah proyek. Dengan agent.md, setiap proyek punya "pengaturan default" yang bisa langsung dipahami oleh AI maupun manusia.

Yang penting diingat: agent.md bukan pengganti keputusan teknis. AI tetap bisa salah dan tetap butuh review manusia. Tapi dengan panduan yang jelas, jumlah kesalahan yang harus dikoreksi bisa berkurang drastis — dan itu artinya lebih banyak waktu untuk pekerjaan yang benar-benar penting.

Contoh Praktis: agent.md di Proyek TypeScript

Supaya lebih konkret, berikut contoh bagaimana agent.md bisa diterapkan di proyek TypeScript yang umum dipakai tim Indonesia:

# agent.md

## Bahasa dan Gaya
- Semua kode dan komentar dalam Bahasa Inggris.
- Nama file dan folder menggunakan camelCase untuk file biasa, PascalCase untuk komponen React.
- TypeScript strict mode wajib. Dilarang menggunakan `any` kecuali dengan alasan yang didokumentasikan.

## Struktur
- Komponen React di src/components, satu komponen per file.
- Utility function di src/lib, bukan di dalam komponen.
- Test diletakkan berdampingan dengan file yang diuji (co-located), format `file.test.ts`.

## Dependency
- JANGAN menambah dependency baru tanpa persetujuan.
- Prefer library yang sudah dipakai di proyek daripada menambah yang baru.

## Build dan Lint
- Jalankan `npm run lint` dan `npm run typecheck` sebelum menyelesaikan task.
- Semua test harus hijau sebelum pull request.

File seperti ini memberi AI konteks yang sangat spesifik: aturan penamaan, struktur folder, batasan dependency, dan perintah verifikasi. Hasilnya, kode yang dihasilkan AI langsung sesuai dengan konvensi tim — tanpa perlu dikoreksi berulang kali.

Perhatikan bahwa contoh di atas menggunakan perintah tegas: "wajib", "dilarang", "JANGAN". Ini bukan kebetulan. AI bekerja lebih baik dengan instruksi yang eksplisit daripada yang implisit. Kalimat seperti "usahakan mengikuti standar" terlalu kabur; "TypeScript strict mode wajib" jauh lebih efektif.

Kesalahan Umum Saat Membuat agent.md

Membuat agent.md yang kurang efektif lebih umum daripada yang berhasil. Beberapa kesalahan yang sering terjadi:

Terlalu panjang. agent.md yang puluhan halaman justru kontraproduktif. AI hanya punya konteks terbatas, dan instruksi yang terlalu banyak akan saling menenggelamkan. Fokus pada aturan yang paling sering dilanggar, bukan semua aturan yang ada.

Terlalu umum. "Tulis kode yang baik" tidak memberi informasi apa pun. agent.md yang baik berisi aturan spesifik untuk proyek itu: "gunakan zod untuk validasi", "pakai TanStack Query untuk data fetching", "jangan simpan token di localStorage".

Tidak diperbarui. Konvensi proyek berubah, tapi agent.md yang dibuat sekali dan dilupakan akan cepat usang. AI akan mengikuti instruksi lama yang sudah tidak relevan, dan hasilnya justru lebih buruk daripada tanpa agent.md.

Menyalin dari proyek lain. agent.md sangat kontekstual. Menyalin file dari proyek lain tanpa menyesuaikan bisa membawa konvensi yang salah dan membingungkan AI. Setiap proyek perlu agent.md-nya sendiri.

Menaruh terlalu banyak harapan. agent.md bukan jaminan kualitas. AI tetap bisa salah, terutama untuk keputusan arsitektur yang kompleks. agent.md mengurangi kesalahan konvensi, bukan menggantikan judgment manusia.

Masa Depan File Instruksi untuk AI

Ekosistem file instruksi untuk AI masih berkembang pesat. Beberapa tren yang perlu diperhatikan:

Standarisasi. Ada dorongan untuk menyatukan konvensi file instruksi lintas tool. AGENTS.md muncul sebagai kandidat standar yang diadopsi oleh banyak tool berbeda, mengurangi fragmentasi yang ada saat ini.

Instruksi hierarkis. Alih-alih satu file besar, muncul pola instruksi bertingkat: file global untuk organisasi, file per proyek, dan file per direktori. Ini memungkinkan instruksi yang lebih tepat sasaran tanpa menenggelamkan AI dalam satu file raksasa.

Integrasi dengan tooling. File instruksi mulai terintegrasi dengan linter, formatter, dan CI pipeline. Misalnya, konvensi di agent.md bisa diverifikasi otomatis oleh tooling, bukan hanya diandalkan pada kepatuhan AI.

Dinamis dan kontekstual. Tool AI masa depan kemungkinan akan memuat instruksi yang relevan secara otomatis berdasarkan task yang sedang dikerjakan, bukan membaca seluruh file setiap kali.

Bagi developer, tren ini berarti keterampilan menulis instruksi yang jelas untuk AI akan makin berharga. File seperti agent.md adalah bentuk paling awal dari keterampilan tersebut — dan yang bisa melakukannya dengan baik akan mendapat keuntungan kompetitif yang nyata.

Kesimpulan

agent.md adalah alat sederhana dengan dampak yang besar. Satu file markdown yang ditulis dengan baik bisa mengubah hasil kode AI dari "menebak-nebak" menjadi "mengikuti konvensi tim secara konsisten".

Bagi tim yang sudah rutin memakai AI coding assistant, jawabannya hampir pasti ya: agent.md adalah investasi kecil dengan dampak yang langsung terasa. Bagi developer individu, file ini juga berguna, terutama jika sering berpindah-pindah proyek. Dengan agent.md, setiap proyek punya "pengaturan default" yang bisa langsung dipahami oleh AI maupun manusia.

Yang penting diingat: agent.md bukan pengganti keputusan teknis. AI tetap bisa salah dan tetap butuh review manusia. Tapi dengan panduan yang jelas, jumlah kesalahan yang harus dikoreksi bisa berkurang drastis — dan itu artinya lebih banyak waktu untuk pekerjaan yang benar-benar penting.