Best Practice CLAUDE.md: template praktis untuk project nyata

CLAUDE.md membantu Claude Code memahami struktur, command, dan aturan project tanpa perlu penjelasan ulang di setiap sesi. Tetapi file ini bukan kebijakan keamanan dan bukan tempat menaruh semua dokumentasi.

Aturan tim harus singkat dan bisa diverifikasi; preferensi pribadi tetap lokal; pembatasan keras memakai permissions dan hooks. Artikel ini menjelaskan apa yang perlu masuk ke CLAUDE.md dan apa yang sebaiknya tetap di luar, dengan format praktis untuk pemula.

Tujuannya adalah memberi template yang bisa disalin dan tetap mudah direview oleh tim.

Core idea: CLAUDE.md is guidance, not enforcement

Aturan tim harus singkat dan bisa diverifikasi; preferensi pribadi tetap lokal; pembatasan keras memakai permissions dan hooks. Menurut dokumentasi resmi, CLAUDE.md adalah panduan kontekstual, Auto memory menyimpan pembelajaran lokal, settings mengatur client, dan hooks menjalankan command pada event tertentu.

Mechanism	Role	Best for
CLAUDE.md	Human-written persistent guidance	Conventions, architecture, verification commands
Auto memory	Claude’s local learned notes	Debugging insights, preferences, repeated discoveries
settings / permissions	Client configuration and permission rules	Allow, deny, extra directories
hooks	Commands run at lifecycle events	Blocking risky actions, verification, formatting

Where to place CLAUDE.md files

Claude Code membaca CLAUDE.md dan CLAUDE.local.md dari direktori kerja ke atas. Aturan root masuk sejak awal sesi; aturan nested muncul saat file terkait dibaca.

repo/
  CLAUDE.md                 # shared project guidance
  CLAUDE.local.md           # personal, gitignored
  .claude/
    rules/
      api.md                # path-scoped rule
  packages/admin/CLAUDE.md  # loaded when this subtree is read

What to keep in always-loaded memory

Simpan command build, test, batas arsitektur, aturan nama, pola terlarang, dan review gate. Jangan simpan secrets, log panjang, catatan rapat, rencana sekali pakai, atau research mentah.

• Keep build, test, lint, type-check, and release verification commands.
• Keep edit boundaries, non-edit boundaries, naming rules, and review gates.
• Do not keep secrets, long meeting notes, historical logs, or one-off task instructions.
• Do not paste entire official docs. Keep the URL and the decision rule.

Copy-paste CLAUDE.md template

Template berikut sengaja singkat agar konteks tidak berat. Sesuaikan dengan project dan buat setiap aturan bisa diverifikasi.

# Project Instructions

## Project map
- App: Next.js 15 + TypeScript
- API: src/app/api/**
- DB: Prisma schema in prisma/schema.prisma
- Tests: Vitest for units, Playwright for critical browser flows

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

## Change rules
- Prefer small edits that follow existing patterns.
- Do not change auth, billing, or migrations without explicit task scope.
- When editing API handlers, update validation and tests in the same pass.
- Before final response, report commands run and any skipped verification.

## Review checklist
- No secrets in code, logs, fixtures, or screenshots.
- Error paths are tested, not only the happy path.
- Public copy and docs use the same terminology as the UI.

Use imports and .claude/rules carefully

Import @path berguna untuk organisasi, bukan untuk menghemat token. Konten yang diimport tetap masuk konteks. Untuk project besar, hapus konten lama dan pindahkan aturan per path ke .claude/rules/.

# CLAUDE.md

Read the short project overview in @docs/project-map.md.
Do not import long meeting notes here.

## Compact Instructions
- Preserve current objective, files changed, tests run, and unresolved risks.
- Drop raw command output unless it explains a failure.

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

# API rules
- Validate request bodies with Zod.
- Return typed error responses.
- Add or update tests for every changed handler.

Three practical use cases

1. Manfaat paling besar muncul pada onboarding, perbaikan bug, dan produksi konten dengan aturan tautan internal. Untuk onboarding, tulis peta project dan command verifikasi lebih dulu.
2. Untuk bug, sertakan command reproduksi, lokasi log, dan test minimal.
3. Untuk konten, simpan tone, internal link, dan quality gate di CLAUDE.md; catatan panjang tetap di Obsidian atau docs.

Failure cases and pitfalls

1. Kesalahan umum adalah import seluruh README, aturan kabur, dan mengandalkan CLAUDE.md untuk keamanan. Simpan hanya aturan yang selalu perlu.
2. Ganti “buat rapi” dengan command dan batas file yang jelas.
3. Keamanan kuat butuh permissions dan PreToolUse hooks; CLAUDE.md saja tidak cukup.

Team maintenance rule

Update CLAUDE.md saat kesalahan berulang, komentar review berulang, command berubah, atau batas arsitektur berubah.

# quick review before changing CLAUDE.md
rg -n "TODO|deprecated|temporary|secret|password|token" CLAUDE.md .claude/rules
git diff -- CLAUDE.md .claude/rules

Next step and monetization path

Untuk workflow lengkap, gabungkan dengan Obsidian, optimasi token, dan halaman konsultasi. Workflow lengkap cocok digabungkan dengan Obsidian, optimasi token, dan halaman konsultasi. Related articles: Obsidian workflow, productivity tips, permissions guide, and consultation page.

What was verified

Update ini mengikuti dokumentasi resmi memory, context window, settings, dan commands. Official references: memory, context window, settings, and commands.