CLAUDE.md dan AGENTS.md: apa itu, apa yang ditulis di dalamnya, dan mengapa agen mengabaikan aturan

Apa itu CLAUDE.md dan AGENTS.md

Keduanya adalah file Markdown biasa di akar repositori, yang otomatis dimuat agen ke dalam konteks di awal sesi. Melalui file ini Anda memberi tahu agen hal-hal yang tidak bisa ia pelajari sendiri dari kode: cara menyalakan lingkungan, perintah apa yang dipakai untuk memverifikasi pekerjaan, aturan proyek mana yang tidak bisa ditawar, dan di mana dokumentasi rincinya berada.

CLAUDE.md adalah file yang dibaca Claude Code. AGENTS.md adalah format terbuka dengan gagasan yang sama, didukung oleh banyak agen pemrograman. Jika tim memakai beberapa agen, isi utama sebaiknya disimpan di AGENTS.md, lalu CLAUDE.md merujuk ke sana. Claude Code mendukung impor file lain dengan awalan @:

# CLAUDE.md
@AGENTS.md

Dengan begitu aturan hanya ada di satu tempat dan tidak berbeda antara dua file.

Bagaimana agen membaca file ini

Isi file instruksi masuk ke jendela konteks model bersama prompt sistem dan tetap di sana sepanjang sesi. Ada tiga konsekuensi penting.

• Setiap baris memakan tempat di konteks. File dibaca utuh pada setiap peluncuran, meskipun tugas saat ini hanya membutuhkan sepersepuluhnya.
• Ini teks, bukan aturan yang dieksekusi. Model mempertimbangkannya bersama konteks lain, dan tidak ada jaminan kepatuhan seratus persen. Larangan keras harus didukung mekanisme: pemeriksaan, hook, dan hak akses.
• File bisa disusun berlapis. Claude Code memuat CLAUDE.md dari akar proyek dan dari folder pengguna ~/.claude/, sedangkan file di subfolder dimuat ketika agen bekerja dengan file di dalam folder tersebut. Dengan cara ini aturan modul bisa disimpan berdampingan dengan modulnya.

Apa yang ditulis di CLAUDE.md dan AGENTS.md

File instruksi yang baik adalah peta, bukan buku pelajaran. Ia menjawab pertanyaan yang akan diajukan agen kepada rekan berpengalaman pada hari pertamanya.

1. Cara menyusun dan memverifikasi proyek

Bagian yang paling berharga. Perintah konkret yang wajib dijalankan agen sebelum mengatakan «selesai»: tes, linter, pemeriksaan tipe, dan menyalakan lingkungan. Tanpanya, agen memeriksa dirinya «dengan perasaan».

2. Batasan keras

Daftar pendek hal-hal yang tidak boleh dilanggar dalam keadaan apa pun: invarian keamanan dan data. Tulis sebagai invarian, bukan sebagai instruksi implementasi: «semua kueri SQL diparameterisasi», bukan «gunakan fungsi ini di file itu».

3. Peta proyek

Di mana letak apa: beberapa baris tentang struktur folder dan tempat mencari detail. Untuk setiap topik besar ada tautan ke dokumen terpisah yang akan dibuka agen hanya ketika ia mengerjakan topik itu.

4. Di mana status pekerjaan disimpan

Ke mana harus melihat untuk melanjutkan dari titik terakhir sesi sebelumnya: file rencana, log kemajuan, atau backlog. Ini mengatasi «amnesia» agen antarsesi.

Apa yang tidak perlu ditulis

• Hal yang bisa dibaca agen dari kode. Daftar dependensi ada di package.json atau pyproject.toml, struktur kelas ada di kodenya sendiri.
• Nasihat umum. «Tulis kode yang bersih» atau «berhati-hatilah» tidak mengubah perilaku dan hanya memakan tempat.
• Sejarah proyek dan catatan sekali pakai. «Pada Maret kami pindah dari MySQL 5.7» tidak membantu tugas saat ini.
• Instruksi rinci untuk tugas yang jarang. Prosedur deploy atau migrasi data dibutuhkan seminggu sekali — pindahkan ke dokumen terpisah atau skill.
• Rahasia. File ada di repositori dan seluruhnya masuk ke model. Token dan kata sandi hanya boleh ada di variabel lingkungan.

Mengapa agen mengabaikan aturan yang tertulis di file

Kisah yang sering terjadi: agen membuat kesalahan, lalu sebuah aturan ditambahkan ke file. Kesalahan lagi, aturan lagi. Beberapa bulan kemudian file berisi ratusan baris, dan aturan keamanan yang paling penting dilanggar seolah-olah tidak pernah ada. Biasanya ada empat penyebab, dan semuanya bekerja bersamaan.

File yang membengkak

File 600 baris kira-kira 10–20 ribu token. Jendela konteks terlihat besar, tetapi ia diperebutkan oleh kode, keluaran perintah, dan riwayat percakapan. Semakin banyak instruksi memakan tempat, semakin sedikit perhatian yang didapat setiap aturan dan semakin sempit ruang untuk tugas itu sendiri.

Aturan di tengah

Model bahasa jauh lebih lemah dalam memanfaatkan informasi dari bagian tengah teks panjang dibanding dari awal dan akhirnya. Aturan di baris ke-300 dari 600 berada di titik paling lemah.

Tanpa prioritas

Larangan yang tidak bisa ditawar dan catatan gaya yang sepintas lalu ditulis sama saja, sebagai satu baris dalam daftar. Agen tidak punya cara untuk tahu mana yang lebih penting. Dan jika ada tiga aturan gaya yang saling bertentangan, perilaku agen menjadi acak dari satu peluncuran ke peluncuran berikutnya.

Pembusukan

Menambahkan aturan itu gratis, tetapi menghapusnya menakutkan: «jangan-jangan ada sesuatu yang bergantung padanya». Karena itu file terus bertambah, dan proporsi baris yang berguna terus turun. Ukurannya bisa dilihat dari rasio sinyal terhadap derau: berapa baris yang benar-benar dibutuhkan untuk tugas tipikal, dan berapa yang tidak.

Cara memperbaiki: router, bukan tembok teks

Memperbaiki satu penyebab saja tidak cukup: jika file dipangkas tetapi tetap tanpa struktur, aturan-aturannya tetap bercampur. Yang berhasil adalah kombinasi beberapa langkah.

1. Jadikan file masukan sebagai router. 50–150 baris: perintah verifikasi, batasan keras, peta proyek, dan tautan ke dokumen tematik.
2. Pindahkan topik ke file terpisah. Misalnya docs/agents/deploy.md dan docs/agents/database.md. Agen membukanya bila perlu. Di Claude Code, skills cocok untuk prosedur yang berulang karena hanya dimuat saat dibutuhkan.
3. Naikkan hal yang kritis. Batasan keras diletakkan di awal file, dalam blok pendek tersendiri dengan penanda MUST yang jelas.
4. Hilangkan pertentangan. Untuk setiap topik hanya satu aturan. Jika ada pengecualian, tulis tepat di sebelah aturannya.
5. Dukung aturan dengan mekanisme. Jika pelanggaran tidak boleh terjadi, teks saja tidak cukup. Dibutuhkan pemeriksaan yang menangkapnya: linter, tes, hook pre-commit, atau hook agen, atau pembatasan hak akses.
6. Tinjau secara berkala. Pasang batas jumlah baris dan setiap kali menambah aturan, tanyakan apa yang bisa dihapus atau dipindahkan.

Aturan atau pemeriksaan?

Contoh AGENTS.md yang ringkas

# AGENTS.md — backend pembayaran (FastAPI, PostgreSQL)

## MUST — jangan dilanggar
- Jumlah uang adalah int dalam sen, tidak pernah float
- SQL hanya yang diparameterisasi, tanpa f-string
- Jangan ubah migrasi yang sudah diterapkan, hanya tambahkan migrasi baru
- Rahasia hanya dari variabel lingkungan

## Verifikasi sebelum kata «selesai»
docker compose up -d     # lingkungan
make lint                # ruff + mypy
make test                # pytest
make e2e                 # skenario checkout
Tes unit yang hijau tanpa e2e belum berarti «selesai».

## Peta
- app/payments/   — perhitungan jumlah, diskon, webhook penyedia
- app/api/        — endpoint HTTP
- tests/e2e/      — skenario pengguna
Rincian: docs/agents/architecture.md, docs/agents/database.md

## Status pekerjaan
- PLAN.md      — tujuan saat ini, kriteria selesai, langkah berikutnya
- PROGRESS.md  — apa yang sudah dikerjakan dan cara verifikasinya, jalan buntu
- BACKLOG.md   — hal yang terlihat di sela-sela: catat di sini, jangan perbaiki sekarang

Di akhir sesi, perbarui PROGRESS.md dan langkah berikutnya di PLAN.md.

Perhatikan apa yang tidak ada di sini: daftar pustaka, nasihat gaya, dan sejarah proyek. Semua itu sudah terlihat dari kode, dikunci oleh pemeriksaan, atau ada di dokumen tematik.

Amnesia antarsesi: file instruksi plus file rencana

File instruksi menjelaskan cara bekerja di proyek, tetapi bukan apa yang sedang terjadi. Untuk itu diperlukan file status terpisah yang dibaca agen di awal dan diperbarui di akhir sesi. Isinya: tujuan, hal yang sudah dikerjakan beserta cara verifikasinya, keputusan dengan alasannya, opsi yang ditolak, dan satu rumusan langkah berikutnya. Uji kualitasnya sederhana: buka sesi baru, tulis «lanjutkan», dan lihat apakah agen langsung bekerja tanpa bertanya.

Jangan campur dua file ini. Instruksi berubah jarang dan berlaku untuk semua tugas. Rencana berubah setiap sesi dan berlaku untuk tugas saat ini. Jika keduanya dicampur, file instruksi cepat membengkak dengan catatan usang.

Bagaimana memastikan file bekerja

File instruksi juga perlu diuji. Ambil beberapa tugas tipikal — perbaikan bug, fitur kecil, refaktor — dan lihat apa yang dilakukan agen tanpa petunjuk: apakah ia menjalankan perintah yang benar, membuka dokumen tematik yang tepat, dan mematuhi batasan keras. Jika ada aturan yang dilanggar, tanyakan dulu apakah aturan itu terlihat, apakah ada pertentangan, dan apakah ia bisa digantikan pemeriksaan otomatis. Menambah baris baru adalah pilihan terakhir.

Kesimpulan

CLAUDE.md dan AGENTS.md adalah pintu masuk agen ke proyek. Keduanya berfungsi ketika tetap menjadi peta yang singkat: perintah verifikasi, batasan keras di bagian atas, tautan ke rincian, dan tautan ke file rencana. Jika suatu aturan diabaikan, penyebabnya hampir selalu file yang membengkak dan tidak terstruktur, dan aturan yang benar-benar kritis harus didukung pemeriksaan dan hook. Cara menyusun instruksi dan status agen dibahas langsung dalam praktik di kursus harness engineering.