Yazı
Claude Code Nasıl Çalışıyor?
Claude Code'un ajan döngüsü, izin sistemi, bağlam sıkıştırma, MCP, skill, eklenti ve müdahale noktaları ile alt ajan mimarisi: arXiv makalesi ve açık kaynak mimari incelemesine dayanan bir rehber.
Bu yazıda ne var?
Claude Code, terminal ve dosya sistemi üzerinde çalışan, komut satırı ve düzenleme oturumları yürüten, harici hizmetlerle konuşabilen ajan tabanlı bir kodlama aracıdır. Dışarıdan bakıldığında büyük dil modelindeymiş gibi görünse de ürünün özü neredeyse tamamen deterministik altyapıdır: izin ve bağlam yönetimi, araç (tool) yönlendirme ve kurtarma mantığı. Bu yazı, arXiv:2604.14228 (“Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems”) ve eşlik eden açık kaynak inceleme deposu VILA-Lab/Dive-into-Claude-Code üzerinden sistemin nasıl parçalara ayrıldığını, teknik jargondan arındırılmış ama derinliği koruyan bir dille özetler.
Tek bakışta: mimari harita
Aşağıdaki tablo, GitHub deposu ve makalede vurgulanan ölçek ile tasarım kırılımlarını bir arada görmenize yardımcı olur. Rakamlar belirli bir sürüme (ör. ~v2.1.88) özgü analizden gelir; ürün geliştikçe değişebilir.
| Özellik | Tipik büyüklük / yapı | Ne anlama geliyor? |
|---|---|---|
| Kod tabanı (TypeScript) | ~1.900 dosya, ~512K satır (analiz sürümüne göre) | “Ajan” denince akla gelen ML çağrısı kodun küçük bir dilimini oluşturur; asıl efor altyapıda. |
| “Yapay zeka” oranı (kabaca) | ~%1,6 model karar mantığı; ~%98,4 altyapı | Basit while döngüsünü taklit etmek nispeten kolaydır; buna karşılık müdahale noktaları, izin sınıflandırıcısı, bağlam sıkıştırma ve izolasyon gibi dıştaki tüm altyapıyı aynı düzeyde yeniden üretmek esas zorluk yaratır. |
| Tek yürütme düzeni | Tek queryLoop (CLI, SDK, IDE arayüzleri) |
Aynı çekirdek, farklı yüzeylerde tutarlı davranış. |
| Araç havuzu (örnek) | 50+ araç; taban listesi + MCP + eklentiler | Mod ve politikalara göre süzülür; yinelenen araçlar elenir. |
| İzin modları | 7 kademeli güven spektrumu | Kullanıcı güveni zamanla değişebilen bir yön olarak modellenir. |
| Ön-model sıkıştırma | 5 aşamalı “lazy degradation” hattı | Token bütçesi tükenmeden önce kademeli tasarruf. |
| Genişleme | 4 mekanizma: MCP, eklentiler, skill, hook | Her biri farklı bağlam maliyetiyle “en dıştaki halka”ya kadar genişler. |
| Alt ajan | Worktree / uzak / işlem-içi izolasyon; özet sadece üst ajana döner | Üst bağlam, alt ajanın ayrıntı seline gömülmez. |
Kalbin özü: basit bir döngü
Makale ve VILA-Lab özeti, çekirdeği ReAct tarzı bir while döngüsü olarak tanımlar: bağlamı topla → modeli çağır → araçları yürüt → tekrar. Uygulama ayrıntısı, olayları üreten bir AsyncGenerator ile akışın (stream) parça parça işlenmesi ve her adımda izin, güvenlik ve sıkıştırma katmanlarının devreye girmesidir.
Aşağıdaki şema, “kavramsal” akışı verir; üretimde bu halkanın etrafında onlarca politika ve kurtarma yolu vardır.
┌──────────────────────────────────────────────────────────┐
│ CLAUDE CODE DÖNGÜSÜ │
│ (model akışı + izin + araç yürütme + durdurma koşulları)│
└──────────────────────────────────────────────────────────┘
│
▼
┌─────────────┐ akış (stream) ┌──────────────┐
│ Bağlamı │ ─────────────────────▶ │ Model çağrısı │
│ topla │ (her çağrıdan önce └──────┬───────┘
└──────┬────── 5 katman compaction) │
│ │
│ ┌──────────────────────────────┘
│ ▼
│ ┌──────────────┐ izin / hook ┌──────────────┐
└──▶│ Araç │◀───────────────▶│ Yürüt + log │
│ yönetimi │ deny-first └──────┬───────┘
└──────┬────── │
│ │
└──────── tekrar veya stop ◀─────┘
Bir turda olanlar: yalnızca “modeli çağır” değil
Depodaki belgelendirme, her tur için tipik olarak dokuz adımlı bir çerçeve önerir. Ekranda model konuşuyormuş gibi görünen çıktı, aslında perde arkasında yürüyen bir zincirin sonucudur: ayarlar → oturum durumu → bağlamın toplanması → örneğin beş katmanlı ön-işleme (ön-model adımları) → model → araçların yönlendirilmesi → izin denetimi → yürütme → durdurma koşulları. Böylece üretimde gecikmenin yalnızca “API süresinden” ibaret olmadığı anlaşılır.
| Aşama | Kullanıcıya görünen | Teknik anlam (özet) |
|---|---|---|
| Ön hazırlık | “Bekliyor…” / hafif hazırlık | Ayar çözümlemesi, oturum durumu, bağlam parçalarının bir araya getirilmesi. |
| Compaction (5’li) | Genelde fark edilmeden | Token sınırı öncesi kademeli: bütçe, snip, microcompact, çökertme, “auto-compact” gibi aşamalar; ucuzdan pahalıya. |
| Model | Yanıt ve araç planı | “Düşünce” burada; fakat eylem, bir sonraki aşamaya bağlı. |
| İzin | Onay istemi veya otomasyon | “Deny-first” ve mod spektrumu; sınıflandırıcı ve kural ağaçları. |
| Son | İşlem bitti / devam | Durdurma koşulları: araç yok, tur sınırı, taşma, önceden tanımlı müdahale noktası devreye girmesi, kullanıcı iptal vb. |
Beş değer, on üç ilke, somut uygulama
Makale, mimarinin arkasında beş insani değer / ihtiyaç (insanın karar yetkisi, güvenlik, güvenilir yürütme, yetenek büyütme, bağlama uyum) olduğunu ve bu değerlerin on üç tasarım ilkesi üzerinden yürütüldüğünü öne sürer. Aşağıda, okunabilirlik için ilkeleri sınıfladım; ayrıntılı tanım ve gerekçe için makaleye ve depodaki “Values and Design Principles” bölümüne başvurabilirsiniz.
Beş değer (özet)
| Değer | Pratikte neyi korur? |
|---|---|
| İnsan karar otoritesi | Kullanıcı, güven yörüngesinde kalır; aşırı onay yükü için “daha çok uyarı” yerine sınır / akış düzenlenmesi tercih edilebilir. |
| Güvenlik, mahremiyet | “İnsan dikkati düşse bile” riskleri azaltan birden çok savunma hattı. |
| Güvenilir yürütme | Ne yapıldığının ve durdurma koşullarının anlaşılır olması; hata kurtarma. |
| Yetenek büyütme | “Unix aracı” gibi davranan yalın bir sarmalayıcı; model, deterministik altyapıya güvenir. |
| Bağlama uyum | Proje sınırları, aşamalı genişleme, zaman içinde değişen “güven hikâyeleri” (CLAUDE.md, kurallar vb.). |
On üç ilke: tasarım soruları dili
Aşağıdaki tabloda, depodan alınan ilke isimlerinin yanına “sorduğunuz soru”u ekledim. Kendi ajan ürününüzde de aynı soruları açıkça sormak, mimari anlaşmazlıkları erken bitirir.
| İlke (orijinal ada göre) | Tasarım sorusu |
|---|---|
| Deny-first, insan yönlü yükseltme | Tanımsız eylem serbest mi, engelli mi, insana mı bırakılıyor? |
| Kademeli güven spektrumu | Sabit izin seviyesi mi, yürütme boyunca ileri-geri oynayabilen bir yelpaze mi? |
| Savunma derinliği (defense in depth) | Tek sınır mı, yoksa paylaşılan açık uçları sınırlayan birden çok hat mı? |
| Dışa alınmış programlanabilir politika | Kurallar kodda mı, yapılandırma ve yaşam döngüsü müdahale noktalarında mı? |
| Bağlam, kıt bir kaynak | Tek ham kesme mi, kademeli bir düşme (lazy degradation) mı? |
| Ekleme-odaklı kalıcı durum (append-only) | “Son durumun üstüne yaz” mı, yoksa denetlenebilir ekleme günlüğü mü? |
| Minimum iskele, maksimum harness | Büyümeyi “görkemli iskele”de mi, operasyonel altyapıda mı yatırıyorsunuz? |
| Kurallar yerine değerler, belirleyici bariyerlerle | Kural kitabı mı, yoksa değerler + belirleyici güvenlik bariyerleri mi? |
| Çok mekanizmalı birleştirilebilir genişleme | Tek büyük API mı, farklı maliyetli katmanlı mekanizmalar mı? |
| Geri alınabilirliği önceleyen risk dengesi | Her eylemde aynı sıkı gözetim mi, geri alınabilir eylemlerde daha hafif denetim mi? |
| Şeffaf dosya tabanlı bellek / yapılandırma | Opak veri tabanı mı, sürümlenebilir dosyalar mı? |
| İzole alt ajan sınırları | Ortak bağlam mı, yoksa ayrı izinler ve yalnızca özetin dönmesi mi? |
| Zarif kurtarma, dayanıklılık | İlk hata mı, kademeli geri dönüş mü? |
Not: Aynı inceleme, “uzun vadede anlama (comprehension)” için ek bir değerlendirme merceği de uyguluyor; yapay zekâ destekli geliştirme altında bireylerin bazı testlerde daha düşük skor verebildiğine dair ampirik referanslara dikkat çekiliyor—yani ajan, hız kazandırırken ekip öğrenmesi için ayrı önlemler düşünmek gerekebilir.
İki kritik kavram: “kısıt” ve kademeli bağlam sıkıştırma
Her ajan, bir bağlam penceresi sınırına bağlıdır (örnek olarak eski modellerde ~200K, yeni serilerde 1M token mertebesi depo analizinde geçer). Her model çağrısından önce çalışan beş aşamalı sıkıştırma (compaction) hattı, “tek hamlede budamak” yerine önce bütçe, sonra küçük kesintiler, ardından anlamsal/özet adımlarıyla “ucuzdan pahalıya” ilerler. Kullanıcıya sorunsuz görünür; arka planda ise ciddi bir maliyet optimizasyonudur.
Güvenlik ve izin: yelpaze ve sınıflandırıcı
Depo, yedi izin modunu kademeli bir güven yelpazesi olarak anlatıyor; örnek yön: plan → default → acceptEdits → auto (Makine öğrenmesi sınıflandırıcı) → dontAsk → bypassPermissions ve dahili bubble gibi durumlar. Deny-first ilkesi, geniş bir deny kuralının daima dar bir allow’u geçerli kılmasını söyler: en katı kural kazanır.
Otomasyon modu için ayrı bir sınıflandırıcı (depoda yoloClassifier olarak geçer) hızlı bir filtre ve üzerine eklenen aşamalar içerebilir; ayrı bir iç şablon dili, iç ve dış etki alanlarını dikkate alır. Bu, “güvenli tıkla ve unut” değil, modele dayalı bir onay engeli tasarımıdır.
Savunma derinliği katmanlar arası örneklerle de görülür: katmanlar aynı performans tavanını paylaştığında, bütün savunma hattı birlikte zayıflayabilir. Örnek: çok sayıda alt komut içeren girdilerde, olay döngüsünü kilitlememek için belirli eşiklerde güvenlik ayrıştırması tamamen atlanabiliyor; bu tür ortak başarısızlık senaryoları, yalnızca “yedi katman var” demenin yetmeyeceğini hatırlatır. Ayrıca, henüz güven atfedilmeden çalışan uzantı veya MCP aşaması, kök nedeni benzer olabilecek zafiyet örnekleriyle (depoda vurgulanan “pre-trust” penceresi) birlikte ele alınmalıdır: güven yalnızca sohbet penceresinde değil, bileşenin yüklenmeye başladığı ilk anda tasarlanmalıdır.
Oturumlar arasında: izinler sürdürülmüyor—güven her oturumda yeniden kuruluyor; bu, hız pahasına denetlenebilirlik ister.
Bağlam ve bellek: dosyalar, hiyerarşi, vektör araması olmadan
Claude Code, bellek için vektör veri tabanı şart koşmaz: bellek dosya merkezli ve sürümlenmeye, incelemeye, geri almaya uygundur. CLAUDE.md hiyerarşisi, yönetim → kullanıcı → proje → yerel gibi katmanlarda ilerler; yönergeler, deterministik system yerine çoğunlukla kullanıcı tarafı bağlamı gibi enjekte edilerek, modelin olasılıksal uyum davranışı hedeflenir.
Depo, pencereyi besleyen öğeleri dokuz kaynaktan oluşan tek bir çerçeveyle anlatır. “Belleği tazelemek” tarafında ise vektör / gömme araması olmadan, bellek dosyası üst bilgilerini tarayıp (LLM ile) en ilgili birkaç dosyayı seçen bir yol tercih edilebilir. Bu, gösterişli bir “vektör veritabanı” katmanına hiç girmeden, sade ama denetlenebilir bir tasarım tercihidir.
Genişleme: dört mekanizma, farklı maliyet
Genişleme mekanizmaları bağlam maliyetine göre sıralanabilir: kancalar (düşük; ek token açısından neredeyse sıfıra yakın) → Skill’ler (düşük) → eklentiler (orta) → MCP (yüksek). Özetle üç enjeksiyon noktası: ne görür (assemble) → neye ulaşır (model) → nasıl ve hangi onayla çalıştırır (execute). Araç listesi, taban listesi, moda göre süzme ve MCP birleşimi gibi adımlarla oluşur; yinelenenler elenir.
Müdahale noktaları, onlarca olay türü ve farklı yürütme modelleri (kabuk, ayrı LLM değerlendirmesi, webhook, alt ajan doğrulaması) ile, “dış dünya ile güvenli köprü” gibi tasarlanmıştır.
Alt ajanlar: özet geri, bağlam koruması
Alt ajan, uzun süren keşifleri ana oturumdan ayırır: yan zincir (sidechain) oturum kayıtlarında üretilen ayrıntıların yalnızca özeti üst ajana döner. Böylece üst oturumun bağlamı, alt ajanın ayrıntı taşkınından korunur. İzolasyon worktree, uzak veya işlem içi gibi modlarda ele alınır; eşzamanlılık için flock gibi kilitlerden söz edilir. Skill mevcut bağlama enjekte olur; Ajan (AgentTool) ayrı bağlam açtığı için daha maliyetlidir ama bağlamın şişmesini önler. Üst ajan açıkça ayrıcalık (örneğin belirli izinleri atlama) tanımladığında alt ajan kısıtları farklı yorumlanabilir; kullanıcının açık onayı önceliklidir.
Oturum kalıcılığı: ekleme odaklı kayıt, zincir üzerinde yama, geri sarma
Oturumlar ekleme odaklı JSONL transkript, genel istem geçmişi ve alt ajan yan zincirleri gibi kanallarla sürer. Amaç, sorgu gücünden çok denetim izi vermektir. Sıkıştırılmış biçimde zincir, “baş / çapa / kuyruk” tanımlayıcılarıyla okuma anında yamalanabilir; diskte yıkıcı son düzeltme yapmama tercih edilebilir. --rewind-files gibi senaryolar için dosya geçmişi kontrol noktaları düşünülmüştür. Bu, bir IDE otomasyon aracını klasik sohbet “çöp kutusu”ndan ayıran taraftır.
OpenClaw ile karşılaştırma: aynı sorular, farklı yanıtlar
Makale, Claude Code’u bağımsız açık kaynak OpenClaw ile karşılaştırır. Özetlenen fark şu: aynı görünen tasarım soruları, dağıtım ortamı değişince farklı mimarilere dönüşüyor. Örnek eksenler (arXiv özetiyle uyumlu): eylem başına güvenlik sınıflandırması yerine ortam düzeyinde erişim denetimi; tek CLI döngüsü yerine ağ geçidine gömülü yürütme; bağlam penceresini büyütmek yerine ağ geçidi ölçeğinde yetenek kaydı. Bu, “taklitçi ajan = aynı ürün” varsayımını sarsar.
Gelecekteki açık tasarım yönleri
Makale, ampirik, mimari ve politika literatürüne dayanarak ajanlar için altı açık tasarım yönü ileri sürüyor; bu yazının amacı sayı ve başlık üzerinde kilitlenmek değil, sizin yol haritanıza giren soruları işaret etmek: hangi katmanda yürüyen güvenlik, hangi bağlam ekonomisi, hangi denetim modeli, hangi insan–makine sınır yönetişimi? Tam liste ve gerekçe için orijinal makaleye başvurmanız en doğru kaynak olacaktır.
Pratik çıkarımlar: kendi ajan ürününüz veya ekip politikalarınız için
- Çekirdek kopyalama cazibesine kanmayın—fark, izin, sıkıştırma, müdahale noktaları, izolasyon, kalıcılık ve hata yollarındadır.
- Ortak hata modlarını (hepsi aynı tavan altında) haritalayın: bir savunma hattı zayıfladığında “diğer altı yeter” olmayabilir.
- Genişlemenin maliyetini tek bir API’ye sığdırmayın: bazı eklentiler, bağlamı ağır, bazıları hafif olmalıdır.
- Alt ajan, maliyet ve güven sınırı yönetim aracıdır—sadece “daha zeki görünmek” için değil, ana bağlamı korumak için vardır.
- Oturumları sürdürmek ≠ güveni sürdürmek—yeniden onay, kasıtlı yavaşlamadır, ihmal değil.
Kaynaklar
- Liu, Zhao, Shang, Shen, “Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems” (arXiv:2604.14228, 2026) — açık TypeScript incelemesi, OpenClaw kıyası, tasarım ilkeleri, geleceğe dönük açık sorular.
- VILA-Lab, Dive-into-Claude-Code — sürüme dayalı metrikler, 9 adımlı tur, izin/compact genişleme/alt ajan/oturum bölümleri; resmî ve topluluk referans derlemesi.