Template CLAUDE.md untuk Claude Code di codebase yang sudah ada

CLAUDE.md mengurangi briefing berulang di setiap sesi

Saat memakai Claude Code di codebase yang sudah berjalan, masalahnya sering bukan kemampuan model. Masalahnya adalah konteks proyek tidak selalu terbawa: package manager apa yang dipakai, folder app ada di mana, file apa yang generated, command apa yang berbahaya, dan kapan sebuah tugas dianggap selesai.

CLAUDE.md menyimpan konteks itu sebagai instruksi persisten. Dokumentasi resmi Claude Code memory menjelaskan bahwa file ini dibaca saat sesi dimulai. Namun file ini adalah context, bukan enforcement keras. Untuk memblokir command atau path, pakai settings, permissions, hooks, CI, dan aturan repo. Untuk area secrets dan deployment, baca juga dokumentasi security.

Di artikel ini, harness berarti pijakan kerja agar agent tetap aman dan fokus. Jangan mulai dari handbook panjang. Mulai dari file kecil yang mencegah kesalahan berulang berikutnya. Untuk variasi lain, baca template CLAUDE.md dan panduan permissions Claude Code.

Template CLAUDE.md yang bisa langsung disalin

Versi pertama cukup berisi snapshot proyek, command, batas kerja, aturan kualitas, dan definition of done.

# CLAUDE.md

## Project snapshot
- Product: content site and paid template store
- Stack: Astro, TypeScript, MDX, npm
- Main app: site/
- Source articles: site/src/content/blog*/
- Owner voice: practical, evidence-based, no hype

## Commands
- Install dependencies: cd site && npm install
- Start local dev server: cd site && npm run dev
- Build check: cd site && npm run build
- Search fast: rg "keyword" site/src
- Inspect git state: git status --short

## Working rules
- Read existing files before editing.
- Keep changes scoped to the requested slug or feature.
- Do not edit .env, dist, generated reports, or unrelated locale files.
- Preserve pubDate, category, tags, author, lang, and heroImage unless they are broken.
- Ask before destructive git operations, production deploys, or secret rotation.

## Article quality
- Japanese canonical articles should be 4000-6000 characters excluding code.
- Include at least three real use cases.
- Include concrete pitfalls and how to avoid them.
- Include runnable code or config examples, not pseudocode.
- Check official docs when the topic may have changed.

## Definition of done
- The requested files are edited.
- Code fences and JSON/YAML examples are valid.
- Links to internal pages and official docs are present.
- Verification commands have run or skipped checks are explained.
- Remaining risks are stated in the final message.

Simpan sebagaiCLAUDE.mddi root repo. Catatan pribadi sebaiknya masuk keCLAUDE.local.md. Jika repo sudah memakaiAGENTS.md, jangan gandakan semua aturan; buatCLAUDE.mdkecil yang mengimpor aturan umum lalu tambahkan aturan khusus Claude Code.

Simpan batas eksekusi di settings

Menulis “jangan push” diCLAUDE.mdmembantu, tetapi tidak memblokir tindakan. Batas yang kritis harus ada di settings, CI, branch protection, atau approval deployment.

{
  "permissions": {
    "allow": [
      "Read",
      "Edit(site/src/content/blog/**)",
      "Bash(rg:*)",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(node:*)"
    ],
    "deny": [
      "Bash(git reset:*)",
      "Bash(git checkout --:*)",
      "Bash(git push:*)",
      "Bash(npm publish:*)",
      "Edit(.env*)",
      "Edit(reports/**)"
    ]
  }
}

Pakai.claude/settings.local.jsonuntuk guardrail pribadi dan.claude/settings.jsonuntuk default tim. Sebelum dipakai di repo nyata, cek schema terbaru di dokumentasi resmi settings. CLAUDE.md memberi konteks; settings memberi batas eksekusi.

Tiga use case nyata

Use case	Isi CLAUDE.md	Dampak
Maintenance artikel lokal	target slug, daftar locale, frontmatter yang harus dipertahankan, panjang body, CTA, verifikasi	Mengurangi locale hilang, sisa bahasa Inggris, link rusak, dan tanggal basi
Bug kecil di SaaS	folder yang boleh diedit, command test, approval DB, aturan logging	Mengurangi refactor di luar scope dan migration berisiko
Code review tim	severity, file, line, impact, reproduction, test gap	Review menjadi actionable untuk PR atau issue

Pada konten multi-bahasa, file yang lengkap belum tentu benar. Body bisa tertinggal dalam bahasa Inggris. Dengan menulis folder locale, path internal link, dan batas description, Claude Code akan memeriksa satu grup artikel secara utuh.

Pada SaaS, scope lebih penting daripada kalimat umum seperti “buat kode bagus”. Bug UI kecil tidak boleh menyentuh billing, auth, atau migration tanpa persetujuan. Tuliskan langkah yang bisa diverifikasi: baca file terkait, ubah permukaan terkecil, jalankan test yang sesuai, minta izin untuk perubahan data.

Pada review, format output menentukan manfaat. Minta severity, path, line, user impact, reproduction, dan missing test. Jika ingin menjalankan review lewat script, gunakan official CLI reference.

Pitfall yang sering terjadi

Pitfall pertama adalah file terlalu panjang. Policy 300 baris terlihat lengkap, tetapi memakan context dan makin jarang diikuti. Simpan aturan yang sering dipakai saja. Aturan khusus path lebih baik masuk ke path-scoped rule atau dokumen terpisah.

Pitfall kedua adalah menulis secret. API key, nama customer, URL dashboard privat, dan angka revenue yang belum publik tidak masuk keCLAUDE.md. Tulis aturan penanganannya saja: secret ada di environment variable, tidak dicetak, dan file sensitif dibuka setelah konfirmasi.

Pitfall ketiga adalah command basi. Jika proyek pindah dari Yarn ke npm, Jest ke Vitest, atau Next.js ke Astro, updateCLAUDE.mdsegera. Command lama membuat Claude Code salah arah dengan percaya diri.

Pitfall keempat adalah lupa verification receipt. Final answer harus menyebut command yang dijalankan, hasil, file yang berubah, link yang dicek, dan risiko tersisa. Kebiasaan ini menangkap banyak kesalahan kecil sebelum publish.

Rollout kecil yang realistis

Mulai dari template ini, lalu pakai untuk tiga tugas kecil: edit konten, perbaikan copy UI, dan code review. Tambahkan aturan hanya jika aturan itu benar-benar mencegah kesalahan yang terjadi. Batas yang wajib dipatuhi dipindahkan ke settings, CI, branch protection, atau approval deployment.

Untuk situs yang punya monetisasi, CTA adalah bagian dari kualitas. Products, checkout, training, dan form konsultasi harus tetap benar setelah perubahan teks atau layout. Masukkan pengecekan itu ke definition of done.

Untuk prompt, template, dan checklist yang reusable, lihat ClaudeCodeLab products. Untuk rollout tim dengan permissions, review gates, training, danCLAUDE.mdyang disesuaikan dengan repo nyata, gunakan Claude Code training and consultation. Template terbaik bukan yang paling panjang, tetapi yang mencegah kesalahan berulang berikutnya.