Panduan Lengkap Menulis CLAUDE.md: Best Practice untuk Konfigurasi Project

Apa Itu CLAUDE.md?

CLAUDE.md adalah file konteks yang membantu Claude Code memahami project-mu. Letakkan di root project, dan Claude Code otomatis membacanya di awal setiap sesi. CLAUDE.md yang ditulis dengan baik bisa meningkatkan kualitas respons Claude Code secara drastis.

Lokasi File dan Prioritas

Kamu bisa meletakkan file CLAUDE.md di beberapa lokasi, dan semuanya akan dimuat:

~/.claude/CLAUDE.md          # Pengaturan global (shared di semua project)
./CLAUDE.md                   # Root project (shared dengan tim)
./CLAUDE.local.md             # Pengaturan lokal (tambahkan ke .gitignore)
./src/CLAUDE.md               # Pengaturan level subdirektori

• Global: Preferensi coding style pribadimu
• Root project: Aturan dan tech stack yang dibagikan tim
• Lokal: Pengaturan pribadi yang tidak di-commit ke Git
• Subdirektori: Konteks tambahan untuk modul tertentu

Template Awal

Berikut template CLAUDE.md yang praktis:

# Project Overview

Backend API e-commerce. Menangani manajemen order, inventori, dan autentikasi user.

## Tech Stack

- Language: TypeScript 5.x
- Runtime: Node.js 22
- Framework: Fastify
- DB: PostgreSQL 16 + Prisma ORM
- Testing: Vitest
- CI: GitHub Actions

## Struktur Direktori

src/
  routes/       # Definisi API endpoint
  services/     # Business logic
  repositories/ # Data access layer
  middleware/   # Auth, logging, error handling
  utils/        # Fungsi utilitas
  types/        # Definisi tipe

## Konvensi Coding

- Gunakan arrow function
- Selalu gunakan try-catch untuk error handling dengan custom error class
- Penamaan: camelCase (variabel/fungsi), PascalCase (tipe/class)
- Nama file: kebab-case
- Gunakan path alias `@/` daripada relative import

## Command Umum

- Jalankan test: `npm test`
- Type check: `npx tsc --noEmit`
- Lint: `npm run lint`
- Migrasi DB: `npx prisma migrate dev`
- Dev server: `npm run dev`

## Aturan Penting

- Selalu buat migrasi setelah mengubah prisma/schema.prisma
- Setiap API endpoint harus memiliki Zod validation schema
- Daftarkan route baru di routes/index.ts

Tips Menulis CLAUDE.md yang Efektif

1. Jaga Tetap Ringkas

CLAUDE.md mengonsumsi token context window. Hindari penjelasan bertele-tele dan gunakan bullet point.

# Contoh buruk
Project ini menggunakan TypeScript. TypeScript adalah bahasa yang dikembangkan
oleh Microsoft yang menambahkan tipe ke JavaScript...

# Contoh bagus
- Language: TypeScript 5.x (strict mode)

2. Dokumentasikan Apa yang Tidak Diinginkan

Mencantumkan anti-pattern secara eksplisit ternyata sangat efektif.

## Dilarang

- Tidak boleh ada tipe `any`
- Tidak boleh default export (hanya named export)
- Tidak boleh console.log untuk debugging (gunakan logger)
- Jangan pernah menghapus atau melewati test yang sudah ada

3. Definisikan Workflow

Pandu Claude Code tentang cara mendekati task.

## Menambahkan Fitur Baru

1. Buat definisi tipe di `src/types/`
2. Implementasikan data access layer di `src/repositories/`
3. Implementasikan business logic di `src/services/`
4. Definisikan endpoint di `src/routes/`
5. Tulis unit test untuk setiap layer
6. Verifikasi semua test lulus dengan `npm test`

4. Tangkap Tribal Knowledge

Dokumentasikan informasi penting yang tidak tertulis di tempat lain.

## Catatan Khusus Project

- `user_id` menggunakan UUID v7 (untuk pengurutan berbasis waktu)
- Semua kalkulasi harga harus menggunakan `Decimal.js` (menghindari error floating-point)
- Environment variable dipusatkan di `src/config.ts` — jangan pernah akses process.env secara langsung

Penggunaan Tim

Setup .gitignore

Jauhkan pengaturan pribadi dari version control:

# .gitignore
CLAUDE.local.md

Sertakan dalam Code Review

Perlakukan CLAUDE.md sebagai dokumen project yang penting. Sertakan dalam review PR dan jaga agar tetap up to date sebagai tim.

Kapan Harus Update CLAUDE.md

• Saat menambahkan library baru
• Saat mengubah konvensi coding
• Saat merestrukturisasi direktori
• Saat kamu melihat Claude Code berulang kali membuat kesalahan yang sama

Kesimpulan

CLAUDE.md mengubah Claude Code menjadi ahli di project spesifikmu. Mulai dengan membuat scaffold menggunakan /init, lalu perbaiki seiring waktu. Bagikan dengan tim agar semua orang mendapatkan manfaat dari interaksi Claude Code yang lebih optimal.