Cara Menulis Claude.md yang Baik

• LLM adalah fungsi tanpa status, sehingga CLAUDE.md berfungsi sebagai dokumen inti yang memperkenalkan codebase kepada Claude di setiap sesi
• File ini harus memuat WHAT (struktur), WHY (tujuan), dan HOW (cara kerja) proyek secara ringkas; terlalu banyak perintah yang tidak perlu justru menurunkan performa
• Claude dapat mengabaikan isi CLAUDE.md jika, sesuai instruksi pada system message, dianggap kurang relevan
• File yang efektif hanya berisi informasi singkat yang berlaku umum, sementara instruksi detail dipisahkan ke dokumen lain dan dikelola dengan pendekatan Progressive Disclosure
• Karena CLAUDE.md adalah titik dengan pengaruh tertinggi dalam agent harness, file ini sebaiknya ditulis manual dengan cermat, bukan dibuat otomatis

---

Sifat Stateless pada LLM dan Peran CLAUDE.md

• LLM menggunakan bobot yang tetap pada saat inferensi dan tidak mempertahankan pembelajaran atau ingatan antar sesi
  • Karena itu, semua informasi harus diberikan sebagai token input agar model dapat memahami codebase
• Coding agent seperti Claude Code harus mengelola memori secara eksplisit, dan CLAUDE.md adalah satu-satunya file yang otomatis disertakan dalam semua percakapan
• Akibatnya, tiga hal berikut menjadi penting
  1. Saat sesi dimulai, Claude tidak mengetahui apa pun tentang codebase
  2. Di setiap sesi, informasi yang diperlukan harus diberikan lagi
  3. Sarana standar untuk itu adalah CLAUDE.md

Onboarding Codebase: WHAT, WHY, HOW

• CLAUDE.md berperan sebagai dokumen onboarding yang membantu Claude memahami proyek
  • WHAT: memberikan peta kode seperti tech stack, struktur proyek, dan susunan monorepo
  • WHY: menjelaskan tujuan dan fungsi tiap komponen
  • HOW: menjelaskan cara melakukan pekerjaan nyata seperti build, test, dan typecheck
• Namun, mencantumkan semua perintah itu tidak efisien; hanya informasi minimum yang benar-benar diperlukan yang sebaiknya dimasukkan

Mengapa Claude Mengabaikan CLAUDE.md

• Claude Code menyisipkan system reminder seperti berikut ke dalam pesan pengguna

  IMPORTANT: this context may or may not be relevant...
  

  • Karena itu, Claude dapat mengabaikan konteks tersebut jika menilai bahwa isinya tidak relevan dengan tugas saat ini
• Semakin banyak instruksi yang tidak berlaku umum di dalam file, semakin besar kemungkinan file itu diabaikan
• Diperkirakan Anthropic menambahkan ini karena kualitas hasil meningkat saat instruksi yang tidak perlu diabaikan

Prinsip Menulis CLAUDE.md yang Baik

Less (instructions) is more

• LLM secara stabil hanya dapat mengikuti sekitar 150~200 instruksi
  • Semakin kecil modelnya, semakin tajam penurunan performanya, dan semakin tidak cocok untuk tugas multi-langkah
• System prompt Claude Code sendiri sudah berisi sekitar 50 instruksi
  • Karena itu, CLAUDE.md sebaiknya hanya memuat instruksi yang umum dan benar-benar penting dalam jumlah minimum
• Semakin banyak instruksi, semakin merata penurunan kualitas pelaksanaan semua instruksi

Panjang File dan Cakupan Penerapan

• LLM bekerja lebih baik dalam konteks yang fokus dan sangat relevan
• Karena CLAUDE.md disertakan di semua sesi, hanya informasi yang berlaku umum yang sebaiknya dipertahankan di dalamnya
• Secara umum, disarankan untuk menjaganya di bawah 300 baris, dan kalau bisa lebih pendek lagi
  • Contoh file dari HumanLayer kurang dari 60 baris

Progressive Disclosure

• Pada proyek besar, sulit memasukkan semua informasi ke satu file, sehingga pendekatan Progressive Disclosure direkomendasikan
  • Instruksi detail dipisahkan ke file Markdown lain di folder agent_docs/
  • Contoh: building_the_project.md, running_tests.md, code_conventions.md, dan sebagainya
• Di CLAUDE.md, cukup cantumkan daftar file-file tersebut dan penjelasan singkatnya, serta instruksi agar Claude membacanya saat diperlukan
• Gunakan referensi file:line alih-alih potongan kode agar tetap mutakhir
• Ini mirip dengan konsep Claude Skills, tetapi fokusnya pada pengelolaan instruksi, bukan penggunaan alat

Claude Bukan Linter

• Memasukkan pedoman style kode ke dalam CLAUDE.md tidak efisien
  • LLM mahal dan lambat, serta lebih tidak deterministik dibanding linter
• Aturan style biasanya dipelajari secara alami dari pola kode yang sudah ada, sehingga tidak perlu instruksi terpisah
• Untuk formatting, gunakan linter yang bisa memperbaiki otomatis (seperti Biome), lalu berikan ke Claude hanya hasil perbaikannya
• Jika perlu, gunakan Stop Hook atau Slash Command untuk mengotomatiskan formatting dan verifikasi

Jangan Dibuat Otomatis

• CLAUDE.md yang dibuat dengan perintah /init atau fitur pembangkitan otomatis tidak direkomendasikan
  • Alasannya, file ini adalah titik leverage tinggi yang memengaruhi semua sesi dan semua output
• Satu baris instruksi yang salah bisa memberi dampak berantai yang buruk pada kualitas kode secara keseluruhan
• Karena itu, setiap kalimat harus ditinjau dengan cermat dan ditulis manual

Kesimpulan

• CLAUDE.md adalah dokumen untuk melakukan onboarding Claude ke codebase, dan harus mendefinisikan WHY, WHAT, HOW dengan jelas
• Instruksi harus diminimalkan, dan hanya isi yang umum serta ringkas yang perlu dimasukkan
• Dengan Progressive Disclosure, informasi yang diperlukan bisa diberikan secara bertahap
• Jangan gunakan Claude sebagai linter; gunakan tool khusus serta fitur hook dan command secara berdampingan
• Alih-alih membuatnya otomatis, penulisan manual yang hati-hati diperlukan untuk memaksimalkan kualitas harness secara keseluruhan