Cara Menulis AGENTS.md dan CLAUDE.md yang Benar

Hampir semua tim yang develop dengan AI coding agent sekarang punya AGENTS.md atau CLAUDE.md di repo mereka — tapi punya file itu ternyata tidak otomatis berarti membantu. Kebanyakan file jatuh ke salah satu dari dua ekstrem: kosong atau generic sampai tidak berguna, atau sebaliknya terlalu panjang dan penuh detail yang justru membuat agent lebih lambat dan lebih mahal dijalankan. Artikel ini membahas cara menulis konten kedua file itu dengan benar, berdasarkan prinsip context engineering dan temuan riset terbaru soal dampaknya terhadap performa agent — bukan sekadar template yang di-copy-paste tanpa dipikir ulang.

Masalah: Kenapa Kebanyakan AGENTS.md Tidak Efektif

Ada dua pola kegagalan paling umum yang ditemukan di lapangan.

Pola pertama — kosong atau generic. Tim membuat AGENTS.md sekali di awal proyek, isinya template umum (“tulis kode yang bersih”, “ikuti best practice”), lalu tidak pernah disentuh lagi. File semacam ini secara praktis tidak memberi informasi apapun yang tidak sudah diketahui model dari training-nya sendiri.

Pola kedua — over-generated. Tim menjalankan perintah semacam /init yang membuat agent menganalisis seluruh codebase dan menghasilkan dokumentasi arsitektur lengkap secara otomatis. Hasilnya terlihat impresif — halaman demi halaman detail struktur, alur data, konvensi — tapi justru inilah yang menurut riset paling bermasalah.

Riset dari ETH Zurich dan LogicStar.ai menguji empat coding agent (Claude Code dengan Sonnet 4.5, Codex dengan GPT-5.2 dan GPT-5.1 Mini, serta Qwen Code) dalam tiga kondisi: tanpa context file, context file hasil generate otomatis, dan context file yang ditulis manual oleh developer. Hasilnya konsisten di semua model yang diuji: context file hasil generate otomatis menurunkan task success rate sekitar 3% dan menaikkan biaya inference lebih dari 20%. Context file yang ditulis manual oleh developer performanya lebih baik — meningkatkan success rate sekitar 4% — tapi tetap menaikkan biaya hingga 19% dan menambah jumlah langkah yang diambil agent sebelum menyelesaikan task.

Penjelasan di balik angka ini masuk akal begitu dipikir lebih dalam: setiap baris instruksi yang masuk ke context bukan cuma “informasi gratis” — itu sesuatu yang harus diproses, dipertimbangkan, dan kadang membuat agent melakukan langkah verifikasi ekstra yang sebenarnya tidak perlu. Kalau instruksi itu menyebut detail arsitektur, agent cenderung mengecek ulang detail itu ke kode meski sebenarnya sudah jelas dari konteks task. Kalau instruksinya tidak akurat atau sudah usang, agent malah mengikuti informasi yang salah alih-alih membaca kode secara langsung.

flowchart LR
    A[Kosong / Generic] --> B[Ideal: Ringkas & Actionable] --> C[Over-Generated / Terlalu Detail]
    A -.->|Task success rendah, tidak ada guidance| D[Performa Buruk]
    C -.->|Cost tinggi, langkah ekstra, guidance salah arah| D
    B -.->|Guidance tepat sasaran, cost terkendali| E[Performa Baik]

Titik optimalnya bukan di salah satu ujung spektrum, dan bukan juga soal “makin detail makin baik”. Bagian-bagian berikutnya membahas prinsip konkret untuk sampai ke titik itu.

Prinsip 1 — Setiap Baris Harus Layak Ada di Sana

Uji paling sederhana untuk tiap baris yang mau kamu tulis: bisakah agent menyimpulkan ini sendiri dari membaca kode, package manifest, atau dokumentasi yang sudah ada? Kalau jawabannya ya, baris itu kandidat kuat untuk dihapus.

// ANTI-PATTERN — bisa disimpulkan agent dari package.json
Proyek ini menggunakan Express.js untuk HTTP server dan Prisma
sebagai ORM untuk berinteraksi dengan PostgreSQL.

// BENAR — informasi yang TIDAK bisa disimpulkan dari kode
Semua endpoint HARUS melalui middleware rateLimiter di
src/middleware/rate-limit.ts. Endpoint baru yang tidak
memakainya akan gagal di security review, bukan cuma
rekomendasi.

Kalimat pertama di contoh anti-pattern gampang ditemukan agent hanya dengan membaca package.json — menulis ulang itu di AGENTS.md cuma menambah token tanpa menambah informasi baru. Kalimat kedua sebaliknya: aturan bisnis/proses yang tidak tertulis di manapun di kode, dan kalau dilanggar konsekuensinya nyata.

Prinsip ini kelihatan sederhana tapi sering dilanggar karena menulis deskripsi umum terasa “aman” — seperti menjelaskan proyek ke orang baru. Masalahnya, agent bukan orang baru yang butuh orientasi umum; agent butuh sinyal spesifik tentang hal yang akan membuatnya salah langkah kalau tidak tahu.

Prinsip 2 — Jangan Duplikasi yang Sudah Ada

README ditulis untuk manusia, AGENTS.md ditulis untuk agent — dua audiens dengan kebutuhan berbeda meski soal proyek yang sama. Duplikasi antara keduanya bukan cuma boros, tapi menurut riset lanjutan justru bisa menurunkan task success karena membuat file lebih panjang tanpa menambah nilai apapun.

Cara praktis mengecek duplikasi: sebelum menambah baris baru ke AGENTS.md, cari dulu apakah informasi itu sudah ada di README, package.json/go.mod, atau dokumentasi arsitektur. Kalau sudah ada, cukup referensikan lokasinya (Lihat docs/architecture.md untuk detail arsitektur), jangan salin ulang isinya.

Prinsip 3 — Command Konkret, Bukan Instruksi Kabur

Instruksi yang kabur memaksa agent menebak atau mencoba-coba, yang berarti langkah ekstra dan potensi kesalahan.

// ANTI-PATTERN
Jalankan test sebelum submit perubahan.

// BENAR
Jalankan `pnpm test:unit -- --grep auth` untuk test module auth
saja, atau `pnpm test:unit` untuk seluruh unit test. Test e2e
(`pnpm test:e2e`) butuh Docker aktif — jangan jalankan kalau
Docker belum running, akan timeout 5 menit tanpa pesan error jelas.

Versi “BENAR” di atas bukan cuma command yang lebih spesifik — dia juga menyertakan gotcha (test e2e butuh Docker) yang kalau tidak ditulis akan membuat agent membuang waktu debug masalah yang sebenarnya bukan soal kode, tapi soal environment.

Pola yang sama berlaku untuk instruksi lain: “ikuti konvensi penamaan yang ada” kabur, “gunakan camelCase untuk function, PascalCase untuk class, dan awali private method dengan underscore” konkret. “Update dokumentasi kalau perlu” kabur, “update docs/api-changelog.md dengan format [tanggal] - [breaking/non-breaking] - [deskripsi]” konkret.

Prinsip 4 — Prioritaskan Risiko Tinggi, Bukan Kelengkapan

AGENTS.md bukan tempat mendokumentasikan seluruh arsitektur sistem — itu tugas dokumentasi arsitektur terpisah. Fokusnya harus ke hal yang, kalau agent salah asumsi, dampaknya signifikan.

PRIORITASKAN untuk ditulis:
  ✓ Security boundary (kredensial, akses data sensitif, PII)
  ✓ Invariant bisnis yang tidak terlihat dari kode (idempotency,
    urutan transaksi, aturan konsistensi data)
  ✓ File/folder yang tidak boleh diubah (generated code, migration
    lama yang sudah di-apply)
  ✓ Konsekuensi nyata kalau instruksi dilanggar (bukan cuma "sebaiknya")

JANGAN prioritaskan:
  ✗ Detail implementasi yang sudah jelas dari kode
  ✗ Preferensi gaya yang tidak berdampak fungsional
  ✗ Sejarah/rationale keputusan lama yang tidak actionable sekarang
  ✗ Penjelasan konsep umum programming yang sudah diketahui model

Rasio yang berguna sebagai pengingat: satu baris yang mencegah insiden nyata jauh lebih bernilai daripada sepuluh baris yang menjelaskan hal yang sudah jelas. Kalau kamu ragu apakah suatu instruksi layak masuk, tanyakan: “kalau baris ini tidak ada, seberapa besar kemungkinan dan seberapa parah dampaknya kalau agent salah langkah di sini?” Baris dengan jawaban “kemungkinan tinggi, dampak parah” jelas layak masuk. Baris dengan jawaban “kemungkinan rendah, dampak kecil” sebaiknya dibuang.

Prinsip 5 — Instruksi Tertulis Bukan Jaminan, Tetap Butuh Enforcement Teknis

Satu hal yang penting disadari: menulis instruksi di AGENTS.md, sekalipun sudah eksplisit, bukan jaminan mutlak agent akan patuh. Ada kasus nyata di mana sebuah proyek yang AGENTS.md-nya sudah berisi 25 baris instruksi — termasuk peringatan eksplisit terhadap asumsi berlebihan — tetap mengalami kegagalan: agent mengganti seluruh kode terkait SQLite menjadi MariaDB hanya karena kata “MariaDB” muncul di beberapa komentar kode, lalu memicu inferensi luas yang salah soal stack yang sebenarnya dipakai. Context file yang sudah ditulis dengan hati-hati itu tetap tidak mencegah kegagalan tersebut.

Pelajarannya: AGENTS.md adalah pelengkap untuk otomasi dan guidance, bukan pengganti enforcement teknis yang sesungguhnya. Aturan yang benar-benar kritis — larangan hardcode credential, batas akses ke data sensitif, aturan yang kalau dilanggar bisa menyebabkan insiden produksi — tetap perlu dijaga lewat mekanisme yang lebih kuat: lint rule, pre-commit hook, CI check, atau code review manusia untuk perubahan berisiko tinggi.

• AGENTS.md memandu, tapi tidak mem-blokir. Untuk aturan yang pelanggarannya berakibat serius, jangan berhenti di menulis instruksi — tambahkan enforcement teknis (lint, CI, atau review wajib).
• Instruksi yang sudah ditulis dengan baik pun bisa “kalah” dari sinyal kuat lain di kode (seperti komentar yang menyesatkan). Jangan berasumsi context file menyelesaikan semua kelas masalah.

Anatomi File yang Baik — Section demi Section

Struktur umum yang terbukti berguna di banyak proyek, disusun dari yang paling stabil ke paling sering berubah:

Section “Project overview” sengaja ditandai opsional dan disarankan singkat — informasi ini paling gampang jadi duplikasi dari README atau package manifest. Section “Commands” dan “Done-when criteria” yang justru paling penting karena tidak ada substitusi lain untuk itu — agent tidak bisa menebak command test yang benar hanya dari membaca kode.

Ukuran dan Batasan Teknis

Ada batas ukuran teknis yang perlu diperhatikan: Codex CLI menerapkan batas 32 KiB untuk AGENTS.md, dan konten di luar batas itu dipotong secara diam-diam tanpa peringatan apapun — artinya kalau file kamu kelewat panjang, bagian akhir instruksinya bisa saja tidak pernah dibaca sama sekali tanpa kamu sadari.

Terlepas dari batas teknis itu, rule of thumb yang lebih penting adalah soal efektivitas, bukan cuma soal muat atau tidak. Mulai dari file pendek — sekitar 10 sampai 30 baris untuk proyek baru — dan tambah isinya hanya ketika terbukti dibutuhkan, misalnya setelah beberapa kali agent membuat kesalahan yang sama karena tidak tahu suatu konvensi. Ini kebalikan dari kebiasaan menulis dokumentasi lengkap di awal “supaya aman” — pendekatan itu justru menghasilkan file yang menurut riset performanya lebih buruk.

CATATAN UKURAN:
  □ Mulai dari 10-30 baris untuk proyek baru
  □ Tambah baris HANYA setelah ada bukti konkret dibutuhkan
    (misalnya agent berulang kali salah asumsi soal hal yang sama)
  □ Review berkala — hapus instruksi yang sudah tidak relevan,
    jangan cuma menumpuk tambahan baru
  □ Kalau memakai Codex CLI, pastikan total ukuran di bawah 32 KiB

Studi Kasus: Before vs After

Mari lihat penerapan prinsip di atas pada contoh nyata — memakai module payment dari studi kasus e-commerce monolith yang sudah kita bahas sebelumnya.

Versi “Buruk” — Hasil /init Mentah, Terlalu Panjang dan Generic

# AGENTS.md — payment module

## Overview
Module payment menangani semua hal terkait pembayaran dalam sistem
e-commerce ini. Module ini menggunakan Go sebagai bahasa pemrograman
dan PostgreSQL sebagai database. Struktur kode mengikuti pola clean
architecture dengan pemisahan domain, application, dan infrastructure
layer.

## Struktur Kode
Module ini memiliki beberapa folder utama:
- domain/ berisi entity dan business logic
- application/ berisi use case dan service
- infrastructure/ berisi implementasi database dan external service
- gateway/ berisi integrasi dengan payment provider
- testing/ berisi helper untuk unit test

## Konvensi
- Gunakan nama variabel yang deskriptif
- Tulis komentar untuk function yang kompleks
- Ikuti Go idiomatic style
- Pastikan kode readable dan maintainable
- Tulis unit test untuk semua function baru
- Gunakan error handling yang baik

## Testing
Jalankan test sebelum melakukan perubahan untuk memastikan tidak
ada yang rusak. Pastikan semua test lulus sebelum submit.

File ini 90% duplikasi (struktur folder bisa dilihat langsung dari ls, konvensi Go idiomatic sudah diketahui model) dan 10% instruksi kabur (“testing yang baik”, “error handling yang baik” tidak bisa dieksekusi secara konkret). Tidak ada satupun invariant kritis yang sebelumnya sudah kita identifikasi — idempotency, state machine, audit trail — padahal itu justru yang paling penting untuk module payment.

Versi “Baik” — Ringkas, Actionable, Fokus ke Risiko Tinggi

# AGENTS.md — payment module

## Invariant yang TIDAK BOLEH Dilanggar
- Charge/refund HARUS idempotent lewat idempotency_key di tabel
  transactions — jangan buat mekanisme idempotency baru.
- Status transaksi HANYA berubah lewat state machine di
  domain/transaction_state.go, jangan update status secara langsung.
- Setiap perubahan status wajib menulis audit_trail dalam
  transaksi database yang sama (bukan best-effort terpisah).

## Test
- `go test ./modules/payment/... -run TestIdempotency` WAJIB lulus
  untuk setiap PR yang menyentuh charge/refund flow.
- Gateway eksternal di-mock lewat testing/mock_gateway.go — jangan
  panggil sandbox provider asli di unit test (rate limit ketat).

## Dependency
- Baca data order lewat application/OrderReader interface, JANGAN
  query tabel orders milik checkout module secara langsung.

Versi ini jauh lebih pendek tapi jauh lebih bernilai — setiap baris adalah sesuatu yang tidak bisa disimpulkan agent hanya dari membaca kode (invariant bisnis, command test spesifik, batasan yang berkonsekuensi nyata kalau dilanggar), dan tidak ada satupun baris yang menduplikasi hal yang sudah jelas dari struktur folder atau bahasa pemrograman yang dipakai.

Kiat untuk CLAUDE.md Secara Spesifik

Kalau tim kamu memakai Claude Code, CLAUDE.md punya peran yang sedikit berbeda dari AGENTS.md. Untuk tim yang memakai beberapa AI coding agent sekaligus, pola yang disarankan adalah menjadikan AGENTS.md sebagai source of truth dan CLAUDE.md sebagai jembatan sederhana:

# CLAUDE.md
@AGENTS.md

Tapi ada kasus di mana CLAUDE.md layak punya instruksi tambahan sendiri di luar baris import itu — khusus untuk hal yang benar-benar spesifik ke Claude Code dan tidak relevan untuk tool lain:

# CLAUDE.md
@AGENTS.md

## Khusus Claude Code
- Skill kustom untuk generate migration ada di .claude/skills/db-migration/
- MCP server internal untuk query staging database tersedia sebagai
  tool `staging_db_query` — pakai ini daripada psql manual untuk
  investigasi data.

Bagian “Khusus Claude Code” ini sengaja dipisah dari AGENTS.md supaya tool lain (Cursor, Codex CLI) yang membaca AGENTS.md yang sama tidak bingung dengan instruksi yang tidak relevan buat mereka — misalnya referensi ke skill atau MCP tool yang memang cuma tersedia di Claude Code.

Checklist Menulis AGENTS.md

SEBELUM COMMIT, CEK TIAP BARIS:
  □ Bisakah agent menyimpulkan ini sendiri dari kode/README/manifest?
    Kalau ya, hapus.
  □ Apakah ini duplikasi dari dokumen lain? Kalau ya, referensikan
    saja lokasinya, jangan salin ulang.
  □ Apakah instruksinya cukup konkret untuk langsung dieksekusi
    (command persis, path persis)? Kalau kabur, tulis ulang lebih
    spesifik atau hapus.
  □ Kalau ini aturan kritis, apakah sudah ada enforcement teknis
    (lint/CI) sebagai backup, bukan cuma mengandalkan kepatuhan agent?
  □ Total ukuran file masih di bawah batas wajar (untuk Codex CLI,
    di bawah 32 KiB)?
  □ Apakah file ini sudah lama tidak direview? Jadwalkan review
    berkala, bukan hanya nambah terus tanpa pernah memangkas.

Ringkasan

• Dua pola kegagalan paling umum: file kosong/generic yang tidak berguna, dan file over-generated yang justru menurunkan task success rate dan menaikkan biaya menurut riset ETH Zurich/LogicStar.ai.
• Uji tiap baris: bisakah agent menyimpulkannya sendiri dari kode/README/manifest? Kalau ya, hapus — redundansi adalah musuh utama context file yang efektif.
• Command harus konkret, bukan kabur — “jalankan pnpm test:unit -- --grep auth” bukan “jalankan test”.
• Prioritaskan risiko tinggi: security boundary, invariant bisnis, file terlarang — bukan kelengkapan dokumentasi arsitektur.
• Instruksi tertulis bukan jaminan mutlak — aturan kritis tetap perlu enforcement teknis lewat lint, CI, atau review manusia.
• Struktur yang direkomendasikan: commands dan done-when criteria wajib dan konkret; project overview singkat saja untuk hindari duplikasi README.
• Mulai kecil (10–30 baris), tambah hanya berdasarkan bukti kebutuhan nyata, dan review berkala untuk memangkas yang sudah tidak relevan.
• CLAUDE.md idealnya cuma jembatan (@AGENTS.md) plus instruksi tambahan yang benar-benar spesifik ke Claude Code saja, seperti referensi skill atau MCP tool internal.