Claude Code Özyinelemeli Bir Ajan Değil: Kaynak Kodu Okudum ve Kontrol Ettim

Claude Code'un v2.1.88 sürümüyle gelen kaynak kod haritası (source map), aracın arkasındaki gerçek mimariyi gün yüzüne çıkardı. Kodları incelediğimizde, yapay zeka ajanları hakkında doğru bilinen pek çok yanlış olduğunu görüyoruz. İşte Edumints olarak yazılım geliştirme ve AI ajanları perspektifinden çıkardığımız dersler:

Efsane 1: "Ajan her araç sonucunda kendini özyinelemeli (recursive) çağırır"

Kodda özyineleme yoktur; queryLoop fonksiyonu içinde tek bir while (true) asenkron döngüsü çalışır. Durum nesnesi (state) her adımda yerinde güncellenir.

Pratik Çıkarım: Ajan mimarisi tasarlarken yığın (stack) taşması riskini önlemek için döngüsel yapılar kurmak daha kararlı ve güvenlidir.

Efsane 2: "Bağlam (context) dolduğunda sadece kırpılır"

Bağlam yönetimi için ucuzdan pahalıya giden 5 aşamalı katmanlı bir yapı vardır. En pahalı aşama olan autocompact ardışık 3 kez başarısız olursa oturum boyunca sessizce devre dışı kalır.

Pratik Çıkarım: AI uygulamalarında bağlam sınırlarını yönetirken maliyet ve performans dengesini korumak için kademeli temizlik mekanizmaları kurmalıyız.

Efsane 3: "Tam sıkıştırma (compaction) son mesajları her zaman harfi harfine korur"

Tam sıkıştırmada mesaj dizisi sıfırdan oluşturulur ve model kendi yazdığı bir özet (retelling) üzerinden devam eder; mesajlar kelimesi kelimesine korunmaz.

Pratik Çıkarım: Kritik verilerin kaybolmaması için modelin özetleme kalitesine güvenmek yerine önemli bilgileri sistem istemlerinde (system prompt) sabit tutmalıyız.

Efsane 4: "Araçlar model konuşmayı bitirdikten sonra çalışır"

Model çıktısı akarken (streaming) tool_use bloku gelir gelmez araç arka planda eş zamanlı çalışmaya başlar.

Pratik Çıkarım: Eş zamanlı araç çalıştırma hız kazandırır ancak yan yana çalışan araçların yarış durumlarını (race conditions) iyi yönetmek gerekir.

Efsane 5: "Tek model mesajı tek yanıttır ve stop_reason güvenilirdir"

Metin, düşünme ve araç çağrıları ayrı mesajlar olarak iletilir. stop_reason güvenilmez olduğu için döngü araç çağrısını doğrudan kontrol eder.

Pratik Çıkarım: Akış tabanlı entegrasyonlarda durum kontrollerini meta verilere değil, ham veri bloklarının içeriğine dayandırmak kararlılığı artırır.

Efsane 6: "İzinler hiyerarşiktir"

İzinler kaynağa değil katılık seviyesine göredir. deny her zaman üstündür. Bypass edilse bile hassas klasörler (.git, .claude) için ek onay istenir.

Pratik Çıkarım: Güvenlik sistemlerinde "tam yetki" verilse bile kritik dizinler için ek savunma hatları tasarlanmalıdır.

Efsane 7: "Alt ajan (subagent) yanınızda çalışan başka bir Claude'dur"

Alt ajanlar ana durum bilgisini değiştiremez ve onay kutusu gösteremezler. Çıkan onaylar otomatik reddedilir.

Pratik Çıkarım: Alt ajanlara otonom görevler verirken onay gerektirmeyen, sınırlı ve net tanımlı işler atamalıyız.

Efsane 8: "Claude Code'un uzantıları yalnızca birkaç standart kancadan (hook) ibarettir"

5 temel eklenti mekanizması ve 28 farklı olay tetikleyicisi vardır. Yeteneklerin (skills) sadece başlıkları bağlama yüklenir, gövdeler çağrıldığında okunur.

Pratik Çıkarım: Eklenti sistemlerinde kaynak tasarrufu sağlamak için "lazy loading" (tembel yükleme) prensibi uygulanmalıdır.

Son Bir Şey: Güvenlik Riski

Klasör güvenliği sorusu sorulmadan önce settings.json dosyası okunuyor. Bu durum, güvenilmeyen dizinlerdeki ayarların çalıştırılması riskini doğurur.

Aslında Neler Değişti?

Bu mimariyi anladıktan sonra uygulayabileceğimiz pratik çıkarımlar:

Bütçe hesaplarını soyut ajan çağrıları yerine döngü adımı bazında yapın.
Alt ajanlara kullanıcı onayı gerektiren işler vermeyin.
Bağlam dolmasını önlemek için ara ara bağlamı manuel temizlemek otomatik sıkıştırmadan daha ucuzdur.

Orijinal makaleye buradan ulaşabilirsiniz.