Subagent nedir ve beş kodlama aracında nasıl kullanılır?

Alt ajan işi ayrı bağlamda yapar, size sonucu döner

Bir kodlama ajanına büyük bir iş verdiğinizde iki yol var: ana konuşma her şeyi kendisi yapar ya da işin bir parçasını bir alt ajana (subagent) devreder. Alt ajan o parçayı kendi bağlamında yapar; okuduğu dosyalar, koştuğu testler ana konuşmayı doldurmaz.

Cursor belgesi bunu iki cümleyle söylüyor: “Intermediate output stays in the subagent. The parent only sees the final summary.” 18 Ekim 2026 itibarıyla alt ajan beş araçta var: Claude Code, OpenAI’ın Codex’i, Cursor, Google’ın Gemini CLI’ı ve GitHub Copilot. Claude Code, Cursor ve Copilot alt ajanın kendi bağlam penceresinden söz ediyor; Gemini CLI ayrı bir bağlam döngüsü diyor, Codex ise ajanları paralel başlatıp sonuçlarını tek yanıtta topluyor.

Bu yüzden iki işte kazandırır: çıktısı kalabalık işler (test koşmak, günlük taramak, onlarca dosya okumak) ve birbirinden bağımsız araştırmalar. Örnekler, diffox’u geliştirirken her gün kullandığımız depodan; orada Claude Code çalışıyor.

Alt ajan sohbet geçmişinizi görmez; görev metni kendi başına anlaşılmalı

Alt ajanla en sık yapılan hata, ana konuşmada konuşulanı bildiğini varsaymaktır. Claude Code belgesine göre alt ajan yeni bir bağlam penceresiyle başlar: sohbet geçmişinizi, çağrılmış skill’leri ve Claude’un okuduğu dosyaları görmez. Başlarken elinde olan şudur:

Bu yüzden görev metni amacı, dokunabileceği dosyaları ve ne raporlayacağını kendi başına söylemelidir. Ana konuşmada “şu hatayı” diye andığınız şey alt ajan için yoktur; dosya yolunu, hata mesajını ve beklenen çıktıyı yazın. Cursor belgesi de aynısını söylüyor: alt ajanlar boş bir bağlamla başlar ve önceki sohbet geçmişine erişemez. Codex, Gemini CLI ve Copilot belgeleri bunu yazmıyor; hangi araçla çalışırsanız çalışın görev metnini kendi başına anlaşılır yazmak güvenli yoldur. Codex belgesi ise ayrıca alt ajandan ara çıktı yerine özet döndürmesini istemeyi öneriyor.

Beş araçta alt ajan: tanım klasörü, devretme, yerleşik ajanlar

Beşinde de alt ajan bir dosyayla tanımlanır ve proje ya da kullanıcı düzeyinde durur. Araçların asıl ayrıldığı yer, ana ajanın işi kendiliğinden devredip devretmediğidir:

Kaynak: her aracın alt ajan belgesi, 18 Ekim 2026. Codex’te tanım TOML, diğerlerinde YAML başlıklı Markdown dosyasıdır. Gemini CLI’ın tarayıcı ajanı varsayılan olarak kapalı. Copilot’un yerleşik ajan listesi sayfadan sayfaya değişiyor: başvuru sayfası yedi, nasıl yapılır sayfası dört sayıyor.

Tablonun ayrıldığı yer üçüncü sütun. Codex’te bu, effort düzeyine bağlı: modeller sayfası en üst düzey Ultra’nın işi alt ajanlara bölerek yürüttüğünü yazıyor; alt ajan sayfası ise yerel Codex’in alt ajanı “iki ajan başlat” gibi doğrudan bir istekle ya da AGENTS.md veya bir skill’deki yönergeyle başlattığını söylüyor. Diğer dördünde ana ajan işi kendisi de devredebilir; Copilot’un belgesi modelin işi devretmeyip kendisi de yapabileceğini ayrıca söylüyor.

Tanımlar araçlar arasında taşınıyor: Cursor .claude/agents/ ve .codex/agents/ klasörlerini de okur (aynı adda .cursor/ kazanır), Copilot CLI de .claude/agents/’ı okur. Yani .claude/agents/ altına yazdığınız dosyayı Claude Code, Cursor ve Copilot CLI okur; frontmatter alanlarının üçünde de aynı çalıştığını belgeler garanti etmiyor.

Google, 18 Haziran 2026’da ücretsiz kullanıcılar ile Google AI Pro ve Ultra aboneleri için Gemini CLI’ın hizmetini durdurup onları Antigravity CLI’a yönlendirdi; ücretli API anahtarıyla ya da şirket lisansıyla Gemini CLI’ı kullanmaya devam edebilirsiniz. Antigravity’nin alt ajan belgesini 28 Ekim 2026 günü okuduk. Alt ajanlar projede .agents/agents/, kullanıcı için ~/.gemini/config/agents/ klasöründe tanımlanıyor. Ana ajan, işi alt ajanın açıklamasına bakarak devrediyor; hazır gelen üç ajan var: research, browser ve self. Alt ajan ana ajanın sohbet geçmişini almıyor, işe temiz bir bağlamla başlıyor; tanımında model yoksa ana ajanın modeliyle çalışıyor. İç içe en çok 10 kat açılabiliyor.

İyi bir alt ajan tanımı dar bir iş, dar araçlar ve kısa bir rapor ister

Tanım dosyası üç şeyi belirler: ne zaman çağrılacağını (açıklama), neye erişeceğini (araçlar) ve ne döndüreceğini (prompt). Claude Code’da şöyle görünür; zorunlu alanlar name ve description:

---
name: test-runner
description: Testleri çalıştırır, yalnızca başarısız olanları raporlar
tools: Read, Grep, Glob, Bash
model: haiku
---

Test paketini çalıştır. Yalnızca başarısız testleri, her birini hata
mesajıyla birlikte raporla. Hiçbir dosyayı düzenleme.

• Açıklama bir tetikleyicidir. Claude Code ve Gemini CLI işi açıklamaya bakarak devreder. Açıklamaya ajanın ne olduğunu değil, ne zaman çağrılacağını yazın.
• Araçları daraltın. Claude Code’da tools alanı alt ajanın kullanabileceği araçları sınırlar; boş bırakırsanız alt ajanlara açık bütün araçları devralır. Yalnız okuyacak bir ajana yazma aracı vermeyin.
• İzinler ana ajandan gelir. Codex’te alt ajan ana ajanın izinlerini, sağlayıcısını ve MCP sunucularını devralır; tanım dosyası bunları değiştiremez. Sandbox ve onay ayarı da ana ajanınkidir.
• Raporu kısa isteyin. Prompt’un son cümlesi ne döneceğini söylesin: başarısız testler, bulunan dosyalar, bir karar. Uzun ara çıktı ana konuşmaya geri taşınırsa alt ajanın kazancı kaybolur.
• Otomatik kullanımı kapatabilirsiniz. Copilot bulut ajanında disable-model-invocation: true yazan ajan yalnız elle seçilince çalışır. Copilot’ta bir özel ajanın prompt’u en çok 30.000 karakter olabilir.

Model, eşzamanlılık ve iç içe sınırları araca göre değişir

Tanımda model yazmazsanız belgelere göre Claude Code, Codex, Cursor ve Copilot’ta alt ajan ana ajanın modeliyle çalışır. Gemini CLI’nın alt ajan sayfası da aynısını yazıyor, ama aynı belgenin model sayfası /model komutunun ve --model bayrağının alt ajanların modelini değiştirmediğini söylüyor; ikisi tam örtüşmüyor. Aynı anda kaç alt ajan çalışabileceği ve alt ajanın başka bir alt ajan başlatıp başlatamayacağı ise araca göre değişir:

Kaynak: her aracın alt ajan belgesi, 18 Ekim 2026. “Belgede yazmıyor”: o gün okuduğumuz sayfalarda bu bilgiyi veren bir cümle bulamadık. Copilot CLI’ın başvuru sayfası ortam değişkenleri bölümünde derinliği 4, sınırlar tablosunda 6 veriyor. Gemini CLI her alt ajanı varsayılan olarak 30 tur ve 10 dakikayla sınırlar.

Claude Code modeli sırayla dört yerden arar: o çağrıdaki model parametresi, tanımdaki model alanı, CLAUDE_CODE_SUBAGENT_MODEL ortam değişkeni, sonra ana konuşmanın modeli. Sınıra takılınca ne olduğu da yazılı: 20 alt ajan çalışırken yenisi başlatılamaz ve hata, Claude’a yeniden denememesini söyler. Gemini CLI iç içe çağrıyı sonsuz döngüyü ve aşırı token harcamasını önlemek için kapatıyor.

Effort düzeyi çoğu araçta alt ajan sayısını değiştirmez

Beş aracın beşinde de modelin bir cevaba ne kadar düşünerek varacağını belirleyen bir ayar var: effort ya da akıl yürütme düzeyi. Alt ajanla ilişkisi iki soruda toplanıyor: alt ajan ana ajanın düzeyini devralır mı, kendi düzeyini seçebilir mi?

Kaynak: her aracın model ve alt ajan belgesi, 18 Ekim 2026. Cursor’da düzeylerin adları modele göre değişiyor.

Claude Code, Cursor, Gemini CLI ve Copilot’un belgeleri effort’u alt ajan sayısına bağlamıyor. Claude Code belgesi yüksek düzeyde gördüğü farkı şöyle anlatıyor: “tested more edge cases and verified more of its work before answering. It also made more choices on its own.” Alt ajan sayısından söz etmiyor. Copilot’ta paralel alt ajanlar effort’a değil ayrı bir moda bağlı: /fleet komutunda ana ajan işi parçalara bölüp bölemeyeceğine kendisi karar verir.

İstisna Codex’in en üst düzeyi ultra. Modeller sayfası CLI, uygulama ve IDE için aynı cümleyi kuruyor: “Ultra mode goes beyond a single-agent run. It uses subagents to accelerate complex work.” ChatGPT Work’te de Ultra, uygun işi alt ajanlara kendiliğinden devretmeyi açıyor. Diğer düzeylerde ise alt ajan sayfasına göre yerel Codex alt ajanı istenince ya da AGENTS.md veya bir skill söyleyince başlatır.

Ultracode: Claude Code’da işi onlarca alt ajana bölen ayar

Claude Code’un /effort kaydırıcısında effort düzeylerinin yanında bir de ultracode anahtarı var. Belge onu bir düzey olarak değil, ayrı bir ayar olarak tanımlıyor: “a Claude Code setting rather than a model effort level”. Açıkken Claude, esaslı her iş için siz istemeden bir dinamik iş akışı planlar: işi bölen ve alt ajanları yöneten bir betik yazar, betiği bir çalışma ortamı arka planda yürütür; oturumunuz bu sırada yanıt vermeye devam eder.

Açmanın dört yolu var:

• Tek bir iş için: prompt’unuza ultracode kelimesini yazın; oturumun effort düzeyi değişmez. Kelime yalnız sizin yazdığınız prompt’ta sayılır.
• Oturum boyunca: /effort ultracode ya da kaydırıcıdaki anahtar.
• Açılışta: claude --effort ultracode; bu, effort düzeyini de xhigh yapar.
• Her oturumda: ayar dosyasında "ultracode": true.

Bedeli belgede açıkça yazıyor: her istek daha çok token harcar ve daha uzun sürer; abonelikte oturum ya da haftalık sınıra daha erken ulaşırsınız. Ultracode açıkken 20 alt ajan sınırı uygulanmaz; iş akışının kendi sınırları vardır: varsayılan olarak aynı anda 16 ajan, bir koşuda en çok 1.000 ajan. Ultracode kapalıyken 25’ten çok ajan ya da 1,5 milyon token tahmini “Large workflow” uyarısı çıkarır; ultracode açıkken bu uyarı da gösterilmez.

Dinamik iş akışları Mayıs 2026’nın sonunda geldi ve haftalık özette “research preview” olarak duyuruldu; iş akışları sayfasında 18 Ekim 2026 günü bir durum etiketi yoktu. Adı benzeyen iki şeyle karıştırmayın: ultrathink yalnız o tur için daha derin düşünme ister ve effort düzeyini değiştirmez; /code-review ultra ise bulutta inceleme ajanları çalıştıran ayrı bir komuttur ve Claude onu kendiliğinden başlatmaz.

Alt ajanlar birbiriyle konuşur mu: araca göre değişir

Alt ajanın sonucu çağırana döner; bu beşinde de ortak. Araçlar üç soruda ayrılıyor: alt ajanlar birbirine yazabilir mi, ana ajan çalışan ya da bitmiş bir alt ajana sonradan yazabilir mi, bir takım özelliği var mı?

Kaynak: her aracın belgesi, 18 Ekim 2026. Copilot’ta kardeş ajanlara yazmak için paylaşılan kardeş iletişimi açık olmalı; belge nasıl açıldığını yazmıyor.

Claude Code’un agent teams özelliği bu işin en ileri hâli: bir oturum takımın lideridir, üyeler ayrı oturumlardır, her biri kendi bağlam penceresinde çalışır ve birbirine adıyla yazar. Herkese birden yazmak yok; her alıcıya ayrı mesaj gider. Belgenin kendi ölçütü: “Use subagents when you need quick, focused workers that report back. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own.” Agent teams deneyseldir, varsayılan olarak kapalıdır ve her üye ayrı bir Claude örneği olduğu için daha çok token harcar.

Yazışabilmek, yazışmaya dayanmayı gerektirmez. En sağlam düzen hâlâ işi birbirinden bağımsız parçalara bölmek ve sonucu ana ajanda birleştirmek. Copilot’un fleet belgesi de bunu söylüyor: koordinasyon örtük ortak bellekle değil açık bir durumla yürür, alt ajanlar çağrılar arasında durum tutmaz; her birine eksiksiz bağlam verin.

Paralel ajanlar ayrı worktree ve ayrı dosyalarla güvenli çalışır

Okumakla yetinen alt ajanlar aynı dizinde yan yana çalışabilir. Sorun, birden çok ajan dosya düzenleyip commit attığında başlar: aynı dizini, aynı dalı ve aynı git index’ini paylaşırlar. Bu, hangi aracı kullandığınızdan bağımsız bir git sorunudur. Depomuzda bunun için dört kural var.

Ayrı worktree. Claude Code’da tanıma isolation: worktree yazarsanız alt ajana geçici bir worktree, yani deponun ayrı bir çalışma dizini açılır; alt ajan değişiklik yapmadan biterse kendiliğinden kaldırılır. Belgeye göre bu worktree varsayılan olarak üzerinde çalıştığınız daldan değil, deponun varsayılan dalından açılır.

Ayrı dosyalar. Aynı dizini paylaşan ajanlar için kuralımız: commit kendi yollarıyla atılır (git commit --only <yollar>), çünkü yalın bir git commit index’in tamamını, başka ajanın hazırladığı işi de alır. İşi bölerken her ajana ayrı bir dosya kümesi verin.

Tek başına anlaşılan görev metni. Claude Code ve Cursor’da alt ajan sohbet geçmişinizi görmez; görev metni amacı, dokunabileceği dosyaları ve ne raporlayacağını kendi başına söylemelidir. Ayar dosyasındaki hook’lar ise kendiliğinden ulaşır: Claude Code’da PreToolUse hook’u alt ajanın araç çağrılarından önce de çalışır.

Temizlik. Değişiklik içeren worktree diskte kalır. Depomuzda 27 Ağustos 2026’da 41 worktree birikmişti, 37’si tek bir inceleme turundan. Dağınıklığı insanlar değil iş akışları ürettiği için çözüm de oraya kondu: her oturum, birleşmiş pull request’lerin dallarını ve işi bitmiş worktree’leri kaldıran bir betikle açılıyor.

Her işe alt ajan gerekmez

Alt ajan bağlamı korur ama kendi bağlamını sıfırdan kurar; görev metnini yazmak ve sonucu okumak da bir maliyettir. Claude Code belgesi şu durumlarda ana konuşmayı öneriyor:

• Sık soru-cevap gerekiyorsa. İşi adım adım birlikte düzelteceksiniz.
• Aşamalar aynı bağlamı paylaşıyorsa. Planlama, uygulama ve test aynı bilgiye dayanıyor.
• Değişiklik küçük ve hedefi belliyse. Bir dosyada birkaç satır.
• Hız önemliyse. Alt ajan işe sıfırdan başlar ve bağlam toplamak zaman alır.

Alt ajanın yeri tek bir soruyu kendi başına cevaplayabilen işlerdir: “testleri koş, başarısızları getir”, “bu modülü kim çağırıyor”, “bu üç kütüphaneyi karşılaştır”. diffox’un incelemesi de bu fikre dayanır: yapay zekâ kod incelemesini uzman ajanlara böler, her biri değişikliğe kendi sorusuyla bakar. Nasıl seçildiklerini mimari yazımızda anlattık.