# Claude Code di Monorepo: CLAUDE.md Bertingkat dan Skill

> Berkas memori bertingkat, skill per direktori, worktree untuk kerja paralel, dan pencarian yang tidak membaca seluruh repo — menjalankan agen di monorepo besar.

URL: https://www.matthewswong.com/id/blog/claude-code-monorepo-workflow/

- Author: Matthews Wong (https://www.matthewswong.com/id/about/)
- Published: 2026-08-18
- Updated: 2026-08-18
- Category: AI

> **Key takeaway:** Monorepo mematahkan satu CLAUDE.md tunggal karena tidak ada satu himpunan konvensi yang benar di mana-mana. Struktur yang berhasil adalah berkas memori root yang pendek, berkas tingkat paket di sebelah tiap aplikasi, prosedur yang dipindahkan ke skill, dan git worktree terpisah agar agen paralel tidak pernah menyunting working tree yang sama.

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.

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.

*Distribusi yang sama seperti yang sudah dimiliki kodenya. Kolom kanan adalah intinya: setiap lapisan punya biaya berbeda, jadi taruh sebuah aturan di tempat yang biayanya sepadan dengan seberapa sering ia berlaku.*

## 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.

> Tuliskan perintah build dan tes tiap paket ke berkas memori paket itu, persis seperti yang Anda ketik. Sebagian besar giliran terbuang di monorepo adalah agen menebak filter workspace atau mantra task runner mana yang berlaku di sini.

## 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.

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.

> Jangan mengarahkan dua agen ke paket yang sama di worktree berbeda. Keduanya akan menghasilkan dua refactor yang sama-sama masuk akal atas berkas yang sama, dan hasil merge-nya lebih buruk daripada salah satunya. Pisahkan berdasarkan paket atau berdasarkan urusan, jangan berdasarkan ambisi.

*Jaring pengaman sesungguhnya sebuah monorepo. Apa pun yang diubah agen secara lokal, pipeline-lah yang membuktikan ia tidak merusak sebelas paket yang tidak pernah ia buka — karena itulah pekerjaan agen harus menargetkan pipeline yang hijau, bukan tes lokal yang hijau. Diagram:*

## 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.

## Sumber dan bacaan lanjutan

- Dokumentasi Claude Code: memory dan CLAUDE.md
- Dokumentasi Claude Code: skills
- Dokumentasi Claude Code: subagents
- Dokumentasi Claude Code: mengelola biaya secara efektif
- Dokumentasi Git: git worktree

## Source links

- https://code.claude.com/docs/en/memory
- https://code.claude.com/docs/en/skills
- https://code.claude.com/docs/en/sub-agents
- https://code.claude.com/docs/en/costs
- https://git-scm.com/docs/git-worktree

## FAQ

### Monorepo sebaiknya punya satu CLAUDE.md atau beberapa?

Beberapa. Simpan berkas root yang pendek untuk hal yang benar di mana-mana — repo ini apa, cara membangunnya, aturan kerasnya — dan taruh konvensi khusus paket di berkas memori di sebelah tiap paket. Berkas memori bersifat komposabel, jadi agen mengambil konvensi area yang sedang ia kerjakan.

### Seberapa panjang sebaiknya berkas memori root?

Cukup pendek sehingga Anda rela membayarnya di setiap sesi, karena memang begitu: ia dimuat di awal sesi apa pun yang Anda kerjakan. Panduan resminya menyarankan di bawah sekitar dua ratus baris dan memindahkan instruksi alur kerja yang detail ke skill yang hanya dimuat saat dipanggil.

### Bagaimana mencegah agen membaca separuh repositori?

Bersikaplah spesifik dalam permintaan, pasang code intelligence untuk bahasa bertipe agar lompat-ke-definisi menggantikan pembacaan berkas spekulatif, delegasikan pencarian luas ke subagent yang konteksnya menyerap tumpahan berkas, dan beri tiap paket ikhtisar satu paragraf agar agen tidak perlu menyimpulkannya sendiri.

### Apakah git worktree sepadan di monorepo?

Sepadan untuk dua atau tiga tugas bersamaan, dengan satu catatan: tiap worktree butuh dependensi terpasang sendiri dan keluaran build sendiri, jadi pemakaian disk dan waktu instalasi berlipat. Lebih dari sekitar tiga, biaya penyiapannya melampaui manfaat paralelismenya. Jangan pernah mengarahkan dua agen ke paket yang sama di worktree berbeda.

### Apa yang pantas di berkas memori versus di aturan lint?

Kalau mesin bisa memeriksanya, mesinlah yang harus. Format, urutan impor, dan aturan dependensi antar paket adalah milik formatter, linter, dan pemeriksaan build. Berkas memori sebaiknya memuat hal yang hanya bisa diberitahukan manusia: kenapa sebuah paket ada, apa yang tidak boleh ia lakukan, dan keputusan mana yang sudah final.

---

- HTML version: https://www.matthewswong.com/id/blog/claude-code-monorepo-workflow/
- English: https://www.matthewswong.com/en/blog/claude-code-monorepo-workflow/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json
