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

[GN⁺]

Komentar Hacker News

• Claude sering cenderung mengabaikan instruksi di CLAUDE.md
  Semakin banyak informasi di file yang tidak terkait dengan tugas tertentu, semakin besar kemungkinan Claude tidak mengikuti instruksi tersebut
  Seorang teman menyuruh Claude memanggilnya “Mr Tinkleberry”, dan setiap kali Claude melupakannya, itu jadi tanda bahwa file tersebut sedang diabaikan

• Saya sudah lama memakai pendekatan Table-of-Contents
  Panduan per tugas dipisahkan ke file markdown masing-masing, lalu di CLAUDE.md hanya dimasukkan daftarnya beserta penjelasan singkat
  Dengan begitu context window tetap rapi
  Contoh file saya bisa dilihat di sini

  • Saya juga pernah mencoba cara yang sama, tetapi hasilnya tidak konsisten
    Claude hampir tidak pernah benar-benar membaca file dokumen lain itu

• Saya merasa kalau memberi Claude terlalu banyak context justru menurunkan kualitas
  Karena itu saya selalu menjaga dua versi kode

  1. Kode asli tanpa komentar dan spasi kosong
  2. Kode yang disertai komentar
     Untuk LLM saya hanya memberikan versi pertama
     Menurut saya kuncinya adalah rasio compute terhadap informasi. Kapasitas komputasi itu terbatas
  • Pengalaman saya juga mirip, tetapi efisiensinya meningkat saat isi yang berulang dimasukkan ke file catatan Claude
    Tidak semua hal perlu dimasukkan, tetapi memasukkan informasi inti memberi ROI yang tinggi
    Claude bekerja baik pada proyek umum, tetapi sering bingung saat menghadapi framework atau tool baru
  • Anda bilang menjaga dua versi kode, jadi saya penasaran bagaimana konsistensinya dikelola
    Saya ingin tahu apakah Anda memakai skrip untuk menghapus komentar dan spasi kosong setelah modifikasi
  • Saya rasa di dalam file dokumentasi, kepadatan informasi perlu dijaga tetap tinggi
  • Anda bilang tidak memberi LLM versi yang berisi komentar, tetapi saya penasaran bagaimana itu diterapkan dalam praktik
  • Pada akhirnya, attention itu terbatas. Jika context dimasukkan berlebihan, fokus akan terpecah

• Sebenarnya ada cara menyelesaikan ini tanpa pengaturan serumit itu
  Yaitu dengan mendokumentasikan(documenting) kode secara jelas
  Jika tiap file menjelaskan secara ringkas apa fungsinya, itu sendiri sudah berperan sebagai prompt
  README.md bisa dimanfaatkan secara aktif
  LLM sudah dilatih dengan informasi publik yang ada, jadi tidak perlu menciptakan sesuatu yang sepenuhnya baru

  • Tetapi saat menulis dokumentasi untuk AI, diperlukan cara yang berbeda dari dokumentasi untuk pembaca manusia
    Saran seperti “dokumentasikan kode dengan baik” saja tidak cocok dalam konteks ini
  • Saya juga merasa komunitas AI kadang menemukan ulang roda secara tidak perlu
    README memang bagus, tetapi CLAUDE.md punya tujuan yang berbeda
    Misalnya, Claude/agents.md punya fungsi untuk otomatis dimasukkan ke context saat mengakses direktori tertentu
    Dalam codebase yang kompleks, pengelolaan context jauh lebih penting
  • CLAUDE.md bukan sekadar dokumen, melainkan berfungsi untuk menyesuaikan prompt awal model
    Jadi nasihat seperti “tulislah prompt yang tepat” justru meleset dari inti persoalan
  • Misalnya, aturan seperti “query database harus selalu menggunakan indeks” sebaiknya ditulis di mana?
    Jika dimasukkan ke README, pada akhirnya README akan berperan seperti CLAUDE.md
    Tujuan CLAUDE.md adalah memberikan informasi inti lebih dulu agar Claude tidak perlu membaca ulang semua dokumen setiap saat
    Manusia bisa mengingat, tetapi Claude lupa di setiap tugas, jadi perlu struktur yang mengurangi re-onboarding

• Sejujurnya, kalau harus sampai menyiapkan infrastruktur AI seperti ini, rasanya lebih baik saya coding sendiri saja

  • Tetapi pengaturan terkait style cukup dibuat sekali lalu bisa dipakai ulang
    Saya mengelola aturan umum dan aturan khusus proyek secara terpisah
  • Setup yang dibahas di artikel itu bisa selesai dalam hitungan beberapa jam
    Tidak memakai AI itu hanyalah kehilangan produktivitas
  • Sebagian besar setup awal bahkan bisa diserahkan ke LLM
  • Sebenarnya upayanya tidak sebesar itu. Masalahnya justru terlalu berlebihan dalam mengoptimalkan tool
  • Yang penting adalah apakah biayanya berulang atau sekali saja
    Jika setup hanya perlu sekali, itu layak untuk diinvestasikan
    “Setup itu merepotkan” mirip alasan orang yang menghindari pengaturan debugger

• Saya biasanya cukup menyalin lalu menempelkan kode yang diperlukan ke jendela percakapan, lalu memakainya seperti sedang mengobrol
  Model sekarang sudah jauh membaik, jadi tanpa file .md pun hasilnya cukup bagus
  File-file seperti ini mungkin bisa memberi sedikit peningkatan, tetapi menurut saya bukan sihir produktivitas 100x

  • Tetapi ini adalah use case yang berbeda
    Yang sedang dibahas di sini adalah saat Claude menjalankan sendiri implementasi fitur penuh atau perbaikan bug
  • Pengalaman saya juga mirip. Saya pernah membuat CLAUDE.md sekali, tetapi sekarang tidak lagi memakainya
    Cukup beri context yang diperlukan dan hasilnya sudah bekerja dengan baik. Rasanya agak seperti bikeshedding
  • Meski begitu, kalau daftar tabel atau kolom database dirangkum lebih dulu, itu bisa mengurangi pengulangan

• Saya membiarkan Claude menulis CLAUDE.md sendiri
  Jika diberi tahu “README.md untuk pengguna, CLAUDE.md untukmu”,
  instruksi seperti “selalu periksa dokumentasi API” juga akan diperbarui secara otomatis
  Tidak perlu tahu prompt ajaib, yang penting hasilnya bagus

  • Tetapi saya ragu apakah ada bukti bahwa instruksi yang ditulis AI sendiri lebih baik daripada yang ditulis manusia
    Tidak terlihat ada alasan bahwa AI pasti paling pandai mem-prompt dirinya sendiri