Claude Code'da Subagent (Alt Ajan) Kullanımı: Kapsamlı Rehber

Claude Code'da uzun bir görev verdiğinizde bazen şunu fark edersiniz: konuşma, ihtiyacınız olmayan arama sonuçları, log çıktıları ve okunan dosya içerikleriyle şişer; bağlam penceresi dolar, Claude asıl işten uzaklaşır. Subagent (alt ajan) tam olarak bu sorunu çözmek için var: belirli bir görevi kendi izole bağlam penceresinde, kendi sistem promptu ve kendi araç erişimiyle yürüten, sonunda yalnızca bir özetle ana konuşmaya dönen özel bir yapay zekâ yardımcısı. Bu yazıda subagent'ların ne olduğunu, hazır gelen ajanları, kendi subagent'ınızı nasıl oluşturacağınızı, frontmatter alanlarını, araç ve model kontrolünü, ön plan/arka plan çalışmayı ve zincirleme iş akışlarını -- tamamen resmi Claude Code dokümantasyonuna (code.claude.com/docs) dayanarak -- adım adım anlatıyorum.

Subagent Nedir?

Subagent'lar belirli görev türlerini ele alan uzmanlaşmış yapay zekâ yardımcılarıdır. Yan bir görev -- arama sonuçları, log dosyaları veya bir daha referans vermeyeceğiniz dosya içerikleriyle -- ana konuşmanızı doldurabilecekse subagent kullanmalısınız: iş kendi bağlamında yapılır, ana konuşmaya yalnızca özet döner. Aynı türde işçiyi aynı talimatlarla tekrar tekrar başlattığınızı fark ederseniz, o zaman özel bir subagent tanımlamanın vakti gelmiştir.

Her subagent kendi bağlam penceresinde, özel bir sistem promptuyla, belirli bir araç erişimiyle ve bağımsız izinlerle çalışır. Claude bir görevin bir subagent'ın açıklamasıyla eşleştiğini fark ettiğinde işi o subagent'a devreder; subagent bağımsız çalışır ve sonuçları döndürür. Resmi dokümantasyona göre subagent'lar şu konularda size yardımcı olur:

• Bağlamı korumak: keşif ve uygulama işlerini ana konuşmanın dışında tutarak.
• Kısıtlar uygulamak: bir subagent'ın hangi araçları kullanabileceğini sınırlayarak.
• Yapılandırmayı yeniden kullanmak: kullanıcı düzeyinde subagent'larla projeler arasında.
• Davranışı uzmanlaştırmak: belirli alanlar için odaklı sistem promptlarıyla.
• Maliyeti kontrol etmek: görevleri Haiku gibi daha hızlı, daha ucuz modellere yönlendirerek.

Önemli bir not: subagent'lar tek bir oturum içinde çalışır. Birçok bağımsız oturumu paralel çalıştırıp tek bir yerden izlemek istiyorsanız arka plan ajanları (background agents) konusuna, birbirleriyle iletişim kuran oturumlar için ise agent teams konusuna bakmanız gerekir -- bu ikisi bu yazının kapsamı dışında.

Hazır Gelen (Built-in) Subagent'lar

Claude Code, uygun olduğunda Claude'un otomatik olarak kullandığı hazır subagent'larla birlikte gelir. Her biri ana konuşmanın izinlerini, ek araç kısıtlamalarıyla birlikte devralır. Explore ve Plan araştırmayı hızlı ve ucuz tutmak için CLAUDE.md dosyalarınızı ve ana oturumun git durumunu atlar; diğer tüm hazır ve özel subagent'lar ikisini de yükler.

Ajan	Model	Araçlar	Amaç
Explore	Ana konuşmadan miras alır (Claude API'de Opus ile sınırlı)	Salt okunur; Write ve Edit reddedilir	Dosya keşfi, kod arama, kod tabanı incelemesi
Plan	Ana konuşmadan miras alır	Salt okunur; Write ve Edit reddedilir	Plan modunda kod tabanı araştırması
general-purpose	Ana konuşmadan miras alır	Subagent'lara açık tüm araçlar	Karmaşık, çok adımlı araştırma ve değişiklik gerektiren görevler
statusline-setup	Sonnet	Sınırlı	/statusline çalıştırıldığında durum çubuğunu yapılandırma
claude-code-guide	Haiku	Sınırlı	Claude Code özellikleri hakkında sorulara yanıt verme

Claude, kod tabanında değişiklik yapmadan arama veya anlama ihtiyacı duyduğunda Explore'a devreder; bu, keşif sonuçlarını ana konuşma bağlamınızın dışında tutar. Explore'u çağırırken Claude bir derinlik seviyesi belirtir: hedefli aramalar için quick, dengeli keşif için medium, kapsamlı analiz için very thorough. Aynı isimde kullanıcı veya proje subagent'ı tanımlarsanız (örneğin model: haiku ile kendi Explore'unuzu), bu hazır ajanın yerini alır.

Hazır subagent'ları kısıtlamak isterseniz üç yol vardır: belirli bir türü permissions.deny listesine Agent(Explore) gibi eklemek, Agent aracının tamamını reddederek Claude'un hiçbir subagent'a devretmesini engellemek, veya CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 ortam değişkeniyle yalnızca Explore ve Plan'ı kaldırmak (Claude bu durumda dosyaları doğrudan okur).

Hızlı Başlangıç: İlk Subagent'ınızı Oluşturun

Subagent'lar, YAML frontmatter'lı Markdown dosyalarıdır. Bir tane oluşturmak için ya Claude'dan yazmasını istersiniz ya da dosyayı kendiniz yazarsınız. Kullanıcı düzeyinde, kod inceleyip iyileştirme öneren bir subagent oluşturalım:

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

Claude, name, description, tools listesi, model ve bir sistem promptu içeren dosyayı yazar. ~/.claude/agents/code-improver.md dosyasını açtığınızda şuna benzer bir içerik görürsünüz:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Dosya ~/.claude/agents/ içinde olduğu için subagent makinenizdeki her projede kullanılabilir. Yalnızca bir projeye özgü kılmak isterseniz aynı dosyayı o projenin .claude/agents/ dizinine taşırsınız. Ardından yeni subagent'ı deneyin:

Use the code-improver agent to suggest improvements in this project

Claude yeni subagent'a devreder, o da kod tabanını tarayıp iyileştirme önerileriyle döner. Claude yeni subagent'ı bulamıyorsa Claude Code'u yeniden başlatıp tekrar deneyin -- bu yalnızca ~/.claude/agents/ dizini oturum başlamadan önce yoksa olur, çünkü çalışan bir oturum sonradan oluşturulan bir agents dizinini algılamaz.

Önemli bir güncel not: resmi dokümantasyona göre /agents komutu artık etkileşimli bir oluşturma sihirbazı açmıyor; çalıştırıldığında yalnızca Claude'dan istemenizi veya .claude/agents/ dizinini doğrudan düzenlemenizi hatırlatan bir mesaj basıyor. Subagent dosyaları, frontmatter alanları ve dizin konumları değişmedi; yalnızca terminal sihirbazı kaldırıldı.

Subagent Kapsamları (Scope)

Subagent dosyalarını farklı konumlarda saklayarak kimin erişebileceğini belirlersiniz. Aynı isimde birden fazla subagent tanımlıysa Claude Code, önceliği en yüksek konumdakini kullanır:

Konum	Kapsam	Öncelik	Nasıl oluşturulur
Managed settings	Organizasyon geneli	1 (en yüksek)	Yönetilen ayarlar üzerinden dağıtılır
--agents CLI bayrağı	Mevcut oturum	2	Claude Code başlatılırken JSON geçirilir
.claude/agents/	Mevcut proje	3	Claude'a sorarak veya elle dosya oluşturarak
~/.claude/agents/	Tüm projeleriniz	4	Claude'a sorarak veya elle dosya oluşturarak
Plugin'in agents/ dizini	Plugin'in etkin olduğu yerler	5 (en düşük)	Plugin ile birlikte kurulur

Proje subagent'ları (.claude/agents/) belirli bir kod tabanına özgü olduğunda idealdir; versiyon kontrolüne eklendiğinde ekibiniz birlikte kullanıp geliştirebilir. Çalışma dizininizden depo köküne kadar yol üzerindeki her .claude/agents/ dizini taranır; aynı ismi tanımlayan birden fazla iç içe dizin varsa çalışma dizinine en yakın olan tanım kullanılır.

Kullanıcı subagent'ları (~/.claude/agents/) tüm projelerinizde kullanılabilen kişisel ajanlardır. Her iki dizin de özyinelemeli (recursive) olarak taranır, yani tanımları agents/review/ gibi alt klasörlere organize edebilirsiniz -- alt klasör yolu subagent'ın kimliğini etkilemez, kimlik yalnızca name frontmatter alanından gelir.

CLI ile tanımlanan subagent'lar yalnızca o oturum için geçerlidir ve diske kaydedilmez; hızlı test veya otomasyon betikleri için kullanışlıdır. Tek bir --agents çağrısında birden fazla subagent tanımlanabilir:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

Frontmatter Alanları: Tam Referans

Bir subagent dosyasının frontmatter'ı yalnızca name ve description zorunlu olmak üzere, aşağıdaki alanları destekler:

Alan	Zorunlu	Açıklama
name	Evet	Küçük harf ve tirelerden oluşan benzersiz tanımlayıcı. Dosya adının bununla eşleşmesi gerekmez.
description	Evet	Claude'un bu subagent'a ne zaman devredeceğini belirler.
tools	Hayır	Subagent'ın kullanabileceği araçlar. Belirtilmezse subagent'lara açık tüm araçları miras alır.
disallowedTools	Hayır	Miras alınan veya belirtilen listeden çıkarılacak araçlar.
model	Hayır	sonnet, opus, haiku, fable, tam bir model ID'si (örn. claude-opus-4-8) veya inherit. Varsayılan inherit.
permissionMode	Hayır	default, acceptEdits, auto, dontAsk, bypassPermissions veya plan.
maxTurns	Hayır	Subagent durmadan önceki maksimum ajan turu sayısı.
skills	Hayır	Başlangıçta subagent'ın bağlamına önceden yüklenecek skill'ler; tam içerik enjekte edilir.
mcpServers	Hayır	Bu subagent'a özel MCP sunucuları -- var olan bir sunucuya referans veya satır içi tanım.
hooks	Hayır	Yalnızca bu subagent aktifken çalışan yaşam döngüsü hook'ları.
memory	Hayır	Kalıcı hafıza kapsamı: user, project veya local.
background	Hayır	true ise bu subagent her zaman arka planda çalışır. Belirtilmezse Claude karar verir (varsayılan: arka plan).
effort	Hayır	Bu subagent aktifken çaba (reasoning effort) seviyesi: low, medium, high, xhigh, max.
isolation	Hayır	worktree ise subagent, deponun izole bir git worktree kopyasında çalışır; değişiklik yapılmazsa worktree otomatik temizlenir.
color	Hayır	Görev listesindeki görüntüleme rengi: red, blue, green, yellow, purple, orange, pink, cyan.

Frontmatter'dan sonraki metin subagent'ın sistem promptu olur. Subagent'lar Claude Code'un tam sistem promptunu değil, yalnızca bu sistem promptunu ve çalışma dizini gibi temel ortam bilgilerini alır.

Model Seçimi

model alanı hangi modelin kullanılacağını belirler: bir model takma adı (sonnet, opus, haiku, fable), tam bir model ID'si, inherit (ana konuşmayla aynı model) veya boş bırakılırsa yine inherit. Claude Code, model çözümlemesini şu sırayla yapar:

1. CLAUDE_CODE_SUBAGENT_MODEL ortam değişkeni, bir model takma adına veya ID'sine ayarlıysa.
2. Çağrı anında Claude'un geçtiği model parametresi.
3. Subagent tanımındaki model frontmatter alanı.
4. Ana konuşmanın modeli.

Subagent'lar ayrıca ana konuşmanın genişletilmiş düşünme (extended thinking) yapılandırmasını da miras alır: ana oturumda düşünme açıksa subagent'ta da açıktır, kapalıysa kapalı kalır. Subagent başına ayrı bir düşünme ayarı yoktur.

Araç Erişimini Kontrol Etme

Subagent'lar, ana konuşmada kullanılabilen yerleşik araçları ve MCP araçlarını miras alır; ancak Agent, AskUserQuestion, EnterPlanMode, ExitPlanMode (permissionMode plan değilse) gibi birkaç araç varsayılan olarak her subagent'tan çıkarılır. Araç erişimini kısıtlamak için tools alanını izin listesi, disallowedTools alanını ise reddetme listesi olarak kullanırsınız:

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

Bu örnekte subagent yalnızca Read, Grep, Glob ve Bash kullanabilir; dosya düzenleyemez, yazamaz ve hiçbir MCP aracı kullanamaz. Tam tersine, belirli araçları hariç tutmak için disallowedTools kullanılabilir:

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

Her iki alan da tam araç adlarına ek olarak MCP sunucu düzeyinde kalıpları destekler: mcp__sunucu veya mcp__sunucu__* o sunucunun tüm araçlarını verir veya kaldırır. Her iki alan da ayarlıysa önce disallowedTools uygulanır, sonra tools kalan havuza göre çözümlenir.

Ana thread claude --agent ile bir ajan olarak çalıştığında, hangi subagent türlerini başlatabileceğini Agent(agent_type) söz dizimiyle sınırlayabilirsiniz:

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

Bu bir izin listesidir: yalnızca worker ve researcher subagent'ları başlatılabilir. Kısıtlama olmadan herhangi bir subagent'ı başlatmasına izin vermek için parantezsiz Agent kullanılır; tools listesinden Agent'ı tamamen çıkarırsanız o ajan hiçbir subagent başlatamaz.

Subagent'a Özel MCP Sunucuları

mcpServers alanı, ana konuşmada bulunmayan MCP sunucularına yalnızca belirli bir subagent'ın erişmesini sağlar. Satır içi tanımlanan sunucular subagent başladığında bağlanır, subagent bittiğinde bağlantısı kesilir:

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

Bir MCP sunucusunu tamamen ana konuşmanın dışında tutmak ve araç tanımlarının orada bağlam tüketmesini önlemek istiyorsanız, sunucuyu .mcp.json yerine burada satır içi tanımlayın: subagent araçları alır, ana konuşma almaz. MCP sunucularını Claude Code'a nasıl ekleyeceğinizi (transport türleri, kapsamlar, kimlik doğrulama) MCP rehberimde ayrıntılı işledim.

İzin Modları (Permission Modes)

permissionMode alanı, subagent'ın izin isteklerini nasıl ele alacağını belirler. Subagent, ana konuşmadan izin bağlamını miras alır ve aşağıdaki durumlar dışında bu modu geçersiz kılabilir:

Mod	Davranış
default	İstemlerle standart izin kontrolü
acceptEdits	Çalışma dizinindeki dosya düzenlemelerini ve yaygın dosya sistemi komutlarını otomatik kabul eder
auto	Arka plandaki bir sınıflandırıcı komutları ve korumalı dizin yazımlarını inceler
dontAsk	İzin istemlerini otomatik reddeder; açıkça izin verilmiş araçlar yine çalışır
bypassPermissions	İzin istemlerini tamamen atlar -- dikkatli kullanılmalı
plan	Plan modu (salt okunur keşif)

Ana konuşma bypassPermissions veya acceptEdits kullanıyorsa bu öncelik kazanır ve geçersiz kılınamaz. Ana konuşma auto modundaysa subagent da auto modunu miras alır ve frontmatter'daki permissionMode göz ardı edilir.

Kalıcı Hafıza (memory alanı)

memory alanı, subagent'a konuşmalar arasında hayatta kalan kalıcı bir dizin verir; subagent bunu kod tabanı kalıpları, hata ayıklama bulguları veya mimari kararlar gibi zaman içinde biriken bilgiler için kullanır:

Kapsam	Konum	Ne zaman kullanılır
user	~/.claude/agent-memory/<ajan-adi>/	Öğrenimlerin tüm projelerde hatırlanması gerektiğinde
project	.claude/agent-memory/<ajan-adi>/	Bilgi projeye özgü ve versiyon kontrolüyle paylaşılabilir olmalı
local	.claude/agent-memory-local/<ajan-adi>/	Bilgi projeye özgü ama versiyon kontrolüne girmemeli

Hafıza etkinleştirildiğinde subagent'ın sistem promptu hafıza dizinini okuma/yazma talimatlarını ve MEMORY.md dosyasının ilk 200 satırını veya 25KB'sini (hangisi önce gelirse) içerir; Read, Write ve Edit araçları hafıza dosyalarını yönetebilmesi için otomatik etkinleştirilir. Önerilen varsayılan kapsam project'tir çünkü subagent bilgisini versiyon kontrolüyle paylaşılabilir kılar.

Subagent Yaşam Döngüsünde Hook'lar

Subagent'lar, yaşam döngüleri sırasında çalışan hook'lar tanımlayabilir. İki yapılandırma yolu vardır: subagent'ın frontmatter'ında (yalnızca o subagent aktifken çalışır) veya settings.json içinde (subagent başladığında/bittiğinde ana oturumda çalışır).

Bu örnek, yalnızca salt okunur SQL sorgularına izin veren bir subagent oluşturur; PreToolUse hook'u her Bash komutundan önce doğrulama betiğini çalıştırır:

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

Doğrulama betiği stdin üzerinden gelen JSON'dan Bash komutunu çıkarır ve yazma işlemlerini (INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE) tespit ederse çıkış kodu 2 ile engeller:

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

Proje düzeyinde, settings.json içinde SubagentStart ve SubagentStop olaylarına bağlanarak ana oturumda tetiklenen hook'lar da tanımlayabilirsiniz. Eşleştirici (matcher) değeri subagent'ın name frontmatter alanıdır:

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

Subagent olarak çağrıldığında frontmatter'daki Stop hook'ları otomatik olarak SubagentStop olayına dönüştürülür. Hook olayları ve girdi şeması hakkında ayrıntılı bilgi için hooks rehberime bakabilirsiniz.

Subagent'ları Çağırma

Claude, isteğinizdeki görev tanımına, subagent yapılandırmalarındaki description alanına ve mevcut bağlama göre otomatik olarak devreder. Proaktif devretmeyi teşvik etmek için subagent'ın açıklamasına "use proactively" gibi ifadeler ekleyebilirsiniz. Otomatik devretme yetmiyorsa, üç yöntemle bunu kendiniz tetikleyebilirsiniz:

• Doğal dil: promptunuzda subagent'ı adıyla anın; Claude devredip devretmeyeceğine karar verir. Örnek: Use the test-runner subagent to fix failing tests
• @ ile bahsetme: @ yazıp dosyalarda olduğu gibi listeden subagent'ı seçmek, o subagent'ın kesinlikle çalışmasını garanti eder.
• Oturum geneli: --agent bayrağı veya agent ayarıyla, tüm oturumun sistem promptu, araç kısıtlamaları ve modeli o subagent'ınki olur.

Oturumun tamamını bir subagent olarak başlatmak için:

claude --agent code-reviewer

Bu, subagent'ın sistem promptunun Claude Code'un varsayılan sistem promptunun tamamen yerini almasını sağlar; CLAUDE.md dosyaları ve proje hafızası normal mesaj akışıyla yine yüklenir. Bunu bir projedeki her oturum için varsayılan yapmak isterseniz .claude/settings.json içine ekleyin:

{
  "agent": "code-reviewer"
}

Ön Planda mı, Arka Planda mı?

Subagent'lar ön planda veya arka planda çalışabilir. Ön plan subagent'ları tamamlanana kadar ana konuşmayı bloklar ve izin istemleri doğrudan size iletilir. Arka plan subagent'ları ise siz çalışmaya devam ederken eşzamanlı çalışır; bir izin gerektiren araç çağrısına ulaştığında istem ana oturumunuzda, hangi subagent'ın sorduğu belirtilerek belirir -- onaylayarak devam etmesine izin verebilir veya Esc ile yalnızca o çağrıyı reddedebilirsiniz.

Resmi dokümantasyona göre subagent'lar varsayılan olarak arka planda çalışır; Claude, sonuca hemen ihtiyaç duyduğu durumlarda bir subagent'ı ön planda çalıştırır. Arka plan subagent'ları, ön plan subagent'larına göre daha küçük bir yerleşik araç kümesiyle çalışır ve her izin istemini ana oturumunuza yansıtır. Kendiniz de yönlendirebilirsiniz: Claude'dan bir görevi ön planda veya arka planda çalıştırmasını isteyebilir, ya da çalışan bir görevi arka plana almak için Ctrl+B tuşlayabilirsiniz.

İç İçe Subagent'lar (Nested Spawning)

Varsayılan olarak bir subagent kendi subagent'ını oluşturamaz: Claude Code, Agent aracını her subagent'tan çıkarır, bu yüzden delege edilen iş kendi kendine tamamlanır ve tek bir özetle döner. İç içe geçmeye izin vermek için, altında istediğiniz katman sayısını belirten CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH ortam değişkenini settings.json içinde ayarlamanız gerekir:

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

Bu değerle subagent'larınız kendi ikinci bir katmana devredebilir, o ikinci katman ise daha fazla devredemez. İç içe subagent'lar, kendisi paralel alt görevlere bölünen delege edilmiş bir görev için uygundur -- örneğin her bulgu için bir doğrulayıcı gönderen bir inceleme subagent'ı -- böylece ara çıktı hiçbir zaman ana konuşmanıza ulaşmaz, yalnızca en üst düzey subagent'ın özeti size döner.

Pratik Örnek: code-reviewer + debugger Zincirleme İş Akışı

Subagent'ların gerçek gücü, birden fazlasını art arda veya paralel kullanmakta ortaya çıkar. Resmi dokümantasyondaki iki örnek subagent'ı ele alalım. Önce salt okunur bir kod inceleyici:

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Sonra, tanı koyup düzeltme de yapabilen bir hata ayıklayıcı (bu ajan Edit aracına da sahip, çünkü hata düzeltmek kod değişikliği gerektirir):

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Bu iki subagent'ı zincirlemek için Claude'a şunu söylemeniz yeterli:

Use the code-reviewer subagent to find performance issues, then use the
debugger subagent to fix them

Claude önce code-reviewer'a devreder, o performans sorunlarını bulup özetler; Claude bu özeti debugger'a aktarır, o da düzeltmeleri uygular ve doğrular. Her iki subagent'ın ayrıntılı çıktısı (git diff'ler, log'lar, ara denemeler) kendi bağlam pencerelerinde kalır -- ana konuşmanıza yalnızca iki özet ulaşır. Bağımsız araştırmalar için subagent'ları paralel de çalıştırabilirsiniz, örneğin: Research the authentication, database, and API modules in parallel using separate subagents -- her biri kendi alanını bağımsız keşfeder, sonra Claude bulguları sentezler. Dikkat: her subagent tamamlandığında sonucu ana konuşmanıza döner, bu yüzden çok sayıda subagent'ı ayrıntılı sonuçlarla çalıştırmak bağlamınızı yine de doldurabilir.

Ana Konuşma mı, Subagent mı?

Resmi dokümantasyon net bir ayrım öneriyor. Ana konuşmayı şu durumlarda kullanın:

• Görev sık geri bildirim veya yinelemeli iyileştirme gerektiriyorsa.
• Planlama, uygulama ve test gibi birden fazla aşama önemli ölçüde bağlam paylaşıyorsa.
• Hızlı, hedefli bir değişiklik yapıyorsanız.
• Gecikme (latency) önemliyse -- subagent'lar sıfırdan başlar ve bağlam toplamak zaman alabilir.

Subagent'ları şu durumlarda kullanın:

• Görev, ana bağlamınızda ihtiyacınız olmayan ayrıntılı çıktı üretiyorsa.
• Belirli araç kısıtlamaları veya izinler uygulamak istiyorsanız.
• İş kendi içinde tamamlanabilir ve bir özetle dönebilir nitelikteyse.

Yeniden kullanılabilir promptlar veya ana konuşma bağlamında (izole subagent bağlamı yerine) çalışan iş akışları istiyorsanız, bunun yerine Skills düşünülmelidir.

En İyi Pratikler

• Odaklı subagent'lar tasarlayın: her subagent tek bir spesifik görevde uzmanlaşmalı.
• Ayrıntılı açıklamalar yazın: Claude, ne zaman devredeceğine description alanına bakarak karar verir.
• Araç erişimini sınırlayın: hem güvenlik hem odaklanma için yalnızca gerekli izinleri verin.
• Versiyon kontrolüne ekleyin: proje subagent'larını ekibinizle paylaşın.
• Salt okunur olabilecek subagent'lardan Write/Edit'i çıkarın -- örneğin bir kod inceleyicinin dosya değiştirmesine gerek yoktur.

Sık Karşılaşılan Sorunlar

Belirti	Olası neden ve çözüm
Yeni oluşturulan subagent Claude tarafından bulunamıyor	Oturum başladıktan sonra agents dizini ilk kez oluşturulduysa, çalışan oturum bunu algılamaz. Claude Code'u yeniden başlatın.
Subagent hiç araç kullanamıyor gibi görünüyor	tools listesindeki hiçbir giriş gerçek bir araca çözümlenmiyorsa (yanlış yazım gibi) subagent genellikle hangi girdilerin tanınmadığını belirten bir hatayla başlamayı reddeder. Alan adlarını kontrol edin.
Subagent kendi subagent'ını başlatamıyor	Bu varsayılan davranıştır. İç içe geçmeye izin vermek için CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH ortam değişkenini ayarlayın.
Aynı isimde iki subagent tanımlı, hangisi çalışacağı belirsiz	Kapsam önceliği geçerlidir: managed settings > --agents > proje > kullanıcı > plugin. Aynı dizindeki (alt klasörler dahil) yinelenen isimler için dosya adlarından birini değiştirin.
Subagent beklenenden farklı bir modelde çalışıyor	Çözümleme sırası CLAUDE_CODE_SUBAGENT_MODEL ortam değişkeni > çağrı anındaki model parametresi > frontmatter'daki model > ana konuşmanın modelidir. Her seviyeyi kontrol edin.

Sıkça Sorulan Sorular

Subagent nedir, normal Claude Code konuşmasından farkı ne?

Subagent (alt ajan), Claude Code'un belirli bir görevi kendi bağlam penceresinde, kendi sistem promptu ve kendi araç erişimiyle yürüten özel bir yapay zekâ yardımcısıdır. Normal konuşmada her adım ana bağlama eklenirken, bir subagent'a devredilen iş kendi izole penceresinde kalır; ana konuşmaya yalnızca özet sonuç döner. Bu sayede log dosyası, arama sonucu ya da test çıktısı gibi hacimli veriler ana bağlamı doldurmaz.

Kendi subagent'ımı nasıl oluştururum?

En kolay yol, Claude'dan oluşturmasını istemektir: örneğin "~/.claude/agents/ içinde salt okunur bir code-reviewer subagent'ı oluştur" demek yeterlidir. Elle oluşturmak isterseniz .claude/agents/ (proje) veya ~/.claude/agents/ (kullanıcı) dizininde name ve description alanlarını içeren YAML frontmatter'lı bir .md dosyası yazarsınız; frontmatter'dan sonraki metin subagent'ın sistem promptu olur.

Explore, Plan ve general-purpose hazır subagent'ları ne işe yarar?

Bunlar Claude Code'a önceden yüklü gelen hazır subagent'lardır. Explore, kod tabanında arama ve keşif yapan salt okunur, hızlı bir ajandır (Write/Edit erişimi yok). Plan, plan modunda kod tabanını araştırıp Claude'a bağlam toplayan salt okunur bir ajandır. general-purpose ise hem keşif hem değişiklik gerektiren, çok adımlı karmaşık görevler için kullanılan, subagent'lara açık tüm araçlara sahip tam yetkili bir ajandır.

Bir subagent'ın erişebileceği araçları nasıl sınırlarım?

Frontmatter'da tools alanını izin listesi olarak kullanabilirsiniz, örneğin tools: Read, Grep, Glob yalnızca bu üç aracı verir. Alternatif olarak disallowedTools alanıyla, subagent'ın normalde miras aldığı araç havuzundan belirli araçları (örneğin Write, Edit) çıkarabilirsiniz. Her iki alan da mcp__sunucu veya mcp__sunucu__* gibi MCP sunucu düzeyinde kalıpları destekler.

Subagent'lar arka planda mı yoksa ön planda mı çalışır?

Resmi dokümantasyona göre subagent'lar varsayılan olarak arka planda çalışır: siz ana konuşmada çalışmaya devam ederken subagent kendi işini yürütür ve bir izin isteği çıktığında bu istek ana oturumunuza, hangi subagent'ın sorduğu belirtilerek yansır. Claude, sonucu hemen ihtiyaç duyduğu durumlarda bir subagent'ı ön planda (bloklayarak) çalıştırmayı seçebilir. Ctrl+B ile çalışan bir görevi arka plana da alabilirsiniz.

Subagent'lar kendi subagent'larını oluşturabilir mi?

Varsayılan olarak hayır: bir subagent'a Agent aracı verilmez, bu yüzden kendi başına başka bir subagent başlatamaz ve delege edilen işi kendisi tamamlayıp tek bir özetle döner. İç içe (nested) subagent'lara izin vermek için settings.json içinde CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH ortam değişkenini istediğiniz katman sayısına ayarlamanız gerekir.

Özet

Subagent'lar, Claude Code'u tek bir devasa bağlam penceresi içinde her şeyi yapmaya çalışan bir asistandan, işi doğru uzmanlara devreden bir orkestra şefine dönüştürür. Explore, Plan ve general-purpose gibi hazır ajanlar günlük keşif ve çok adımlı işler için hazır gelirken, .claude/agents/ veya ~/.claude/agents/ içine yazacağınız birkaç satırlık bir YAML frontmatter'lı Markdown dosyasıyla kendi uzman ajanlarınızı tanımlayabilirsiniz. tools/disallowedTools ile neyi yapabileceğini, model ile hangi modeli kullanacağını, permissionMode ile izin davranışını, hooks ile yaşam döngüsü kancalarını, memory ile kalıcı bilgiyi kontrol edersiniz. Görev büyükse subagent'ları zincirleyin veya paralel çalıştırın; her biri kendi bağlamında çalışıp ana konuşmanıza yalnızca özetiyle dönsün.

Subagent'ları Claude Code'un diğer otomasyon katmanlarıyla -- örneğin hooks ile olay tabanlı otomasyonla ya da MCP ile dış sistem entegrasyonuyla -- birleştirdiğinizde, terminalinizdeki tek bir asistan yerine görev bazında uzmanlaşmış, bağlamını koruyan bir ajan filosu elde edersiniz. Henüz Claude Code'u kurmadıysanız kurulum rehberimden başlayabilirsiniz.