Anla Dene

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

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:

AdNe için
ExploreKod tabanında hızlı arama ve inceleme; salt okunur, Write ve Edit araçları yasak
PlanPlan modunda, plan sunulmadan önce araştırma; salt okunur
General-purposeHem 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

  1. Ö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.
  2. 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.
  3. 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.
  4. Dosyayı aç ve kontrol et. Frontmatter'ı (ilk --- bloğu) istediğinle karşılaştır, özellikle tools alanını. Dosyayı kendin de elle yazabilirsin; örnek aşağıda.
  5. 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 o agents klasörü hiç yoksa, ilk dosyayı oluşturduktan sonra Claude Code'u yeniden başlat.
  6. Ç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çin claude --agent <ad> var.
  7. 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.

AlanNe işe yarar
nameBenzersiz ad; zorunlu
descriptionClaude'un bu subagent'a ne zaman iş vereceği; zorunlu
toolsKullanabileceği araçlar; yazılmazsa subagent'ların kullanabildiği tüm araçları miras alır
disallowedToolsYasaklanan araçlar
modelsonnet, opus, haiku, fable, tam bir model kimliği ya da inherit
permissionModeİzin modu
skillsBaşlangıçta bağlama yüklenecek skill'ler; içeriğin tamamı yüklenir
mcpServersBu subagent'a açık MCP sunucuları
hooksYalnızca bu subagent için hook'lar
memoryOturumlar arası kalıcı bellek kapsamı: user, project ya da local
isolationworktree yazılırsa subagent depoyu geçici bir kopyada kullanır
colorGö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

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 kullanAna konuşmada kal
Araştırma ve keşif; çıktı bağlamı doldurur ama yalnızca özet lazımSık gidip gelme ve tekrar tekrar düzeltme gereken iş
Kod incelemesi: taze gözle bakar, çünkü kodu yazarken bulunmamıştırPlanlama, 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ı:

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

Video

Video: yakında.

Kaynak

Son doğrulama: 2026-10-21

Anla Dene bağımsız bir eğitim sitesidir; Anthropic, OpenAI ya da Google ile bağlantılı değildir. Ürün adları sahiplerine aittir.

anladene.com · Anla Dene Akademi · Gizlilik