Claude Code'da alt ajanlarla fan out yapın, sonra geri geleni kontrol edin

İnsanlar Google'a «claude fan out subagents» yazıyor ve epey kişi sonuna «command» ekliyor, sanki çevrilecek bir şalter varmış gibi. Bir yöntem var, bir de komut var. İkisini de 16 Ekim 2026'da Claude Code 2.1.301 üzerinde ve Anthropic'in belgelerine göre kontrol ettik.

Sonra belgelerin pek az bahsettiği kısım geliyor, bu yazıyı yazmamızın sebebi de o: sonuçlarla ne yapılacağı. Her gece bir fan out çalıştırıyoruz. Altı alt ajan bu blogun her yeni yazısını on yedi dile çeviriyor ve ana oturum onların işini birleştiriyor. Her biri kurallara uyduğunu bildiriyor. Onları başlatmadan önce yazdığımız kontrol yine de bir şeyler buluyor.

Kısa cevap

Fan out, bir oturumun bir işi birbirine bağlı olmayan parçalara bölmesi, her parçayı bir alt ajana vermesi, hepsini aynı anda çalıştırması ve geri geleni birleştirmesi demektir. Claude Code'da bunu üç şekilde yapabilirsiniz.

Bu sayfanın geri kalanı her yolu tek tek ele alıyor, ardından kendi fan out'umuzda yaptığımız kontrolleri.

Bir alt ajan neyi görür, neyi görmez

Belgelerdeki üç gerçek, işi nasıl böleceğinizi belirler.

Her alt ajan sıfırdan başlar. Kendi bağlam penceresinde, kendi sistem prompt'u, araçları ve izinleriyle çalışır. Konuşmanızı, daha önce kullandığınız skill'leri ya da Claude'un zaten okuduğu dosyaları görmez. Bilmesi gereken her şey görev tanımında olmalıdır.

Sonuçlar ana konuşmaya döner. Bir alt ajanın işinin ayrıntılı kısmı kendi bağlamında kalır ve yalnızca sonucu geri döner. Ama uzun raporlar gönderen çok sayıda alt ajan yine de ana bağlamınızı doldurabilir ve her biri çalışırken kendi token'larını harcar.

Sınırlar var. Varsayılan olarak bir oturumda aynı anda 20 alt ajan çalışabilir. 21'inci alt ajan Concurrent subagent limit reached hatasıyla başarısız olur ve hata Claude'a yeniden denememesini söyler. Sınırı CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS ile yükseltebilir veya düşürebilirsiniz. Alt ajanlar, ana konuşmanın en fazla üç katman altına kadar kendi alt ajanlarını başlatabilir ve bir oturum boyunca toplam sayıya bir sınır yoktur.

Yol 1: düz sözcüklerle isteyin

En basit fan out tek bir cümledir. Anthropic'in belgelerindeki örnek:

Research the authentication, database, and API modules in parallel using separate subagents

Her alt ajan kendi alanını keşfeder, ardından Claude tek bir sentez yazar. Belgeler asıl önemli olan koşulu ekler: bu, araştırma yolları birbirine bağlı olmadığında en iyi sonucu verir. Veritabanı sorusu auth sorusunun cevabına ihtiyaç duyuyorsa, elinizde üç parça değil, tek bir adım dizisi vardır.

Düz sözcükler kararı Claude'a bırakır. .claude/agents/ içinde özel bir alt ajan tanımladıysanız, onu @ ile anmak o görev için çalışmasını garanti eder. Bu dosyaların nasıl çalıştığını Claude Code alt ajanları sayfamız anlatıyor.

Yol 2: /batch, bir fan out komutuna en yakın şey

/batch, Claude Code ile birlikte gelen bir skill'dir. Ona bir talimat verirsiniz:

/batch migrate src/ from JavaScript to TypeScript

Kod tabanını araştırır, işi 5 ila 30 bağımsız birime böler ve size bir plan gösterir. Onayladığınızda her birim için bir arka plan alt ajanı başlatır, her biri yalıtılmış bir git worktree içinde çalışır. Her alt ajan kendi birimini uygular, testleri çalıştırır ve değişikliğini yayınlar. Bir git deposu ya da başka bir sürüm kontrol sistemi için worktree'leri oluşturan bir WorktreeCreate hook'u gerekir.

Yavaşlamanız gereken an plandır. Bölme orada belirlenir ve her şey bölmeye bağlıdır: aynı dosyaya dokunan iki birim ya da başka bir birimin çıktısına ihtiyaç duyan bir birim, her alt ajan ne kadar iyi olursa olsun temiz bir şekilde birleşmez. Birim listesini bir meslektaşınızın hazırladığı bir geçiş planını okur gibi okuyun.

Yol 3: claude -p üzerinde bir döngü

İş bir dosya listesiyse ve her çağrı üzerinde kontrol istiyorsanız, Anthropic'in en iyi uygulamaları bir döngü tarif eder. Önce listeyi Claude'a yazdırın (list all 2,000 Python files that need migrating and save the list to files.txt). Sonra:

for file in $(cat files.txt); do
  claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)" \
    --permission-mode dontAsk
done

Bu örnekteki üç ayrıntı kopyalanmaya değer.

• Cevap makine tarafından okunabilir. «Return OK or FAIL», script'inizin düz yazı okumadan hataları sayabileceği anlamına gelir.
• İzinler baştan belirlenir. --allowedTools geçişin tam olarak ihtiyaç duyduğu şeyi onaylar, --permission-mode dontAsk ise orada olmayan birini beklemek yerine geri kalan her şeyi reddeder.
• İki üç dosyayla başlarsınız. Belgeler bunu açıkça söyler: ilk dosyalarda ters gidenlere göre prompt'u iyileştirin, sonra listenin tamamını çalıştırın.

Yazıldığı haliyle döngü dosyaları birbiri ardına işler. Birkaç çağrıyı aynı anda çalıştırmak sıradan bir shell işidir, ama her çağrı makinenizde ve kotanızda tam bir oturumdur. Birkaç ajan aynı ağır komutu aynı dakikada başlattığında ne olduğunu bu yazıda ölçtük ve burada da hikâye aynı: az sayıda paralel çağrıyla başlayın.

CI için belgeler --bare eklemeyi önerir; bu seçenek hook'ları, skill'leri, MCP sunucularını ve CLAUDE.md dosyasını atlar, böylece her makine aynı çalıştırmayı alır. Bare modu abonelik girişinizi kullanmaz: ANTHROPIC_API_KEY gerektirir.

Her gece nasıl fan out yapıyoruz

Gerçekten çalıştırdığımız fan out şu. Gece çalışan SEO ekibimiz her yeni yazıyı İngilizce ve Fransızca olarak elle yazıyor. Ardından ikinci bir ajan, Claude Code alt ajanlarıyla yazıyı on yedi dile daha çeviriyor ve Geleneksel Çinceyi çevirmek yerine bir script ile Basitleştirilmiş Çinceden üretiyor. 13 Eylül 2026'dan bu yana on bir yazı bu süreçten geçti ve her biri yirmi dosya olarak geldi.

Parçalar

Altı alt ajan, her birine üç dil (sonuncusuna iki): İspanyolca, Portekizce ve İtalyanca; Almanca, Felemenkçe ve Lehçe; Rusça, Ukraynaca ve Türkçe; Japonca, Korece ve Çince; Tayca, Vietnamca ve Endonezce; Arapça ve Hintçe. Hiçbir dil bir diğerine bağlı değil, bunu temiz bir fan out yapan da bu.

Her görev tanımı aynı beş şeyi taşır, çünkü alt ajan başka hiçbir şey görmez:

• İngilizce kaynak ve ton ile ürün terimleri için referans olarak Fransızca sürüm;
• her dil için sitede o dilde zaten yayınlanmış metinler, böylece alt ajan yenilerini uydurmak yerine sitenin zaten kullandığı sözcükleri kullanır;
• katı kurallar: marka ve ürün adları olduğu gibi kalır, kod bayt bayt aynı kalır, uzun tire yok;
• kontrol script'i ve OK diyene kadar onu çalıştırma talimatı;
• kendi parçasında ya da dışında gördüğü şüpheli her şeyi bildirme isteği.

Kontrol, başlatmadan önce yazılır

Kontrol bir script'tir, bir alt ajanın görüşü değil. Her dil için dosyayı İngilizce kaynakla karşılaştırır:

• aynı slug ve tarih, H1'e eşit başlık;
• aynı sayıda bölüm, alt bölüm, görsel, bağlantı ve tablo satırı, ve gövdede meta verilerdeki soru sayısı kadar SSS cevabı;
• bayt bayt aynı bağlantılar, bayt bayt aynı kod parçaları;
• sayılan marka adları, asla İngilizcedekinden az değil;
• her dil için ayarlanmış sınırlar içinde bir uzunluk, çünkü Çince aynı şeyi İngilizcenin ihtiyaç duyduğu karakterlerin yaklaşık %36'sıyla, Japonca ise yaklaşık yarısıyla söyler;
• dilde varsa aksanlar (Lehçe, Türkçe, Vietnamca).

Her alt ajan «bitti, tüm kontroller geçti» cümlesinin bir türeviyle bitirir. Dikkate aldığımız tek karar, ana oturumun tüm dosyalar üzerinde bir kerede yeniden çalıştırdığı aynı script'tir.

Merkezi kontrolün yakalayıp alt ajan raporlarının yakalamadığı şeyler

Tablo içinde çevrilen kod. 13 Eylül'de alt ajanların yaklaşık yarısı, bir tablodaki aynı ters tırnakların içinde bir komutun ardından gelen sözcükleri çevirdi. Her biri görev tanımını anladığı gibi uygulamıştı. Düzeltme alt ajanlara değil görev tanımına gitti: bir kod parçası yalnızca komutu içerir, ardından gelen sözcükler ters tırnakların dışında durur.

Kendi kontrolümüz yanlıştı. 6 Eylül'de, değiştirdiğimiz eski metne göre ayarlanmış bir uzunluk kontrolü 17 alt ajandan 11'ini işaretledi. 11'inin hepsi haklıydı: yeni metnin daha uzun olması gerekiyordu. Düzeltilmiş Fransızcaya göre ayarlandığında hiçbirini işaretlemedi. Merkezi bir kontrol de yanılabilir ve bunu görmenin yolu, onu önce iyi olduğunu zaten bildiğiniz bir teslimat üzerinde çalıştırmaktır.

Parçalar arasında tutarlılık. 15 Ekim'de, aynı şekilde çevrilen yeni bir özellik sayfasında, birleştirme kontrolü 90 dosya boyunca yalnızca beklenen metinlerin değiştiğini doğruladı. Ama Japonca, Korece ve Çince alt ajanlarının her biri «You may also like» için, dillerinin komşu bir sayfada zaten kullandığından farklı bir başlık seçmişti. Her seçim doğru bir çeviriydi. Hiçbiri siteyle tutarlı değildi. Hiçbir alt ajan bunu kendi parçasının içinden göremezdi: bunu yalnızca birleştirilmiş sonuç üzerinden yapılan bir geçiş görür.

Yanlış bir sözcük her yapısal kontrolü geçer. Sitenin dillerinden biri bir zamanlar yapay zeka ajanlarına oto bayileri dedi ve bu aylarca yayında kaldı. Aynı uzunluk, aynı noktalama, marka yerinde: tüm sayımlar yeşildi. Bunu yakalayan tek şey, bilinen yanlış sözcükleri tek tek sayan bir liste; bu liste her dağıtımı engeller ve her yeni sözcük bulduğumuzda bir satır uzar.

Parçanın dışındaki bildirimler. 15 Ekim'de Türkçe üzerinde çalışan alt ajan, sitenin mevcut 97 metinde «agent» için «ajan» yerine, bir kurum anlamına gelen «ajans» yazdığını bildirdi. Görev tanımı yasakladığı için onlara dokunmadı. Bir ticket açtık ve düzeltme ertesi gün yayına çıktı. Alt ajanlara yalnızca ne yaptıklarını değil, ne gördüklerini de sormak ucuzdur ve karşılığını verir.

Birleştirme tek bir yerde yapılır

Alt ajanlar depoya doğrudan yazmaz. Her biri kendi dosyalarını döndürür, bir script onları birleştirir, sonra sonucu önceki sürümle metin metin karşılaştırır: yalnızca istediğimiz metinler değişmiş olabilir. Bundan sonra deponun kontrolleri ve sitenin build'i, birleştirilmiş sonuç üzerinde bir kez çalışır. Build'i her alt ajan için bir kez çalıştırmak daha yavaş olurdu ve asla yayına çıkmayacak yarı birleştirilmiş durumları test ederdi.

Ne zaman fan out yapılmamalı

• Parçalar birbirine bağlı. B parçası A parçasının çıktısına ihtiyaç duyuyorsa, onları sırayla çalıştırın.
• İş küçük. Her alt ajan sıfırdan başlar ve ihtiyacı olanı yeniden okur. On dakikalık bir görevde yeni başlangıçlar kazandırdıklarından fazlasına mal olur.
• Kontrolü yazamıyorsunuz. Hepsini kendiniz okumadan iyi bir parçayı kötüsünden ayırmanın bir yolu yoksa, zamanınızı birleştirmede harcarsınız.
• Kota dar. Her alt ajan kendi token'larını harcar. Fan out zaman kazandırır ve ana bağlamı temiz tutar, faturayı küçültmez.

AgentsRoom nereye oturuyor

Alt ajanlar tek bir Claude Code oturumunun içinde yaşar. Onların işini değil sonuçlarını görürsünüz ve birini yolun ortasında yönlendiremezsiniz. Her parçanın izleyebileceğiniz, yanıtlayabileceğiniz ve ayrı ayrı inceleyebileceğiniz bir ajan olmasını istediğinizde, bunun yerine ayrı oturumlar çalıştırın: her ticket kendi git worktree'sinde, parçalar birbirine iş devrettiğinde de Agent Teams. Bir ekip adımı bir kontrol komutu taşıyabilir ve çalıştırmanın devam edip etmeyeceğine ajanın kendi iddiası değil, o komutun çıkış kodu karar verir. Bu, yukarıdakiyle aynı kural, bu kez çalıştırıcı tarafından uygulanıyor. Claude Code, Codex ve AgentsRoom'un desteklediği diğer ajan CLI'larıyla çalışır.

Hâlâ alt ajanlar ile Agent Teams arasında karar veriyorsanız, bu karşılaştırma her birinin ne işe yaradığını açıklıyor.