Ayrı bir dikkat penceresi olarak subagent

1. Subagent nedir ve ne işe yarar

Subagent, Claude Code'un görev devrettiği uzmanlaşmış bir asistandır: işi kendi bağlam penceresinde yapar ve oturumunuza kısa bir özet döndürür. Dosya okumaları, aramalar ve araç çağrıları onun bağlamında kalır.

Neden böyle: ana oturumda mesajlar, okunan dosyalar ve komut sonuçları aynı pencerede yer kaplar ve bu pencerenin hacmi sınırsız değildir. Pencere doldukça Claude Code geçmişi kısaltır ve bazı ayrıntılar kaybolabilir. Subagent, ara işleri ayrı bir pencereye taşımanızı, ana sohbette ise yalnızca sonucunu tutmanızı sağlar.

En basit subagent

İlk çalıştırma için Claude Code'da basit bir mesaj yeterlidir: Claude'dan açıkça bir subagent çağırmasını isteyin ve onun görevini tarif edin. Önceden kendi rol dosyanızı oluşturmanıza gerek yok, bu görev için yerleşik asistan yeterlidir. Örneğin:

index.html dosyasını okumak için subagent'ı çağır.
Dosyanın kısa bir haritasını oluştursun: ana bölümler
ve her birinin ne yaptığı. Ardından içeriğin kısa bir özetini
3-5 cümleyle yazsın.
Dosyayı değiştirme. Subagent'ın cevabını bu oturuma döndür.

Ana ajan görevi asistana iletir, iş bitince de onun yanıtını konuşmanızda gösterir. Arka planda çalıştırıldığında aşağıda, giriş alanının altında, subagent'ın adını ve çalışma durumunu gösteren bir çubuk belirir. Subagent'ın oturumunu açıp neyi okuduğunu ve ne yaptığını görmek için bu çubuğa tıklayın. Çalışma sırasında subagent için ayrı bir çalıştırmanın gerçekten başladığını kontrol edin: düz metinle yapılan istek Claude'un seçimini yönlendirir, ancak tek başına delegasyonu garanti etmez.

Subagent hangi bilgileri alır

Aynı görevi sabit kurallarla tekrarlamak gerekirse, kendi rolünüzü bir dosyada tanımlayabilirsiniz. Böyle bir özel subagent'ın başlangıçta iki ana girdisi vardır:

• yapılandırma dosyanızdaki rol talimatı - uzmanlık alanı ve davranış kuralları;
• ana ajanın talebinize göre hazırladığı görev açıklaması.

Claude Code bunlara kendiliğinden ortak bir arka plan da ekler: projenin CLAUDE.md dosyaları, git status anlık görüntüsü ve ortamla ilgili bilgiler. Ana ajanla yaptığınız konuşma bunların arasında yoktur.

Şemada önemli olan tek şey şu: subagent görevi kendi penceresinde yürütür, ana sohbete ise özet döndürür. Ana ajanın tüm ara okumaları ve aramaları kendi bağlamına yüklemesi gerekmez. Yine de özetin kendisi de ana bağlamda yer kaplar.

Bu ayrımın bir bedeli var: özet, sonuca giden yolun tamamını göstermez. Ona bakarak asistana hangi verilerin yetmediğini ya da neyi kontrol etmeden bıraktığını fark etmeyebilirsiniz. Bu yüzden yanıtta gerekçeler ve sınırlamalar bulunmalı, vardığı sonuçları da kontrol etmekte fayda var.

Claude neden her şeyi hatırlamaz

Bağlam penceresi, modelin bir sonraki yanıtı hazırlarken elinde bulunan bilgilerdir: talimatlar, erişilebilir sohbet geçmişi, okunan kod, komut sonuçları. Ajanın birkaç mesaj önce konuştuğunuz bir karara dayanabilmesi bu sayededir. Pencerenin bir sınırı var; tüm sohbeti bütün ayrıntılarıyla sonsuza kadar tutmaz.

Ekran görüntüsünde /context komutu 4k/200k tokens (2%) gösteriyor: kullanılabilir 200 bin tokenin yaklaşık 4 bini dolu. Token küçük bir metin parçasıdır: bir kelime, kelimenin bir kısmı ya da bir işaret. Bu yüzden 200 bin token 200 bin kelimeye eşit değildir. Bu, gösterilen oturumun pencere boyutudur; başka bir model veya yapılandırmada farklı olabilir.

Aşağıda yeri neyin kapladığı görülüyor: System prompt - sistem talimatları, Memory files - yüklenen bellek ve kural dosyaları, Skills - skill'ler hakkında bilgiler, Messages - mesajlar. Burada neredeyse hiç yazışma yok, ama pencerenin bir kısmı şimdiden talimatlarla dolu. Free space: 196k (98.0%) satırı kalan boş alanı gösterir. Sohbet ilerledikçe, dosyalar okundukça ve komutlar çalıştırıldıkça bu alan azalır.

Şimdi bu mekanizmayı kod okuyan özel bir reviewer örneğinde inceleyelim: hangi bilgileri alıyor ve rol dosyası nasıl oluşturuluyor. Burada söz konusu olan yeni, sıradan bir çalıştırma; önceki işi sürdürmenin ya da geçmişin bir kopyasını aktarmanın yollarına bu örnekte gerek yok.

2. Reviewer proje hakkında ne bilir

Ayrı bağlam, asistanın hiçbir şey bilmediği anlamına gelmez. Başlangıç talimatları ve projeye erişimi vardır. Örneğimizdeki özel reviewer bilgileri şuralardan alır:

CLAUDE.md, Claude Code için genel talimatlar içeren bir dosyadır: örneğin kaynak kodun nerede durduğu ve projede hangi kurallara uyulduğu. Sırf bu kontrol için onu oluşturmanız gerekmez.

Konuşma geçmişiniz otomatik olarak aktarılmaz. Ana ajan app.js dosyasını daha önce okuduysa, bu okumanın içeriği reviewer'da kendiliğinden belirmez. Ama dosya bir yere kaybolmadı: asistan onu yeniden açabilir.

Sohbette alınan kararlarda da durum aynı. Diyelim ki listedeki iki aynı adın ayrı alışverişler olarak kalması gerektiğini konuştunuz. Silme kontrolü için bu önemli bir gereksinim. Ana ajan onu göreve eklerse ya da asistan yazılı olduğu belgeyi okursa reviewer'a ulaşır.

3. Rol dosyasını oluşturuyoruz

Rolü proje içinde .claude/agents/reviewer.md yoluna koyacağız. Farklı projelerde kullanılabilecek rolleri kullanıcı klasöründeki ~/.claude/agents/ içinde de saklayabilirsiniz; ~ işareti kullanıcının ev klasörünü gösterir. Şimdilik proje seçeneği yeterli.

Dosyayı Claude Code'dan isteyerek oluşturabilirsiniz:

Sayfanın kodunu değişiklik yapmadan kontrol etmek için
.claude/agents/reviewer.md oluştur. Yalnızca Read, Grep, Glob'a izin ver.
Reviewer gerekçeli bulguları, kontrol edilen kapsamı ve
sınırlamaları döndürür; bulgu olmaması da kabul edilebilir.
Oluşturulan dosyayı göster.

Sonuçta sıradan bir metin dosyası oluşmalı. Sihir yok. Aşağıda hazır bir sürüm var: ajanın yanıtını onunla karşılaştırabilir ya da kendiniz kaydedebilirsiniz. Bu adda bir rolünüz zaten varsa, gerekli bir talimatın üzerine yazmamak için önce içeriğine bakın.

---
name: reviewer
description: Hazır bir sayfanın kodunu davranış hatalarına karşı kontrol eder ve gerekçeli bir rapor döndürür. Düzeltme yapmadan sayfa incelemesi istendiğinde kullanılır.
tools: Read, Grep, Glob
---
Belirtilen dosyaların kodunu verilen gereksinimlere göre incele.
Dosyaları değiştirme. Sayfayı çalıştırma sözü verme: sende yalnızca okuma ve arama var.
Her bulgu için yeri, beklenen davranışı, sonucun dayanağını,
kontrol koşullarını ve etkisini belirt. Veri yetmiyorsa bunu not et.
Neyi kontrol ettiğini ve neyi kontrol etmediğini ayrıca listele.
Verilen kriterlere göre sorun bulmadıysan, bunu açıkça yaz.

İki --- satırı arasındaki bloğa frontmatter denir: Markdown dosyasının başındaki ayarlar. Burada name rolün adını belirler, description ana ajana rolü ne zaman seçeceğini anlatır, tools ise kullanılabilir araçları listeler. Altında sözcüklerle yazılmış sıradan talimatlar gelir.

Örnekteki üç araç, kodu incelemek için tam olarak gerekeni yapar: Read dosyayı okur, Grep içerikte arama yapar, Glob dosyaları ada veya yola göre bulur. Bu yüzden reviewer silme fonksiyonunu bulup okuyabilir, ama sayfayı tarayıcıda açamaz ve terminalde komut çalıştıramaz.

"Dosyaları değiştirme" satırı görevi tarif eder. tools alanı ise görevi yerine getirme araçlarını sınırlar. Yalnızca metindeki ricayı bırakıp araçları sınırlamazsanız, asistanın elinde yazma olanakları kalabilir. Hazır örnekte iki parça da yerinde, sınırlamayı sonradan eklemeye gerek yok.

Rol dosyası skill'e benzer: ayarlar ve talimat metni. Karıştırmak kolay. Ama burada kontrol için ayrı bir çalıştırma ayarlıyoruz. Skill genellikle mevcut konuşmaya tekrarlanabilir bir prosedür ekler, gerçi skill'ler de ayrı bir bağlamda çalışabilir. Seçimi iki dosyanın benzer görünüşüne göre değil, işin nasıl yürütülmesi gerektiğine göre yapın.

4. Reviewer'ı kontrol edip çağırıyoruz

Dosyanın diskte olması ilk sonuçtur. Şimdi oturumun onu görüp görmediğini kontrol edelim. Dosyayı açın ve reviewer adına, açıklamaya, araç satırına ve metne bakın: tarayıcıyı başlatma ya da hataları hemen düzeltme vaadi var mı?

Claude Code giriş alanına @ yazın ve agent etiketli reviewer'ı seçin. Gereken şey tam olarak rol, dosya yolu içeren benzer bir öğe değil. Listeden seçmek, bu görev için asistanı açıkça belirtmenizi sağlar.

Rol görünmüyorsa önce yolu kontrol edin: dosya, açık projenin .claude/agents/ klasöründe olmalı. Sonra frontmatter'a bakın: iki ayırıcı satır, ad ve açıklama. Tanım dosyasının kendisini kontrol etmesini Claude Code'dan da isteyebilirsiniz.

Claude Code belgelerine göre, zaten izlenen bir klasördeki değişiklikler birkaç saniye içinde algılanır. agents klasörü oturum başladıktan sonra ilk kez oluştuysa yeniden başlatma gerekir. Mevcut oturumu kapatın, ardından normal terminalde, aynı proje klasöründen şunu çalıştırın:

claude --continue

Bu komut, geçerli dizindeki son konuşmayı sürdürür. Başlattıktan sonra @ listesini yeniden kontrol edin. Claude'u başlatma komutu, çıktıktan sonra terminale yazılır; halihazırda çalışan bir konuşmanın içine değil.

İlk görev için bir alışveriş listesi sayfası alalım: işaretleme index.html içinde, mantık app.js içinde, iki dosya da proje kökünde. Kendi projenizde yolları ve beklenen davranışı kendinize göre değiştirin. Listeden reviewer'ı seçtikten sonra, bu anmanın yanına şu metni ekleyin:

Proje kökündeki index.html ve app.js dosyalarını incele.
Öğe ekleme ve silmeyi kontrol et: sayaç kalan öğe sayısıyla
eşleşmeli, bir kaydı silmek aynı adlı başka bir kaydı silmemeli.
Dosyaları değiştirme. Koda dair sonuçlarını ve tarayıcıda
neyin kontrol edilmesi gerektiğini döndür.

Dar bir kontrol için gereken her şey burada var: nereye bakılacağı, ne olması gerektiği ve nasıl bir sonuç beklendiği. Ayrı bir brief dosyasına gerek yok. Ana ajan, seçilen reviewer için görevi formüle eder; @ ile seçim işi kimin yapacağını belirler, mesajınızın kelimesi kelimesine aktarılmasını değil.

5. Sonuç nasıl gelir

İsteği gönderdikten sonra reviewer çalıştırmasının başlayıp başlamadığına bakın. Normal etkileşimli bir oturumda bu iş arka planda yürüyebilir: onu panelde görür ve konuşmaya devam edebilirsiniz. /tasks komutu, yakın zamanda tamamlananlar dahil görevlere bakmanıza yardımcı olur.

Kontrol bittiğinde ana ajan sonucu alır ve size iletir. Aktarım fazla kısaysa şunu isteyin: "reviewer'ın son raporunu eksiksiz göster". Böylece bulgunun ve kontrol sınırlamalarının tam ifadesini korumak kolaylaşır.

Örneğin, sayaçla ilgili alıştırma amaçlı bir rapor şöyle görünebilir:

app.js'deki ekleme ve silmeyi kontrol ettim.
removeItem() içinde liste yeniden çiziliyor, ama bu yolda
updateCounter() çağrısını bulamadım. Sayacın kalan kayıt
sayısını göstermesi bekleniyor.
Tarayıcıda kontrol: bir öğe ekle, onu sil,
sayacı boş listeyle karşılaştır.
Aynı adlı kayıtların silinmesini ayrıca kontrol etmedim.
Tarayıcıda çalıştırmadım.

Bu, yanıtın biçimine bir örnek; sayfanızda tam olarak bu hatanın bulunacağı sözü değil. Reviewer'ımızın elinde yalnızca kod okuma var, bu yüzden son satır onun olanaklarını dürüstçe anlatıyor. Koda dayalı bir sonuç, çalıştırmadan da gerekçeli olabilir, ama dayanağı kontrol edilmeli: örneğin, sayacı aynı yolda başka bir fonksiyon güncelliyor olabilir mi?

Belirtilen yeri açın ya da anlatılan adımları tarayıcıda tekrarlayın. Sorun doğrulanırsa düzeltmeyi ana ajana verebilirsiniz. Doğrulanmazsa kendi gözleminizi aktarın ve sonucu yeniden kontrol etmesini isteyin. Güzel biçimlendirilmiş bir rapor, tam olarak neyin değiştirilmesi gerektiğine henüz karar vermez.

"Verilen kriterlere göre sorun bulamadım" yanıtı da, neyin kontrol edildiği anlaşılıyorsa kabul edilebilir. "Silme mantığının bulunduğu dosyayı bulamadım" ise kısmi bir sonuç demektir: önce yolu netleştirmek gerekir. Sayı tutsun diye raporu tahminlerle doldurmanın anlamı yok.

Bu arada listede yerleşik Explore ve Plan rolleri de görünebilir. Bunlar kendi rol dosyalarınızı oluşturmadan kullanılabilir.

6. Ne zaman devretmeye değer

İlk başarılı kontrolden sonra her işlem için ayrı bir asistan istemek kolay. Anlaşılır bir cazibe. Ama yeni bir çalıştırma bir şey katmalı: bağımsız bir bakış ya da ayrıntılı seyri ana konuşmada gerekmeyen kendi başına bir iş.

Birbirine bağlı birkaç adım da subagent için tek bir görev oluşturabilir. İşleyiciyi bulmak, çağrılarını kontrol etmek ve bir sonuç çıkarmak - bütünlüklü, normal bir görev. Yalnızca her adımı ayrı bir asistana dağıtmamak gerekir; yoksa komşu adımın sonuçlarını herkese yeniden anlatmak zorunda kalırsınız.

Subagent için model model alanıyla ayrıca atanabilir. şimdilik buna gerek yok: önce anlaşılır bir rol ve doğrulanabilir bir sonuç elde etmek daha faydalı. Ayrı çalıştırma tek başına ne daha güçlü ne de daha zayıf bir model anlamına gelir.

İkinci rol başka bir şeyi kontrol etmeli

Diyelim ki reviewer'ın yanında, kullanıcı senaryosunu kontrol edecek bir playtester da istiyorsunuz. Önceki talimatın yeni adla bir kopyası neredeyse hiçbir şeyi değiştirmez. Önce işin konusunu ve sonucunu birbirinden ayırın:

Örneğin rol yalnızca aynı adlı iki alışverişten birinin silinmesini inceleyebilir: işlemden sonra tek kayıt kalmalı, sayaç da 1 göstermeli. Bu, ölçülebilir bir görev. "Sayfa iyi mi, değerlendir" ise zevke dayalı tavsiyelere fazlasıyla yer bırakır.

Şimdi görevi araçlarla karşılaştırın. Reviewer'ımızdaki gibi yalnızca okuma ve aramayla asistan tarayıcıda işlem yapamaz. Bir kontrol senaryosu hazırlayabilir ya da yazıya geçirdiğiniz gözlemleri inceleyebilir. Bu, kontrolün hazırlığı ya da analizidir; kendi başına yapılmış bir playtest değil.

Aynı adlı iki alışverişten birinin silinmesi için bir kontrol
senaryosu hazırla. Her adım için eylemi ve beklenen sonucu
belirt. Kodu değiştirme, çalıştırdığını iddia etme.
Gözlemlerimi paylaştıktan sonra beklenenle gerçekleşeni
karşılaştır ve hangi verilerin eksik olduğunu listele.

Kendi başına çalıştırma için kullanılabilir bir tarayıcı aracı ve çalıştırmanın gerçekten gerçekleştiğinin kontrolü gerekir. Bunun için yalnızca playtester adı yetmez. Önce kontrol yöntemini seçin, sonra rolde onun ne zaman çağrılacağını ve dürüstçe hangi sonucu döndürebileceğini tarif edin.

7. Bu, oturumunuzda nasıl görünüyor

Artık oturumun gördüğü bir rol dosyanız ve ona verebileceğiniz kısa bir kontrol göreviniz var. Başlangıç için bu kadarı yeterli. Önceden onlarca benzer reviewer toplamaya gerek yok.

Bundan sonra sorunun ortaya çıktığı katmanı düzeltin. Önemli bir koşulu aktarmadınız mı - görevi tamamlayın. Şüpheli bir sonuç mu aldınız - dayanağını kontrol edin. Reviewer sürekli fazla genel yanıtlar mı döndürüyor - rol talimatını netleştirin. Dosya projede kalacak ve bir sonraki kontrole bu kurallarla başlayacaksınız.

Tekrarlanan görevler için reviewer'a brief işinize yarayacak. Yanıtı aldıktan sonra bulguları kontrol etmeye ve düzeltmeleri seçmeye geçin.