Claude Code di monorepo besar: batasi konteks dan pertahankan akurasi

Mengapa monorepo besar membuat Claude kurang akurat

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.

Mulai dengan mendefinisikan tugas, bukan repo

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

Gambarkan batas yang jelas yang tidak boleh dilanggar Claude

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

Cara menulis ringkasan lokal yang berguna

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:

• Untuk apa paket/service ini, dan untuk apa bukan (batas ruang lingkup)
• Di mana kerja dimulai (titik masuk seperti file utama, route, command, atau komponen)
• Apa yang aman dipanggil dari luar (API publik, modul yang diekspor, event, endpoint)
• Apa yang menjadi dependensinya (database, queue, cache, config, layanan eksternal)
• Aturan apa yang penting di sini (pola penamaan, gaya error, logging, dan cara menulis tes)

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.

Di mana ringkasan disimpan dan bagaimana menjaganya tetap mutakhir

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:

• Apa folder ini (tujuan dalam 1–2 kalimat)
• Permukaan publik (titik masuk utama, modul yang diekspor, atau API)
• Dependensi kunci (internal dan eksternal)
• Batas (apa yang tidak boleh di-import atau diubah)
• Cara mengetes (cek lokal tercepat)
• Last updated: 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.

Alur kerja langkah-demi-langkah untuk tetap berada dalam konteks yang benar

Akurasi sering tergantung pada bagaimana Anda mengatur percakapan. Buat Claude “mendapat” konteks dalam potongan kecil daripada menebak dari snapshot besar.

Langkah 1: Minta peta singkat dulu

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

Langkah 2: Mulai dengan satu irisan dan satu batas

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:

• Definisikan tujuan dan batas dalam satu kalimat.
• Wajibkan asumsi dan hal yang tidak diketahui (Claude harus mencantumkannya).
• Minta file yang tepat yang dibutuhkan berikutnya (batasi ke 3–6).
• Berikan hanya file-file itu, lalu ulangi.
• Wajibkan rencana singkat sebelum patch apa pun.

Langkah 3: Paksa asumsi eksplisit dan permintaan file

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.

Gunakan batasan dan kontrak dalam prompt Anda

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:

• Hanya modifikasi file di bawah packages/payments/.
• Jangan edit packages/auth/, infra/, atau konfigurasi bersama.
• Jika perlu perubahan di luar cakupan, berhenti dan minta izin.
• Jaga perubahan minimal: perbaiki bug, hindari refactor.

Lalu definisikan pengecekan penerimaan. Tanpanya, Claude bisa menghasilkan kode yang tampak benar tetapi melanggar aturan repo.

• Jalankan unit test untuk paket (sebutkan perintah yang dipakai).
• Jalankan lint/format (sebutkan tool, atau katakan “gunakan konfigurasi yang ada”).
• Jalankan typecheck/build untuk paket.
• Konfirmasi aplikasi masih bisa dijalankan (cukup dengan perintah run sederhana).

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

Perangkap umum yang menyebabkan drift dan edit yang salah

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:

• Jawaban berbicara tentang “pola umum” tanpa menyebut file nyata Anda
• Mengenalkan utilitas bersama baru alih-alih menggunakan yang ada
• Mengubah import melintasi batas paket
• Mengabaikan feature flag atau cabang khusus env
• Menyarankan menambah dependency ke paket inti bersama

Anggap import lintas-paket sebagai keputusan, bukan default. Pertahankan edit lokal kecuali Anda sengaja memperluas cakupan.

Daftar periksa cepat sebelum Anda meminta apa pun ke Claude

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:

• Batas: Kerjakan hanya di \u003cpackage\u003e/\u003cpath\u003e. Tujuan: \u003cone sentence\u003e. Abaikan semua kecuali diminta.
• Pemicu konteks: Ringkasan lokal: \u003c5-10 lines\u003e. File entry: \u003cpath/to/file\u003e.
• Kendala: Folder yang diizinkan: \u003c...\u003e. Jangan ubah: \u003cfolders/files or APIs\u003e. Pertahankan perilaku: \u003cwhat must stay true\u003e.
• Permintaan file dahulu: “Sebelum mengusulkan perubahan, sebutkan file minimal yang perlu dilihat (maks 5) dan alasannya.”
• Format keluaran: “Balas dengan rencana singkat dulu. Setelah saya konfirmasi, berikan saran bergaya patch per file.”

Jika Claude mengusulkan perubahan di luar batas Anda, anggap itu sinyal: kencangkan prompt, atau perluas batas dengan sengaja dan nyatakan kembali dengan jelas.

Contoh: melakukan perubahan di satu paket tanpa membangunkan seluruh monorepo

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:

1. Peta: “Perubahan ini terbatas pada CartPage dan ikon ui-kit. Tidak ada edit checkout/auth.”
2. Asumsi: minta daftar asumsi dan tunggu konfirmasi.
3. Permintaan file: setujui hanya file yang benar-benar diperlukan (CartPage, useCart, ikon ui-kit, index ui-kit).
4. Rencana: konfirmasi cocok dengan batas.
5. Edit: buat diff sekecil mungkin, lalu minta tes yang diperbarui.

Setelah perubahan, dokumentasikan agar konteks masa depan tetap kecil:

• Perbarui kedua ringkasan lokal dengan export baru dan file yang disentuh.
• Tambahkan catatan singkat di header halaman cart: apa yang dilakukan tombol dan di mana state diurus.
• Catat perintah tes yang lulus (dan snapshot yang diperbarui bila ada).

Langkah berikutnya: buat ini dapat diulang untuk tim Anda

Jika cara ini berhasil untuk satu orang tapi tidak bagi tim, biasanya yang hilang adalah pengulangan. Jadikan “kebersihan konteks” sebagai default, bukan kebiasaan pribadi.

Ubah prompt terbaik Anda menjadi template tim

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

Jaga ringkasan mutakhir dengan ritme ringan

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.