Claude · Gelişmiş · 202 Genişlet · Konu 2 / 5
4.2 Subagents
Ağır işi ayrı bağlamda yaptır, yalnızca özeti al.
Bu sayfada ne öğreneceksin
- Subagent'ın ne olduğunu ve ana konuşmanı neden temiz tuttuğunu
- Kendi subagent'ını bir dosyayla nasıl tanımlayacağını ve hangi alanların olduğunu
- Ne zaman subagent kullanacağını, ne zaman ana konuşmada kalacağını
Kısaca
Claude Code'la çalışırken her dosya okuma, her arama sonucu, her araç çağrısı ana konuşmanın bağlam penceresine girer. O pencere sınırlıdır. Bir şeyi öğrenmek için Claude'a birçok dosya okutursan, yalnızca bir bilgiye ihtiyacın olduğu halde hepsi pencerede kalır.
Subagent bunun çaresidir. Dokümana göre subagent, belirli türde işleri yapan özelleşmiş bir yapay zekâ yardımcısıdır. Kendi bağlam penceresinde, kendi sistem istemi (system prompt), araç erişimi ve izinleriyle çalışır. İş bitince ana konuşmana yalnızca özet döner. Aradaki dosya okumaları ayrı bir döküm dosyasında kalır; kursun ifadesiyle ana konuşman "yolculuğun gürültüsünü" görmez, cevabı alır. Bedeli: ana konuşman, subagent'ın sonuca nasıl vardığını görmez.
Subagent ayrı istek gönderir; dokümana göre bu istekler ana konuşmayla aynı kullanım sınırlarına sayılır. Yani bedava değildir. Güncel kullanım koşulları için costs sayfasına bak.
Yerleşik subagent'lar
Claude Code hazır birkaç subagent ile gelir ve uygun gördüğünde kendisi kullanır:
| Ad | Ne için |
|---|---|
| Explore | Kod tabanında hızlı arama ve inceleme; salt okunur, Write ve Edit araçları yasak |
| Plan | Plan modunda, plan sunulmadan önce araştırma; salt okunur |
| General-purpose | Hem keşif hem eylem gerektiren çok adımlı işler |
Dokümana göre Explore ve Plan, hızlı kalmak için senin CLAUDE.md dosyalarını ve git durum özetini almadan başlar. Diğer yerleşik ve özel subagent'lar ikisini de yükler.
Adım adım
- Önce ihtiyacı belirle. Tekrar tekrar aynı türde bir işçiye mi ihtiyacın var (salt okunur kod gözden geçirici, araştırmacı)? Doküman bunu şöyle koyuyor: aynı talimatla aynı türde işçiyi sürekli çağırıyorsan özel subagent tanımla.
- Kapsamı seç.
.claude/agents/içindeki dosya yalnızca o projede çalışır (commit edersen ekip de kullanır).~/.claude/agents/içindeki dosya makinendeki tüm projelerde çalışır. - Claude'a yazdır. Kurs en kolay yolun, Claude'dan dosyayı yazmasını istemek olduğunu söylüyor. Ne istediğini ve nereye kaydedeceğini anlat. "Hazır prompt" bölümünde örnek var. Claude ad, açıklama, araç listesi, model ve sistem istemini yazar.
- Dosyayı aç ve kontrol et. Frontmatter'ı (ilk
---bloğu) istediğinle karşılaştır, özellikletoolsalanını. Dosyayı kendin de elle yazabilirsin; örnek aşağıda. - Yüklendi mi bak. Doküman, Claude Code'un
~/.claude/agents/ve.claude/agents/klasörlerini izlediğini söylüyor; dosya ekleyince ya da düzenleyince birkaç saniyede algılar. Tek istisna: oturum başladığında oagentsklasörü hiç yoksa, ilk dosyayı oluşturduktan sonra Claude Code'u yeniden başlat. - Çağır. Doğal dille adını söyle ya da
@yazıp listeden seç:@ile seçersen o subagent'ın çalışması garantidir, Claude'a bırakılmaz. Ayrıca tüm oturumu bir subagent olarak başlatmak içinclaude --agent <ad>var. - Sonucu değerlendir. Subagent özet döndürür. Beklediğin ayrıntı eksikse bir sonraki bölümdeki çıktı biçimi önerisini sistem istemine ekle.
Dosya ve alanlar
Subagent bir Markdown dosyasıdır: üstte YAML alanları, altta sistem istemi. Dokümana göre yalnızca name ve description zorunludur. Çok kelimeli alan adları camelCase yazılır (maxTurns, disallowedTools) ve tabloyla birebir aynı olmalı; Claude Code tanımadığı alanı hata vermeden yok sayar.
| Alan | Ne işe yarar |
|---|---|
name | Benzersiz ad; zorunlu |
description | Claude'un bu subagent'a ne zaman iş vereceği; zorunlu |
tools | Kullanabileceği araçlar; yazılmazsa subagent'ların kullanabildiği tüm araçları miras alır |
disallowedTools | Yasaklanan araçlar |
model | sonnet, opus, haiku, fable, tam bir model kimliği ya da inherit |
permissionMode | İzin modu |
skills | Başlangıçta bağlama yüklenecek skill'ler; içeriğin tamamı yüklenir |
mcpServers | Bu subagent'a açık MCP sunucuları |
hooks | Yalnızca bu subagent için hook'lar |
memory | Oturumlar arası kalıcı bellek kapsamı: user, project ya da local |
isolation | worktree yazılırsa subagent depoyu geçici bir kopyada kullanır |
color | Görev listesinde ve dökümde görünen renk |
Daha fazla alan var (maxTurns, background, effort ve diğerleri); tam liste dokümanın sub-agents sayfasındaki "Frontmatter reference" bölümünde. Dosyanın gövdesi subagent'ın sistem istemidir: subagent yalnızca bu istemi ve çalışma klasörü gibi temel ortam bilgisini alır, Claude Code'un kendi sistem istemini almaz.
Subagent başladığında ne görür? Taze, yalıtılmış bir bağlam penceresiyle başlar: senin konuşma geçmişini, daha önce çağırdığın skill'leri, Claude'un okuduğu dosyaları görmez. Claude görevi özetleyen bir devir mesajı yazar ve subagent buradan çalışır. Bir kuralın subagent'a ulaşmasını istiyorsan (örneğin "vendor/ klasörünü yok say") Claude'a devir verirken o kuralı da söylemeni doküman öneriyor.
Not: Eski Claude Code sürümlerinde /agents komutu bir sihirbaz açıyordu. Dokümana göre güncel sürümde /agents yalnızca Claude'dan yazmasını istemeni ya da klasörleri elle düzenlemeni hatırlatan bir not yazdırır. Eski videolarda sihirbazı görürsen dosya ve alanlar aynı kalır.
İyi bir subagent nasıl tasarlanır
- Net description yaz. Ana ajan, tüm subagent'ların ad ve açıklamasını görür ve hangisini çağıracağına buna bakarak karar verir. Kursa göre description ikinci bir iş daha yapar: ana ajan subagent'a görevi yazarken description'ı kılavuz alır. Örneğin "hangi dosyaları incelemesini istediğini tam olarak söylemelisin" yazarsan ana ajan devir mesajına dosya listesini koyar. Otomatik devrin sık olmasını istiyorsan kurs ve doküman description'a "proactively" ya da "use proactively" gibi bir ifade koymanı söylüyor.
- Çıktı biçimi tanımla. Kurs bunu en önemli iyileştirme sayıyor: biçim, subagent'a ne zaman bittiğini söyleyen doğal durma noktaları verir. Biçim yoksa subagent ne zaman yeter diyeceğini bilemez ve gereğinden uzun çalışır.
- Engelleri raporlat. Çıktı biçimine "karşılaşılan engeller" bölümü ekle (kurulum sorunu, özel bayrak isteyen komut, soruna yol açan bağımlılık). Aksi hâlde ana konuşma aynı çözümü baştan bulmak zorunda kalır.
- Araç erişimini sınırla. Kursun önerisi: araştırmacı yalnızca
Glob,Grep,Read; kod gözden geçirici ayrıcagit diffiçinBash;EditveWriteyalnızca kodu değiştirmesi gereken subagent'a. Bu hem istenmeyen yan etkiyi önler hem rolü netleştirir.
Ne zaman subagent, ne zaman ana konuşma
Kursun karar sorusu: ara işlem önemli mi? Yalnızca sonuç lazımsa (aramanın yolu değil) devret. Ara adımları görüp tepki vermen gerekiyorsa ana konuşmada kal.
| Subagent kullan | Ana konuşmada kal |
|---|---|
| Araştırma ve keşif; çıktı bağlamı doldurur ama yalnızca özet lazım | Sık gidip gelme ve tekrar tekrar düzeltme gereken iş |
| Kod incelemesi: taze gözle bakar, çünkü kodu yazarken bulunmamıştır | Planlama, uygulama, test gibi birçok aşamanın bağlamı paylaştığı iş |
| Özel sistem istemi gereken iş (örneğin ton ve hedef kitle tanımlı bir metin yazarı) | Hızlı, küçük, hedefli değişiklik |
| Araç ve izin kısıtı uygulamak istediğin, kendi içinde tamamlanan iş | Gecikmenin önemli olduğu iş; fork olmayan subagent sıfırdan başlar ve bağlamı toplamak zaman alabilir |
Kursun "zarar veren" üç kalıbı:
- Uzmanlık iddiası: "Sen bir Python uzmanısın" gibi istemler değer katmaz, çünkü Claude bu bilgiye zaten sahip.
- Sıralı boru hatları: Hatayı çoğalt, ayıkla, düzelt diye üç subagent sıralarsan, her adım öncekinin keşfine bağlı olduğundan bilgi devirlerde kaybolur.
- Test koşucuları: Testler kırılınca tam çıktıya ihtiyacın var. Yalnızca "testler başarısız" diyen bir özet, ayrıntı için ek betik yazdırır. Kurs, kendi denemelerinde test koşucu kalıbının tüm yapılandırmalar arasında en kötü sonucu verdiğini söylüyor.
Dokümanla küçük bir fark var: doküman, hacimli çıktı üreten işleri (test, belge çekme, günlük işleme) izole etmeyi etkili bir kullanım olarak gösteriyor ve örnek istem olarak "test setini çalıştır, yalnızca başarısız testleri hata mesajlarıyla raporla" diyor. Yani ikisi çelişmek zorunda değil: sana düşen, hata ayıklamak için tam çıktıya ihtiyaç duyup duymadığına bakmak. Duyuyorsan ana konuşmada çalıştır. Benzer bir fark sıralı boru hattında da var: doküman "önce code-reviewer ile performans sorunlarını bul, sonra optimizer ile düzelt" gibi subagent'ları art arda çağırmayı bir kalıp olarak gösteriyor, kurs ise her adım öncekinin keşfine bağlıysa bilginin kaybolacağını söylüyor. Adımlar birbirine bağımlıysa ana konuşmada kal.
Ayrıca dokümandaki uyarı: çok sayıda subagent ayrıntılı sonuç döndürürse yine ana bağlamı doldurabilir ve her biri kendi istek bütçesini harcar. Bağımsız araştırmaları paralel çalıştırabilirsin, ama yolları birbirine bağlıysa paralel çalıştırma. Ana konuşmadaki bir şey hakkında kısa soru soracaksan doküman subagent yerine /btw öneriyor.
Skill'lerle birlikte
Subagent'ın skills alanına skill adı yazarsan o skill'in tamamı subagent başlarken bağlamına yüklenir. Önceki sayfadaki tersi de var: skill'e context: fork yazarsan skill ayrı bir subagent'ta çalışır. Doküman ikisini şöyle ayırır: skills alanında subagent sistem istemini ve skill'i yönetir; context: fork ile skill içeriği, seçtiğin ajan türüne verilir. İki durumda da subagent senin konuşma geçmişini görmeden başlar.
Hazır komutlar
Subagent dosyasının yeri (kişisel kapsam için klasörü aç; bu bir terminal komutudur):
mkdir -p ~/.claude/agents
Bu içeriği ~/.claude/agents/okuyucu-denetci.md olarak kaydet. Kurgusal bir salt okunur denetçidir; kendi projene göre değiştir:
---
name: okuyucu-denetci
description: Yeni yazılmış ya da değiştirilmiş kodu okunabilirlik ve hata açısından inceler. Kod değiştikten hemen sonra, hangi dosyaları incelemesini istediğini tam olarak söyleyerek çağır.
tools: Read, Grep, Glob, Bash
model: inherit
---
Sen salt okunur bir kod denetçisisin. Dosyaları değiştirme.
Çalışırken:
1. Önce git diff ile değişiklikleri gör.
2. Yalnızca değişen dosyalara odaklan.
Cevabını şu biçimde ver:
Özet: Neyi inceledin, genel değerlendirmen.
Kritik: Hemen düzeltilmesi gereken hatalar.
Uyarı: Düzeltilmesi iyi olacak noktalar.
Öneri: İsteğe bağlı iyileştirmeler.
Karşılaşılan engeller: Kurulum sorunu, özel bayrak isteyen komut, soruna yol açan bağımlılık. Yoksa "yok" yaz.
Bir subagent'ı oturumdan çağırmak için @ yazıp listeden seç, ya da tüm oturumu o subagent olarak başlat (terminalde):
claude --agent okuyucu-denetci
Hazır prompt
Claude'a subagent'ı yazdırmak için:
~/.claude/agents/ içinde okuyucu-denetci adlı kişisel bir subagent oluştur. Yeni yazılmış kodu okunabilirlik ve hata açısından incelesin, dosyaları değiştirmesin (salt okunur olsun). Cevabını Özet, Kritik, Uyarı, Öneri ve Karşılaşılan engeller başlıklarıyla versin.
Subagent'ı denemek için:
okuyucu-denetci subagent'ını kullanarak son değişikliklerime bak. İncelemesi gereken dosyalar: [dosya adları].
Araştırmayı ana konuşmandan ayırmak için:
Bu projede [konu] nerede ele alınıyor? Bunu bir subagent ile araştır ve bana yalnızca ilgili dosyaları ve tek paragraflık bir özet getir.
Sık yapılan hata
- Çıktı biçimi vermemek. Subagent gereğinden uzun çalışır ve dönen özet işine yaramaz. Sistem istemine bölümlü bir biçim yaz.
- Subagent'ın konuşmanı gördüğünü sanmak. Görmez. Önceki kararlarını ya da çağırdığın skill'leri bilmez; gereken bilgiyi devir mesajına koyduğundan emin ol. Konuşmanın tamamını görmesini istiyorsan doküman fork'u (konuşmanın kopyasıyla başlayan subagent) öneriyor;
/subtaskile elle başlatabilirsin. - Gereğinden geniş araç vermek. Salt okunur olması gereken denetçiye
EditveWriteverme. - Yanlış yazılmış alan. Claude Code tanımadığı alanı hata vermeden yok sayar. Dokümana göre yazım yanlışını bulmak için
claude --debugile başlat ve hata ayıklama günlüğündedoes not recognize or applyifadesini ara. Dosyası hiç yüklenmeyen subagent için de aynı günlüğe bak;nameya dadescriptioneksik dosyalar atlanır. - Test çalıştırmak için subagent kullanıp çıktıyı kaybetmek. Hata ayıklayacaksan tam çıktıyı ana konuşmada gör.
- Subagent'a sır vermek. Proje subagent'ları commit edilip ekiple paylaşılır. Parola, anahtar yazma.
Video
Video: yakında.
Kaynak
- Anthropic Academy, Introduction to subagents: What are subagents?, Creating a subagent, Designing effective subagents, Using subagents effectively
- Anthropic Academy, Claude Code 101: Subagents
- Claude Code dokümanı: Create custom subagents (yerleşik subagent'lar, kapsam, frontmatter alanları, başlangıç bağlamı, çağırma, ne zaman kullanılır)
- Claude Code dokümanı: Extend Claude with skills (
context: fork)
Son doğrulama: 2026-10-21