Claude Code di Monorepo: CLAUDE.md Bertingkat dan Skill

Nasihat tentang agentic coding kebanyakan ditulis untuk repositori satu layanan, di mana satu berkas memori masuk akal menggambarkan seluruh proyek. Monorepo langsung mematahkan asumsi itu: front end dan API berbeda pendapat soal pengujian, dua paket punya aturan lint berbeda, dan proses rilis hanya berlaku untuk satu dari dua belas paket.

Menuliskan semuanya ke dalam satu berkas root menghasilkan dokumen yang tak seorang pun rawat dan dibayar setiap sesi. Alternatifnya adalah mendistribusikan pengetahuan dengan cara yang sama seperti kode didistribusikan.

Kenapa satu berkas memori berhenti bekerja

Tiga masalah terpisah muncul begitu sebuah repositori punya lebih dari beberapa paket independen.

• Konvensinya bertabrakan. Aturan yang benar untuk API menjadi salah untuk design system, dan berkas yang memuat keduanya memaksa agen memilih.
• Biayanya konstan. Berkas memori root dimuat di awal setiap sesi, jadi instruksi untuk paket yang tidak Anda sentuh tetap dibayar.
• Ia usang tanpa terlihat. Tak seorang pun meninjau berkas instruksi lima ratus baris di dalam pull request, jadi ia melenceng dari kode yang digambarkannya.

Panduan resminya menyarankan menjaga berkas memori yang selalu dimuat tetap berisi hal esensial saja — kira-kira dua ratus baris — dan memindahkan instruksi khusus ke skill yang dimuat sesuai kebutuhan. Di monorepo, nasihat itu bukan opsional, itu satu-satunya yang bisa berskala.

Tata letak yang bekerja

Berkas memori bersifat komposabel: Claude Code membaca lapisan enterprise, user, dan project, dan berkas di dalam subdirektori berlaku ketika pekerjaan terjadi di sana. Itu persis bentuk yang dibutuhkan monorepo.

monorepo/
  CLAUDE.md                  # short: what the repo is, how to build, hard rules
  apps/
    web/CLAUDE.md            # Next.js conventions, only loaded for web work
    api/CLAUDE.md            # NestJS conventions, module layout, test command
  packages/
    ui/CLAUDE.md             # component rules, story requirements
    domain/CLAUDE.md         # invariants that must never be broken
  .claude/
    skills/
      release/SKILL.md       # the release runbook, invoked on demand
      migration/SKILL.md     # how to write and verify a DB migration

# Root CLAUDE.md stays under a couple of hundred lines. Everything that
# is only true inside one package lives next to that package, and
# everything procedural becomes a skill that loads when it is needed.

Aturan yang saya pakai untuk memutuskan tempat sesuatu: kalau benar di mana-mana, taruh di root; kalau benar di dalam satu paket, taruh di sebelah paket itu; kalau berupa prosedur berlangkah, jadikan skill. Apa pun yang tidak cocok dengan ketiganya biasanya konvensi yang seharusnya ditegakkan linter alih-alih dijelaskan dalam prosa.

Mencari tanpa membaca seluruh repositori

Di repositori besar, kegagalan bawaannya adalah biaya eksplorasi — agen mem-grep, membuka lima berkas kandidat, dan separuh konteks Anda habis sebelum ada kode yang ditulis. Empat hal memperbaiki sebagian besarnya.

• Pasang code intelligence untuk bahasa bertipe. Satu lompat-ke-definisi menggantikan pencarian plus beberapa pembacaan berkas spekulatif, dan language server yang terpasang melaporkan error tipe setelah penyuntingan.
• Bersikaplah spesifik. Permintaan yang menyebut berkas dan fungsinya berbiaya sebagian kecil dari permintaan yang berbunyi perbaiki alur checkout.
• Delegasikan pencarian luas ke subagent, agar tumpahan isi berkas tinggal di konteksnya dan hanya kesimpulan yang kembali.
• Beri setiap paket ikhtisar satu paragraf di berkas memorinya sendiri. Murah untuk dimuat, dan itu menghapus satu putaran eksplorasi utuh.

Bersama-sama, keempatnya mengubah bentuk sebuah sesi: lebih sedikit membaca, lebih cepat menyunting, dan context window yang masih lapang saat keputusan menarik akhirnya tiba.

Worktree, bukan branch, untuk kerja paralel

Menjalankan dua agen dalam satu working tree adalah race condition dengan antarmuka yang manis. Git worktree memberi tiap tugas checkout-nya sendiri dari repositori yang sama, dan itu isolasi termurah yang mungkin.

# One worktree per task keeps two agents from editing the same file.
git worktree add ../repo-invoices -b feature/invoice-pdf
git worktree add ../repo-flaky   -b fix/flaky-order-test

# Each directory is a normal checkout with its own node_modules and its
# own Claude Code session. Nothing is shared except the object store.
cd ../repo-invoices && claude
cd ../repo-flaky    && claude

# When the branch lands, remove the worktree rather than deleting the folder.
git worktree remove ../repo-flaky

Di monorepo ada satu catatan yang layak direncanakan: tiap worktree butuh dependensi terpasang sendiri dan keluaran build sendiri, jadi ruang disk dan waktu instalasi berlipat. Dua atau tiga worktree bersamaan biasanya titik manisnya; lebih dari itu biaya penyiapannya melampaui manfaat paralelismenya.

Apa yang sebaiknya ditegakkan secara mekanis

Instruksi berbentuk prosa adalah alat yang lemah untuk aturan yang bisa diperiksa mesin. Di monorepo rasionya makin penting, karena aturannya lebih banyak dan tempat melanggarnya juga lebih banyak.

• Format dan urutan impor adalah milik formatter, bukan milik satu paragraf di berkas memori.
• Aturan impor antar paket adalah milik aturan lint atau pemeriksaan graf dependensi yang menggagalkan build.
• Apa pun yang berbiaya nyata — migrasi, rilis, perubahan skema — adalah milik skill berlangkah, agar prosedurnya diikuti alih-alih diingat-ingat.

Berkas memorinya lalu menyusut menjadi hal yang hanya bisa diberitahukan manusia: kenapa paket ini ada, apa yang tidak boleh ia lakukan, dan keputusan mana yang sudah final.

Mengadopsi ini di monorepo yang sudah ada

Anda tidak butuh migrasi besar. Urutan ini memberi manfaat pada sore hari pertama.

1. Pangkas berkas memori root menjadi hal esensial dan catat apa yang Anda buang.
2. Pindahkan setiap bagian yang dibuang ke sebelah paket yang digambarkannya, sebagai berkas memori kecil di sana.
3. Ubah dua atau tiga prosedur nyata — rilis, migrasi, insiden — menjadi skill.
4. Tambahkan perintah build dan tes per paket, lalu bekerjalah seminggu dan tambahkan apa pun yang terus ditebak salah oleh agen.

Langkah terakhir itulah yang berbunga. Isi terbaik untuk berkas-berkas ini tidak ditulis di muka; ia adalah koreksi yang Anda dapati sendiri mengetiknya untuk kedua kali.

Monorepo tidak butuh berkas instruksi yang lebih besar, ia butuh distribusi pengetahuan yang sama seperti yang sudah dimiliki kodenya. Root yang pendek, paket ber-scope, prosedur sebagai skill, isolasi lewat worktree, dan aturan mekanis yang ditegakkan perkakas — dengan itu semua di tempatnya, agen berperilaku seperti developer yang tahu ia sedang berdiri di bagian mana dari repositori.