Claude Code alt ajanları: bağlam izolasyonu, orkestratör ve denetçi, ne zaman gerekmezler

Claude Code alt ajanları nedir

Alt ajan, ana ajanın ayrı bir görev için başlattığı bir ajan örneğidir. Kendi bağlam penceresi, kendi sistem promptu ve izin verilen araçların kendi listesi vardır. Ana ajan ona görev tanımını verir, alt ajan bağımsız çalışır — dosya okur, komut çalıştırır — ve geriye yalnızca nihai mesajı döndürür.

Buradaki anahtar kelime izolasyondur. Alt ajanın yolda okuduğu her şey — onlarca dosya, uzun test çıktısı, çıkmaza giden hipotezler — kendi bağlamında kalır ve ana oturumun bağlamına girmez. Ana ajan kısa bir sonuç görür: «X fonksiyonunda hata var, nedeni şu, etkilenen üç yer şunlar.»

Claude Code alt ajanları, çoklu ajan sistemlerinin özel bir örneğidir: tek bir «düşün — yap — kontrol et» döngüsü yerine, her biri kendi rolü ve sorumluluğu olan düğümlerden oluşan bir grafik ortaya çıkar.

Bağlam izolasyonu neden önemli

Bağlam penceresi ajanın asıl kaynağıdır. Aynı anda içinde CLAUDE.md talimatları, diyalog geçmişi, okunan kod ve komut çıktıları bulunur. Ajan bir hatanın nedenini yarım saat aradığında, bağlam ilgisiz dosyalar ve yalnızca bir satırının önemli olduğu günlüklerle dolar.

Uzun süre ajanla çalışan herkes sonuçlarını bilir: model proje kurallarını daha kötü tutmaya başlar, ayrıntıları karıştırır ve otomatik geçmiş sıkıştırması sırasında önemli olanı kaybeder. Alt ajan bunu yapısal olarak çözer: kirli iş ayrı bir bağlamda yapılır ve yanıttan sonra atılır.

• Arama ve keşif. «Ödeme fonksiyonunun çağrıldığı tüm yerleri bul ve nasıl çalıştıklarını anlat» tipik bir alt ajan görevidir.
• Gürültülü kontroller. Test çalıştırmasını ve başarısız olanların incelenmesini alt ajana verin, nedenlerin listesini alın.
• Büyük belgeleri okuma. Yüzlerce sayfalık bir şartname birkaç gerçek için gerekiyorsa, bunları alt ajan çıkarsın.

Alt ajanı nasıl kurarsınız: .claude/agents klasörü

Kendi alt ajanınız, YAML başlıklı bir Markdown dosyasıyla tanımlanır. Proje dosyaları deponun .claude/agents/ klasöründe durur ve git üzerinden tüm ekibe ulaşır; kişisel olanlar ~/.claude/agents/ içinde yaşar ve tüm projelerinizde çalışır. Alt ajanı Claude Code içinde /agents komutuyla etkileşimli olarak da oluşturabilir ve düzenleyebilirsiniz.

---
name: code-reviewer
description: Kod değişikliklerini hatalar ve proje kurallarının ihlalleri açısından denetler. Görev bittikten sonra, commit öncesinde kullan.
tools: Read, Grep, Glob, Bash
---
Sen bir kod denetçisisin. Hiçbir şeyi düzeltmen gerekmez.

1. Değişikliklere bak: git diff.
2. Her değişikliği mantık hataları, hata yönetimi ve
   güvenlik (SQL, çıktı kaçışı, sırlar) açısından kontrol et.
3. AGENTS.md içindeki kurallarla karşılaştır.
4. Bulguların listesini döndür: dosya, satır, sorun, neden önemli.
   Bulgu yoksa bunu açıkça yaz.

Alanların anlamları:

Dosyanın gövdesi alt ajanın sistem promptudur. Diyaloğunuzun geçmişini görmez, bu yüzden rolü ve yanıt biçimini bilmesi gereken her şey promptta ya da ana ajanın verdiği görevde olmalıdır.

Alt ajanı nasıl çağırırsınız

Görev tanımı alt ajanın description alanına uyuyorsa ana ajan onu kendisi seçebilir. Açıkça istemek daha güvenilirdir: «Değişiklikleri kontrol etmek için code-reviewer alt ajanını kullan». Açıklamaya «proaktif kullan» gibi ifadeler yazmak, ajanın onu hatırlatma olmadan çağırma olasılığını artırır, ama bunu garanti etmez.

Alt ajan olarak araştırmacı

Neredeyse her projede kurulmaya değer ikinci bir dosya, yalnızca okuma yetkisi olan bir araştırmacıdır. Kod hakkındaki soruları yanıtlar ve hiçbir şeyi değiştirmez.

---
name: explorer
description: Kod tabanında bir şeyin nerede ve nasıl çalıştığına dair soruları yanıtlar. Kısa bir sonuç için çok sayıda dosya okunması gerektiğinde kullan.
tools: Read, Grep, Glob
---
Kodu incelersin ve hiçbir şeyi değiştirmezsin.
Döndür: sorunun kısa yanıtı, yanıtın dayandığı dosyaların ve satırların
listesi ve doğrulanamayan noktalar.

Böyle bir alt ajan özellikle görevin başında faydalıdır: ana ajan, her şeyi okuyup bağlamını harcamadan ihtiyaç duyulan yerlerin haritasını alır ve sonrasında somut dosyalarla çalışır.

«Orkestratör ve yürütücüler» şeması

En yaygın çoklu ajan şeması şudur: bir orkestratör ajan planı ve genel görünümü tutar, somut adımları yürütücülere dağıtır. Orkestratör tüm kodu kendisi okumaz; görevleri formüle eder, sonuçları kabul eder ve bir sonraki adıma ya da bir öncekine geri dönmeye karar verir.

1. Orkestratör görevi bağımsız parçalara böler ve her biri için kendi kendine yeterli bir talimat yazar: amaç, nerede aranacağı, neyin tamam sayılacağı, yanıtın hangi biçimde döneceği.
2. Yürütücüler talimatları kendi bağlamlarında yerine getirir.
3. Orkestratör yanıtları toplar, parçaların birbirine uyduğunu kontrol eder ve bir sonraki adımı ya da önceki adıma geri dönüşü başlatır.

Şemanın zayıf noktası görev aktarımıdır. Alt ajan yalnızca kendisine yazılanı bilir. «Konuştuğumuz hatayı düzelt» talimatı onun için boştur: tartışmayı görmemiştir. İyi bir talimat, depoyu ilk kez açan yeni bir meslektaş için yazılmış bir görev gibi okunmalıdır.

Yürütücü ne döndürmeli

Yanıt biçimini önceden belirtin: dosya listesi, çıktı, bulunan nedenler, doğrulanamayanlar. Kısa ve yapılandırılmış bir yanıt orkestratörün bağlamını korur; «doğrulanmayanlar» maddesi ise yürütücünün — her ajan gibi — başarıyı raporlama eğiliminden doğan yanlış güveni engeller.

Ayrı denetçi: yargıç ile yürütücüyü neden ayırmalı

Aynı ajan hem kodu yazıp hem de kendi kendini kontrol ettiğinde, yargıç ve sanık aynı kafayı paylaşır. Ajan ne yapmak istediğini hatırlar ve kodda yazılanı değil kendi niyetini görür. Ayrıca işi bitirmekle ilgilidir: kontrol bir formalite haline gelir.

Ayrı bağlamdaki bir denetçi bu sorunlardan uzaktır. Karar geçmişini bilmez, yalnızca diff'i ve proje kurallarını görür ve sonucu taze bir bakışla değerlendirir. Bu, canlı bir ekipteki ilkeyle aynıdır: yazar kendi pull request'ini onaylamaz.

• Denetçiye yalnızca okuma ve kontrol çalıştırma araçları verin — dosya düzenleme yetkisi vermeyin. Böylece sorunu bildirmek yerine sessizce düzeltmeye başlamaz.
• Kontrol kriterlerini açıkça yazın: hata sayılan şey nedir, hangi proje kuralları zorunludur.
• Bulgularla ne yapılacağına karar verme işini orkestratöre ya da insana bırakın. Denetçi bulur, yürütücü düzeltir.

Denetçi mekanik kontrolleri yerine koymaz. Testler, linter ve tip denetimi deterministik düğümlerdir ve her modelden daha güvenilirdir. Denetçi, mekaniğin göremediğini yakalar: yanlış mantığı, anlaşmalara aykırılığı, gereksiz karmaşıklığı.

Alt ajanları paralel çalıştırmak

Claude Code birden fazla alt ajanı aynı anda çalıştırabilir. Görevin parçaları gerçekten bağımsız olduğunda bu işi hızlandırır: üç modülü incelemek, bir değişikliği üç açıdan (güvenlik, performans, testler) kontrol etmek, birden fazla kaynaktan bilgi toplamak.

Paralellik okumada iyi çalışır, yazmada kötü çalışır. İki yürütücü aynı dosyaları aynı anda düzenlerse birbirlerinin değişikliklerini ezerler ve hiçbiri bunu fark etmez. Ajan grafiği terimleriyle bu, birleştirme kuralı olmayan ortak bir durumdur. Pratik kurallar:

• Paralel çalıştırın: araştırma, analiz, denetim. Sıralı çalıştırın: kesişen dosyalardaki düzenlemeler.
• Yürütücüler yine de paralel yazacaksa alanları ayırın: her biri yalnızca kendi dosyalarında ya da kendi depo kopyasında (örneğin ayrı bir git worktree içinde) çalışsın.
• Sonuçları tek bir düğüm, yani orkestratör birleştirsin; yürütücüler kendi aralarında birleştirmesin.

Alt ajanların gerekmediği durumlar

Çoklu ajan şeması bir bedeldir: daha fazla token, daha fazla süre, bilginin kaybolabileceği daha fazla devir noktası. Claude Code alt ajanları her zaman karşılığını vermez.

Ajanlardan bir grafik kurmadan önce basit sorulara cevap verin: genel hedefin sahibi kim, değişikliği kim veto edip geri alabilir, başarının hangi metriklerle ölçüleceği. Cevaplar yoksa birden fazla ajan yalnızca tek bir ajanın karmaşasını çoğaltır.

Alt ajanlarla sık yapılan hatalar

Belirsiz açıklama

«Kod için yardımcı» gibi bir açıklama, ana ajanın onu ne zaman çağıracağını seçmesine yardımcı olmaz. Tetikleyiciyi yazın: «api/ klasöründe değişiklik yapıldıktan sonra, commit öncesinde».

Bağlamsız talimat

Alt ajan yollar, kabul kriterleri ve kısıtlar olmadan bir görev alırsa, işin yarısını neyin istendiğini tahmin etmeye harcar. Çare bir talimat şablonudur: amaç, girdiler, kısıtlar, yanıt biçimi.

Gereğinden geniş yetkiler

Araştırmacının ve denetçinin dosya düzenleme yetkisine ihtiyacı yoktur. tools alanını kısıtlamak, rolü promptta bir istek olmaktan çıkarıp mekanik bir kısıt yapmanın ucuz yoludur.

Doğrulanmamış rapora güvenmek

Alt ajanın yanıtındaki «tüm testler geçti» bir iddiadır, gerçek değildir. Orkestratör doğrulanabilir şeylere dayanmalıdır: komut çıktısı, çıkış kodu, somut satırlar.

Özet

Claude Code alt ajanları üç işe yarar: ana bağlamı temiz tutmak, doğrulamayı yürütmeden ayırmak ve bağımsız işi paralelleştirmek. Kısa Markdown dosyalarıyla .claude/agents/ içinde tanımlanırlar ve kalitelerini büyük ölçüde rol tanımı, araç seti ve görev talimatının kendi kendine yeterliliği belirler. Görev küçükse ya da diyalogla sıkı bağlıysa tek ajan hâlâ daha iyidir. Tek bir döngüden düğümler, kenarlar ve ortak durumdan oluşan bir sisteme geçiş kursta uygulamalı olarak işlenir.