CLAUDE.md adalah file markdown biasa di root proyek Anda. Claude membacanya secara otomatis setiap sesi. Tingkat proyek: ./CLAUDE.md. Global (semua proyek): ~/.claude/CLAUDE.md. Proyek menimpa global: file global menyimpan default Anda, file proyek menyimpan spesifik repo ini.
Anggap saja sebagai dokumen orientasi yang Anda berikan kepada kontraktor yang sangat terampil yang tidak tahu apa-apa tentang proyek Anda. Tanpa itu, setiap sesi dimulai dengan Claude menebak stack Anda, konvensi penamaan Anda, dan keputusan masa lalu Anda. Tebakan menjadi kode, kode menjadi bug. CLAUDE.md mempersingkat rantai itu. Sebuah file mengalahkan prompt yang cerdas karena berfungsi apakah Anda ingat atau tidak.
Lima bagian yang sangat berguna. Tiga hingga enam baris poin setiap bagian:
1. Stack: framework, DB, auth, email, dengan versi. "Next.js 16, Postgres di Neon, Resend untuk email, Stripe untuk pembayaran, Supabase untuk auth."
2. Rute: di mana segala sesuatu berada. "Aplikasi di /app, tindakan server di /actions, API di bawah /app/api/v2, komponen bersama di /components/ui."
3. Konvensi: aturan yang jelas bagi Anda, tidak terlihat oleh Claude. "Uang dalam sen (int), tanggal UTC, nama file kebab-case, ID sebagai UUID v4."
4. Aturan Keamanan: hal-hal yang tidak boleh terjadi. "Jangan pernah mencatat kunci API. Parameterisasi semua SQL. Batasi laju semua endpoint publik."
5. Jangan Lakukan Ini: jebakan yang sudah Anda alami. "Jangan menambahkan dependensi tanpa bertanya. Jangan menjalankan migrasi dari lokal ke produksi."
Sebuah template yang sudah jadi. Ganti dengan detail proyek Anda yang sebenarnya:
# Plinko Grant Tracker
## Stack
- Next.js 16, Postgres (Neon), Resend, Stripe
- Auth: Supabase Auth dengan Google OAuth
## Routes
- App di /app, actions di /actions, API di bawah /app/api/v2
## Conventions
- Uang dalam sen (int), tanggal UTC, nama file kebab-case
- ID: UUID v4. Kolom Boolean: awalan is_ atau has_
## Security Rules
- Jangan pernah mencatat rahasia, parameterisasi SQL
- Batasi laju semua endpoint POST/PUT/DELETE (10/menit per IP)
- Tabel Supabase baru dikirimkan dengan kebijakan RLS dalam commit yang sama
## Don't Do This
- Jangan menambahkan dependensi tanpa bertanya
- Jangan menjalankan migrasi dari lokal ke produksi
- Jangan gunakan select(*)Perhatikan kekhususannya. "10/menit per IP" dapat ditindaklanjuti. "Gunakan pembatasan laju" tidak.
Kesalahan paling mahal: aturan samar yang terdengar spesifik.
Lemah: "Tangani uang dengan hati-hati." Claude akan menangani uang dengan cara yang menurutnya terbaik, yang mungkin tidak sesuai dengan sistem Anda.
Kuat: "Semua jumlah moneter adalah sen integer. Jangan pernah float. Jangan pernah menampilkan sen mentah; bagi dengan 100 dan format dengan simbol mata uang." Tipe penyimpanan, aturan pemrosesan, aturan tampilan. Tidak ada ambiguitas.
Kesalahan kedua: menulis aspirasi alih-alih batasan. "Kami menghargai kode yang bersih dan mudah dibaca" adalah aspirasi. "File di atas 200 baris dibagi menjadi modul" adalah batasan. Aspirasi membutuhkan penilaian; batasan menghasilkan perilaku yang konsisten. Isi CLAUDE.md Anda dengan batasan.
CLAUDE.md adalah dokumen hidup. Tiga sinyal bahwa ia perlu diperbarui:
Anda menempelkan konteks yang sama ke dalam prompt untuk kedua kalinya. Jika Anda mengatakannya lagi, itu milik CLAUDE.md.
Claude membuat kesalahan yang seharusnya dicegah oleh aturan. Kesalahan adalah aturannya. Tulis sebelum sesi berikutnya.
Anda menjelaskan konvensi kepada seorang kolega. Jika layak diucapkan, layak dimuat secara otomatis.
Disiplin panjang: tiga hingga enam poin per bagian; lebih dari delapan, pisahkan bagiannya. CLAUDE.md yang terlalu panjang untuk dibaca sekilas berhenti berfungsi karena aturan penting terkubur. Enam baris yang tepat mengalahkan enam puluh baris pengisi.
Skala lebih dari sekitar 300 baris: bagi menjadi file topik dengan penyertaan @filename:
# CLAUDE.md (root)
@rules/stack.md
@rules/security.md
@rules/db-migrations.mdSetiap file topik tetap fokus; root tetap pendek.
Commit CLAUDE.md ke kontrol versi. Aturan menjadi dapat ditinjau dalam PR, dan rekan tim baru mengkloning repo dengan Claude sudah dikonfigurasi. Tambahkan setiap aturan Jangan Lakukan Ini dalam commit yang sama dengan perbaikan bug yang mengajarkannya. Satu peringatan: generalisasi jalur khusus mesin sebelum melakukan commit.
Apa yang termasuk dalam CLAUDE.md vs prompt? Radius ledakan. Jika sebuah aturan mencegah kelas kesalahan yang membutuhkan waktu satu jam atau lebih untuk diperbaiki, itu masuk ke CLAUDE.md. Instruksi khusus sesi tetap ada di prompt.
Buat CLAUDE.md pertama Anda dalam sepuluh menit. Berikan prompt ini kepada Claude:
"Saya sedang menyiapkan Claude Code untuk sebuah proyek dengan stack ini: [stack]. Konvensi kunci yang tidak akan diketahui oleh orang baru: [konvensi]. Aturan keamanan yang tidak boleh dilanggar: [aturan]. Hal-hal yang menyebabkan bug sebelumnya: [jebakan]. Buat draf CLAUDE.md dengan lima bagian: Stack, Rute, Konvensi, Aturan Keamanan, Jangan Lakukan Ini."
Draf pertama memberi Anda 80 persen. Sempurnakan dengan apa yang dilewatkan Claude; 20 persen sisanya adalah apa yang spesifik untuk pengalaman Anda yang sebenarnya dengan proyek tersebut.
CLAUDE.md di root proyek memuat stack, rute, konvensi, aturan keamanan, dan jebakan Anda ke setiap sesi. File global untuk default lintas proyek, file proyek untuk penimpaan. Batasan, bukan aspirasi. Enam baris yang tepat mengalahkan enam puluh. Perbarui setiap kali Claude membuat kesalahan yang seharusnya dicegah oleh aturan tertulis.