# Claude Code alt ajanlar (subagent) nasıl kullanılır

Adres: https://agentvera.dev/blog/claude-code-alt-ajanlar/ · Yayın: 2026-10-23

Claude Code subagent (alt ajan) nedir, .claude/agents içinde nasıl yazılır, tools ve model alanları ne işe yarar, ne zaman ayrı paralel ajanlar daha iyi seçimdir?

**Kısaca:**

- Alt ajan kendi bağlam penceresinde, kendi prompt’u, araçları ve modeliyle çalışır; ana sohbete yalnızca son yanıtı döner.
- Alt ajanlar .claude/agents/ içindeki Markdown dosyalarıdır ve yalnızca name ile description zorunludur; tools yazılmazsa ana oturumun tüm araçları gelir.
- Alt ajanlar arama ve inceleme gibi kısa işlere, ayrı paralel ajanlar ise kendi dalında biten özellik ve uzun işlere uygundur.

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](https://code.claude.com/docs/en/sub-agents "Claude Code subagents dokümanı") geliyor. Kısa tanım için [sözlükteki alt ajan maddesine](/sozluk/alt-ajan/ "Alt ajan") 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.

```markdown
---
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:

1. **Claude karar versin.** İsteğin bir alt ajanın açıklamasına uyuyorsa Claude işi kendisi devreder.
2. **Adıyla iste.** “Son commit’imi kontrol etmek için code-reviewer alt ajanını kullan.” Menüden @ ile de anabilirsin.
3. **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:

```bash
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ı](/blog/paralel-kodlama-ajanlari/ "Paralel kodlama ajanları") ve [birden fazla Claude Code ajanı](/blog/birden-fazla-claude-code-ajani/ "Birden fazla Claude Code ajanı") yazılarında anlatılıyor; her ajan kendi [git worktree’sinde](/blog/git-worktree-paralel-gelistirme/ "Git worktree ile paralel geliştirme") ç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ı](/ozellikler/proje-turu-ve-kod-haritasi/ "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ü](/ozellikler/ekip-gorunumu/ "Ekip görünümü") aynı anda 24 ajana kadar gösterir. [Paralel ekip](/ozellikler/paralel-ekip/ "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)](/sozluk/alt-ajan/ "Alt ajan")
- [Paralel kodlama ajanları](/blog/paralel-kodlama-ajanlari/ "Paralel kodlama ajanları")
- [Proje turu ve kod haritası](/ozellikler/proje-turu-ve-kod-haritasi/ "Proje turu ve kod haritası")
- [Paralel ekip](/ozellikler/paralel-ekip/ "Paralel ekip")
- [Claude Code ajanı](/ajanlar/claude-code/ "AgentVera’da Claude Code")

AgentVera’yı denemek için [ana sayfadan](/ "AgentVera") başlayabilirsin.

## Sık sorulanlar

**Claude Code’da alt ajan (subagent) nedir?** Ana Claude Code oturumunun tek bir iş için başlattığı yardımcıdır. Kendi bağlam penceresinde, kendi sistem prompt’u, araçları ve modeliyle çalışır; ana sohbete sadece son sonucu döner.

**Claude Code’da alt ajan nasıl oluşturulur?** Projendeki .claude/agents/ klasörüne, tüm projeler için ise ~/.claude/agents/ klasörüne bir Markdown dosyası ekle. YAML frontmatter’da name ve description zorunlu; gövde sistem prompt’u olur. tools, model, permissionMode ve isolation gibi alanlar isteğe bağlı.

**Alt ajan hangi modeli kullanır?** model alanı sonnet, opus veya haiku gibi bir takma ad, tam model kimliği ya da inherit alır. Belirtilmezse CLAUDE_CODE_SUBAGENT_MODEL ortam değişkeni yoksa ana oturumun modeli kullanılır.

**Alt ajanlar token tasarrufu sağlar mı?** Ana bağlamı temiz tutarlar, çünkü dosya okumaları ve arama çıktıları alt ajanda kalır. Ama iş bedava olmaz; alt ajan istekleri aynı kullanım limitlerinden düşer. Asıl tasarruf, geniş aramaları Haiku gibi daha ucuz bir modele vermekten gelir.

**Ne zaman alt ajan yerine ayrı ajan kullanmalıyım?** İş uzunsa, çok dosyaya dokunuyorsa, arada senin yönlendirmen gerekiyorsa ya da ayrı bir branch olarak bitmesi gerekiyorsa. Kendi git worktree’sindeki ayrı ajanlar bunu sağlar; alt ajanlar ise ana ajanın sonucuna ihtiyaç duyduğu kısa, odaklı işlere uyar.

---

**AgentVera hakkında.** AgentVera, Solviera Teknoloji tarafından geliştirilen macOS, Windows ve Linux masaüstü uygulamasıdır. 18 yapay zeka kodlama ajanını (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) proje bazında, gerçek terminallerde ve kullanıcının kendi CLI kurulum ve girişleriyle yan yana çalıştırır. Ücretsiz planda sınırsız ajan vardır. İndir: https://agentvera.dev/indir/ · Fiyatlar: https://agentvera.dev/fiyatlar/