CLAUDE.md yang Benar — Konstitusi Proyek Anda

Jika Anda hanya menerapkan satu bab, terapkan yang ini. CLAUDE.md adalah prompt dengan pengaruh terbesar yang pernah Anda tulis, karena Claude Code memuatnya ke setiap sesi secara otomatis — sebelum Anda mengetik apa pun. CLAUDE.md yang baik membuat setiap prompt berikutnya jadi lebih pintar secara cuma-cuma. Yang tidak ada membuat Claude menebak, dan menebak adalah asal mula salah package manager, salah framework test, serta momen "kenapa dia menulis ulang seluruh berkas saya".

Inti Utama

CLAUDE.md adalah prompt yang berjalan di setiap giliran. Perlakukan seperti kode produksi, bukan catatan sembarangan.

Karena ia memakan token context di setiap pesan, tujuannya adalah sinyal maksimum per baris: segelintir hal yang tidak bisa disimpulkan Claude dari kode tetapi harus selalu diketahui.

Apa sebenarnya ini

Saat sebuah sesi dimulai, Claude Code otomatis menarik CLAUDE.md ke dalam context. Anda tidak perlu lagi berkata "ingat pakai pnpm" — Anda menulisnya sekali, dan itu berlaku untuk setiap prompt setelahnya. Itulah keajaibannya: tulis sekali, berlaku selalu.

Hierarki memori (di mana CLAUDE.md tinggal)

Claude Code membaca beberapa berkas CLAUDE.md dan menggabungkannya berlapis:

Berkas di direktori induk juga berlaku, jadi sebuah monorepo bisa punya satu konstitusi di root plus CLAUDE.md kecil yang fokus di tiap paket. Berkas yang lebih dekat menang untuk hal yang spesifik.

Apa yang dimasukkan (dan apa yang ditinggalkan)

CLAUDE.md terbaik menjawab: "Apa yang perlu ditempel di monitor seorang engineer baru yang tajam pada hari pertama?"

✅ Masukkan:

• Perintah — build, dev, test, lint, typecheck, test satu berkas. Yang persis.
• Stack & versi — "pnpm (bukan npm/yarn)", "Vitest (bukan Jest)", "React 19".
• Konvensi — struktur berkas, penamaan, pola yang selalu Anda ikuti.
• Peta arsitektur — orientasi 5 baris, atau tautan/import ke dokumen lebih panjang.
• Aturan "jangan pernah X" — batasan keras (lihat bagian khusus di bawah).
• Keanehan environment — "server dev butuh Docker jalan dulu", jebakan-jebakan.

❌ Tinggalkan:

• Apa pun yang bisa dibaca Claude langsung dari kode (ia akan membaca berkasnya sendiri).
• Timbunan besar — menempel spesifikasi API lengkap membengkakkan context setiap giliran.
• Kredensial — jangan pernah. (Lihat Bab 2.6, Menangani Kredensial dengan Aman.)
• Detail basi yang akan usang. Kalau berubah tiap minggu, jangan dipatok di sini.

Aturan praktis: kalau Claude bisa menemukannya dengan membaca satu berkas yang jelas, jangan diulang. Kalau ia harus menebak, tuliskan.

Sebelum / Sesudah: demonstrasinya

Prompt yang sama — "tambahkan test untuk total checkout" — di dua repo.

Tanpa CLAUDE.md — Claude menebak toolchain Anda:

> add a test for the checkout total

Created checkout.test.js using Jest:
  import { describe, it, expect } from '@jest/globals'
  ...
$ npm test
✖  Cannot find module '@jest/globals' — this project uses Vitest, not Jest.
   Also: the project uses pnpm, not npm.

Salah framework, salah runner, salah package manager. Anda menghabiskan lima menit berikutnya untuk membetulkannya — setiap kali.

Dengan CLAUDE.md yang baik berisi:

## Commands
- Test: `pnpm test` (Vitest). Single file: `pnpm test <path>`
## Conventions
- Tests live next to source as `*.test.ts`, use `vitest` imports.

> add a test for the checkout total

Created src/checkout/total.test.ts:
  import { describe, it, expect } from 'vitest'
  ...
$ pnpm test src/checkout/total.test.ts
✓  total › applies tax and discount (3 ms)

Benar sejak percobaan pertama. Lima menit yang terhemat itu, dikalikan setiap sesi, adalah alasan bab ini menempati posisi #1.

Bagian "Jangan pernah X" itu emas

Baris paling berharga di CLAUDE.md mana pun adalah batasan keras — hal yang, ketika dilakukan Claude, membuang waktu atau menimbulkan kerusakan nyata:

## IMPORTANT — Never do these
- NEVER commit directly to `main`. Always branch.
- NEVER run `prisma migrate reset` (it wipes the dev DB).
- NEVER add a dependency without asking — we keep the bundle small.
- ALWAYS run `pnpm typecheck` before saying a task is done.

Trik — penekanan berpengaruh. Kata seperti IMPORTANT, NEVER, dan YOU MUST terbukti meningkatkan kepatuhan. Simpan untuk aturan yang benar-benar penting, agar bobotnya tetap terjaga. (Pertahankan dalam bahasa Inggris seperti di atas — Claude sangat responsif terhadap penanda ini.)

Membuat awal dan merawatnya

Anda tidak menulis CLAUDE.md dari halaman kosong, dan tidak menulisnya sekali saja.

1. Buat draf awal — jalankan /init. Claude menganalisis codebase dan membuat draf CLAUDE.md awal. Lalu pangkas habis-habisan; draf otomatis itu titik awal, bukan akhir.
2. Tumbuhkan dari gesekan — setiap kali Claude salah dengan cara yang sama dua kali, itu tanda ada baris yang hilang. Tambahkan aturannya; Anda baru saja memperbaikinya secara permanen.
3. Tambah memori secara langsung — awali baris prompt dengan # untuk cepat menyimpan catatan ke CLAUDE.md tanpa keluar dari alur kerja. Pakai /memory untuk membuka dan menyunting berkasnya.
4. Pangkas tanpa ampun — CLAUDE.md yang bengkak adalah prompt yang lebih buruk. Kalau satu baris tak lagi sepadan dengan biaya token-nya, hapus.

Pola pikir: CLAUDE.md adalah prompt hidup yang Anda setel, persis seperti menyetel prompt lain — iterasikan menuju versi yang membuat Claude benar sejak awal.

Buat modular dengan import

Untuk hal yang panjang, jangan ditaruh inline — import agar berkas utama tetap ramping:

See @docs/architecture.md for the full system map.
Coding standards: @docs/conventions.md

Claude menarik berkas yang di-import saat relevan. Ini menjaga CLAUDE.md root tetap pendek dan mudah dipindai sambil tetap memberi Claude kedalaman saat dibutuhkan. (Jaga import tetap dangkal — beberapa lompatan, bukan labirin.)

Aturan ber-scope path: .claude/rules/

Untuk proyek besar, panduan resmi kini menyarankan memecah aturan permanen ke berkas-berkas .claude/rules/*.md. Setiap berkas bisa membawa YAML frontmatter seperti:

paths: ["src/api/**/*.ts"]

sehingga aturan itu hanya dimuat saat Claude bekerja pada berkas yang cocok. Hasilnya: CLAUDE.md root tetap mungil, sementara aturan tetap terskalakan di seluruh monorepo.

Peringatan

Lebih banyak bukan berarti lebih baik. CLAUDE.md sepanjang 400 baris yang mengulang apa yang sudah ada di kode membuat setiap prompt lebih lambat dan mengencerkan aturan yang penting. CLAUDE.md terbaik itu pendek, tajam, dan sebagian besar berisi "jangan pernah X" + "ini perintah-perintahnya". Sinyal, bukan volume. Praktik terbaik resmi menyarankan menjaga setiap CLAUDE.md maksimal beberapa ratus baris — untuk setiap baris, tanyakan: "kalau baris ini dihapus, apakah Claude akan salah?"

Bisa diunduh: CLAUDE.md Template Pack

Siap dijatuhkan ke proyek mana pun, di ../../artifacts/claude-md-template-pack/:

Catatan: berkas artefak bersifat netral bahasa (kode/konfigurasi), sehingga dipakai bersama dari edisi bahasa Inggris. Komentar di dalamnya dibiarkan dalam bahasa Inggris karena itu memang bagian dari template kode.

Pasang dalam satu baris:

cp CLAUDE.md.template /path/to/your/project/CLAUDE.md

Lalu hapus bagian yang tidak Anda butuhkan, isi perintah-perintah Anda, dan tambahkan tiga aturan "jangan pernah X" pertama Anda. Itulah CLAUDE.md profesional dalam lima menit.