Monorepolarda Claude Code: bağlamı sınırlama ve doğruluğu koruma

Neden büyük monorepolar Claude'ı daha az doğru yapar

Monorepolarda Claude Code tahmin edilemez hissi verebilir; bunun basit bir nedeni var: depo, modelin aynı anda tutabileceğinden daha büyüktür.

“Bağlam”, Claude'a bu görev için gösterilen dosyalar, kod parçacıkları, notlar ve talimatların tümü ile bunlardan çıkarılabilecek çıkarımlardır. Önemli ayrıntılar eksik olduğunda Claude boşlukları tahminlerle doldurur. Büyük bir repoda bu daha sık olur.

Tekrar eden üç hata modu şunlardır:

İlk olarak, kaçırılan dosyalar. Bir klasörde güvenli görünen bir değişiklik aslında paylaşılan bir tipe, bir yapılandırma kuralına veya başka bir yerde tanımlı bir build adımına bağımlı olabilir. O bağımlılık bağlamda yoksa Claude yanlış şeyi kendinden emin şekilde düzenleyebilir ya da gerçek kaynağı göremediği için erken durabilir.

İkincisi, yanlış benzerlik. Monorepolar genellikle birbirine benzeyen birden çok paket içerir: iki auth modülü, üç API client veya benzer klasör yapısına sahip birkaç React uygulaması. Claude desenleri karıştırabilir, yanlış pakette bir yardımcıyı güncelleyebilir veya “neredeyse doğru” modül adından import edebilir.

Üçüncü, zaman sapması. Büyük kod tabanlarında aynı işi yapan eski ve yeni yollar genellikle yan yana bulunur. Claude sadece eski dosyaları görürse (çünkü bağlamda onlar vardır), ekip ilerlemiş olsa bile eski desenleri (tükenmiş config seçenekleri, eskimiş API'ler) kopyalayabilir.

Gerçek bir örnek: faturalama UI'sında küçük bir değişiklik istersiniz ve Claude, değiştirilmesi gereken uygulamaya özgü sarmalayıcıyı hiç görmediği için diğer uygulamalar tarafından kullanılan ortak bir payments bileşenini düzenler.

Amaç Claude'a tüm monoreponuzu göstermek değil. Amaç, yine de soruyu cevaplamaya yetecek daha küçük, kasıtlı girdiler sağlamaktır: değiştirdiğiniz paket, doğrudan bağımlılıkları ve tipler ile config için bir veya iki “gerçek kaynak”. Ayrıca “dokunulmaz” alanları (diğer uygulamalar, infra, üretilmiş kod) belirtin ve davranışın hangi paketin sorumluluğunda olduğunu onaylayın.

Görevi tanımlamaya repo ile başlamayın

Doğruluk, yapıştırdığınız kod miktarından çok işi ne kadar net tanımladığınıza bağlıdır.

İstediğiniz sonucu net bir şekilde belirleyerek başlayın: belirli bir düzeltme, refactor veya cevap. “Koda dair bir soru” üst düzey kalabilir. “Bir değişiklik yap” isteği sınırlar, girdiler ve başarı kontrolleri gerektirir.

Herhangi bir şeyi paylaşmadan önce şu cümleyi tamamlayan bir cümle yazın: “İşiniz bittiğinde, şunu yapabiliyor olmalıyım…”. Örnekler: “paket X için birim testlerini başarısızlık olmadan çalıştırabilmek” veya “Y endpoint'i için API yanıtında yeni alanı görebilmek.” Bu cümle, depo çok büyük olduğunda kuzey yıldızınız olur.

Değişiklikler için, değişikliğin doğru olduğunu kanıtlayacak en küçük eser setini paylaşın: giriş noktası(ları), ilgili tipler/arayüzler veya şema, bir başarısız test ya da repro adımı ve yolu etkileyen herhangi bir config (routing, feature flag, build veya lint kuralları). Eğer yardımcı olursa, paket klasörünün kısa bir haritasını ekleyin ki Claude hangi dizinin ne işe yaradığını anlasın.

Neceğe bakmaması gerektiğini açıkça söyleyin. "Üretilmiş dosyaları, vendor klasörlerini, build çıktıları, snapshot'ları ve lockfile'ları istemediğim sürece yoksay." Bu, zaman kaybını ve incelemeyeceğiniz yerlerde yapılan değişiklikleri önler.

Ayrıca belirsizlik için beklentileri ayarlayın. Claude'dan tahmin yapmak yerine varsayımları ve bilinmeyenleri işaretlemesini isteyin. Örneğin: “Bu fonksiyonun nerede çağrıldığını göremiyorsan, bunu belirt ve 2 yol öner.”

Claude'ın geçmemesi gereken net sınırlar çizin

Büyük bir monorepoda doğruluk, model görev dışı yakın kodu “yardımcı olarak” çekmeye başladığında düşer. Çözüm basit: değişiklik istemeden önce neyin kapsamda olup neyin olmadığını tanımlayın.

Repo organizasyonunuzla eşleşen bir sınırla başlayın: bir paket, servis, uygulama veya paylaşılan bir kütüphane. Örneğin “checkout UI'sını güncelle” isteği için sınır muhtemelen tek bir uygulama paketi olur; “checkout” kelimesinin geçtiği her yeri değil.

Claude'ın yerinde kalmasına yardımcı olacak sinyaller arasında klasör konvansiyonları (apps/, services/, packages/, libs/), package manifestleri (exports ve dependencies), public giriş noktaları (index dosyaları, export edilen bileşenler, handler'lar) ve testler (genelde hedef yüzeyi gösterir) bulunur. Klasör içindeki bir README hızlı bir sınır işaretçisi olabilir.

Sınırlar, köprüleri adlandırdığınızda en iyi biçimde çalışır. Claude'ın dokunabileceği belirli arayüzleri belirtin ve diğer her şeyi kapalı kabul edin. Tipik köprüler HTTP API sözleşmeleri, event konuları ve payload'lar, paylaşılan türler veya sınırlı sayıda export edilen fonksiyonlardır.

Ayrıca, değişikliğin etkilememesi gereken “dokunulmaz” alanları her seferinde adlandırın. Bunlar genelde infra ve dağıtım config'leri, güvenlik ve auth mantığı, faturalama, veri migrasyonları ve prod şemaları ile birçok takım tarafından kullanılan paylaşılan kütüphanelerdir.

Yardımcı olabilecek somut bir prompt detayı:

“Değişiklikleri sadece packages/cart/ ve testleri içinde yap. packages/types/ içindeki paylaşılan türleri okuyabilirsin ama değiştirme. Infra, auth veya billing'i düzenleme.”

Yararlı yerel özetler nasıl yazılır

Doğruluk, değiştirmek istediğiniz alanın küçük, kararlı bir haritasını sağladığınızda iyileşir. Bir “yerel özet” o haritadır: hızlıca okunacak kadar kısa, tahmin etmeyi önleyecek kadar spesifik.

Her özeti 10–20 satır civarında tutun. Bunu, sınırla sınırlı çalışan yeni bir ekip arkadaşına kodu teslim ediyormuş gibi yazın. Düz dil kullanın ve koddan gerçek isimleri kullanın: klasörler, paketler, export edilen fonksiyonlar.

Yararlı bir yerel özet beş soruyu yanıtlar:

• Bu paket/servisin amacı nedir, ne için değildir (kapsam sınırları)
• İşin nerede başladığı (ana giriş noktaları: önemli dosyalar, route'lar, komutlar veya bileşenler)
• Dışarıdan güvenle çağrılabilecekler (public API'ler, export'lar, event'ler, endpoint'ler)
• Nelere bağımlı olduğu (veritabanları, kuyruklar, cache'ler, config, dış servisler)
• Burada hangi kurallar önemli (isimlendirme, hata stili, logging, test yazım şekli)

Bir “gotchas” satırı ekleyin. Bu, pahalı hataları önler: gizli cache'ler, feature flag'ler, migration adımları ve sessizce bozulan durumlar.

Kopyalayabileceğiniz kompakt bir şablon:

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>

Örnek: faturalama paketini düzenliyorsanız, fatura oluşturan kesin fonksiyonu, yazdığı tablo isimlerini ve retry edilebilir hatalar için kuralı not edin. Böylece Claude sınır üzerinde odaklanır, paylaşılan auth, config veya alakasız paketlere sapmaz.

Özetler nerede durmalı ve nasıl güncel tutulmalı

En iyi özet, Claude'ın ihtiyaç duyduğunda gördüğü özetidir. Kodun yanında tutun ki gözden kaçması zor ve güncellemesi kolay olsun. Örneğin her paket, servis veya uygulama klasörü içine kısa bir SUMMARY.md (veya README bölüm) koyun, kök dizindeki devasa bir doküman yerine.

Basit, tekrarlanabilir bir yapı yardımcı olur. Kısa tutun ki insanlar onu korusun:

• Bu klasörün ne olduğu (1–2 cümlede amaç)
• Public yüzey (ana giriş noktaları, export edilen modüller veya API'ler)
• Ana bağımlılıklar (iç/dış)
• Sınırlar (ne import edilmemeli veya değiştirilmemeli)
• Nasıl test edilir (en hızlı yerel kontrol)
• Last updated: YYYY-MM-DD - <ne değişti bir cümleyle>

Özetler öngörülebilir sebeplerle güncelliğini yitirir. Güncellemeyi bir type tanımını güncellemek gibi treat edin: işin bitişinin parçası olsun, ayrı bir görev değil.

Refactor yapı/isim değiştirirse, yeni modül ana yolsa, bir API/event/şema değişirse (testler yine geçse bile), paketler arası boundary değişirse veya bir bağımlılık kaldırılıp değiştirildiyse özeti güncelleyin.

Pratik bir alışkanlık: bir değişikliği merge ederken, ne değiştiğini belirten bir “Last updated” satırı ekleyin. Koder.ai gibi araçlar kod değişiminde sizi hızlandırabilir, ama özet gelecekteki değişikliklerin doğruluğunu koruyan şeydir.

Doğru bağlam içinde kalmak için adım adım iş akışı

Doğruluk genelde konuşmayı nasıl zamanladığınıza bağlıdır. Claude'a büyük bir snapshot yerine küçük parçalar halinde bağlam kazandırın.

Adım 1: Önce kısa bir harita isteyin

Herhangi bir düzenleme yapmadan önce Claude'dan gördüklerini ve nelerin gerektiğini anlatmasını isteyin. İyi bir harita kısa olur: ilgili paketler, akışın giriş noktası ve testlerin/türlerin nerede olduğu.

İstem örneği:

“Bu değişikliğin bir haritasını oluştur: ilgili paketler, ana akış ve muhtemel dokunma noktaları. Henüz kod önermeyin.”

Adım 2: Bir dilim ve bir sınırla başlayın

Dar bir dilim seçin: bir özellik, bir paket, bir kullanıcı akışı. Sınırı açıkça belirtin (ör. “Sadece packages/billing-api'yi değiştir. shared-ui veya infra'ya dokunmayın.”).

Kontrolü sizde tutacak bir iş akışı:

• Hedefi ve sınırı bir cümlede tanımlayın.
• Varsayımları ve bilinmeyenleri zorunlu kılın (Claude bunları listelemeli).
• Sonraki ihtiyaç duyduğu kesin dosyaları isteyin (3–6 arasıyla sınırlayın).
• Sadece o dosyaları verin, sonra tekrar edin.
• Patch uygulamadan önce kısa bir plan isteyin.

Adım 3: Açık varsayımlar ve dosya talepleri isteyin

Claude bir şeyi kaçırıyorsa bunu belirtmeli. Ondan şu üç şeyi yazmasını isteyin: (1) yaptığı varsayımlar, (2) bunları geçersiz kılacak durumlar, (3) doğrulamak için gerekli sonraki dosyalar.

Örnek: Invoice yanıtına alan eklemeniz gerekiyorsa. Claude handler'ı, DTO/tür tanımını ve bir testi ister. Siz sadece bunları paylaşırsınız. Sohnet tabanlı bir araç kullanıyorsanız aynı kural geçerli: en küçük dosya setini verin, daha fazlası gerçekten gerekmedikçe genişletmeyin.

Prompt'larda kısıtlar ve kontratlar kullanın

Yanlış düzenlemelere karşı en iyi savunuz, prompta yazılı küçük bir “kontrattır”: nerelere dokunabileceği, nasıl başarıyı ölçeceğiniz ve uyması gereken kurallar.

Kolayca uyulabilecek bir sınırla başlayın. Düzenlemelere izin verilen yerleri açıkça söyleyin ve “dokunma” alanlarını adlandırın.

Kontrat şablonu:

• Sadece packages/payments/ altındaki dosyaları değiştirin.
• packages/auth/, infra/ veya paylaşılan config'leri düzenlemeyin.
• Kapsam dışı değişiklik gerekirse önce durup sorun.
• Değişiklikleri minimal tutun: hatayı düzeltin, refactor yapmayın.

Sonra kabul kontrollerini tanımlayın. Bunlar yoksa Claude görünüşte doğru kod üretebilir ama repo kurallarını bozan sonuçlar oluşturabilir.

• Paketin birim testlerini çalıştırın (kullandığınız komutu yazın).
• Lint/format çalıştırın (kullanılan aracı yazın veya existing config deyin).
• Paket için typecheck/build çalıştırın.
• Uygulamanın hala başladığını doğrulayın (basit bir run komutu yeterli).

Stil kısıtları da önemlidir. Hangi desenlerin kullanılacağını ve hangilerinden kaçınılacağını söyleyin. Örnek: “Bu pakette var olan error helper'ları kullan; yeni bağımlılık ekleme; fonksiyon isimlerini camelCase tut; yeni bir mimari katmanı tanıtarak değişik yapma.”

Son olarak herhangi bir düzenlemeden önce kısa bir değişiklik planı isteyin:

“Düzenlemeden önce dokunacağınız 3–5 dosyayı ve beklenen davranış değişikliğini listeleyin. Onay bekleyin.”

Örnek:

“Fatura toplamlarındaki yuvarlamayı düzelt. Sadece packages/billing/src/ ve testleri packages/billing/test/ altında değiştir. Kabul: pnpm -C packages/billing test ve typecheck. Mevcut money util'lerini kullan; API tiplerini yeniden yazma. Önce 4 adımlık bir plan sun.”

Drive'a neden sapma ve yanlış düzenlemelere yol açan yaygın tuzaklar

Monorepoda yanlış düzenlemelerin en hızlı yolu Claude'a bir kerede çok fazla şey vermektir. Büyük bir kod yığını yapıştırdığınızda model genellikle repo özel tasarımınız yerine genel desenlere geri döner.

Başka bir tuzak: mimariyi modelin tahmin etmesine izin vermek. Gerçek giriş noktalarını göstermezseniz ilk gözüken dosyayı seçip mantığı oraya bağlayabilir. Pratikte doğruluk, küçük bir set “gerçek kaynak” dosyasından (giriş modülleri, router'lar, servis kayıtları, paket boundary dokümanları) gelir. Bunlar bağlamda yoksa model boşlukları doldurur.

İsimler de yanıltıcı olabilir. Monorepolarda genelde ui, ui-kit, shared-ui gibi paketler veya iki yerde benzer yardımcılar bulunur. İki parçacığı karıştırırsanız Claude bir dosyayı yamalarken diğer dosya üzerinde düşünüyor olabilir. Örnek: buton stilini değiştirmek istersiniz, packages/ui/Button.tsx'i düzenler ama uygulama packages/ui-kit/Button.tsx'i import eder. Diff güzel görünür ama prodda hiçbir şey değişmez.

Config de sessiz bir sapma kaynağıdır. Davranış environment değişkenlerine, feature flag'lere, build ayarlarına veya workspace tooling'e bağlı olabilir. Bunlardan bahsetmezseniz Claude bayat görünen bir kontrolü kaldırabilir veya bir build adımını bozacak kod ekleyebilir.

Sapma belirtileri:

• Cevap “tipik desenler”den bahsediyor ama gerçek dosyalarınızı adlandırmıyorsa
• Mevcut bir yardımcı yerine yeni bir shared utility ekliyorsa
• Paket sınırları arasında import'ları değiştiriyorsa
• Feature flag'leri veya env'e özgü dalları göz ardı ediyorsa
• Çekirdek paylaşılan pakete yeni bir bağımlılık eklemeyi öneriyorsa

Paketler arası importları varsayılan değil bir karar olarak ele alın. Kapsamı bilinçli şekilde genişletmediğiniz sürece düzenlemeleri yerel tutun.

Claude'a herhangi bir şey sormadan önce hızlı kontrol listesi

Doğru düzenlemeler almak için en hızlı yol sınırlarla başlamaktır, hacimle değil. İyi bir prompt biraz katı hissettirir: Claude'a nerelere bakacağını, neleri yoksayacağını ve “tamam”ın ne anlama geldiğini söyler.

Kod yapıştırmadan önce kısa bir önsöz yazın ve işi depo içindeki bir yere sabitleyin. Paketi, kesin klasörü ve spesifik hedefi adlandırın. Ardından bir yerel özet (amaç, ana bağımlılıklar, önemli konvansiyonlar) ve değişikliği sabitleyecek giriş dosyasını ekleyin.

Kontrol listesi:

• Boundary: Sadece <package>/<path> içinde çalış. Hedef: <one sentence>. Başka her şeyi yoksayın, gerekirse sorun.
• Context starter: Yerel özet: <5-10 satır>. Giriş dosyası: <path/to/file>.
• Constraints: İzin verilen klasörler: <...>. Değiştirilmemeli: <folders/files or APIs>. Davranış korunmalı: <what must stay true>.
• File requests first: “Önce değişiklik önermeden önce görebilmeniz için minimum dosyaları listeleyin (max 5) ve neden.”
• Output format: “Önce kısa bir planla cevap verin. Onay verdikten sonra dosya bazlı patch önerileri verin.”

Claude kapsam dışında değişiklikler önerirse, bunu bir işaret olarak kabul edin: ya promptu sıkılaştırın ya da kasıtlı olarak sınırı genişletip bunu yeniden belirtin.

Örnek: tüm monorepoyu uyandırmadan bir pakette değişiklik yapmak

Diyelim monoreponuzda apps/web-store (bir React uygulaması) ve packages/ui-kit (paylaşılan butonlar, inputlar ve stiller) var. Küçük bir özellik istiyorsunuz: sepette “Save for later” butonu eklemek ve ui-kit'ten yeni bir SaveIcon kullanmak. Başka hiçbir şey değişmemeli.

İstemeden önce sınırlar olarak iş görecek iki yerel özet oluşturun. Kısa, spesifik ve neyin önemli olduğuna dair fikir verin.

# 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

Döngüyü sıkı tutun:

1. Harita: “Bu değişiklik CartPage ve ui-kit ikonlarıyla sınırlıdır. Checkout/auth düzenlemeleri yok.”
2. Varsayımlar: varsayımları zorunlu kılın ve onay bekleyin.
3. Dosya talepleri: sadece gerçekten ihtiyaç duyduğu birkaç dosyayı onaylayın (CartPage, useCart, ui-kit ikonları, ui-kit index).
4. Plan: sınırlarla eşleştiğini onaylayın.
5. Düzenlemeler: en küçük diff'i yapın, sonra güncel testleri isteyin.

Değişiklikten sonra bunu belgelendirin ki gelecekte bağlam küçük kalsın:

• Hem local summary'leri yeni export ve dokunulan dosyalarla güncelleyin.
• Cart page başlığına kısa bir yorum ekleyin: buton ne yapar ve state nerede yönetilir.
• Geçen test komutlarını ve varsa güncellenen snapshot'ları kaydedin.

Sonraki adımlar: bunu ekibiniz için tekrarlanabilir hale getirin

Tek kişi için iyi çalışıp ekipte yaygınlaşmıyorsa eksik parça genelde tekrarlanabilirliktir. “İyi bağlam hijyenini” varsayılan haline getirin, kişisel bir alışkanlık değil.

En iyi prompt'larınızı ekip şablonuna çevirin

Herkesin kopyalayıp doldurabileceği bir prompt iskeleti kaydedin. Kısa ama katı tutun. Hedefi (“tamam” ne demek), izin verilen scope'u, sert sınırları (ve nedenlerini), bir yerel özet ve çıktı kontratını (önce plan, sonra diff ve testler) ekleyin.

Özetleri hafif bir tempoyla güncel tutun

Kimsenin yapmadığı büyük aylık incelemeler atlayın. Özet güncellemelerini normal işe bağlayın: bir değişiklik davranışı, bağımlılıkları veya API'leri etkilediğinde aynı PR içinde özeti güncelleyin.

Basit kural: bir takım arkadaşı “burası nerede?” veya “buna ne bağımlı?” diye soracaksa, özet artık güncel değildir.

Eğer chat-öncelikli bir iş akışını tercih ediyorsanız, Koder.ai bu iterasyon tarzını daha güvenli hale getirmeye yardımcı olabilir. Planning mode, düzenlemeler olmadan önce kapsam üzerinde anlaşmanızı sağlar ve rollback ile snapshot'lar, bir tahminin yanlış çıktığında hızlıca geri dönmeyi kolaylaştırır.