Cara Menulis File CLAUDE.md yang Efektif untuk Claude Code

Kamu menjalankan /init, Claude membuatkan CLAUDE.md, dan beberapa hari kemudian file itu sudah seratus baris lebih karena setiap kali Claude salah kamu menambah satu kalimat. Lalu Claude tetap memakai npm padahal proyekmu pakai pnpm, atau tetap mengubah file yang sudah kamu larang. Kamu menambah kata SANGAT PENTING di sana-sini, dan hasilnya malah makin tidak terarah. Hampir semua orang yang pertama kali menulis CLAUDE.md berhenti di titik ini.

Panduan ini membawamu dari file kosong ke CLAUDE.md yang pendek, konkret, dan bisa diuji, dalam enam langkah. Setiap perintah dan aturan saya cocokkan dengan dokumentasi resmi Claude Code, dan contoh nyatanya diambil dari CLAUDE.md situs ini sendiri. Saya sengaja tidak mengutip bagian yang berisi identitas pribadi.

Yang kamu butuhkan

Tidak banyak, dan semuanya bisa dicoba di repositori latihan.

• Claude Code terpasang dan bisa dijalankan dengan perintah claude.
• Satu repositori git untuk bereksperimen. Lebih baik repo latihan, bukan repo kerja.
• Sekitar 20 menit dan editor teks apa saja.

Semua perintah slash di bawah (/init, /context, /memory, /doctor) diketik di dalam sesi claude, bukan di terminal biasa.

Langkah 1: Buat draf pertama dengan /init

Masuk ke folder proyekmu, jalankan claude, lalu ketik /init. Claude membaca codebase dan membuat CLAUDE.md berisi perintah build, instruksi test, dan konvensi yang ia temukan. Kalau CLAUDE.md sudah ada, /init mengusulkan perbaikan dan tidak menimpanya. Anggap hasilnya draf, bukan hasil akhir.

cd belajar-claude-md      # your practice repo
claude                     # start a session

# Inside the session:
/init
# Claude analyses the codebase and writes ./CLAUDE.md.
# If ./CLAUDE.md already exists, it suggests improvements instead.

File project boleh berada di ./CLAUDE.md atau ./.claude/CLAUDE.md dan sebaiknya di-commit supaya seluruh tim memakainya. Kalau repomu sudah punya AGENTS.md untuk tool lain, baca dulu perbandingannya di AGENTS.md vs CLAUDE.md. Untuk catatan pribadi yang tidak boleh ikut ke git, pakai CLAUDE.local.md di root proyek dan masukkan ke .gitignore.

Langkah 2: Pangkas sampai tinggal yang Claude tidak bisa tebak

Ini langkah yang paling sering dilewati. Dokumentasi menyarankan satu pertanyaan untuk setiap baris: kalau baris ini dihapus, apakah Claude akan membuat kesalahan? Kalau tidak, hapus. Tabel di bawah merangkum apa yang layak masuk dan apa yang tidak.

# Wrong: sounds fine, but none of it can be checked.
This is an important project. Write clean code, follow best practices
and make sure to test your changes properly. Keep files organized.

# Right: each line names a command, a folder or a number.
- Use 2-space indentation
- Run npm test before committing
- API handlers live in src/api/handlers/

Perhatikan perbedaannya di contoh di atas. Versi salah terdengar masuk akal tetapi tidak bisa dicek: kapan sebuah kode disebut bersih? Versi benar menyebut perintah, folder, dan angka yang bisa kamu verifikasi. Dokumentasi memberi pola yang sama: use 2-space indentation lebih baik daripada format code properly.

Langkah 3: Tulis perintah, konvensi, dan aturan keras

Struktur yang saya pakai terdiri dari empat blok pendek dengan header: Commands, Conventions, Hard rules, dan Gotchas. Dokumentasi menyatakan tidak ada format wajib, tetapi file yang terorganisasi dengan header dan bullet lebih mudah diikuti Claude daripada paragraf padat. Berikut contoh untuk proyek fiktif bernama toko-api.

# toko-api

Backend API for a small online shop (Node.js, Express, PostgreSQL).

## Commands
npm run dev         # API server on http://localhost:3000
npm test            # unit tests; the API tests need a local Redis
npm run lint        # ESLint, fix every error before committing
npx tsc --noEmit    # typecheck without building

## Conventions
- Use 2-space indentation
- API handlers live in src/api/handlers/
- Money is stored as integer cents, never as floats

## Hard rules
1. Never edit a migration that is already merged. Add a new one: staging replays them in order.
2. Throw errors through src/api/errors.ts, not raw strings: the client parses its format.

## Gotchas
- npm run build regenerates src/generated/schema.ts. Run npm run schema:build after editing schema.sql.

<!-- maintainers: rule 1 exists because of the staging replay, keep it -->

Setiap aturan keras menyebut apa yang rusak kalau dilanggar. Itulah yang membuat aturan bisa dicek. Beginilah bentuknya di CLAUDE.md situs ini sendiri, bagian Hard rules:

## Hard rules — build breaks if violated

1. **`messages/en.json` and `messages/id.json` must have the exact same key tree.** Missing key in either file → runtime error.
2. **No `{`, `}`, or `<` in blog `content.*` JSON values.** The merge script rejects them. Put markup in JSX; put ICU interpolation only in non-blog UI strings.
3. **Every slug in `BLOG_POSTS_STATIC` must have an entry in `BLOG_META` (and vice versa).** `assertBlogParity()` fails the build otherwise.
4. **Every component key read in a blog component must exist in the translation fragment.** The merge script validates this.
5. **Always import `Link`, `useRouter`, `usePathname` from `@/i18n/navigation`, not from `next/link` or `next/navigation`.** Bare Next.js navigation loses the locale prefix.

Lima aturan, satu baris masing-masing. Aturan 2 sampai 4 juga menyebut pengamannya, yaitu merge script atau assertBlogParity() yang menggagalkan build, jadi aturan tetap berlaku walaupun suatu hari Claude salah membacanya. Satu hal lagi di file ini adalah jebakan yang ditulis sekali: bahwa npm run build gagal kalau lib/blog-sources.json basi, lengkap dengan perintah perbaikannya, supaya Claude tidak perlu menebak penyebabnya.

Langkah 4: Jaga di bawah 200 baris, pindahkan sisanya

Dokumentasi menargetkan di bawah 200 baris per file CLAUDE.md. File yang lebih panjang memakan lebih banyak konteks dan menurunkan kepatuhan. Jujur saja, CLAUDE.md situs ini sendiri lebih dari 500 baris, dan sebagian besarnya adalah prosedur blog yang lebih tepat dipindah ke skill. Itu utang yang saya tahu, dan contoh yang buruk untuk ditiru.

Kamu punya tiga tempat pindah. Aturan yang hanya relevan untuk satu folder masuk ke file seperti .claude/rules/api.md dengan frontmatter paths, dan baru dimuat saat Claude menyentuh file yang cocok. Prosedur bertahap masuk ke skill, yang dimuat saat dipanggil atau saat Claude menilainya relevan. Catatan untuk manusia masuk ke komentar HTML, yang dibuang sebelum file sampai ke Claude.

---
paths:
  - "src/api/**/*.ts"
---

- All API endpoints must include input validation
- Use the shared error format in src/api/errors.ts

# Wrong: five @imports still load at launch, so the context cost is unchanged.
@docs/api.md
@docs/git.md
@docs/testing.md

# Right: keep the always-needed facts in CLAUDE.md,
# and move the one-folder rules into .claude/rules/ with paths.

Jangan memecah file panjang menjadi beberapa @import untuk berhemat. File yang diimpor dimuat di awal sesi sama seperti teks biasa, jadi biayanya tetap sama. Kalau repomu monorepo dengan banyak folder, lihat juga workflow Claude Code untuk monorepo.

Langkah 5: Pasangkan aturan wajib dengan pengaman

CLAUDE.md sampai ke Claude sebagai user message setelah system prompt. Claude membacanya dan berusaha menurut, tetapi dokumentasi tegas bahwa tidak ada jaminan kepatuhan penuh. Untuk memblokir sebuah aksi apa pun keputusan Claude, pakai hook PreToolUse. Hook dijalankan deterministik, sedangkan instruksi CLAUDE.md bersifat saran.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/protect-files.sh  (run: chmod +x on it)
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

case "$FILE_PATH" in
  *.env*)
    # stderr becomes Claude's feedback; exit 2 blocks the edit
    echo "Blocked: $FILE_PATH is protected" >&2
    exit 2
    ;;
esac

exit 0  # no objection; the normal permission flow still applies

Di situs ini polanya sama: setiap aturan keras punya pengaman yang gagal dengan sendirinya, misalnya build yang gagal atau test yang merah. Sebuah baris di CLAUDE.md menjelaskan alasannya kepada Claude, dan pengamannya yang menjaga hasil akhirnya. Hook dipasang di .claude/settings.json dan skripnya harus executable.

Langkah 6: Uji bahwa Claude benar-benar membacanya

Mulai sesi baru, jalankan /context, dan lihat daftar di bawah Memory files. Kalau file tidak ada di sana, Claude tidak bisa melihat satu kata pun darinya. Perintah /memory juga menampilkan lokasi file CLAUDE.md dan CLAUDE.local.md dan membukanya untuk diedit.

/context
# Read the list under "Memory files".
# Your ./CLAUDE.md must be there. A CLAUDE.md in a subfolder is NOT:
# it loads on demand, and a "Loaded" line appears when Claude first
# reads, writes or edits a file in that folder.

/memory          # lists your CLAUDE.md files and opens them for editing
/doctor prompt-audit   # stale or conflicting instructions (v2.1.283+)

Lalu uji perilakunya: minta Claude melakukan sesuatu yang diatur oleh salah satu aturanmu dan lihat apakah ia menurut. Dokumentasi menyarankan memperlakukan CLAUDE.md seperti kode, yaitu meninjaunya saat ada masalah, memangkasnya secara berkala, dan menguji perubahan dengan mengamati apakah perilaku Claude benar-benar bergeser. Untuk mencari instruksi yang usang atau bertentangan, jalankan /doctor prompt-audit, yang butuh Claude Code v2.1.283 atau lebih baru.

Error umum dan cara memperbaikinya

Enam masalah yang paling sering muncul setelah file ditulis, dengan penyebab dan perbaikannya.

Kalau satu masalah terus berulang, jangan menambah baris baru di CLAUDE.md. Tanyakan dulu apakah aturannya perlu pengaman, perlu dipindah ke rule atau skill, atau perlu dipangkas.

Checklist sebelum di-commit

• File kurang dari 200 baris dan tidak ada baris yang bisa Claude simpulkan dari kode.
• Ada blok perintah, konvensi, aturan keras, dan jebakan, masing-masing dengan header.
• Setiap aturan konkret dan bisa dicek, tidak ada nasihat kosong.
• Tidak ada dua instruksi yang bertentangan, termasuk dengan file user dan file subfolder.
• Setiap aturan yang wajib berlaku punya hook, permission, atau test sebagai pengaman.
• /context menampilkan filenya di bawah Memory files, dan catatan pribadi ada di CLAUDE.local.md.

Belajar lebih dalam

Untuk memahami lapisan managed, user, project, dan local serta urutan memuatnya, ikuti pelajaran gratis CLAUDE.md adalah: contoh file, lapisan, dan urutan memuatnya. Untuk melihat bagaimana konteks dikelola di repositori besar, baca context engineering untuk AI agent di monorepo.

Aturannya sederhana: tulis hanya yang tidak bisa Claude tebak, buat setiap baris bisa dicek, dan jangan percayakan aturan wajib pada CLAUDE.md saja. File yang pendek dan konkret dibaca dan diikuti lebih konsisten daripada file panjang yang lengkap.