Bir kodlama ajanı, repository'nize güçlü görüşlerle gelmez. Mevcut olanı okur, mantığı özümser ve bulduğu yapıları tekrarlar. Eğer veri erişim katmanınız ham SQL ve yinelenen sorguların bir karmaşasıysa, ajan seve seve yeni bir düğüm daha ekleyecektir. Eğer test kapsamınız zayıfsa, o da zayıf testler üretecektir. Bu tembellik veya yetersizlik değildir; tam olarak amaçlandığı gibi çalışan bir örüntü eşleştirme sürecidir.

Hayal ettiğiniz ile ajanın inşa ettiği arasındaki boşluğu kapatmak, daha yüksek sesli promptlar veya daha akıllı bir model dileği değil; bağlam ve kısıtlamalar gerektirir. Aracı, üzerinde çalıştığı ortamı düzenleyerek hizalarsınız. İşte bunu yapmanın altı pratik yolu.

Taklit İçin Refactor Edin

Dil modelleri, sözel talimatları takip etmekten çok daha iyi bir şekilde örneklerden genelleme yaparlar. Claude'u, her biri veri erişimini kendi kaotik yöntemiyle yöneten beş farklı modüle yönlendirirseniz, ona aslında hangi örüntüyü istediğinizi tahmin etmesini söylemiş olursunuz. Sonuç genellikle beşinin de vasat bir karışımı olur.

Bunun yerine, ona tek bir temiz referans verin. İdeal yapınızı temsil eden bir modül seçin. Mimari belirgin olsun diye onu gereksiz gürültüden arındırın. Yeni bir özellik istediğinizde, doğrudan o dosyaya atıfta bulunun: "/src/orders/repository.py dosyasındaki örüntüyü takip et." İyi yapılandırılmış tek bir örnek, bir paragraf dolusu soyut kuraldan daha fazla şey anlatır; çünkü kod, yorumlamaya yer bırakmaz. Eğer repository'nizde tek bir temiz örnek yoksa, bir tane yazın. Özlü bir referans uygulama, sonraki her istekte karşılığını veren tek seferlik bir yatırımdır. Ajan; yapıyı, hata ayıklama stilini ve sorumlulukların ayrılmasını kopyalayacaktır, çünkü görünür kıldığınız tek taslak budur.

Önce Plan Modunu Kullanın

Herhangi bir dosya oluşturulmadan veya değiştirilmeden önce Claude'dan bir plan önermesini isteyin. Planı somutlaştırın: hangi dosyalar değişecek, hangi fonksiyonlar eklenecek, hangi bağımlılıklar içe aktarılacak ve yeni parçalar mevcut yapıya nasıl entegre edilecek.

Bu adım, ücretsiz bir çelişki tespit edici görevi görür. Eğer Claude'un planı, ekibiniz migrasyonları ayrı bir orkestre edilmiş iş üzerinden yürütürken uygulama dağıtım hattı (deployment pipeline) içine bir veritabanı migrasyonu eklemeyi öneriyorsa, bu uyumsuzluğu kod incelemesi sırasında değil, saniyeler içinde yakalarsınız. Eğer kullanımdan kaldırılmış bir yardımcı aracı yeniden kullanmayı planlıyorsa, özelliğin yarısı yazılmadan onu yönlendirebilirsiniz. Plan, modelin mimariniz hakkındaki varsayımlarını ortaya çıkarmasını sağlar. Ona, kıdemli olmayan bir yazılımcının tasarım dokümanına meydan okur gibi meydan okuyun. Bu sadece birkaç dakikanızı alır ve düzenli olarak kötü kodun temizlenmesi için harcanacak bir saati kurtarır.

Bağlamı Erken Sağlayın

Çoğu hizalama hatası, ajanın görevi yanlış anlamasından değil, yanlış kısıtlamalar için optimizasyon yapmasından kaynaklanır. Bir çözüm, bütçeyi, bir gecikme gereksinimini veya belirtmeyi unuttuğunuz bir uyumluluk sınırını ihlal ediyorsa, teknik olarak mükemmel olsa bile kullanılamaz olabilir.

Sınırlarınızı ilk prompt'ta belirtin. Eğer uç noktanızın (endpoint) 99. yüzdelik dilimde 200 milisaniyenin altında kalması gerekiyorsa, bunu söyleyin. HIPAA, GDPR veya belirli bir dahili denetim rejimi altında çalışıyorsanız, bunu açıkça belirtin. Altyapı maliyetiniz hassassa ve fazladan bir yönetilen önbellek kümesi (managed cache cluster) ayağa kaldıramıyorsanız, maliyet sınırını netleştirin. Claude Code, varlığından haberdar olmadığı ödünleşimleri müzakere edemez. Bu sınırları ne kadar erken eklerseniz, ajan bunları sonradan yamalanacak birer düşünce olarak değil, çözümünün temeline dahil edecektir.

Belleği Kodlayın

Aynı düzeltmeyi tekrarlamak, zamanınızın ve bağlam pencerenizin (context window) israfıdır. Claude'a belirli bir kütüphaneden kaçınmasını, belirli bir wrapper kullanmasını veya bir isimlendirme kuralına uymasını birden fazla kez söylemek zorunda kaldığınızda durun. Bu düzeltmeyi proje belleğine dönüştürün.

Repository'nizin kök dizininde bir CLAUDE.md dosyası oluşturun. Bu sizin proje kılavuzunuzdur. Onu önemli kurallarla doldurun: unittest yerine pytest kullanın; tüm giden HTTP çağrıları /lib/http içindeki circuit-breaker üzerinden geçmelidir; asla doğrudan eski utils.py dosyasından içe aktarma yapmayın; girdileri handler'a ulaşmadan önce her zaman şema katmanı ile doğrulayın. Claude Code projenizi yüklediğinde bu dosyayı otomatik olarak okur. Zamanla CLAUDE.md, her oturumda kurallarınızı yeniden yazmanıza gerek kalmadan standartlarınızı ölçeklendirdiği için en yüksek kaldıraç etkisine sahip varlıklarınızdan biri haline gelir. Bir zamanlar geçici promptlar olan düzeltmeler, kod tabanının kalıcı birer parçası olur.

Kuralları Hook'lar ile Mekanize Edin

Dokümantasyon yardımcı olur ancak gözden kaçabilir. Bir kural gerçekten kritik olduğunda, onu tavsiye olmaktan çıkarıp zorunluluk haline getirin. Katı kuralların çiğnenmesini imkansız kılmak için hook'lar, pre-commit kontrolleri, CI kapıları veya özel doğrulama betikleri kullanın.

Eğer her yeni modülün karşılık gelen birim testleri (unit tests) olması gerekiyorsa, bunu sadece CLAUDE.md içinde belirtmekle yetinmeyin. /src dizinindeki bir dosya eşleşen bir test olmadan eklendiğinde derlemeyi (build) durduran bir kapsama (coverage) kapısı yapılandırın. Güvenlik politikanız gizli bilgilerin (secrets) commit edilmesini yasaklıyorsa, push işlemini engelleyen bir tarayıcı çalıştırın. Ekibiniz belirli bir içe aktarma (import) sıralaması veya lint kuralları gerektiriyorsa, düzeltmeyi bir pre-commit hook ile otomatize edin. Bu mekanizmalar, Claude'un çıktısını da tıpkı sizinkiler gibi yakalar. İnsan hatası veya model sapması (model drift) olasılığını ortadan kaldırırlar ve "lütfen unutmayın" ifadesini "devam edilemez" ile değiştirirler. Zorunlu kılınmayan bir kural, yalnızca bir öneridir.

Bağımsız İnceleyiciler Çalıştırın

Öz inceleme (self-review) güvenilmezdir. Claude kendi çalışmasını kontrol ettiğinde, genellikle kendi varsayımlarını onaylar çünkü bu varsayımları en başta kendisi oluşturmuştur. Çözüm, bu gözler farklı bir görev tanımı altında çalışan aynı modele ait olsa bile, sürece taze bakış açıları dahil etmektir.

Dar ve açık bir odak noktasına sahip ayrı inceleyici ajanlar (reviewer agents) oluşturun. Birinden sadece güvenlik denetimi yapmasını isteyin: enjeksiyon riskleri, ifşa olmuş dahili uç noktalar (endpoints) veya güvenli olmayan deserialization işlemleri var mı? Bir başkasından test kapsamını ve uç durumları (edge cases) değerlendirmesini isteyin. Üçüncüsü, değişikliğin CLAUDE.md içinde tanımlanan kurallara uyup uymadığını doğrulayabilir. Bu inceleyicilerin karmaşık özel modellere ihtiyacı yoktur. Sadece orijinal üretim adımından bağımsız olmaları yeterlidir. Kodu incelemesi için başka birine —veya bir şeye— başvurmanın yarattığı o zorluk, geliştiriciye çok bariz gelen varsayımları yakalar. Ek token maliyeti, bir hatanın canlı ortama (production) ulaşmasının maliyetiyle kıyaslandığında ihmal edilebilir düzeydedir.

Döngü

Hizalama (Alignment), bitirilecek bir proje değildir; sürdürülecek bir döngüdür. Claude'un çıktısını her düzelttiğinizde, bu düzeltmenin CLAUDE.md dosyanızda yeni bir madde veya araç setinizde (tooling) yeni bir kapı olup olamayacağını sorgulayın. Aynı düzeltmeyi iki kez yapıyorsanız, sisteminizde bir boşluk bulmuşsunuz demektir. Bu boşluğu kalıcı olarak kapatın.

Haftalar geçtikçe bu uygulama katlanarak artar. Ajan tahmin yürütmeyi bırakır ve sizin açtığınız izleri takip etmeye başlar. Kısıtlamalar net, örnekler temiz ve kurallar mekanik olduğu için kod tabanı kendi kendini yazıyormuş gibi hissettirmeye başlar. İşiniz düzeltme yapmaktan, kürasyon yapmaya dönüşür.

Kaynak: https://dev.to/az365ai/how-to-align-claude-code-with-your-codebase-6-techniques-2026-3k28

İsteğe bağlı öğrenme topluluğu: https://t.me/GyaanSetuAi