Claude Code alt ajanları (subagent), ana Claude Code oturumunun tek bir işi devrettiği yardımcılardır. Her biri kendi bağlam penceresinde, kendi sistem prompt’u, araç listesi ve modeliyle çalışır; ana sohbete sadece son yanıtı döner. Bir alt ajanı .claude/agents/ içinde bir Markdown dosyası olarak tanımlarsın. Claude, iş açıklamaya uyduğunda onu kendisi kullanır, istersen sen de adıyla çağırırsın.
Bu yazıda alt ajanların nasıl çalıştığını, dosya biçimini, tools ve model alanlarını, nasıl çağrıldıklarını ve bir alt ajanla yan yana çalışan ayrı bir ajan arasındaki farkı bulacaksın. Bilgiler resmi subagents dokümanından geliyor. Kısa tanım için sözlükteki alt ajan maddesine bakabilirsin.
Alt ajanlar nasıl çalışır
Claude bir işi devretmeye karar verince kısa bir talimatla Agent aracını çağırır (2.1.63 sürümünden önce adı Task’tı). Alt ajan temiz bir bağlamla başlar: kendi sistem prompt’u, devir mesajı, CLAUDE.md dosyan, git durumu ve onun için önceden yüklediğin skill’ler. Ana sohbetin geçmişini görmez.
Sonra izin verilen araçlarla işi yapar ve tek bir sonuç döner. Yol boyunca okuduğu her şey, onlarca dosya, uzun grep çıktısı ya da test logları, kendi bağlamında kalır. Alt ajan kullanmanın asıl nedeni bu: ana sohbete gürültü değil, özet gelir.
Bilmeye değer birkaç sınır:
- Alt ajanlar kendi alt ajanlarını başlatabilir; varsayılan olarak üç katmana kadar.
- Varsayılan olarak aynı anda 20 tane çalışabilir.
- İstekleri ana oturumla aynı kullanım limitlerinden düşer.
- Ön planda çalışabilir (ana ajan bekler) ya da ana ajan devam ederken arka planda.
Hazır gelen alt ajanlar
Claude Code, hiçbir şey yazmadan kullanabileceğin birkaç alt ajanla gelir:
| Alt ajan | Araçlar | Tipik kullanım |
|---|---|---|
| Explore | Sadece okuma | Kod tabanında arama ve okuma; hızlı, orta veya çok kapsamlı |
| Plan | Sadece okuma | Plan modundayken araştırma |
| General-purpose | Tüm araçlar | Hem araştırma hem değişiklik gerektiren çok adımlı işler |
En sık göreceğin Explore. Claude bir şeyin nerede tanımlandığını ya da bir özelliğin dosyalar arasında nasıl çalıştığını bulması gerektiğinde bu işi çoğu zaman Explore’a verir; böylece dosya dökümleri ana bağlamına dolmaz.
Alt ajan dosyaları nerede durur
Alt ajanlar YAML frontmatter’lı Markdown dosyalarıdır. Claude Code onları birkaç yerden yükler; aynı adda iki tane varsa listede üstte olan kazanır:
| Konum | Kapsam |
|---|---|
| Yönetilen ayarlar | Tüm kurum, yöneticiler belirler |
--agents bayrağı (JSON) | Tek oturum |
.claude/agents/ | Tek proje, git ile paylaşılır |
~/.claude/agents/ | Tüm projelerin |
Bir plugin’in agents/ klasörü | Plugin nerede kuruluysa |
Depoya eklemen gerekenler .claude/agents/ içindekiler; böylece tüm ekip aynı inceleyiciyi ya da test koşucusunu kullanır.
Alt ajan dosyasının biçimi
Sadece name ve description zorunlu. Frontmatter’dan sonraki gövde alt ajanın sistem prompt’udur.
---
name: code-reviewer
description: Kod değişikliklerini hata, güvenlik ve okunabilirlik açısından inceler. Kod yazdıktan veya değiştirdikten sonra kullan.
tools: Read, Grep, Glob, Bash
model: sonnet
---
Sen kıdemli bir kod inceleyicisisin. Çağrıldığında:
1. Son değişiklikleri görmek için git diff çalıştır.
2. Değişen dosyaları ve çevresindeki kodu oku.
3. Sorunları önceliğe göre raporla: hatalar, güvenlik, sonra okunabilirlik.
4. Her sorun için dosyayı, satırı ve somut bir düzeltme ver.
Dosya düzenleme. Sadece raporla.description göründüğünden daha önemli. Claude devredip devretmeyeceğine bu metne bakarak karar verir; o yüzden alt ajanın ne yaptığını ve ne zaman kullanılacağını yaz. “Kod yazdıktan sonra kullan” gibi ifadeler Claude’un onu kendiliğinden seçmesine yardım eder.
tools alanı
tools bir izin listesidir. tools: Read, Grep, Glob, Bash ile yukarıdaki inceleyici dosya okuyup komut çalıştırabilir ama düzenleyemez. tools alanını hiç yazmazsan alt ajan, MCP araçları dahil ana oturumun tüm araçlarını devralır. Neyi tutacağını söylemek yerine neyi çıkaracağını söylemek daha kolaysa disallowedTools da var.
Listeyi işin izin verdiği kadar kısa tut. İnceleyicinin Edit’e, araştırmacının Bash’e ihtiyacı yok. Daha az araç, daha az sürpriz ve daha net bir görev demek.
model alanı
model bir takma ad (sonnet, opus, haiku), tam bir model kimliği ya da ana oturumun modelini kullanmak için inherit alır. Alt ajan çağrıldığında Claude Code modeli şu sırayla seçer: o çağrıyla verilen model, dosyadaki model alanı, CLAUDE_CODE_SUBAGENT_MODEL ortam değişkeni, son olarak ana oturumun modeli.
Alt ajanların gerçekten para kazandırdığı yer burası. Geniş dosya aramaları ve log okuma nadiren en güçlü modeli ister. Bunları Haiku’ya ver, kararlar için ana oturumu büyük modelde tut. Harcamayı düşürmenin başka yolları Claude Code token tasarrufu yazısında.
İşe yarayan diğer alanlar
| Alan | Ne yapar |
|---|---|
permissionMode | Alt ajanın izin modu, örneğin plan veya acceptEdits |
skills | Başlangıçta alt ajanın bağlamına yüklenecek skill’ler |
mcpServers | Alt ajanın kullanabileceği MCP sunucuları |
hooks | Bu alt ajan çalışırken geçerli hook’lar |
memory | Kullanıcı, proje veya yerel kapsamda kalıcı hafıza |
maxTurns | Alt ajanın tur sayısı üst sınırı |
background | Varsayılan olarak arka planda çalışsın |
isolation: worktree | Geçici bir git worktree içinde çalışsın |
effort | Alt ajanın akıl yürütme düzeyi |
Alt ajan nasıl çağrılır
Üç yolu var:
- Claude karar versin. İsteğin bir alt ajanın açıklamasına uyuyorsa Claude işi kendisi devreder.
- Adıyla iste. “Son commit’imi kontrol etmek için code-reviewer alt ajanını kullan.” Menüden @ ile de anabilirsin.
- Tüm oturumu onunla çalıştır.
claude --agent code-reviewer, o alt ajanın prompt’u, araçları ve modeliyle bir oturum başlatır.
Tek seferlik bir oturum için dosya oluşturmadan alt ajanları JSON olarak verebilirsin:
claude --agents '{
"code-reviewer": {
"description": "Kod değişikliklerini inceler. Düzenlemelerden sonra kullan.",
"prompt": "Sen kıdemli bir kod inceleyicisisin. Hataları ve düzeltmeleri raporla, düzenleme yapma.",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
}
}'Claude’un belirli bir alt ajanı kullanmasını istemiyorsan onu izinlerindeki deny listesine ekle, örneğin Agent(Explore).
Alt ajan mı, ayrı paralel ajan mı?
İkisi de işi böler ama farklı sorunları çözer.
| Alt ajanlar | Ayrı paralel ajanlar | |
|---|---|---|
| Kim başlatır | Ana Claude oturumu | Sen |
| Ne görürsün | Ana sohbetin içinde son sonucu | Her ajanın tüm oturumunu |
| Bağlam | İş başına temiz, sonra atılır | Uzun ömürlü, ajan başına bir tane |
| Dosyalar | isolation: worktree yoksa aynı çalışma klasörü | Genelde her birine bir git worktree |
| İş sırasında senin katkın | Yok, onunla ana ajan konuşur | Her birini yönlendirebilirsin |
| Neye uygun | Arama, inceleme, araştırma, kısa odaklı işler | Özellikler, refactor’lar, branch ile biten uzun işler |
Ana ajanın devam etmek için bir yanıta ihtiyacı varsa alt ajan kullan: “bu fonksiyonu çağıran her yeri bul”, “bu diff’i incele”, “şu logları özetle”. İş kısa, önemli olan sonucu ve izlemene gerek yok.
Her parça kendi başına gerçek bir işse ayrı ajanlar kullan: bir özellik, bir geçiş, bir test paketi. Her birinin ne yaptığını görmek, sorularına yanıt vermek ve değişikliklerini bir branch olarak incelemek istersin. Bu kurulum paralel kodlama ajanları ve birden fazla Claude Code ajanı yazılarında anlatılıyor; her ajan kendi git worktree’sinde çalışır.
İkisi birlikte de iyi çalışır. Ayrı bir ajan kendi aramaları ve incelemeleri için yine alt ajan kullanabilir. İyi bir varsayılan şu: bir insana vereceğin işler için ayrı ajanlar, o ajanların ayak işleri için alt ajanlar. Daha büyük ekipler için roller ve devirler yapay zeka ajan ekibi yazısında, genel fikir de çoklu ajan orkestrasyonu maddesinde.
Claude Code’da birkaç Claude oturumunun birlikte çalıştığı “agent teams” adlı ayrı bir özellik de var. O, alt ajanlarla aynı şey değil ve bu yazının konusu dışında.
İşe yarayan alt ajanlar için ipuçları
- Her alt ajana tek iş. “Yardımcı” yerine “inceleyici” ve “test koşucusu” daha iyi çalışır.
- Açıklamayı Claude için yaz. Ne olduğunu değil, ne zaman kullanılacağını söyle.
- Araçları sınırla. Araştırma ve inceleme için sadece okuma; düzenleme araçlarını gerektiği yerde ver.
- Modeli bilerek seç. Arama ve özet için Haiku, tasarım ve zor düzeltmeler için daha güçlü bir model.
- Kısa rapor iste. Sonuç ana bağlama girer; alt ajana dosya dökümü değil bulgu döndürmesini söyle.
- Proje alt ajanlarını depoya ekle.
.claude/agents/git’te olursa herkes aynı yardımcıları kullanır.
AgentVera alt ajanları nasıl gösteriyor
AgentVera; Claude Code, Codex ve diğer kodlama ajanlarını yan yana çalıştırmak için bir masaüstü uygulaması. Alt ajanları iki şekilde ele alıyor.
Onları görebilirsin. Bir Claude Code ajanının panelinde “Alt ajanlar” düğmesi, o ajanın başlattığı alt ajanları ve şu an ne yaptıklarını canlı gösterir. Her birinde durumu (Çalışıyor, Bitti, Hata, Durdu), “arka planda” çalışıp çalışmadığı, aldığı “Verilen görev” ve “Rapor” görünür. Bazıları çalışırken “{count} alt ajan çalışıyor — göster” satırı çıkar, böylece gözden kaçmazlar. Proje turu ve kod haritası da tür, durum, araç sayısı ve süreyle bir alt ajan zaman çizelgesi sunar. İkisi de yerel transkriptleri okur ve şimdilik Claude Code ajanları içindir.
Daha ucuz bir Explore. Ayarlar → “Token tasarrufu” altındaki “Keşif alt ajanı” seçeneği, Claude ajanlarına geniş aramalar için sadece okuyan bir keşif alt ajanı verir. Dosya taraması daha ucuz bir modelde, varsayılan olarak Haiku’da çalışır; ana sohbete sadece sonuç döner. Kendi Explore alt ajan dosyan varsa AgentVera seninkini olduğu gibi bırakır. Aynı bölümde akıllı araçlar da var.
İş büyüyünce ayrı ajanlar. Ekip görünümü aynı anda 24 ajana kadar gösterir. Paralel ekip (Pro ve Team planları) bir hedefi parçalara böler, her birini kendi worktree’sinde çalıştırır ve tek bir PR’da birleştirir. Ajanlar arası mesajlaşma ajanların farklı CLI’lar arasında bile birbirine soru sormasını sağlar, ajan koordinasyonu da iki ajan aynı dosyaya dokunduğunda uyarır. Böylece yukarıdaki tablonun ayrı ajan tarafı elinde olur, her Claude ajanının içinde alt ajanlar da çalışmaya devam eder.
Toparlarsak
Ana ajanın bir yanıta ihtiyacı varsa ve işi izlemen gerekmiyorsa alt ajan doğru araç: arama, inceleme, araştırma. Net bir açıklama, kısa bir araç listesi ve bilerek seçilmiş bir modelle tek bir Markdown dosyası yaz. İş kendi branch’ini ve senin dikkatini hak edecek kadar büyükse ayrı bir ajan çalıştır.
Devamını oku:
- Alt ajan (sözlük)
- Paralel kodlama ajanları
- Proje turu ve kod haritası
- Paralel ekip
- Claude Code ajanı
AgentVera’yı denemek için ana sayfadan başlayabilirsin.