Cara Menulis CLAUDE.md: Template Praktis untuk Claude Code

Pull request Anda menerima komentar yang sama untuk ketiga kalinya. Claude Code sudah mengubah fitur yang benar, tetapi lupa menjalankan perintah test milik repository, ikut menyunting migration di luar lingkup, atau melewatkan pemeriksaan tampilan mobile. Mengulang prompt yang lebih panjang pada setiap sesi tidak menyelesaikan masalah operasional ini.

CLAUDE.md yang baik memberi Claude Code sekumpulan keputusan tetap sebelum pekerjaan dimulai. File ini tidak perlu menjelaskan seluruh perusahaan atau menyalin README. Panduan ini menunjukkan informasi yang perlu dimasukkan, batasan yang harus diterapkan di tempat lain, dan cara menguji hasilnya dengan pemeriksa Node.js yang benar-benar dapat dijalankan.

Jawaban singkat

Isi CLAUDE.md dengan perintah, batas perubahan, dan syarat review yang berlaku pada sebagian besar tugas di dalam cakupannya. Pegang lima aturan berikut:

• CLAUDE.md adalah panduan berkelanjutan untuk Claude Code, bukan sistem kontrol akses.
• Letakkan aturan bersama di root repository, catatan pribadi di CLAUDE.local.md, dan aturan khusus path di .claude/rules/.
• Jaga panjangnya kurang lebih di bawah 200 baris. Utamakan path file, perintah, dan syarat lulus daripada uraian latar belakang.
• Terapkan pembatasan keamanan melalui permissions dan hooks, bukan hanya peringatan tertulis.
• Uji instruksi baru pada satu tugas nyata yang kecil sebelum menjadikannya aturan tim.

Tidak perlu merancang file sempurna pada hari pertama. Catat komentar yang muncul dalam tiga review terakhir, lalu pertahankan hanya keputusan yang akan berguna lagi.

Pekerjaan untuk Claude Code dan keputusan untuk manusia

Panduan repository dan batas permission menyelesaikan masalah yang berbeda. Claude Code dapat menelusuri kode lama, membuat perubahan dalam lingkup yang disebutkan, menjalankan pemeriksaan, dan merangkum diff. Manusia tetap memegang keputusan mengenai kebijakan produk, persetujuan production, serta hal yang berkaitan dengan pelanggan, uang, privasi, atau kewajiban hukum.

Keputusan	Serahkan kepada Claude Code	Tetap diputuskan manusia
Penelusuran	Mencari file terkait, pola lama, dan test	Menentukan apakah data pelanggan atau kontrak boleh diperiksa
Implementasi	Mengubah kode dan test dalam lingkup yang disebut	Menyetujui perubahan harga, otorisasi, hukum, atau kebijakan pelanggan
Verifikasi	Menjalankan lint, type check, test, dan build	Menentukan apakah acceptance criteria terpenuhi dan rilis disetujui
Pemeliharaan	Melaporkan file yang berubah dan risiko tersisa	Menambah atau menghapus aturan permanen repository

CLAUDE.md pada dasarnya berkata, “periksa hal-hal ini dalam urutan berikut.” File ini tidak menjamin perintah destruktif tidak akan pernah berjalan. Gunakan permission deny rules atau hook PreToolUse untuk benar-benar memblokir git push --force, akses database production, atau file yang mengandung rahasia. Lapisan penegakan ini dibahas terpisah dalam panduan permission Claude Code.

Tentukan cakupan sebelum mulai menulis

Lokasi file menentukan jangkauan panduannya. CLAUDE.md di root cocok untuk aturan project bersama. ~/.claude/CLAUDE.md berlaku pada seluruh project milik user. CLAUDE.local.md cocok untuk catatan pribadi khusus mesin dan perlu dimasukkan ke gitignore. Pada repository besar, file bertingkat dan aturan berbasis path mencegah instruksi yang tidak relevan ikut dimuat.

repo/
  CLAUDE.md                  # aturan singkat bersama untuk tim
  CLAUDE.local.md            # catatan pribadi; masukkan ke .gitignore
  .claude/
    rules/
      api.md                 # aturan yang hanya diperlukan file API
  packages/
    admin/
      CLAUDE.md              # ditambahkan saat Claude membaca subtree ini

Saat diluncurkan, Claude Code membaca file yang berlaku di direktori saat ini dan direktori induknya. CLAUDE.md bertingkat dimuat ketika Claude membaca file dalam subtree tersebut. Karena itu, letakkan aturan package di dekat package, bukan menumpuk semua instruksi di root.

Import seperti @docs/project-map.md dapat merapikan organisasi, tetapi tidak menghemat context. Isi yang diimport tetap dimuat saat startup. Simpan keputusan yang selalu diperlukan di CLAUDE.md, lalu tunjukkan path untuk detail yang cukup dibaca saat tugas memerlukannya. Di Windows, Claude Code membaca CLAUDE.md, bukan AGENTS.md; import @AGENTS.md secara eksplisit lebih andal daripada mengandalkan symlink.

Mulai dengan template CLAUDE.md ini

Perintah dan aturan perubahan sebaiknya muat dalam satu layar. Template berikut menghindari nasihat kabur seperti “tulis kode yang bersih”. Ia menyebut path, pemeriksaan, pengecualian, dan laporan akhir yang diharapkan dari agent.

# Project Instructions

## Project map
- App: Next.js 15 + TypeScript
- API: src/app/api/**
- Database schema: prisma/schema.prisma
- Tests: Vitest for units, Playwright for checkout

## Commands
- Install: npm ci
- Type check: npm run typecheck
- Unit tests: npm test
- Lint: npm run lint
- Build: npm run build

## Change rules
- Follow nearby code before adding a new abstraction.
- Do not change auth, billing, or migrations unless the task names them.
- When an API handler changes, update validation and tests together.
- Never place secrets in code, fixtures, logs, or screenshots.

## Review checklist
- Run the checks related to the changed files.
- Test an error path as well as the happy path.
- Report changed files, commands run, and skipped checks.

Tim boleh menulis penjelasan lain dalam bahasa Indonesia. Yang penting, setiap aturan dapat diperiksa. Ganti “uji dengan benar” menjadi npm test. Ganti “ikuti desain lama” menjadi “gunakan src/lib/api-response.ts untuk response API”. Instruksi yang memiliki kondisi lulus membuat dua orang berbeda mengambil keputusan yang sama.

Tiga Use case yang jelas

Tiga contoh berikut mencakup review di agensi, perubahan formulir SaaS, dan penerbitan situs konten. Setiap contoh memisahkan input, output, serta pemeriksaan manusia. Uji dulu pada pekerjaan kecil sebelum sebuah aturan ditambahkan secara permanen ke CLAUDE.md.

Use case 1: Mengurangi revisi berulang di agensi web

Dalam agensi, aturan nama CSS, ukuran gambar, dan dukungan browser dapat berbeda untuk setiap klien. Jangan masukkan style guide panjang yang berlaku umum. Pertahankan hanya 3 sampai 5 keputusan yang berulang pada repository tersebut.

Input: Komentar dari tiga review terakhir, file target, serta perintah lint dan build yang sudah ada.

Output: Laporan ringkas berisi komponen lama yang digunakan, halaman yang berubah, pemeriksaan yang dijalankan, dan kondisi browser yang belum diperiksa.

Pemeriksaan manusia: Maksud desain, hak penggunaan foto, teks CTA, dan tampilan akhir di ponsel. Bandingkan jumlah revisi dalam 10 pekerjaan sebelum dan sesudah aturan diterapkan untuk menilai manfaatnya.

Use case 2: Mengubah formulir kontak SaaS dengan aman

Perbaikan visual pada formulir sering melewatkan validasi, email notifikasi, atau jalur error. Tuliskan file yang harus diperiksa bersama ketika formulir berubah: schema input, API handler, template notifikasi, dan test.

Input: Komponen formulir, schema input, API handler, template notifikasi, dan test yang tersedia.

Output: Test untuk submission valid dan input tidak valid, pesan error, serta daftar setting yang berubah. Laporan juga harus memastikan data pribadi tidak masuk ke log.

Pemeriksaan manusia: Kelayakan data pribadi yang dikumpulkan, masa penyimpanan, penerima email, dan keputusan rilis production. Ukur bukan hanya conversion rate, tetapi juga jumlah submission gagal dan waktu penanganan.

Use case 3: Mencegah bagian artikel terlewat saat terbit

Isi artikel dapat benar sementara description, internal link, gambar, atau layout mobile terlupakan. Kekurangan tersebut memengaruhi traffic pencarian dan pendapatan iklan. Simpan syarat publikasi sebagai checklist pendek yang digunakan bersama.

Input: File MDX, schema frontmatter, daftar internal link, perintah build, dan URL target.

Output: Panjang description, broken link, code block, hasil build, dan daftar URL yang diperiksa.

Pemeriksaan manusia: Akurasi isi, search intent, keterbacaan di antara iklan, dan keputusan publikasi. Selain PV, bandingkan search click, engaged reading, dan CTA click setiap minggu.

Periksa CLAUDE.md dengan kode yang dapat dijalankan

Skrip Node.js berikut memeriksa panjang file, heading wajib, dan beberapa pola rahasia yang umum. Simpan sebagai check-claude-md.mjs, kemudian jalankan dengan Node.js 20 atau versi yang lebih baru.

import { readFile } from "node:fs/promises";

const filePath = process.argv[2] ?? "CLAUDE.md";
const text = await readFile(filePath, "utf8");
const lines = text.split(/\r?\n/);
const lineCount = text.endsWith("\n") ? lines.length - 1 : lines.length;

// Pass localized H2 names as the third argument, separated by "|".
const requiredHeadings = (
  process.argv[3] ?? "Commands|Change rules|Review checklist"
)
  .split("|")
  .map((heading) => heading.trim())
  .filter(Boolean);
const h2Headings = new Set();
let fenceMarker = null;

for (const line of lines) {
  const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
  if (fenceMatch) {
    const marker = fenceMatch[1];
    if (fenceMarker === null) fenceMarker = marker;
    else if (marker[0] === fenceMarker[0] && marker.length >= fenceMarker.length) fenceMarker = null;
    continue;
  }
  if (fenceMarker !== null) continue;

  const heading = line.match(/^##\s+(.+?)\s*$/)?.[1];
  if (heading) h2Headings.add(heading);
}

const secretPatterns = [
  ["AWS access key", /AKIA[0-9A-Z]{16}/],
  ["GitHub token", /gh[pousr]_[A-Za-z0-9]{20,}/],
  ["assigned secret", /\b(api[_-]?key|password|token)\s*[:=]\s*["'][^"'\n]{8,}["']/i],
];

const failures = [];
if (lineCount > 200) failures.push(`too many lines: ${lineCount} (max 200)`);
if (requiredHeadings.length === 0) failures.push("required heading list is empty");

for (const heading of requiredHeadings) {
  if (!h2Headings.has(heading)) failures.push(`missing h2: ${heading}`);
}

for (const [label, pattern] of secretPatterns) {
  if (pattern.test(text)) failures.push(`possible secret: ${label}`);
}

if (failures.length > 0) {
  console.table(failures.map((problem) => ({ problem })));
  process.exitCode = 1;
} else {
  console.log(`CLAUDE.md check passed: ${lineCount} lines`);
}

Perintahnya sengaja sederhana agar sama-sama dapat dipakai secara lokal dan di CI:

node check-claude-md.mjs CLAUDE.md
# Jika judul H2 memakai bahasa Indonesia
node check-claude-md.mjs CLAUDE.md "Perintah|Aturan perubahan|Daftar tinjau"

Pemeriksa ini bukan secret scanner lengkap. Gunakan bersama GitHub secret scanning atau scanner khusus. Jika credential ditemukan, menghapus baris yang terlihat saja tidak cukup; hapus dari history bila perlu dan cabut credential tersebut.

Pitfall: File panjang, aturan kabur, dan keamanan semu

Pitfall 1: File terus membesar setelah setiap review. Penyebabnya adalah semua komentar langsung dijadikan aturan permanen tanpa memeriksa apakah masalah akan berulang. Solusinya: tambahkan hanya keputusan yang berulang, hapus perintah usang lebih dahulu, dan pindahkan detail khusus package ke dekat package tersebut.

Pitfall 2: Instruksi tidak dapat diverifikasi. “Pertahankan kualitas” dan “ikuti desain yang ada” tidak memiliki kondisi lulus. Solusinya: tulis target path, perintah, exit status yang diharapkan, lebar browser, atau nama test. Anggota tim baru harus dapat mencapai kesimpulan yang sama.

Pitfall 3: Keamanan bergantung pada kalimat larangan. Menulis “jangan pernah menyentuh production” tidak menciptakan penghalang teknis. Solusinya: masukkan pola command berbahaya ke permission deny rules dan gunakan hook PreToolUse untuk penghentian yang deterministik. CLAUDE.md cukup menjelaskan alasan serta alternatif yang disetujui.

Pitfall 4: Import menjadi tumpukan pengetahuan tersembunyi. Penyebabnya adalah anggapan bahwa file yang diimport tidak memakai context. Padahal isinya dimuat saat startup. Solusinya: simpan keputusan singkat di root dan berikan path atau URL untuk detail yang hanya dibaca ketika dibutuhkan.

Pemeliharaan tanpa dokumentasi usang

Perlakukan perubahan CLAUDE.md seperti perubahan kode. Buka diff, jalankan pemeriksa, dan uji satu tugas yang mewakili penggunaan nyata. Hapus aturan ketika perintah, path, atau arsitektur yang dijelaskannya sudah tidak ada.

Review bulanan yang ringan cukup memakai empat pertanyaan: komentar review mana yang muncul lebih dari sekali, instruksi mana yang diabaikan atau ditafsirkan dengan dua cara, perintah atau path mana yang usang, dan peringatan mana yang seharusnya ditegakkan dengan permission atau hook. Ukuran yang berguna bukan jumlah token, melainkan jumlah revisi, pemeriksaan gagal yang tertangkap sebelum merge, dan waktu untuk menjelaskan ulang dasar repository.

Pertanyaan yang sering diajukan

Berapa panjang CLAUDE.md yang tepat?

Tidak ada batas isi yang kaku, tetapi panduan resmi menyarankan target kurang dari 200 baris. Mulai sekitar 100 baris agar masih ada ruang untuk peta project, perintah, batas perubahan, dan review gate. Pindahkan materi khusus package ke file bertingkat atau .claude/rules/.

Apakah instruksi tetap ada setelah /compact?

CLAUDE.md di root dimasukkan kembali setelah compaction. Instruksi bertingkat dan berbasis path dimuat lagi ketika Claude membaca file yang cocok. Simpan keputusan yang harus bertahan di file, bukan hanya dalam percakapan yang dapat dipadatkan.

Apa bedanya dengan Auto memory?

CLAUDE.md berisi instruksi yang ditulis dan dipelihara manusia. Auto memory berisi catatan lokal yang direkam Claude dari pengalaman, misalnya penemuan debugging dan preferensi. Perintah serta batas bersama masuk ke CLAUDE.md; penemuan lokal baru menjadi aturan tim setelah ditinjau manusia.

Apa isi versi pertama?

Mulai dari perintah install, test, dan build; satu daftar area yang dilindungi; serta isi laporan akhir yang wajib. Jalankan tugas nyata, kemudian tambahkan hanya keputusan yang benar-benar hilang dan menyebabkan pekerjaan ulang.

Susun template project dari materi siap pakai

Menulis CLAUDE.md hanya satu bagian dari workflow yang andal. Permissions, test, handoff, dan review tetap harus selaras dengannya. Katalog materi ClaudeCodeLab menyediakan checklist dan latihan yang dapat diadaptasi menjadi template operasional untuk repository Anda.

Hasil yang benar-benar diuji

Pada 22 Juli 2026, kode check-claude-md.mjs dalam artikel ini dijalankan terhadap dua fixture sementara. Sample valid 10 baris yang memuat semua heading wajib menghasilkan exit code 0 dan pesan lulus. Sample negatif dengan satu heading dihapus dan test token ditambahkan menghasilkan exit code 1 serta tiga temuan: satu heading yang hilang dan dua kecocokan pola rahasia.

Review artikel juga memeriksa syntax JavaScript, URL sumber resmi, internal link, frontmatter, bagian hasil terakhir, dan keberadaan tepat satu CTA komersial utama. Mulailah dengan menjalankan pemeriksa pada CLAUDE.md Anda sendiri, lalu perbaiki masalah pertama yang dilaporkan. Perilaku produk dibandingkan dengan dokumentasi resmi Claude Code untuk memory, context window, settings, dan hooks.