Cara Claude Code memuat beberapa file CLAUDE.md di subdirektori

6 menit baca.
Tags: AIClaude Code

Satu project bisa punya banyak file CLAUDE.md, dan Claude Code membaca semuanya. File di folder parent dimuat saat sesi mulai, file di subfolder dimuat begitu Claude menyentuh file di folder itu, dan tidak ada yang saling menimpa. Semua isinya digabung ke context.

Jawaban cepat

repo/
├── CLAUDE.md                 # loads at launch
├── CLAUDE.local.md           # loads at launch, after CLAUDE.md, not committed
├── .claude/rules/testing.md  # loads at launch, or only for matching files with `paths`
└── apps/web/
    └── CLAUDE.md             # loads when Claude reads or edits a file in apps/web/

Kalau Claude Code dijalankan dari repo/, file di root langsung dimuat. apps/web/CLAUDE.md baru masuk ke context saat Claude pertama kali membuka file di apps/web/. Kalau dijalankan dari dalam apps/web/, dua-duanya langsung dimuat, karena Claude Code juga membaca CLAUDE.md di folder parent.

Untuk melihat file mana yang sedang dimuat, jalankan ini di dalam Claude Code dan lihat bagian Memory files:

/context all

CLAUDE.md apa saja yang dimuat saat startup

Dokumentasi memory menyebut empat scope, dimuat dari yang paling luas ke yang paling spesifik:

  1. Managed policy, diatur admin: /etc/claude-code/CLAUDE.md di Linux, /Library/Application Support/ClaudeCode/CLAUDE.md di macOS
  2. File user kamu: ~/.claude/CLAUDE.md
  3. File project: ./CLAUDE.md atau ./.claude/CLAUDE.md
  4. File lokal: ./CLAUDE.local.md

Selain itu, Claude Code membaca CLAUDE.md dan CLAUDE.local.md dari working directory sampai semua folder di atasnya. Kalau dijalankan dari foo/bar/, yang dimuat adalah foo/CLAUDE.md dan foo/bar/CLAUDE.md. Urutannya dari root filesystem turun sampai folder tempat kamu mulai. Dalam satu folder, CLAUDE.local.md dimuat setelah CLAUDE.md.

CLAUDE.local.md cocok untuk catatan pribadi di repo bersama, misalnya URL database lokal atau akun test. Masukkan ke .gitignore.

Kalau kamu mau ~/.claude/CLAUDE.md yang beda untuk tiap akun (kerja dan pribadi), caranya dengan folder config terpisah per akun. Ini dibahas di beberapa akun Claude Code dengan CLAUDE_CONFIG_DIR.

Kapan CLAUDE.md di subfolder dimuat?

File di bawah working directory tidak dimuat saat launch. Claude Code memuat tiap file saat Claude pertama kali membaca, menulis, atau mengedit file di subfolder itu. cat atau head lewat Bash juga dihitung sebagai membaca.

Jadi di monorepo, begitu Claude membuka packages/api/src/server.ts, packages/api/CLAUDE.md ikut dimuat. Sesi yang tidak pernah menyentuh packages/api/ tidak perlu menanggung instruksi itu.

Pemuatan ini pernah tidak konsisten. Issue #2571 mengumpulkan laporan CLAUDE.md di subfolder yang tidak dimuat, termasuk satu kasus yang dimuat di sesi interaktif tapi tidak dengan claude -p. Bot menutup issue itu karena tidak aktif pada Februari 2026, tanpa perbaikan dari tim. Kalau file di subfolder terasa diabaikan, cek /context all setelah Claude membuka file di folder itu, jangan langsung menebak.

Kalau dua CLAUDE.md saling bertentangan

Tidak ada yang menimpa. Menurut dokumentasi, semua file yang ditemukan "are concatenated into context rather than overriding each other," dan kalau dua instruksi bertentangan, "Claude may pick one arbitrarily."

File yang lebih dalam tidak otomatis menang hanya karena lebih spesifik. Kalau CLAUDE.md di root bilang "pakai npm" dan apps/web/CLAUDE.md bilang "pakai pnpm", hasilnya tergantung untung-untungan. Tulis file di subfolder sebagai tambahan untuk file root ("di package ini, jalankan juga pnpm test:e2e"), dan taruh instruksi yang berbeda di luar file root.

Pecah file besar dengan @ import

CLAUDE.md bisa memasukkan file lain dengan @path:

# CLAUDE.md

See @README.md for the project overview.

## Workflow
- Git: @docs/git-workflow.md
- Personal setup: @~/.claude/my-project-notes.md

Path relatif dihitung dari file yang berisi import, bukan dari tempat Claude Code dijalankan. Import bisa bersarang sampai empat tingkat. Path di dalam backtick atau code block tidak di-import, jadi kamu tetap bisa menyebut nama file tanpa memuatnya.

Saat project pertama kali meng-import file di luar working directory, Claude Code minta persetujuan kamu. Kalau ditolak, import itu tetap nonaktif untuk project itu.

Import tidak menghemat context. File yang di-import dimuat saat launch bersama CLAUDE.md yang memanggilnya, jadi fungsinya merapikan teks, tidak mengurangi context.

Instruksi untuk file tertentu saja: .claude/rules

Untuk instruksi yang hanya relevan bagi sebagian file, pakai .claude/rules/. Tiap file Markdown di sana adalah satu rule, dan daftar paths di frontmatter menentukan kapan rule itu dimuat:

---
paths:
  - "src/api/**/*.ts"
  - "src/**/*.{test,spec}.ts"
---

# API rules

- Validate request bodies with Zod.
- Every handler gets an integration test.

Rule tanpa paths dimuat saat launch, sama seperti .claude/CLAUDE.md. Rule dengan paths baru dimuat saat Claude membaca, menulis, atau mengedit file yang cocok. Glob-nya relatif terhadap folder yang berisi .claude/.

Dibanding CLAUDE.md di subfolder, rule bisa mencocokkan tipe file di seluruh repo, hal yang tidak bisa dilakukan folder. Kalau YAML-nya rusak, Claude Code mengabaikan frontmatter dan memuat rule itu di semua tempat. claude --debug menampilkan error parsing-nya.

Rule level user di ~/.claude/rules/ berlaku untuk semua project di mesin kamu, dan dimuat sebelum rule project.

Kecualikan CLAUDE.md yang tidak kamu perlukan di monorepo

Di monorepo besar, CLAUDE.md milik tim lain bisa ikut masuk ke context kamu, terutama yang ada di folder parent. claudeMdExcludes melewatinya. Taruh di .claude/settings.local.json supaya cuma berlaku untuk kamu:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

Pattern-nya berupa glob yang dicocokkan dengan path absolut. Kamu bisa mengaturnya di settings user, project, local, atau managed, dan array-nya digabung. CLAUDE.md dari managed policy tidak bisa dikecualikan.

CLAUDE.md di folder yang ditambah dengan --add-dir

claude --add-dir ../shared-config memberi Claude akses ke folder lain, tapi CLAUDE.md-nya tidak ikut dimuat secara default. Ubah dengan environment variable:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

Kalau variable itu diisi, Claude Code memuat CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md, dan file .claude/rules/ yang tidak memakai paths dari folder tambahan itu.

Cek apa yang sudah dimuat

/context all menampilkan semua memory file di context saat ini. Jalankan setelah Claude membuka file di subfolder, dan CLAUDE.md di folder itu akan muncul di daftar.

/memory menampilkan lokasi CLAUDE.md untuk user dan project kamu, termasuk file yang belum ada, dan bisa membukanya di editor.

Seberapa panjang tiap file

Dokumentasi menyarankan tiap CLAUDE.md di bawah 200 baris, karena file yang panjang jadi kurang konsisten diikuti. Itu alasan yang bagus untuk memecahnya.

Repo blog ini punya satu CLAUDE.md sepanjang 615 baris di root, isinya aplikasi Next.js, migrasi Prisma, workflow konten, dan setup deploy. Dengan aturan di atas, file itu bisa dipecah jadi file root pendek berisi command dan checklist, apps/henggana-web-t3/CLAUDE.md untuk arsitektur aplikasi, dan rule dengan paths: ["content/**"] untuk workflow menulis. Dengan begitu, sesi yang cuma mengedit post blog tidak memuat catatan migrasi Prisma.

Ringkasan cara kerjanya

Semua file CLAUDE.md dimuat dan digabung: folder parent dan ~/.claude/CLAUDE.md saat launch, file di subfolder begitu Claude membuka file di folder itu. Tidak ada yang menimpa, jadi jangan taruh instruksi yang bertentangan di dua file. Pakai .claude/rules/ dengan paths untuk instruksi per tipe file, claudeMdExcludes untuk membuang file yang tidak kamu mau, dan /context all untuk melihat apa yang benar-benar dimuat.