Claude Code ile Verimli Çalışmak — Bölüm 2: Ajanlar, Alt Ajanlar ve Çoklu Ajan Kurulumları

Bölüm 1'de odağımız tek bir oturumu olabildiğince keskin ve derli toplu tutmaktı: bağlam penceresini (context window) takip etmek, gereksiz şişirmemek ve tam olarak ne istediğimizi bilerek yönlendirmek. Bu bölümde ise çıtayı bir seviye yukarı taşıyoruz.

Bir görev artık tek bir pencereye rahatça sığmayacak kadar büyüdüğünde —dallanıp budaklanan bir araştırma, projenin her yerine dokunan kapsamlı bir gözden geçirme ya da aynı anda ilerlemesi gereken üç bağımsız değişiklik gibi— çözüm bilgiyi daha fazla sıkıştırmak değildir. Çözüm işi devretmektir (delegation).

Ajanların ve alt ajanların varlık sebebi tam olarak bu. Bu yazının sonunda alt ajanların perde arkasında aslında ne olduğunu, başarılı bir sonuç almak için bir alt ajana nasıl brifing verileceğini, kendi özel ajanlarınızı nasıl kurgulayacağınızı, devretmenin ne zaman kazandırdığını ve birden fazla Claude'u birbirinin işini bozmadan paralel nasıl çalıştıracağınızı öğrenmiş olacaksınız.

Alt Ajan (Subagent) Gerçekte Nedir?

Alt ajan, ana oturumunuzun tek bir odaklı görevi halletmek için arka planda fırlattığı bağımsız bir Claude sürecidir. Ana ajan perde arkasında bir araç (Task aracı) çağırır ve ona bir talimat verir. Bu talimatla birlikte, sıfır hafızayla çalışan yepyeni bir Claude başlar. İşini tamamladığında ise size tek bir sonuç özet raporu döndürür. Arada gerçekleşen bütün o dosya okumaları, arama adımları ve denemeler sizin ana pencerenizde hiç görünmez.

Alt ajanları bu kadar değerli kılan üç temel özellik var:

• Kendine ait bağımsız bağlam penceresi: Alt ajan dosyaları okur, komut çalıştırır ve analizini kendi temiz penceresinde yapar. Bunların hiçbiri sizinkine yük bindirmez. Bölüm 1'de, Claude'un açtığı her dosyanın o kısıtlı bağlam alanını kaplamak için nasıl yarıştığını konuşmuştuk; alt ajanlar bu maliyetli işi başka bir alana taşıyarak kısıtı ortadan kaldırır.
• Özelleştirilebilir araçlar (ve model seçimi): Bir alt ajana ana oturumdaki araçların tamamını verebileceğiniz gibi, sadece dar bir izin listesi de tanımlayabilirsiniz. Hatta onu ana oturumunuzdan daha ucuz ve hızlı bir modelde (örneğin Haiku) çalıştırabilirsiniz.
• Tertemiz bir başlangıç: Sohbetinizin geçmişine dair hiçbir hafızası olmadan başlar. Sadece ona verdiğiniz talimatı ve projedeki CLAUDE.md dosyasını görür. İşini bitirip özetini sunduktan sonra o pencere kapanır ve yok olur.

İnsanların en çok takıldığı yer tam olarak bu son özellik. İşi devretmek bir sohbet başlatmak değil, net bir devir teslimdir. Alt ajan size takıldığı yerde hızlıca bir soru soramaz veya az önce konuştuğunuz detayları bilemez. Ona, CLAUDE.md'yi okumuş ama projenin o anki sohbetinden habersiz, ekibe yeni katılmış birine anlatır gibi baştan brifing vermelisiniz.

Neden Devretmeli: Bağlam İzolasyonu

Farkı hissetmenin en kestirme yolu, jetonların (token) nereye harcandığını izlemektir. Rutin bir görevi ele alalım ("Auth akışının şu 18 dosyada nasıl ilerlediğini izle"). Bu işi doğrudan ana oturumda yapmakla bir alt ajana devretmeyi karşılaştıralım:

Doğrudan ana oturumda yaptığınızda o 18 dosyanın tamamı pencerenize yığılır ve orada kalır; sonrasında gelen her şeyi otomatik sıkıştırmaya (auto-compaction) doğru zorlar. Devrettiğinizde ise alt ajan onları kendi penceresinde eritir ve geriye temiz bir paragraf döndürür. Cevap aynıdır; ama ana oturumunuz neredeyse hiç şişmez.

Bunu uzun bir çalışma gününe yayın: Akşama kadar akıcı ve keskin kalan bir oturum ile daha öğlen olmadan tıkanan bir oturum arasındaki fark işte budur.

💡 Pratik Kural: Bir görev okuma-ağırlıklı ama çıktısı küçük bir bilgiden oluşuyorsa, onu devredin. "X nerede tanımlanmış?", "Kod tabanında Y zaten yapılıyor mu?" gibi araştırmaların tamamı özet biçimlidir ve özet biçimli işler, alt ajanların tam olarak var olma sebebidir.

Bir Alt Ajana İyi Brifing Vermek

Alt ajan ana sohbetinizi göremez. Bu yüzden ana oturumda tolere edilebilen muğlak ifadeler burada patlar; çünkü arkasına sığınabileceği ortak bir geçmiş yoktur. İyi bir brifing dört şey taşır: Hedef, başlamaya yetecek bağlam (dosya yolları/giriş noktaları), açık bir başarı ölçütü ve ne döndürüleceği.

❌ İş görmeyen brifing:

auth hatasına bir bak

✅ Doğrudan sonuç alan brifing:

Oturum token'larının nasıl doğrulandığını araştır.
- src/auth/ ve middleware/ klasörlerinden başla.
- Şunu bul: doğrulama sırası ve bir token'ın
  kontrol edilmeden güvenilir sayıldığı her yer.
- Yalnızca oku, hiçbir şeyi değiştirme.
- Kısa bir liste döndür; her bulgu için file:line ver.

İkincisi alt ajana nereden başlayacağını, "bitti"nin neye benzediğini ve geri istediğiniz yanıtın tam formatını söyler. Brifing ne kadar sıkıysa özet o kadar işe yarar; ilk rapor konuyu ıskaladığı için yeniden devretmek zorunda kalma ihtimaliniz de o kadar azalır.

Hazır Gelen Ajanlar ve Kendi Kurduklarınız

Kutudan çıktığı haliyle elinizde genel amaçlı (general-purpose) bir ajan var. Claude'un bir şeyi gidip bulmasını ya da açık uçlu, çok adımlı bir arama yapmasını istediğinizde başvurduğu varsayılan ajan budur. Hiçbir şey ayarlamanıza gerek kalmaz; "araştır" veya "kod tabanında şunu ara" demeniz çoğu zaman bunu kendiliğinden tetikler.

Ancak asıl kaldıraç özel ajanlarda (custom agents). Özel bir ajan; üst kısmında biraz YAML yapılandırması (frontmatter) ve gövdesinde bir sistem talimatı olan basit bir Markdown dosyasıdır. İki yerden birinde durur:

• .claude/agents/<isim>.md — Git'e dahil edilen ve ekibinizle paylaşılan projeye özel ajanlar.
• ~/.claude/agents/<isim>.md — Tüm projelerinizde geçerli olan kişisel ajanlarınız.

İsimler çakıştığında proje sürümü kazanır. Bu dosyaları elle yazabilir ya da /agents komutunu kullanarak etkileşimli bir arayüz üzerinden oluşturabilirsiniz. İşte eksiksiz bir örnek:

---
name: test-author
description: Yeni kod için testler yazar ve çalıştırır. Bir özellik uygulandıktan sonra PROAKTİF kullan.
tools: Read, Write, Edit, Bash
model: sonnet
---
 
Odaklı, yüksek sinyalli testler yazarsın. Her değişiklik için:
1. Test edilen kodu ve mevcut testlerini oku.
2. Mutlu yolu, uç durumları ve hata yönetimini kapsa.
3. Test setini çalıştır ve yeşile dönene dek yinele.
Yalnızca şunu raporla: Neyi test ettin, ne geçti ve hâlâ ne başarısız.

Dört alan tüm yükü taşır:

• name — Onu nasıl çağırdığınız (test-author ajanını kullan) ve sistemde nasıl göründüğü.
• description — Onu ne zaman kullanacağı. Claude, kendi başına devredip devretmeyeceğine karar vermek için burayı okur; o yüzden bir özgeçmiş gibi değil, bir tetikleyici gibi yazın. "PROAKTİF kullan" ya da "MUTLAKA kullanılmalı" gibi ifadeler onu otomatik devretmeye iter.
• tools — Bir izin listesi. Bunu atlarsanız ajan tüm araçları (MCP sunucularınız dahil) devralır; kısıtlarsanız daha güvenli ve öngörülebilir bir işçi elde edersiniz.
• model — Bu ajana özel bir model ya da ana oturumunuzla eşleşmesi için inherit. Mekanik işleri daha ucuz ve hızlı bir modele verin, güçlü olanı zor akıl yürütmeye saklayın.

O tools alanı göründüğünden daha güçlüdür. Write ve Edit'i çıkarın; kodunuza elini bile süremeyen salt-okunur bir ajan yazmış olursunuz. Bir kod inceleyici için birebir:

---
name: code-reviewer
description: Bir diff'i hata, güvenlik ve stil açısından inceler. Her commit'ten önce PROAKTİF kullan.
tools: Read, Grep, Glob, Bash
model: sonnet
---
 
Titiz bir gözden geçirensin. Bir değişiklik verildiğinde:
1. Neyin değiştiğini görmek için `git diff` çalıştır.
2. Doğruluk hatalarını, güvenlik açıklarını ve eksik testleri işaretle — en kritik olan en başta.
3. Her madde için file:line alıntıla. Kodu yeniden yazma; raporla.

Ne Zaman Bir Alt Ajana Başvurmalı?

Devretmek bedelsiz değildir; bir alt ajan gecikme ekler, kendi jetonlarını harcar, ona brifing vermek de zamanınızı alır. Dolayısıyla bazı görevlerde hakkını verir, bazılarında ise yalnızca ayak bağı olur.

Ortak nokta: Sonucu küçük ve kendi kendine yeten işi devredin; değeri diyalogda olan işi ana oturumunuzda tutun.

Aynı Anda Birkaçını Çalıştırmak: Çoklu Ajan Ortamı

Her alt ajan izole olduğu için ana oturumunuz bir orkestra şefi (orchestrator) gibi davranabilir: Aynı anda birkaç tanesini fırlatır ve bittikçe özetlerini toplar. Ana ajan tek bir adımda birden çok Task çağrısı yaptığında bunlar eşzamanlı çalışır; bir seferde birkaçı yürür, fazlası da arkalarında kuyruğa girer. Araç basit bir sohbet kutusu olmaktan çıkıp küçük bir ekip gibi hissettirmeye işte burada başlar.

İki desen tekrar tekrar karşınıza çıkar:

1. Dağıtarak arama (Fan-Out): Birkaç salt-okunur ajan aynı anda farklı şeylere bakar (biri veri akışını izler, biri yardımcı fonksiyonları arar, biri testleri kontrol eder) ve her yanıtı, toplam süre yerine sadece en yavaşının süresinde geri alırsınız.
2. Bul, sonra doğrula: Bir ajan bir düzeltme önerir ya da hataları işaretler; ikinci, şüpheci bir ajana her iddia teker teker verilir ve doğrulaması istenir. Bağımsız doğrulama, tek bir geçişte gözden kaçıp makul görünen ama aslında yanlış olan yanıtları yakalar.

⚠️ Kritik Detay: İzole bağlam pencereleri bir yana, dosya sistemi tek bir yerdir. Üç ajanı aynı çalışma dizinine yöneltip hepsine düzenleme yaptırırsanız birbirlerinin değişikliklerinin üzerine yazarlar. Paralel okuma güvenlidir. Paralel yazma izolasyon ister.

Paralel İşi git worktree ile İzole Etmek

Gerçekten paralel, yazma-ağırlıklı iş için en temiz yol git worktree kullanmaktır. Bir worktree, aynı deponun kendi klasöründe ve kendi dalında (branch) duran ikinci bir kopyasıdır; böylece her oturum, düzenlemelerinin başkasınınkiyle çakışamayacağı bir kum havuzu edinir:

# Paralel görev başına bir izole kopya oluşturun
git worktree add ../app-auth -b auth-refactor
git worktree add ../app-perf -b perf-pass
 
# Her birinde ayrı bir Claude Code oturumu çalıştırın
cd ../app-auth && claude

Artık 2-3 oturum gerçekten aynı anda çalışabilir ve işleri bitince dalları ana koda birleştirirsiniz. Baştan bilmekte fayda olan birkaç tuzak var:

• Bağımlılıklar kopyalanmaz: node_modules her worktree'nin içinde yaşar; o yüzden genelde her yeni worktree'de bir kez npm install yaparsınız.
• Farklı portlar seçin: İki dev sunucusu aynı :3000 portuna bağlanamaz. Her oturuma kendi portunu verin.
• Durum tutan işleri paralel çalıştırmayın: Aynı veritabanına migration çalıştıran iki ajan birbiriyle kapışır. Veriyi de izole edin ya da o adımları sıraya koyun.
• Bitince temizleyin: git worktree remove ../app-auth komutu, birleştirdikten sonra kopyayı toparlar.

Bu; birbirine ayak bağı olan ajanlar ile yapısal olarak birbirine giremeyen ajanlar arasındaki temel farktır.

Baştan Sona Örnek Bir Akış

Hepsini birleştirdiğinizde tipik bir "büyük" görev şöyle akar:

1. Önce keşfedin: Salt-okunur bir araştırma devredin ("Bildirimlerin bugün nasıl gönderildiğini haritala ve işin içindeki her dosyayı listele"). Bir özet geri gelir; ana pencereniz, okunan 20 dosyadan arınmış kalır.
2. Özetten planlayın: Bağlamda yalnızca damıtılmış harita varken, siz ve ana oturum bir yaklaşımda anlaşırsınız.
3. İşi paralele dağıtın: Bağımsız parçalar ayrı worktree'lerdeki paralel oturumlara gider; test-author ajanı her parça tamamlandıkça onu kapsar.
4. Birleştirmeden önce gözden geçirin: Salt-okunur code-reviewer ajanı her diff'i denetler ve rapor eder.
5. Birleştirin ve temizleyin: Her dalı ana dala birleştirin, sonra worktree'leri kaldırın (git worktree remove).

Deseni fark edin: Ağır, her-şeyi-oku işi her zaman dışarıya, izole pencerelere itilir; ana oturumunuz ise hafif bir kontrol kulesi olarak kalır. Bölüm 1'in dersi, artık ekip ölçeğinde.

Kaçınılması Gereken Efsaneler

• "Alt ajan sohbetimizi hatırlar." Hatırlamaz. Yalnızca kendi prompt'unu ve CLAUDE.md'yi görür. Ona tam brifing verin.
• "Daha çok ajan her zaman daha hızlıdır." Devretmenin bir maliyeti vardır; basit ya da sıkı bağlı işlerde tek oturum kazanır.
• "Paralel ajanlar aynı klasörü paylaşabilir." Yalnızca okuma için. Paralel yazma ayrı worktree'ler ister, yoksa birbirlerinin kodunu bozarlar.
• "Salt-okunur bir ajan yine de koda dokunabilir." tools listesinden Write/Edit çıkarıldıysa dokunamaz. İzin listesi bir öneri değil, gerçek bir sınırdır.

Buradan Nereye?

İki bölüm, tek bir ana damar: Mesele hep bağlam yönetimiydi. Bölüm 1 tek bir pencereyi hafif tuttu; Bölüm 2 ağır işi kendi pencerelerine itip geri kalanı tek bir ana oturumdan yönettirdi. Buna alışın (okuma-ağırlıklıyı devredin, yazma-ağırlıklıyı izole edin, merkezi temiz tutun) ve Claude Code, tuş tuş yönlendirdiğiniz bir araç olmaktan çıkıp yönettiğiniz gerçek bir iş arkadaşına dönüşsün.

Küçük başlayın: Tekrarladığınız bir iş için tek bir özel ajan yazın ve bir sonraki büyük araştırmanızı doğrudan yapmak yerine devredin. Bütün alışkanlık bundan ibaret.

Okuduğunuz için teşekkürler. Şimdi sıra sizde!