Menulis CLAUDE.md Terbaik: Panduan Lengkap untuk Claude Code

Prompt sistem Claude Code sudah memuat sekitar 50 instruksi sebelum sesi Anda dimulai. Riset pada LLM frontier menunjukkan bahwa kepatuhan terhadap instruksi mulai menurun pada kisaran total 150 hingga 200 instruksi, yang menyisakan sekitar 100 hingga 150 slot untuk semua hal yang Anda ingin Claude ketahui tentang proyek Anda. 

CLAUDE.md adalah berkas yang mengisi slot tersebut. Ini adalah berkas markdown yang Claude Code baca di awal setiap sesi, memberinya konteks persisten tentang basis kode Anda tanpa perlu Anda mengulang-ulang. Namun Claude secara aktif memfilter konten yang dianggap tidak relevan dengan tugas saat ini. Berkas yang gemuk bukan hanya membuang ruang; itu bersaing dengan aturan Anda yang sebenarnya.

Tutorial ini membahas cara membangun CLAUDE.md yang pantas atas setiap baris: apa yang dimasukkan, apa yang dikeluarkan, bagaimana menyusunnya untuk tim, dan cara menjaganya tetap berguna seiring waktu.

Saya juga merekomendasikan untuk melihat panduan Claude Code terbaru kami lainnya:

• Claude Code Plan Mode
• Claude Code di Docker
• Cara Membangun Plugin Claude Code
• Menggunakan Claude Code dengan Model Lokal Ollama

Apa Itu Berkas CLAUDE.md?

CLAUDE.md adalah berkas markdown yang dimuat otomatis oleh Claude Code pada awal setiap percakapan. Berkas ini berada di root proyek Anda dan memberikan instruksi tetap kepada Claude tentang berbagai hal relevan: 

• Stack teknologi yang Anda gunakan
• Cara Anda menjalankan pengujian
• Konvensi mana yang penting
• Apa yang tidak boleh disentuh

Tanpanya, setiap sesi dimulai dari nol. Anda menjelaskan konteks yang sama, mengoreksi asumsi yang sama, dan melihat Claude mengulang kesalahan yang sama seperti kemarin. CLAUDE.md mengatasinya dengan meng-enkode pengetahuan proyek Anda sekali saja.

Ini adalah salah satu dari beberapa sistem konteks yang digunakan Claude Code, dan masing-masing menangani jenis pekerjaan yang berbeda:

Menjalankan /init menghasilkan CLAUDE.md awal dengan menganalisis basis kode Anda, mendeteksi sistem build, kerangka uji, dan pola kode. Jika berkas sudah ada, ia akan menyarankan perbaikan alih-alih menimpanya. Ini titik awal yang masuk akal, tetapi berkas ini terlalu penting untuk dibiarkan berjalan otomatis.

Satu hal penting: konten CLAUDE.md juga bertahan melewati /compact. Saat konteks dikompresi di tengah sesi, Claude membaca ulang berkas dari disk dan menyuntikkannya kembali dalam keadaan segar.

Lokasi berkas dan prioritas

Berkas CLAUDE.md dapat berada di empat lokasi, dari yang paling luas hingga paling spesifik:

• Kebijakan terkelola (skala organisasi): /Library/Application Support/ClaudeCode/CLAUDE.md di macOS. Berlaku untuk semua pengguna di mesin tersebut dan tidak dapat dikecualikan oleh pengaturan apa pun. Di Linux/WSL berada di /etc/claude-code/CLAUDE.md, dan di Windows di C:\Program Files\ClaudeCode\CLAUDE.md.

• Tingkat pengguna: ~/.claude/CLAUDE.md. Instruksi pribadi yang berlaku di setiap proyek pada mesin Anda.

• Tingkat proyek: ./CLAUDE.md atau ./.claude/CLAUDE.md di root repo. Inilah yang Anda commit ke git dan bagikan dengan tim.

• Subdirektori: ./subdir/CLAUDE.md. Cakupannya terbatas pada direktori tersebut dan dimuat sesuai permintaan saat Claude membaca berkas di sana, bukan pada awal sesi.

Berkas yang lebih spesifik memiliki prioritas lebih tinggi daripada yang lebih luas. Jika CLAUDE.md proyek Anda mengatakan "gunakan tab" dan berkas tingkat pengguna Anda mengatakan "gunakan spasi," maka berkas proyek yang berlaku.

Untuk preferensi pribadi yang tidak seharusnya masuk ke version control, buat CLAUDE.local.md dan tambahkan ke .gitignore. Keanehan editor, gaya commit yang disukai, atau override sementara sebaiknya ditempatkan di sini agar tidak mengotori berkas bersama.

Mengetahui di mana berkas berada dan dengan apa ia bersaing, pertanyaan berikutnya adalah apa yang benar-benar perlu dimasukkan ke dalamnya.

Apa yang Perlu Disertakan dalam CLAUDE.md Anda

Sebuah CLAUDE.md terbagi menjadi tiga lapisan: 

1. Apa proyeknya
2. Mengapa ia bekerja seperti itu
3. Bagaimana Claude harus beroperasi di dalamnya

Jika Anda sudah membaca Claude Code Best Practices, Anda akan mengenali prinsip yang sama diterapkan pada cakupan yang lebih sempit. (Jika belum, sebaiknya Anda membacanya setelah artikel ini!)

Gambaran proyek dengan sinyal tinggi

Mulailah dengan satu atau dua baris deskripsi proyek dan stack teknologi Anda beserta versi. Claude bisa menyimpulkan banyak hal dari membaca kode Anda, tetapi ia tidak akan menebak bahwa Anda menggunakan Next.js 15 alih-alih 14, atau bahwa Anda memilih Drizzle ketimbang Prisma.

Sertakan peta struktur direktori. Tidak perlu setiap berkas, cukup tata letak tingkat atas dengan deskripsi singkat:

src/
  data/        # Data loading and preprocessing pipelines
  models/      # Model definitions and training loops
  evaluation/  # Metrics, validation, experiment tracking
  api/         # FastAPI endpoints for model serving
  tests/       # Co-located with source, test_*.py

Tempatkan perintah umum di dalam blok kode. Build, test, lint, dan menjalankan server dev. Perintah di dalam pagar kode adalah sesuatu yang akan dijalankan Claude secara verbatim. Perintah yang ditulis di dalam kalimat hanyalah saran yang mungkin diimprovisasi.

Tujuan dan batasan

Keputusan arsitektural Anda perlu ada dalam berkas karena jika tidak, Claude akan membuat keputusannya sendiri. Jika Anda memilih SQLite daripada Postgres karena suatu alasan, jelaskan. Jika lapisan API Anda mengikuti pola tertentu, paparkan alasannya.

Rasional bernilai nyata di sini. "Jangan pernah force push" adalah instruksi datar yang mungkin diabaikan Claude saat terdesak. "Jangan pernah force push. Ini menulis ulang riwayat bersama dan tidak dapat dipulihkan bagi kolaborator," memberikan konteks yang cukup bagi Claude untuk melakukan generalisasi. Ia tidak hanya akan menghindari git push --force. Ia juga akan ragu sebelum git reset --hard pada branch bersama.

Instruksi kerja untuk Claude

Bagian ini mencakup konvensi yang tidak bisa dipetik Claude hanya dari membaca kode Anda. Jika Anda menggunakan Conventional Commits (feat:, fix:, docs:), sebutkan. Jika branch mengikuti pola penamaan seperti initials/description, tuliskan.

Keanehan dan jebakan juga tempatnya di sini. Setiap basis kode memilikinya: skrip migrasi yang harus dijalankan sebelum build, variabel env yang membutuhkan nilai tertentu sebelum tes lulus, modul yang rusak jika diimpor tidak berurutan. Claude adalah anggota tim baru di setiap sesi, dan hal-hal inilah yang membuat karyawan baru tersandung di hari pertama.

Yang bisa Anda lewati: apa pun yang sudah diketahui Claude dari bahasa itu sendiri. Anda tidak perlu menyuruhnya menggunakan async/await di JavaScript modern atau lebih memilih pathlib di Python 3. Jika suatu konvensi adalah default bahasa, menuliskannya hanya akan menjadi kebisingan yang menyingkirkan instruksi yang benar-benar penting.

Cara Menulis Berkas CLAUDE.md

Menentukan konten yang tepat adalah bagian yang lebih mudah. Bagian yang lebih sulit adalah menulis instruksi yang benar-benar akan diikuti Claude, dan mengetahui apa yang harus dipangkas.

Menulis instruksi yang efektif

Kekhususan mengalahkan niat setiap saat. "Formatkan kode dengan benar" tidak memberi tahu apa pun pada Claude. "Gunakan indentasi 2 spasi, tanpa titik koma, tanda kutip tunggal" memberitahunya secara tepat apa yang harus dilakukan dan memberi sesuatu yang dapat diverifikasi.

Terapkan uji ini pada setiap baris: "Akankah menghapus ini membuat Claude melakukan kesalahan?" Jika jawabannya tidak, baris tersebut dihapus. Rekomendasi resmi kurang dari 200 baris per berkas, dan beberapa tim berpengalaman berjalan dengan kurang dari 60. Ini bukan minimalisme demi minimalisme: berkas yang lebih pendek berarti lebih banyak bagiannya yang terbaca.

Batasi tingkat heading maksimal tiga. Gunakan nama bagian yang dikenali agen dari konvensi README: Commands, Structure, Conventions, Testing. Berkreasi dengan nama bagian justru menambah friksi karena Claude telah melihat jutaan README dan memiliki ekspektasi kuat tentang apa yang ada di mana.

Saat sebuah aturan terus diabaikan meski sudah ada di berkas, jangan tambahkan lebih banyak kata di sekitarnya. Awali dengan IMPORTANT: atau YOU MUST. Namun gunakan ini secara hemat, karena penekanan tidak diskalakan dengan baik. Jika setiap aturan ditandai penting, penekanan itu menjadi tak terlihat.

Apa yang perlu dikeluarkan

Penegakan gaya kode adalah jebakan terbesar. Pemformatan, indentasi, pengurutan impor: ini adalah masalah deterministik dengan solusi deterministik. Linter dan formatter seperti Biome, ESLint, atau Ruff menanganinya lebih cepat, lebih murah, dan dengan konsistensi 100%. Menghabiskan anggaran instruksi untuk aturan gaya adalah beban mati: pekerjaan yang sama bisa dilakukan hook pre-commit secara gratis.

Konvensi bahasa standar juga termasuk daftar pengecualian, karena Claude sudah mengetahui pola TypeScript dan idiom Python. Dokumentasi API lengkap sebaiknya ditautkan alih-alih ditempel. Instruksi khusus tugas yang hanya berlaku untuk alur kerja tertentu sebaiknya ditempatkan di skills, agar dimuat sesuai permintaan alih-alih memakan ruang di setiap sesi.

Satu pola yang perlu digarisbawahi: batasan yang hanya berupa negasi. "Jangan pernah gunakan --legacy-peer-deps" membuat Claude buntu saat menemui konflik dependensi. Pasangkan setiap larangan dengan arahan: "Jangan pernah gunakan --legacy-peer-deps; selesaikan konflik dengan memperbarui paket ke versi yang kompatibel." Jika Anda pernah bekerja dengan Cursor Rules atau berkas konfigurasi AI serupa, Anda akan menemukan prinsip ini berlaku lintas alat.

Sebelum dan sesudah: contoh minimal dari dunia nyata

Beginilah perbedaannya dalam praktik. Di kiri, bagian CLAUDE.md hasil auto-generate yang khas, penuh nasihat generik yang sudah diketahui Claude. Di kanan, bagian yang sama setelah menerapkan uji kekhususan: hanya fakta khusus proyek yang dipertahankan.

Versi kedua lebih singkat dan memberi tahu hal-hal yang tidak dapat disimpulkan Claude dari basis kode.

Membangun berkas dari nol

Jalankan /init di root proyek Anda untuk mendapatkan titik awal yang dihasilkan. Baca setiap baris, potong yang jelas, dan tambahkan yang kurang dari cara tim Anda sebenarnya bekerja. Memulai dari keluaran /init lebih cepat daripada dari berkas kosong, tetapi konten hasil generate tidak boleh didistribusikan tanpa tinjauan.

Jika Anda lebih suka menulis dari nol, mulailah dengan lima bagian: 

1. Gambaran proyek
2. Peta direktori
3. Perintah
4. Konvensi
5. Keanehan

Anda selalu bisa menumbuhkan berkasnya nanti, dan memulai secara minimal berarti setiap baris yang Anda tambahkan berasal dari kesalahan nyata, bukan spekulasi.

Dua sinyal yang menunjukkan berkas perlu pemeliharaan: 

• Claude meminta maaf karena melewatkan instruksi yang sudah ada: Perumusannya ambigu, jadi tulis ulang instruksinya.
• Aturan yang sama dilanggar di beberapa sesi: Berkas terlalu panjang, dan Claude memfilternya, jadi perpendek.

Keduanya menunjuk ke obat yang sama: kata-kata lebih sedikit, struktur lebih jelas.

Menskalakan Berkas CLAUDE.md untuk Tim

Berkas untuk pengembang tunggal bisa tetap ramping tanpa batas. Begitu tim terlibat, berkas memerlukan jenis struktur yang berbeda.

Version control dan kepemilikan bersama

CLAUDE.md tingkat proyek Anda harus masuk ke git. Ini adalah dokumentasi bersama yang menjadi lebih baik saat rekan tim menyumbangkan aturan dari kesalahan mereka sendiri. Perlakukan perubahannya sama seperti PR kode: tinjau, pertanyakan apakah setiap baris baru pantas mendapatkan tempatnya.

Saat konvensi menumpuk melampaui yang muat dalam satu berkas, pindahkan ke .claude/rules/. Setiap berkas Markdown mencakup satu topik dengan nama berkas deskriptif: testing.md, api-design.md, database-migrations.md. Claude menemukan berkas-berkas ini secara rekursif dan memuatnya dengan prioritas yang sama seperti CLAUDE.md utama.

Aturan yang dicakup berdasarkan path membuatnya lebih tertarget lagi. Tambahkan frontmatter YAML, dan aturan hanya dimuat saat Claude bekerja dengan berkas yang cocok:

---
paths:
  - "src/api/**/*.ts"
---
# API conventions go here

Konvensi frontend Anda tidak akan menghabiskan anggaran instruksi saat bekerja di backend, begitu juga sebaliknya.

Di monorepo tempat tim memiliki konvensi yang berbenturan, claudeMdExcludes memblokir berkas tertentu agar tidak dimuat:

{
  "claudeMdExcludes": [
    "**/other-team/.claude/rules/**"
  ]
}

Tempatkan ini di .claude/settings.local.json agar tetap di luar version control.

Pengungkapan progresif dan modularisasi

Menskalakan CLAUDE.md biasanya memicu dorongan untuk memusatkan: satu berkas besar berisi semuanya. Itu arah yang keliru. Memecah CLAUDE.md monorepo menjadi berkas tingkat layanan dapat mengurangi jumlah kata total hingga 80% sembari meningkatkan kepatuhan Claude terhadap aturan; lebih sedikit yang dibaca per sesi berarti lebih sedikit yang harus difilter.

Prinsipnya: tunjukkan, jangan sematkan. Alih-alih @path/to/big-doc.md (yang memuat seluruh berkas ke setiap sesi), tulis "Untuk prosedur migrasi, lihat docs/migrations.md." Claude akan membacanya saat membutuhkan informasi. Sintaks impor @ cocok untuk berkas kecil, tetapi apa pun yang substansial lebih baik dirujuk daripada disematkan.

Berkas CLAUDE.md subdirektori melengkapi pola ini. frontend/CLAUDE.md dengan konvensi React hanya dimuat saat Claude menyentuh berkas di direktori tersebut. Aturan backend tidak mengganggu saat bekerja di frontend.

Memelihara Berkas CLAUDE.md Anda

Menskalakan struktur sebagian besar adalah masalah yang terpecahkan setelah Anda memahami primitifnya. Namun proyek berubah, dan konvensi berevolusi. Aturan yang masuk akal enam bulan lalu menjadi kebisingan yang menyingkirkan aturan yang penting saat ini. Tantangan berkelanjutan adalah menjaga berkas tetap jujur seiring waktu.

Menjaga berkas tetap mutakhir

Tambahkan aturan lebih lambat dari yang Anda kira perlu. Baris baru hanya layak dimasukkan saat Claude benar-benar membuat kesalahan yang bisa dicegah oleh baris tersebut. Setiap aturan harus dapat ditelusuri ke insiden nyata, bukan yang hipotetis.

Arah sebaliknya sama pentingnya: jika Claude sudah mengikuti suatu konvensi tanpa diberi tahu, aturan itu adalah beban mati. Hapus dan bebaskan anggaran instruksi untuk aturan yang benar-benar mengubah perilaku.

Kebiasaan perawatan berupaya rendah adalah meminta Claude, "Tinjau CLAUDE.md ini dan sarankan perbaikan" setiap beberapa minggu. Ia mendeteksi kontradiksi antar aturan, menandai instruksi yang tumpang tindih, dan mengidentifikasi perumusan yang bisa dipadatkan. 

Anda juga dapat menambahkan instruksi tetap di dalam berkas: "Saat Anda menemui asumsi yang keliru selama sesi, sarankan koreksi CLAUDE.md." Ini menciptakan umpan balik di mana berkas membaik melalui penggunaan normal.

Anti-pola yang perlu dihindari

Kegagalan paling umum adalah akumulasi. Aturan menumpuk setelah setiap sesi yang membuat frustasi, tidak ada yang menghapus yang sudah tidak relevan, dan akhirnya, berkas menjadi cukup panjang hingga Claude memfilter setengahnya. Ketika Claude terus mengabaikan aturan, menambah penekanan di atas berkas yang membengkak tidak akan memperbaikinya. Pemangkasan akan.

Jika Anda menggunakan impor @ untuk berkas besar, itu masalah kedua yang perlu diperiksa. Dokumen arsitektur 500 baris yang diimpor dengan @ menyematkan seluruh dokumen ke setiap sesi, menghabiskan anggaran instruksi Anda sebelum Claude memproses aturan pertama yang sebenarnya. Rujuk saja dokumennya.

Menghasilkan otomatis dengan /init dan tidak pernah mengurasi hasilnya adalah cara yang andal untuk mendapatkan perilaku buruk secara menyeluruh. Instruksi yang keliru di CLAUDE.md tidak hanya memengaruhi satu respons. Ia membentuk riset, perencanaan, dan implementasi Claude di setiap sesi sampai ada yang menyadarinya.

Aturan yang saling bertentangan di berbagai berkas menyebabkan perilaku tak terduga. Ketika dua aturan bertentangan, Claude memilih salah satunya tanpa memberi tahu Anda yang mana. Ini menjadi lebih buruk pada proyek yang menggabungkan CLAUDE.md root dengan beberapa berkas .claude/rules/. Tinjauan berkala di seluruh berkas instruksi adalah satu-satunya pencegahan.

Tidak setiap kesalahan pantas mendapatkan aturan baru. Beberapa kegagalan adalah kejadian tunggal. Aturan yang ditambahkan untuk setiap kasus tepi menciptakan berkas penuh dengan instruksi kondisional yang membantu pada situasi sempit dan merugikan pada mayoritas sesi. Tujuannya sejak awal tetap sama: berkas pendek di mana setiap baris mengubah perilaku.

Kesimpulan

CLAUDE.md mungkin adalah berkas paling krusial dalam proyek Claude Code. Berkas ini membentuk setiap sesi sebelum satu pun prompt diketik, dan yang terpelihara dengan baik akan berlipat ganda dampaknya sepanjang berminggu-minggu kerja.

Jika Anda belum memilikinya, jalankan /init, baca hasilnya, dan pangkas setiap baris yang tidak akan mencegah kesalahan nyata. Jika Anda sudah memilikinya, buka sekarang dan terapkan uji yang sama. Jika CLAUDE.md Anda harus sangat besar untuk menjelaskan proyek Anda, itu pertanda bahwa tooling proyek terlalu kompleks, bukan Anda perlu berkas yang lebih besar.

Langkah tepat berikutnya: audit repo Anda dan buat draf baseline hari ini. Mulailah dengan lima bagian, jaga di bawah 60 baris, dan biarkan kesalahan nyata mendorong setiap penambahan setelahnya.

Jika Anda ingin membangun alat yang menggunakan Anthropic API, kursus Introduction to Claude Models kami mencakup seluruh keluarga model dan mengajarkan cara menggunakannya secara efektif.