Siapkan Claude Code di monorepo atau codebase besar

Konfigurasikan Claude Code untuk monorepos dan codebase pohon tunggal besar dengan file CLAUDE.md bersarang, worktrees sparse, code intelligence, dan skills per-paket sehingga Claude tetap fokus pada kode yang sedang Anda kerjakan.

Codebase besar dapat berupa satu repository dengan jutaan baris atau monorepo dengan banyak paket. Claude Code bekerja pada ukuran apa pun, tetapi seiring dengan pertumbuhan codebase, default yang disesuaikan untuk proyek yang lebih kecil dapat mengisi jendela konteks dengan instruksi dan pembacaan file yang tidak terkait dengan tugas, menghabiskan token dan menurunkan kinerja Claude.

Panduan ini menunjukkan kepada pengembang individual dan tim teknik bagaimana membatasi Claude ke bagian codebase yang disentuh oleh tugas. Setiap bagian mencatat apakah pengaturan bersifat pribadi untuk mesin Anda atau berkomitmen pada repository.

Apa yang panduan ini cakup

Tabel di bawah mencantumkan setiap pengaturan dan apa yang dicapainya. Pohon file setelahnya adalah monorepo contoh yang dirujuk oleh setiap sampel kode di halaman ini.

Settings on this page

Setiap pengaturan di bawah ini independen. Mereka berlapis daripada menggantikan satu sama lain, jadi terapkan mana pun yang sesuai dengan repository Anda. Pilih di mana memulai Claude menentukan di mana file pengaturan Anda berada, jadi baca terlebih dahulu. Satukan semuanya menunjukkan semuanya digabungkan.

The example monorepo

Contoh di seluruh halaman ini merujuk pada monorepo dengan tiga paket. Pola yang sama bekerja di codebase pohon tunggal besar: di mana contoh menggunakan packages/api/, gantikan dengan direktori subsistem Anda sendiri seperti src/backend/ atau lib/core/.

monorepo/
  CLAUDE.md                     # instruksi root
  packages/
    api/
      CLAUDE.md                 # instruksi spesifik API
      .claude/skills/
      src/
    web/
      CLAUDE.md                 # instruksi spesifik frontend
      .claude/skills/
      src/
    shared/
      CLAUDE.md                 # instruksi perpustakaan bersama
      src/

Pilih di mana memulai Claude

Di mana Anda meluncurkan claude menentukan file mana yang dapat dibaca dan diedit Claude tanpa hibah izin tambahan, file CLAUDE.md mana yang dimuat ke konteks saat startup, dan pengaturan proyek mana yang berlaku.

Pengaturan proyek di .claude/settings.json tidak diwariskan dari direktori induk dengan cara file CLAUDE.md. Untuk mengetahui direktori mana .claude/settings.json yang dibaca sesi, lihat di mana Claude Code mencari setiap file.

Setiap bagian di bawah menyatakan apakah file pengaturannya berada di repository root atau di subdirektori tempat Anda memulai, dan apakah itu berkomitmen atau disimpan secara lokal.

Layer CLAUDE.md files by directory

Dalam codebase besar, satu CLAUDE.md di repository root cenderung baik tumbuh untuk mencakup konvensi setiap subsistem, menghabiskan konteks pada instruksi yang tidak terkait dengan tugas saat ini, atau tetap terlalu umum untuk berguna. Membagi instruksi di seluruh file per-direktori berarti Claude memuat aturan repository-wide plus hanya konvensi untuk kode yang sedang Anda kerjakan.

Claude Code memuat setiap file CLAUDE.md dari direktori kerja Anda dan setiap direktori induk saat peluncuran, kemudian memuat file setiap subdirektori sesuai permintaan ketika membaca file di sana. File root menetapkan aturan repository-wide dan setiap subdirektori menambahkan miliknya sendiri.

Pemisahan umum adalah dua level:

• Root CLAUDE.md: instruksi yang berlaku di mana-mana, seperti standar coding dan konvensi commit
• Per-subdirektori CLAUDE.md: konvensi spesifik untuk stack area itu. Dalam monorepo itu satu per paket. Dalam pohon tunggal besar itu satu per subsistem seperti src/db/ atau src/api/

Komitkan file ini ke repository sehingga rekan kerja mewarisinya. Pemilik setiap direktori biasanya memelihara filenya.

Untuk memangkas file yang sudah diperiksa, jalankan pemeriksaan /doctor. Root CLAUDE.md menyimpan aturan yang berlaku di setiap paket:

Jalankan skrip paket dari direktori paket, bukan root monorepo.
Awali subjek commit dengan nama paket, misalnya `api: add rate limiting`.
Jangan pernah edit file di bawah packages/*/generated/. Jalankan `npm run codegen` di paket sebagai gantinya.

CLAUDE.md setiap subdirektori, di sini packages/api/CLAUDE.md, menambahkan konvensi spesifik untuk area itu:

Salin `.env.example` ke `.env` sebelum menjalankan apa pun. Tes dan dev server gagal tanpanya.
Tulis kueri database dengan Knex query builder. Jangan pernah letakkan string SQL mentah di route handlers.
Jangan pernah edit migrasi setelah digabung. Tambahkan migrasi baru sebagai gantinya.

Ketika Anda memulai Claude dari packages/api/, itu memuat baik packages/api/CLAUDE.md dan root CLAUDE.md. Claude melihat instruksi lokal bersama aturan repository-wide, tanpa instruksi dari packages/web/ dalam konteks. Hal yang sama berlaku untuk subdirektori apa pun dalam pohon non-monorepo. Untuk mengonfirmasi file mana yang dimuat, jalankan /context dan periksa daftar di bawah Memory files.

Beberapa cara untuk menjaga file tetap terkini seiring dengan perubahan codebase dan model:

• Tinjau dalam pull request: perlakukan edit CLAUDE.md seperti perubahan dokumentasi lainnya sehingga konvensi melacak kode
• Kunjungi kembali setelah rilis model utama: instruksi yang mengatasi keterbatasan model yang lebih lama mungkin menjadi overhead setelah model yang lebih baru menangani kasus itu sendiri. Misalnya, aturan yang memaksa refactor file tunggal dapat dihapus setelah keterbatasan hilang
• Tambahkan hook Stop yang mengusulkan pembaruan: hook Stop menerima jalur ke transkrip sesi ketika Claude selesai merespons, jadi skrip dapat meninjau sesi dan mengusulkan pembaruan CLAUDE.md sementara kesenjangan yang dieksposnya masih segar

Untuk lebih lanjut tentang bagaimana file CLAUDE.md dimuat dan berinteraksi, lihat Memory and project instructions.

Choose between per-directory CLAUDE.md and path-scoped rules

File CLAUDE.md per-direktori dan path-scoped rules di bawah .claude/rules/ keduanya memungkinkan Anda menargetkan instruksi ke bagian pohon. Mereka berbeda dalam di mana file berada dan kapan dimuat.

Untuk perbandingan yang juga mencakup skills, lihat Compare similar features.

Exclude irrelevant CLAUDE.md files

Ketika Anda memulai Claude dari repository root, CLAUDE.md setiap subdirektori dimuat segera setelah Claude membaca file di direktori itu. Pengaturan claudeMdExcludes melewati file tertentu berdasarkan jalur atau pola glob sehingga mereka tidak pernah dimuat.

Gunakan ini untuk direktori yang tidak pernah Anda kerjakan, seperti paket tim lain, kode legacy, atau subtree yang di-vendor. Daftar pengecualian bersifat statis, bukan switch per-tugas. Untuk fokus pada satu paket hari ini dan paket lain besok, mulai Claude dari direktori paket itu bukan mengedit pengecualian.

Jika Anda hanya menginginkan pengecualian ini untuk diri sendiri, letakkan pengaturan di .claude/settings.local.json. Claude Code menambahkan file itu ke gitignore global Anda ketika menyimpan pengaturan di sana. Karena Anda membuatnya dengan tangan di sini, tambahkan ke gitignore Anda sendiri. Pola menggunakan sintaks glob yang cocok dengan jalur file absolut, jadi mulai pola gaya-relatif dengan **/ untuk cocok di mana saja di pohon. Contoh di bawah mengecualikan paket yang dimiliki oleh tim lain:

{
  "claudeMdExcludes": [
    "**/packages/web/**"
  ]
}

Ini melewati setiap CLAUDE.md dan file rules di bawah paket itu. Root CLAUDE.md dan paket yang Anda kerjakan masih dimuat secara normal.

Pola ini mencakup kasus umum lainnya:

• "**/packages/*/CLAUDE.md": mengecualikan CLAUDE.md setiap paket sambil menjaga root
• "**/packages/legacy-*/**": mengecualikan setiap paket yang namanya cocok dengan glob, termasuk rules
• "/home/user/monorepo/legacy/CLAUDE.md": mengecualikan satu file tertentu berdasarkan jalur absolut

File CLAUDE.md kebijakan yang dikelola tidak dapat dikecualikan, jadi instruksi organisasi-wide selalu berlaku. Anda dapat mengatur claudeMdExcludes di settings scope apa pun: user, project, local, atau managed. Array menggabung di seluruh scope, jadi tim dapat mengatur default level-proyek sementara individu menambahkan override lokal.

Untuk dokumentasi pengecualian lengkap, lihat Exclude specific CLAUDE.md files.

Kurangi apa yang Claude baca

Instruksi hanya bagian dari apa yang berakhir dalam konteks Claude. Pembacaan file adalah biaya lain yang tumbuh dengan codebase. Pengaturan di bawah memblokir pembacaan jalur yang tidak relevan dan menggantikan pemindaian file yang lengkap dengan pencarian language-server.

Block reads of generated and vendored code

Pencarian konten Claude menghormati .gitignore secara default, jadi jalur yang sudah terdaftar di sana, seperti node_modules/, dist/, dan build/, tetap keluar dari hasil pencarian tanpa konfigurasi tambahan.

Untuk jalur yang diperiksa, seperti SDK yang di-vendor atau kode yang dihasilkan berkomitmen, tambahkan aturan deny Read di permissions.deny untuk memblokir Claude dari membuka file itu.

Aturan deny dapat mencakup semua orang yang bekerja di repository, hanya Anda, atau setiap sesi di mesin, tergantung pada file pengaturan mana yang Anda masukkan:

• Semua orang yang bekerja di repository: komitkan aturan ke .claude/settings.json, di root repository jika Anda memulai Claude di sana, atau di .claude/ setiap paket jika Anda memulai dari subdirektori. Seperti pengaturan proyek lainnya di halaman ini, file itu tidak diwariskan dari direktori induk.
• Hanya Anda: gunakan .claude/settings.local.json di root repository, yang dimuat di setiap sesi CLI di dalam repository terlepas dari direktori awal, kecuali dalam kasus di mana Claude Code tidak menggunakan root repository, seperti di Windows. Pola relatif seperti contoh Read(./**/vendor/**/*) masih jangkar di direktori kerja saat ini sesi daripada root repository, jadi jika Anda memulai sesi dari subdirektori, tulis aturan di file ini sebagai jalur absolut //, seperti Read(//absolute/path/to/repo/**/vendor/**/*). Sebelum v2.1.211, .claude/settings.local.json juga dimuat hanya dari direktori awal.
• Semua orang, ditegakkan di setiap sesi: atur aturan di managed settings, yang tidak dapat ditimpa oleh pengaturan user dan project.

Contoh di bawah memblokir artefak build dan SDK yang di-vendor. Pola direktorinya berakhir dengan /**/* daripada /** sehingga setiap aturan mencakup segalanya di dalam direktori tetapi bukan direktori itu sendiri. Claude kemudian masih dapat mendaftar direktori itu atau mengubah ke dalamnya, misalnya dengan ls dist atau cd build.

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**/*)",
      "Read(./**/build/**/*)",
      "Read(./**/*.generated.*)",
      "Read(./**/vendor/**/*)"
    ]
  }
}

Aturan deny mencakup alat file bawaan Claude. Di Bash, mereka mencakup perintah file yang dikenali Claude Code, seperti cat, head, grep, dan find, ketika jalur yang ditolak muncul sebagai argumen, dan target dari redirection seperti < file. Claude Code juga membuat upaya terbaik untuk meninggalkan jalur yang ditolak keluar dari hasil alat Grep dan Glob bawaan. Pencarian Bash seperti grep -r atau find di atas direktori yang berisi file yang ditolak masih menyertakan mereka dalam outputnya.

Aturan deny tidak mencakup subprocess yang membuka file sendiri. Untuk sintaks pola lengkap, lihat Aturan izin Read dan Edit.

Reduce file reads with code intelligence

Dalam codebase besar, menemukan di mana simbol didefinisikan atau digunakan dapat menghabiskan banyak pembacaan file dan panggilan grep. Plugin code intelligence menghubungkan Claude ke language server sehingga dapat melompat ke definisi, menemukan referensi, dan permukaan kesalahan tipe secara langsung bukan memindai pohon.

Marketplace resmi memiliki plugin untuk TypeScript, Python, Go, Rust, dan bahasa umum lainnya. Jalankan perintah di bawah ini di dalam sesi Claude Code untuk menginstal plugin TypeScript:

/plugin install typescript-lsp@claude-plugins-official

Jika instalasi gagal, cocokkan pesan yang dilaporkan Claude Code:

• Marketplace "claude-plugins-official" not found: tambahkan marketplace dengan /plugin marketplace add anthropics/claude-plugins-official, kemudian coba ulang instalasi.
• Plugin tidak ditemukan di marketplace: periksa nama plugin.

Untuk mengaktifkan plugin untuk semua orang di repository daripada menginstalnya sendiri, tambahkan ke pengaturan proyek enabledPlugins.

Plugin code intelligence memerlukan biner language server bahasa di setiap mesin pengembang. Lihat biner mana yang diperlukan setiap bahasa. Menginstal dari marketplace resmi memerlukan akses jaringan ke GitHub, di mana marketplace dihosting. Di jaringan terbatas, tambahkan marketplace dari host Git internal atau jalur lokal sebagai gantinya.

Ini berpasangan baik dengan claudeMdExcludes dan aturan Read deny di atas. Mereka menjaga konten yang tidak relevan keluar dari konteks, dan code intelligence menjaga Claude dari membaca melalui apa yang tersisa untuk menemukan definisi.

Scope worktrees dan file access

Pengaturan ini mengontrol apa yang ada di disk di worktrees dan direktori mana Claude dapat membaca dan menulis di luar titik awal Anda.

Check out only the directories you need

Flag --worktree memulai sesi di worktree git baru sehingga perubahan tetap terisolasi dari checkout utama Anda. Secara default itu memeriksa seluruh repository. Dalam repository besar, pengaturan worktree.sparsePaths menggunakan git sparse-checkout untuk menulis hanya direktori yang terdaftar plus file level-root ke disk, sehingga worktrees dimulai lebih cepat dan menggunakan lebih sedikit ruang.

Jika semua orang yang bekerja di direktori ini memerlukan jalur yang sama, komitkan pengaturan ke .claude/settings.json. Untuk menambahkan jalur untuk diri sendiri, gunakan .claude/settings.local.json: daftar menggabung di seluruh scope, jadi file lokal dapat menambahkan jalur ke daftar berkomitmen tetapi tidak menghapusnya.

Contoh JSON pada halaman ini menunjukkan satu pengaturan sekaligus. Jika .claude/settings.json Anda sudah berisi kunci lain, seperti aturan permissions.deny di atas, tambahkan kunci worktree bersama mereka daripada mengganti file. Put it together menunjukkan hasil gabungan.

Contoh di bawah menunjukkan file berkomitmen:

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ]
  }
}

Ketika Claude membuat worktree, itu memeriksa hanya .claude/, packages/api/, dan packages/shared/ bukan pohon penuh. Jalur di sparsePaths relatif terhadap repository root, terlepas dari subdirektori mana Anda memulai Claude dari. Jalur direktori apa pun bekerja di sini, bukan hanya root paket.

Ini sangat berguna untuk isolasi worktree subagent. Subagent adalah instance Claude paralel yang dihasilkan untuk subtask, dan masing-masing yang berjalan di worktree mendapat checkout ringan bukan pohon penuh. Semua worktrees dalam sesi berbagi sparsePaths yang sama, jadi jika satu subagent memerlukan packages/api/ dan yang lain memerlukan packages/web/, daftarkan keduanya.

Daftarkan direktori di sparsePaths, bukan file individual. File level-root seperti package.json, tsconfig.base.json, dan file lock selalu diperiksa bersama direktori yang Anda daftarkan. Direktori level-root tidak, jadi sertakan .claude dalam daftar jika Anda menginginkan repository root's .claude/settings.json atau .claude/rules/ tersedia di dalam worktree. Untuk project skills, agents, dan commands, lihat What worktrees share with the main checkout.

Sparse checkout memerlukan git untuk mengaktifkan extensions.worktreeConfig di .git/config bersama repository saat worktree sparse ada. Claude Code menghapus entri itu setelah worktree terakhir dihapus, tetapi hanya jika Claude Code yang menambahkannya. Itu tidak pernah menghapus nilai yang Anda atur sendiri. Sebelum v2.1.207, entri tetap ada setelah worktree terakhir dihapus, dan alat berbasis go-git seperti tea gagal membuka repository sampai Anda menjalankan git config --unset extensions.worktreeConfig.

Untuk menghindari duplikasi direktori besar seperti node_modules di seluruh worktrees, pasangkan sparsePaths dengan symlinkDirectories di .claude/settings.json yang sama:

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": [
      "node_modules"
    ]
  }
}

Ini membuat symlink dari node_modules/ setiap worktree kembali ke salinan repository utama bukan menduplikasinya di disk.

Untuk referensi pengaturan worktree lengkap, lihat Worktree settings.

Grant access across packages or repositories

Bagian ini berlaku ketika Anda memulai Claude dari subdirektori, atau ketika tugas mencakup beberapa checkout. Jika Anda memulai dari repository root dalam pohon besar tunggal, Claude sudah memiliki akses ke setiap file dan Anda dapat melewati ini.

Ketika Anda memulai Claude dari packages/api/, itu dapat membaca dan menulis file dalam direktori itu. Jika tugas memerlukan perubahan di seluruh paket, seperti memperbarui tipe bersama yang diimpor oleh api dan web, Anda perlu memberikan akses ke direktori sibling. Mekanisme yang sama memberikan akses ke repository yang diperiksa secara terpisah.

Pengaturan additionalDirectories di .claude/settings.json memberikan Claude akses ke direktori di luar direktori kerja. Contoh di bawah memberikan akses ke dua paket sibling:

{
  "permissions": {
    "additionalDirectories": [
      "../shared",
      "../web"
    ]
  }
}

Jalur relatif diselesaikan terhadap direktori tempat Anda memulai Claude. Dengan konfigurasi ini, Claude dapat membaca dan mengedit file di packages/shared/ dan packages/web/ sambil bekerja dari packages/api/.

Anda juga dapat memberikan akses saat runtime tanpa mengedit pengaturan dengan melewatkan --add-dir ketika Anda memulai Claude:

claude --add-dir ../shared

Bagaimanapun Anda menambahkan direktori, Claude dapat membaca dan mengedit file di dalamnya. Apakah CLAUDE.md direktori, file .claude/rules/, dan skills juga dimuat tergantung pada cara Anda menambahkannya:

Untuk memuat file CLAUDE.md dan rules dari direktori yang ditambahkan dengan --add-dir atau /add-dir, atur variabel lingkungan CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD:

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

Variabel lingkungan tidak berpengaruh pada direktori yang terdaftar dalam pengaturan additionalDirectories. Lihat Load from additional directories untuk detail.

Untuk direktori sibling yang semua orang di area ini butuhkan, komitkan additionalDirectories ke .claude/settings.json. Untuk pilihan pribadi atau akses satu kali, gunakan .claude/settings.local.json atau lewatkan --add-dir saat peluncuran.

Tambahkan skills per-direktori

Subdirektori apa pun dapat mendefinisikan skills yang dibatasi pada stack-nya sendiri. Skill dimuat sesuai permintaan ketika Claude menentukan itu relevan, jadi tooling spesifik API tidak menghabiskan konteks selama pekerjaan frontend.

Skills hidup di bawah .claude/skills/ di dalam direktori. Komitkan mereka bersama kode area itu sehingga siapa pun yang mengkloning repository mendapatkannya. Dalam monorepo ini dapat menjadi satu set skills per paket. Dalam codebase pohon tunggal besar itu satu set per subsistem seperti src/db/.claude/skills/.

Buat direktori skill di dalam subdirektori:

mkdir -p packages/api/.claude/skills/api-testing

Kemudian tulis SKILL.md di dalam direktori itu, di sini packages/api/.claude/skills/api-testing/SKILL.md. Contoh ini mengajarkan Claude pola pengujian paket API:

---
name: api-testing
description: Pola pengujian untuk paket API. Gunakan saat menulis atau memodifikasi tes di packages/api/.
---

## Struktur tes

Tes berada di `src/__tests__/` mencerminkan struktur direktori `src/`.
Setiap file rute memiliki file `.test.ts` yang sesuai.

## Menjalankan tes

- Semua tes: `npm test`
- File tunggal: `npm test -- src/__tests__/routes/users.test.ts`
- Mode watch: `npm test -- --watch`

## Utilitas tes

- `src/__tests__/helpers/db.ts`: menyediakan `setupTestDb()` dan `teardownTestDb()` untuk tes database
- `src/__tests__/helpers/auth.ts`: menyediakan `createTestUser()` dan `getAuthToken()` untuk endpoint yang diautentikasi

## Pola

- Gunakan `supertest` untuk asersi HTTP, bukan fetch mentah
- Selalu bungkus tes database dalam transaksi yang rollback
- Mock layanan eksternal di `src/__tests__/mocks/`

Subdirektori berbeda memegang skills berbeda dengan cara yang sama: packages/web/.claude/skills/component-patterns/ menjelaskan konvensi komponen frontend bukan pengujian. Ketika Claude bekerja pada file di packages/api/, itu memuat skill api-testing. Ketika itu bekerja di packages/web/, itu memuat component-patterns sebagai gantinya. Tidak ada skill direktori yang dimuat selama tugas yang lain.

Anda juga dapat membatasi skill berdasarkan pola file bukan penempatan. Field frontmatter paths mengambil pola glob, dan Claude memuat skill secara otomatis hanya ketika bekerja dengan file yang cocok. Gunakan ini untuk skill yang hidup di .claude/skills/ repository root tetapi berlaku hanya untuk file tertentu di mana pun mereka muncul, seperti skill migrasi database yang dibatasi pada **/migrations/**.

Untuk lebih lanjut tentang membuat dan mengorganisir skills, lihat Skills.

Jaga skills tetap dapat ditemukan

Dengan skills tersebar di banyak direktori, daftar yang Claude pilih dari dapat tumbuh besar. Claude memilih skill dengan membaca nama dan deskripsi setiap skill yang ditemukan, dan hanya konten skill yang dipilih dimuat penuh ke dalam konteks. Bagian ini mencakup cara menjaga daftar itu tetap kecil.

Skill mana yang dalam scope tergantung pada di mana Anda memulai Claude:

• Dari subdirektori seperti packages/api/: skills dari direktori itu, setiap parent hingga repository root, dan level user dan enterprise
• Dari repository root: skills root, ditambah skills dari setiap subdirektori Claude sentuh selama sesi, yang dapat terakumulasi menjadi ratusan
• Setelah menambahkan sibling dengan --add-dir: skills sibling itu juga dimuat. Pengaturan additionalDirectories memberikan akses file saja dan tidak memuat skills

Nama selalu dimuat, tetapi ketika ada banyak, beberapa skills kehilangan deskripsi mereka sepenuhnya, yang dapat menghapus kata kunci Claude gunakan untuk memutuskan apakah skill berlaku. Jaga deskripsi tetap pendek dan pimpin dengan kata yang permintaan akan berisi, seperti "menulis atau memodifikasi tes di packages/api/".

Untuk skills yang banyak direktori bagikan, seperti konvensi PR atau checklist deploy, letakkan di .claude/skills/ repository root sehingga mereka dimuat dari direktori awal apa pun. Ketika shared skills memerlukan riwayat versi mereka sendiri atau harus bekerja di seluruh repositories, paketkan sebagai plugin sebagai gantinya. Plugin skills menggunakan namespace plugin-name:skill-name, jadi mereka tidak pernah bertabrakan dengan skills per-direktori. Tim platform dapat memversi dan memperbarui mereka di satu tempat.

Untuk menemukan skills mana yang tidak digunakan, aktifkan logs exporter OpenTelemetry dan atur OTEL_LOG_TOOL_DETAILS=1 sehingga nama skill dicatat verbatim bukan diredaksi. Event skill_activated mencatat setiap invokasi dalam atribut skill.name-nya, dan invocation_trigger mencatat apakah perintah, Claude, atau skill bersarang menginvokasinya, yang memberi tahu Anda apa yang harus dikonsolidasikan atau dihentikan.

Centralize conventions when layering stops scaling

File CLAUDE.md per-direktori dapat menjadi sulit untuk diatur seiring dengan pertumbuhan codebase. Konvensi melayang, file menjadi usang, dan tidak ada yang memiliki root. Menyelesaikan itu biasanya jatuh ke tim yang memelihara setup Claude Code repository bukan ke setiap pengembang yang bekerja di area mereka sendiri.

Pindahkan konvensi dan konten referensi keluar dari CLAUDE.md yang selalu dimuat dan ke mekanisme yang dimuat sesuai permintaan:

• Skills: materi referensi Claude dimuat hanya ketika relevan dengan tugas
• Plugins: bundel terversi dari skills, hooks, dan perintah yang tim platform miliki secara terpusat
• MCP servers: jika organisasi Anda sudah menjalankan pencarian kode atau indeks RAG di atas repository, eksposnya sebagai alat MCP sehingga Claude menanyainya bukan membaca file secara langsung

Lihat pengaturan yang dikelola server atau endpoint untuk bagaimana tim platform dapat memberlakukan ini secara terpusat.

Recommend the right plugin at session start

Setelah konvensi hidup di plugins, rekan kerja yang memulai Claude di bagian pohon yang tidak familiar tidak memiliki sinyal tentang plugin mana yang pemilik area itu pertahankan. Hook SessionStart dapat menutup kesenjangan itu, karena Claude Code menambahkan teks biasa yang hook cetak ke stdout ke konteks Claude sebelum prompt pertama.

Misalnya, Anda dapat menulis skrip yang membaca direktori peluncuran dari input hook, mencarinya dalam peta path-to-plugin yang berkomitmen ke repository, dan mencetak rekomendasi untuk Claude relay dalam balasan pertamanya. Lihat Automate actions with hooks untuk menulis dan mendaftarkan hook.

Put it together

Konfigurasi gabungan di bawah menggunakan tata letak monorepo. File yang sama bekerja untuk subdirektori apa pun dalam pohon tunggal besar. Setiap .claude/settings.json subdirektori harus mandiri daripada berlapis pada file root.

Contoh berkomitmen worktree, additionalDirectories, dan aturan deny Read di .claude/settings.json sehingga setiap pengembang di packages/api/ mendapat akses sibling yang sama, jalur sparse, dan pengecualian. File di bawah adalah pengaturan per-area berkomitmen untuk packages/api/:

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": [
      "node_modules"
    ]
  },
  "permissions": {
    "additionalDirectories": [
      "../shared"
    ],
    "deny": [
      "Read(./**/dist/**/*)",
      "Read(./**/build/**/*)"
    ]
  }
}

Karena sesi ini dimulai dari packages/api/, file CLAUDE.md paket sibling sudah keluar dari scope, jadi claudeMdExcludes tidak diperlukan di sini. Tambahkan ke .claude/settings.local.json repository root sebagai gantinya jika Anda juga memulai sesi dari root.

Entri additionalDirectories berlaku ketika Anda memulai Claude dari packages/api/ secara langsung. Di dalam worktree yang dibuat dari sesi ini, direktori kerja adalah worktree root, jadi file pengaturan ini tidak dimuat. Paket sibling sudah dapat dijangkau di dalam worktree tanpanya, tetapi aturan deny memerlukan salinan kedua di .claude/settings.json repository root sehingga sesi worktree mengambilnya, seperti catatan pengaturan worktree menjelaskan:

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**/*)",
      "Read(./**/build/**/*)"
    ]
  }
}

Setelah setup, repository memiliki tata letak ini:

monorepo/
  CLAUDE.md
  .claude/settings.json                           # aturan deny untuk sesi worktree
  packages/
    api/
      CLAUDE.md
      .claude/settings.json                       # worktree, additionalDirectories, aturan deny
      .claude/skills/api-testing/SKILL.md
    web/
      CLAUDE.md
      .claude/skills/component-patterns/SKILL.md
    shared/
      CLAUDE.md

Dengan setup ini, memulai Claude dari packages/api/:

• Memuat root CLAUDE.md dan packages/api/CLAUDE.md, melewati packages/web/CLAUDE.md
• Dapat membaca dan mengedit file di packages/api/ dan packages/shared/
• Melewati pembacaan output build di bawah dist/ dan build/ di packages/api/
• Memiliki skill api-testing tersedia sesuai permintaan
• Membuat worktrees yang berisi .claude/, packages/api/, packages/shared/, dan file level-root, dengan aturan deny diterapkan di seluruh worktree dari file pengaturan root

Scope and plan changes that span packages

Konfigurasi di atas mengontrol apa yang Claude lihat. Ketika perubahan tunggal menyentuh beberapa paket, seperti memperbarui tipe bersama bersama dengan setiap situs panggilan yang menggunakannya, bagaimana Anda membatasi dan mengurutkan tugas juga mempengaruhi hasilnya.

Dua teknik membantu menjaga perubahan lintas-paket konsisten:

• Berikan Claude seluruh perubahan dalam satu sesi: menyerahkan edit bersama dan situs panggilannya bersama-sama menjaga keputusan di balik setiap edit konsisten, bukan menurunkan mereka per paket
• Rencanakan sebelum mengedit: rencanakan terlebih dahulu dalam plan mode, dan Claude menulis rencana ke file. Sesi lintas-paket panjang mengompak konteksnya sepanjang jalan. Claude Code menyuntikkan kembali file rencana setelah setiap compaction, sehingga rencana bertahan di mana riwayat percakapan mungkin tidak

Langkah berikutnya

Setelah konfigurasi ini ada, Anda dapat menyempurnakannya:

• Gunakan hooks untuk menjalankan linter per-direktori atau type-checker setelah Claude mengedit file
• Tinjau Kelola biaya secara efektif untuk memahami bagaimana ukuran codebase mempengaruhi penggunaan token dan cara menetapkan batas pengeluaran sebelum rollout yang lebih luas
• Baca Bagaimana Claude Code bekerja dalam codebase besar di blog Claude untuk pola rollout organisasi dan model kepemilikan yang duduk di atas konfigurasi per-repository di halaman ini