Claude Code di monorepo dapat melenceng ketika repositori sangat besar. Pelajari batasan, ringkasan lokal, dan alur kerja yang dapat diulang untuk menjaga jawaban tetap tepat.
Claude Code di monorepo bisa terasa tidak terduga karena alasan sederhana: repositori lebih besar daripada yang bisa dimuat model ke dalam memori kerja sekaligus.
“Konteks” adalah kumpulan file, potongan kode, catatan, dan instruksi yang telah ditunjukkan ke Claude untuk tugas ini, plus apa yang bisa ia simpulkan dari hal-hal itu. Ketika detail penting hilang, Claude mengisi celah dengan tebakan. Dalam repo besar, itu terjadi lebih sering.
Tiga mode kegagalan muncul berulang kali:
Pertama, file yang terlewat. Perubahan yang terlihat aman di satu folder ternyata bergantung pada tipe bersama, aturan konfigurasi, atau langkah build yang didefinisikan di tempat lain. Jika dependensi itu tidak ada dalam konteks, Claude mungkin dengan yakin mengedit hal yang salah atau berhenti terlalu dini karena tidak melihat sumber kebenaran yang sebenarnya.
Kedua, kesamaan palsu. Monorepo sering berisi banyak paket yang tampak mirip: dua modul auth, tiga klien API, atau beberapa aplikasi React dengan struktur folder serupa. Claude bisa mencampur pola antar-paket, memperbarui helper di paket yang salah, atau mengimpor dari nama modul yang “hampir benar”.
Ketiga, drift waktu. Basis kode besar biasanya punya cara lama dan baru untuk melakukan hal yang sama. Jika Claude hanya melihat file yang lebih lama, ia bisa menyalin pola usang (opsi konfigurasi yang deprecated, API lama) meskipun tim telah beralih.
Contoh nyata: Anda meminta perubahan kecil pada UI billing, dan Claude mengedit komponen payments bersama yang dipakai oleh aplikasi lain karena ia tidak melihat pembungkus spesifik aplikasi yang sebenarnya seharusnya diubah.
Tujuannya bukan menunjukkan seluruh monorepo ke Claude. Tujuannya adalah memberi input yang lebih kecil dan disengaja yang tetap menjawab pertanyaan: paket yang Anda ubah, dependensi langsungnya, dan satu atau dua “sumber kebenaran” untuk tipe dan konfigurasi. Juga sebutkan area yang “jangan sentuh” (aplikasi lain, infra, kode yang dihasilkan) dan konfirmasi paket mana yang memiliki perilaku tersebut.
Akurasi bergantung lebih sedikit pada berapa banyak kode yang Anda tempelkan dan lebih pada seberapa jelas Anda menggambarkan pekerjaan.
Mulailah dengan hasil yang Anda inginkan: perbaikan spesifik, refactor, atau jawaban. Pertanyaan tingkat tinggi bisa dibiarkan umum. Permintaan “lakukan perubahan” perlu batasan, input, dan pemeriksaan keberhasilan.
Sebelum membagikan apa pun, tulis satu kalimat yang menyelesaikan frasa ini: “Setelah kamu selesai, saya harus bisa…”. Contoh: “menjalankan unit test untuk paket X tanpa kegagalan” atau “melihat field baru pada respons API untuk endpoint Y.” Kalimat itu menjadi bintang penunjuk arah saat repo sangat besar.
Untuk perubahan, bagikan himpunan artefak terkecil yang bisa membuktikan perubahan itu benar: titik masuk, tipe/interface atau schema relevan, satu tes yang gagal atau langkah repro dengan hasil yang diharapkan, dan konfigurasi apa pun yang memengaruhi jalur ini (routing, feature flag, build, atau aturan lint). Jika perlu, tambahkan peta folder singkat paket agar Claude memahami fungsi tiap direktori.
Jelaskan hal yang tidak boleh dilihat. Katakan: “Abaikan file yang dihasilkan, folder vendor, output build, snapshot, dan lockfile kecuali saya minta.” Itu mencegah waktu terbuang dan edit di tempat yang tidak akan Anda tinjau.
Tetapkan juga ekspektasi terhadap ketidakpastian. Minta Claude menandai asumsi dan hal yang tidak diketahui alih-alih menebak. Contoh: “Jika kamu tidak bisa melihat di mana fungsi ini dipanggil, katakan begitu dan usulkan 2 cara untuk menemukannya.”
Di monorepo besar, akurasi menurun ketika model mulai “membantu” dengan menarik kode di sekitarnya yang bukan bagian dari tugas. Solusinya sederhana: definisikan apa yang masuk cakupan dan apa yang keluar cakupan sebelum meminta perubahan.
Mulailah dengan batas yang cocok dengan organisasi repo Anda: sebuah paket, service, aplikasi, atau library bersama. Jika perubahan adalah “perbarui UI checkout,” batasnya mungkin satu paket aplikasi, bukan setiap tempat kata “checkout” muncul.
Sinyal yang membantu Claude tetap di tempatnya meliputi konvensi folder (apps/, services/, packages/, libs/), manifest paket (exports dan dependencies), titik masuk publik (file index, komponen yang diekspor, handler), dan tes (sering mengungkap area permukaan yang dimaksud). README di dalam folder bisa menjadi penanda batas yang cepat.
Batas bekerja paling baik ketika Anda menamai jembatan antar-batas itu. Sebutkan antarmuka spesifik yang boleh disentuh dan anggap semua hal lain sebagai batas. Jembatan umum adalah kontrak API HTTP, topik dan payload event, tipe bersama, atau sekumpulan kecil fungsi yang diekspor.
Sebutkan juga zona “jangan sentuh” saat perubahan tidak dimaksudkan memengaruhi mereka. Yang umum: konfigurasi infrastruktur dan deployment, logika keamanan dan auth, billing dan pembayaran, migrasi data dan skema produksi, serta library bersama yang dipakai banyak tim.
Rincian prompt konkret yang membantu:
“Lakukan perubahan hanya di dalam packages/cart/ dan test-nya. Kamu boleh membaca tipe bersama di packages/types/ tetapi jangan mengubahnya. Jangan edit infra, auth, atau billing.”
Akurasi meningkat ketika Anda menyediakan peta kecil dan stabil dari area yang ingin diubah. “Ringkasan lokal” adalah peta itu: cukup singkat untuk dibaca cepat, cukup spesifik untuk mencegah tebakan.
Jaga setiap ringkasan sekitar 10–20 baris. Tulis seolah-olah Anda menyerahkan kode kepada rekan baru yang hanya perlu menyentuh batas ini, bukan seluruh repo. Gunakan bahasa sederhana dan nama asli dari kode: folder, paket, fungsi yang diekspor.
Ringkasan lokal yang berguna menjawab lima pertanyaan:
Tambahkan satu baris “gotchas”. Di sinilah Anda mencegah kesalahan mahal: cache tersembunyi, feature flag, langkah migrasi, dan apa pun yang bisa rusak tanpa disadari.
Berikut template ringkas yang bisa Anda salin:
Local summary: <package/service name>
Purpose: <1 sentence>
Scope: <what to touch> | Not: <what not to change>
Entry points: <files/routes/commands>
Public surface: <exports/endpoints/events>
Data sources: <tables/collections/queues/caches>
Conventions: errors=<how>, logging=<how>, tests=<where/how>
Gotchas: <flags/caching/migrations/edge cases>
Contoh: jika Anda mengedit paket billing, catat fungsi tepat yang membuat invoice, nama tabel yang ditulis, dan aturan untuk error yang bisa di-retry. Lalu Claude bisa fokus pada batas itu alih-alih berkeliaran ke auth bersama, konfigurasi, atau paket tak terkait.
Ringkasan terbaik adalah yang Claude lihat saat membutuhkannya. Letakkan di samping kode yang dijelaskan sehingga sulit diabaikan dan mudah di-update. Misalnya, simpan SUMMARY.md singkat (atau bagian README.md) di dalam setiap paket, service, atau app daripada satu dokumen raksasa di akar repo.
Struktur yang sederhana dan dapat diulang membantu. Buat cukup singkat sehingga orang mau memeliharanya:
YYYY-MM-DD - <apa yang berubah dalam satu kalimat>Ringkasan menjadi usang karena alasan yang dapat diprediksi. Perlakukan pembaruan seperti memperbarui definisi tipe: bagian dari menyelesaikan pekerjaan, bukan tugas terpisah.
Perbarui ringkasan saat refactor mengubah struktur atau nama, modul baru menjadi cara utama melakukan sesuatu, API/event/schema berubah (meskipun tes masih lulus), batas antar-paket bergeser, atau dependensi dihapus/diganti.
Kebiasaan praktis: ketika Anda merge perubahan, tambahkan satu baris “Last updated” yang menyatakan apa yang berubah. Alat seperti Koder.ai dapat membantu mempercepat perubahan kode, tetapi ringkasan adalah yang menjaga perubahan di masa depan tetap akurat.
Akurasi sering tergantung pada bagaimana Anda mengatur percakapan. Buat Claude “mendapat” konteks dalam potongan kecil daripada menebak dari snapshot besar.
Sebelum mengedit, minta Claude menjelaskan apa yang dilihatnya dan apa yang dibutuhkan. Peta yang baik singkat: paket kunci yang terlibat, titik masuk alur, dan tempat tes atau tipe berada.
Prompt:
“Buat peta perubahan ini: paket yang terlibat, alur utama, dan kemungkinan titik sentuh. Jangan ajukan kode dulu.”
Pilih irisan sempit: satu fitur, satu paket, satu alur pengguna. Nyatakan batasnya dengan jelas (mis. “Hanya ubah packages/billing-api. Jangan sentuh shared-ui atau infra.”).
Alur kerja yang menjaga Anda tetap mengendalikan:
Jika Claude kekurangan sesuatu, ia harus mengatakannya. Minta dia menulis: (1) asumsi yang dibuat, (2) apa yang membuktikan asumsi salah, dan (3) file berikutnya yang diperlukan untuk mengonfirmasi.
Contoh: Anda perlu menambah field ke respons Invoice di satu paket. Claude meminta handler, definisi DTO/tipe, dan satu tes. Anda bagikan hanya itu. Jika Anda menggunakan builder berbasis chat seperti Koder.ai, aturan yang sama berlaku: beri himpunan file terkecil, lalu perluas hanya jika benar-benar diperlukan.
Pertahanan terbaik terhadap edit yang keliru adalah “kontrak” kecil yang tertulis dalam prompt: apa yang boleh disentuh, bagaimana Anda menilai keberhasilan, dan aturan yang harus diikuti.
Mulailah dengan batas yang mudah dipatuhi dan diverifikasi. Jelaskan secara eksplisit tempat edit diizinkan, dan sebutkan zona “jangan sentuh” agar tidak tergoda menjelajah.
Template kontrak:
packages/payments/.packages/auth/, infra/, atau konfigurasi bersama.Lalu definisikan pengecekan penerimaan. Tanpanya, Claude bisa menghasilkan kode yang tampak benar tetapi melanggar aturan repo.
Kendala gaya juga penting. Beritahu Claude pola yang harus diikuti dan yang harus dihindari, berdasarkan apa yang sudah ada di codebase. Contoh: “Gunakan helper error yang ada di paket ini; jangan tambahkan dependency baru; pakai camelCase untuk nama fungsi; jangan perkenalkan lapisan arsitektur baru.”
Akhirnya, wajibkan rencana singkat sebelum mengedit:
“Sebelum mengedit, sebutkan 3–5 file yang akan disentuh dan perubahan perilaku yang tepat. Tunggu persetujuan.”
Contoh:
“Perbaiki pembulatan pada total invoice. Hanya ubah packages/billing/src/ dan test di packages/billing/test/. Penerimaan: pnpm -C packages/billing test dan typecheck. Gunakan money utils yang ada; jangan ubah tipe API. Beri rencana 4 langkah dulu.”
Cara tercepat mendapatkan edit yang salah di monorepo adalah memberi Claude terlalu banyak sekaligus. Ketika Anda menempelkan tumpukan kode besar, ia sering kembali ke pola generik alih-alih desain spesifik yang sudah ada di repo Anda.
Perangkap lain adalah membiarkannya menebak arsitektur. Jika Anda tidak menunjukkan titik masuk yang nyata, ia mungkin memilih file pertama yang tampak masuk akal dan memasang logika di sana. Dalam praktiknya, akurasi datang dari sekumpulan kecil file “sumber kebenaran” (modul entry, router, registri service, dokumen batas paket). Jika itu tidak ada dalam konteks, model mengisi celah.
Nama juga bisa menipu. Monorepo sering punya paket seperti ui, ui-kit, shared-ui, atau helper yang diduplikasi seperti date.ts di dua tempat. Jika Anda mencampur potongan dari keduanya, Claude bisa mempatch satu file sambil menalar tentang yang lain. Contoh: Anda minta mengubah style tombol, ia mengedit packages/ui/Button.tsx, tetapi aplikasi mengimpor packages/ui-kit/Button.tsx. Diff terlihat baik, tapi tidak ada perubahan di produksi.
Konfigurasi adalah sumber drift lain yang diam-diam. Perilaku bisa bergantung pada env var, feature flag, pengaturan build, atau tooling workspace. Jika Anda tidak menyebutkannya, Claude bisa menghapus pemeriksaan “aneh” yang hanya penting ketika flag aktif, atau menambahkan kode yang merusak langkah build.
Tanda-tanda Anda sedang drift:
Anggap import lintas-paket sebagai keputusan, bukan default. Pertahankan edit lokal kecuali Anda sengaja memperluas cakupan.
Cara tercepat mendapatkan edit yang benar adalah memulai dengan batasan, bukan volume. Prompt yang baik terasa agak ketat: memberi tahu Claude tempat melihat, apa yang diabaikan, dan apa arti “selesai”.
Sebelum menempelkan kode, tulis prefasi singkat yang mematok pekerjaan ke satu tempat di repo. Sebut paket, folder yang tepat, dan tujuan spesifik. Lalu sertakan ringkasan lokal (tujuan, dependensi kunci, konvensi penting) dan file entry yang menjadi jangkar perubahan.
Checklist:
\u003cpackage\u003e/\u003cpath\u003e. Tujuan: \u003cone sentence\u003e. Abaikan semua kecuali diminta.\u003c5-10 lines\u003e. File entry: \u003cpath/to/file\u003e.\u003c...\u003e. Jangan ubah: \u003cfolders/files or APIs\u003e. Pertahankan perilaku: \u003cwhat must stay true\u003e.Jika Claude mengusulkan perubahan di luar batas Anda, anggap itu sinyal: kencangkan prompt, atau perluas batas dengan sengaja dan nyatakan kembali dengan jelas.
Misal monorepo Anda punya apps/web-store (aplikasi React) dan packages/ui-kit (button, input, style bersama). Anda ingin fitur kecil: menambahkan tombol “Save for later” di halaman cart, menggunakan SaveIcon baru dari ui-kit. Tidak ada yang lain boleh berubah.
Sebelum meminta edit, buat dua ringkasan lokal sebagai batas. Jaga singkat, spesifik, dan tegas tentang apa yang penting.
# apps/web-store/LOCAL_SUMMARY.md
Purpose: Customer shopping UI.
Entry points: src/routes.tsx, src/pages/cart/CartPage.tsx
Cart rules: cart state lives in src/cart/useCart.ts
Do not touch: checkout flow (src/pages/checkout), payments, auth.
Tests: npm test -w apps/web-store
# packages/ui-kit/LOCAL_SUMMARY.md
Purpose: shared UI components.
Exports: src/index.ts
Icons: src/icons/*, add new icons by exporting from index.
Do not touch: theming tokens, build config.
Tests: npm test -w packages/ui-kit
Lalu jaga loop tetap singkat:
CartPage dan ikon ui-kit. Tidak ada edit checkout/auth.”CartPage, useCart, ikon ui-kit, index ui-kit).Setelah perubahan, dokumentasikan agar konteks masa depan tetap kecil:
Jika cara ini berhasil untuk satu orang tapi tidak bagi tim, biasanya yang hilang adalah pengulangan. Jadikan “kebersihan konteks” sebagai default, bukan kebiasaan pribadi.
Simpan satu kerangka prompt yang bisa disalin dan diisi semua orang. Buat singkat tapi ketat. Sertakan tujuan (apa arti “selesai”), cakupan yang diizinkan, batas keras (dan alasannya), ringkasan lokal, dan kontrak keluaran (rencana dulu, lalu edit bergaya diff dan tes).
Lewati review besar bulanan yang tidak pernah dilakukan. Lampirkan pembaruan ringkasan ke pekerjaan normal: ketika perubahan mengubah perilaku, dependensi, atau API, perbarui ringkasan lokal di PR yang sama.
Aturan sederhana: jika rekan kerja akan bertanya “di mana ini berada?” atau “apa yang bergantung pada ini?”, ringkasan sudah usang.
Jika Anda lebih suka alur kerja chat-first, Koder.ai dapat membantu membuat iterasi gaya ini lebih aman. Mode perencanaan membantu menyepakati cakupan dan batas sebelum perubahan terjadi, dan snapshot dengan rollback memungkinkan Anda mencoba perubahan tanpa terjebak saat tebakan ternyata salah.
Claude menjadi kurang akurat ketika ia tidak dapat “melihat” sumber kebenaran yang sebenarnya.
Dalam monorepo besar, model seringkali melewatkan file dependensi, membingungkan dua paket yang mirip, atau menyalin pola lama karena itulah yang ada dalam konteks.
Jangan mencoba memasukkan seluruh repositori. Mulailah dengan himpunan terkecil yang dapat membuktikan perubahan tersebut benar.
Default yang baik:
Bagikan apa yang menjadi jangkar perilaku, bukan semua yang sekadar punya nama mirip.
Set praktis:
Pilih satu batas yang sesuai dengan organisasi repo Anda: sebuah paket, aplikasi, atau service.
Lalu nyatakan secara eksplisit apa yang di luar cakupan. Contoh batasan:
packages/cart/ dan test-nya.”Karena monorepo sering berisi modul yang mirip (ui, ui-kit, shared-ui) dan helper yang diduplikasi (date.ts di beberapa tempat).
Claude bisa menerapkan ide yang benar ke paket yang salah, atau mengimpor dari modul yang “hampir benar”. Cegah ini dengan menyebutkan paket dan titik masuk yang tepat.
Ringkasan lokal adalah peta singkat dari area yang Anda ingin ubah, biasanya 10–20 baris.
Cantumkan:
Letakkan di dekat kode yang dijelaskan sehingga mudah ditemukan dan di-update.
Default sederhana:
SUMMARY.md atau bagian kecil di README.md paketBeritahu Claude sejak awal untuk menandai asumsi dan hal yang belum diketahui daripada menebak.
Aturan berguna:
Gunakan loop ketat yang memaksa konteks didapatkan secara bertahap:
Tulis ‘kontrak’ mini dalam prompt dan jadikan dapat ditegakkan:
Ini memudahkan review dan mengurangi perubahan lintas-paket yang tidak disengaja.