İncelemeyi bir subagent'a devretmek ve raporu kontrol etmek

"Sayfayı incele" isteği inceleyiciye epeyce karar bırakır: davranıştaki hataları mı arayacak, tasarımı mı değerlendirecek, yoksa kodu yazmanın başka bir yolunu mu önerecek. Karşılığında düzenli bir yorum listesi alabilirsiniz, ama bu liste asıl işinize neredeyse hiç yardım etmez. Claude Code'daki bir subagent'a anlaşılır bir görevi nasıl vereceğinizi ve ardından görevin yerine getirilip getirilmediğini nasıl kontrol edeceğinizi inceleyelim.

Henüz reviewer rolünü ayarlamadıysanız, önce rolü oluşturun ve ilk çalıştırmayı yapın. Burada görevin kendisine ve yanıtın eksiksiz olmasına odaklanacağız.

1. İnceleyiciye ne verilir

İnceleyici başkasının işini kontrol eder ve yorumlarını gerekçeleriyle birlikte döndürür. Örneklerimizde bu, reviewer adlı, önceden ayarlanmış özel bir subagenttir; yalnızca dosyaları okuyup içlerinde arama yapabilir: Read, Grep, Glob. Kodu inceler, ama düzeltmez ve sayfayı tarayıcıda açmaz. reviewer adı bu rolü kendiliğinden oluşturmaz: rolün projenizde zaten ayarlı olduğu varsayılıyor.

Olağan yeni bir çalıştırmada böyle bir subagent, sohbetinizin tüm geçmişini kendiliğinden almaz. Onun için ayrı bir görev metnini, sizin konuştuğunuz ana ajan yazar. Bu yüzden "aynı adlı iki ürün ayrı kayıt sayılır" gibi önemli bir gereksinim ya görevin içine ya da inceleyiciden okuması istenen belgeye girmelidir. Bu düzen subagent bağlamıyla ilgili belgelerde anlatılıyor; burada konuşmanın kopyasıyla çalışan fork'tan değil, özel bir rolün çalıştırılmasından söz ediyoruz.

"Projeye bak" ile "Kayıt silmeyi ve sayacın güncellenmesini kontrol et; kodu değiştirme" isteklerini karşılaştırın. İkincisinde nereye bakılacağı ve hangi eylemi beklemediğiniz zaten belli. Geriye, doğru sonucun ne sayılacağını netleştirmek kalıyor.

Kısa, tek seferlik bir kontrol için bir ileti yeterlidir. Kriter çoksa ya da kontrol düzeltmelerden sonra tekrarlanacaksa, bir brief kaydetmek daha pratiktir: projenin yanında duran kısa bir görev tanımı. On sayfalık ayrı bir spesifikasyon değil. İnceleyicinin onlar olmadan tahmin yürütmek zorunda kalacağı birkaç koşul.

Bütün soruları önceden kestirmek mümkün değil, buna gerek de yok. Girdi eksik olduğunda inceleyici bu boşluğu raporda belirtmeli. Ana ajan da eksik noktayı size sorup netleştirebilir. İyi bir görev tanımı farklı yorumları azaltır, ama iyi bir yanıtı garanti etmez: model net bir görevde de yanılabilir.

2. Görevin dört bölümü

Amaç, hangi davranışın kontrol edileceği sorusunu yanıtlar. Alışveriş listesi sayfası için bunlar ekleme, silme ve kayıt sayacıdır. "Projeyi daha iyi hale getirmek" fazla geniş: şu anda hangi iyileştirmenin önemli olduğu belli değil.

Girdi, dosyaları ve beklenen davranışı belirtir. Koddan aynı adlara izin verilip verilmediği anlaşılmıyorsa, app.js dosyasının yolu tek başına yetmez. Bu ürün kararı açıkça aktarılmalı. Bu arada neyle kontrol edileceğini de belirtin: bizde bu yalnızca kod okuma, tarayıcı yok.

Sınırlar bu kontrolü komşu görevlerden ayırır. Örneğin stiller, mobil görünüm ve listenin oturumlar arasında kaydedilmesi şimdilik kapsam dışında. dosyaları değiştirmiyoruz. Gereken dosya yoksa, kontrolün ona bağlı kısmını durdurup bunu bildiriyoruz; içeriğini uydurmuyoruz.

Sonuç, ne almak istediğinizi anlatır: kontrol edilen kapsam, gerekçeli bulgular ve sınırlamalar. Mutlaka beş hata bulunmasını istemeyin. Claude Code'un inceleme önerilerinde böyle bir görev tanımının riskine ayrıca dikkat çekiliyor: kusur arama talimatı, işin doğru yapıldığı yerlerde bile yorum yazmaya iter.

Her dal, diğerlerinin vermediği bir şeyi ekler: dosya yolu beklenen davranışı belirlemez, amaç da düzenleme yasağını tanımlamaz. İnceleyicinin kontrol sırasında bunları birbiriyle karşılaştırabilmesi için bu koşulları bir araya toplayın.

Yani "Alışveriş listesi sayfasını kontrol et" yerine aşağıdaki görevi veriyoruz. Bunu bir ileti olarak gönderebilir ya da proje kökünde REVIEW_BRIEF.md dosyasına kaydedebilirsiniz:

# Alışveriş listesi kontrolü
Amaç: ekleme, silme ve sayacı kod üzerinden kontrol et.
Girdi: proje kökündeki index.html ve app.js.
Beklenen: eklenen öğe listede görünür;
sayaç öğe sayısına eşittir; bir kaydı silmek
aynı adlı başka bir kaydı silmez.
Sınırlar: dosyaları değiştirme; stiller, mobil görünüm ve
listenin oturumlar arasında kaydedilmesi bu kontrole dahil değil.
Gereken bir dosya ya da gereksinim eksikse boşluğu belirt,
tahmin yürütme ve erişilebilen kısım için sonuç döndür.
Sonuç: reviewer biçimine uy; neyin kontrol edildiğini
ve neyin kontrol edilmeden kaldığını belirt. Bulgu olmaması kabul edilebilir.

Hemen aşağıda reviewer biçimine bakacağız. Rolünüzde henüz kalıcı bir biçim yoksa, onu aynı tek seferlik iletiye ekleyebilirsiniz. Alan adları zorunlu değil: önemli olan, unutmamanıza yardım ettikleri bilgi.

"Raporda önce en önemli üç bulguyu göster" isteği yanıtın uzunluğunu sınırlar, kontrolün derinliğini değil. Böyle bir sınır gerekiyorsa, başka bulgu olup olmadığını ayrıca belirtmesini isteyin. Üçüncü yorumdan sonra durup görevi kontrol edilmiş ilan etmek olmaz.

3. Dosyalara ne kaydedilir

Belirli bir görevin koşulları değişir: bugün sayacı, yarın listenin kaydedilmesini kontrol ediyoruz. Bunların yeri brief'tir. Oysa hatanın yerini ve gerekçesini gösterme isteği neredeyse her incelemede gerekir. Onu bir kez rol talimatına yazmak daha pratiktir.

Output contract ya da çıktı kontratı, burada üzerinde anlaşılmış yanıt biçimi demek. Kulağa olduğundan daha ciddi geliyor: bunlar inceleyici için sıradan talimatlardır, ne Claude Code'un özel bir ayarıdır ne de otomatik bir kalite kontrolü. Biçim, raporda gereken bilgiyi bulmayı kolaylaştırır, ama o bilgiyi güvenilir yapmaz.

Üstteki iki dal farklı şeylerden sorumlu: brief kontrolün içeriğini belirler, rol talimatı ise rapor biçimi dahil daha fazlasını. İnceleyicinin kaydedilmiş brief'i kullanması için ondan dosyayı okumasını isteyin. Oraya kendiliğinden bakmaz. Altta, gerekçelerini ve eksiksizliğini sizin değerlendirmeniz gereken bir rapor çıkar.

Aşağıdaki bölümü, var olan .claude/agents/reviewer.md rol dosyasının metin kısmına, ayarlarından sonra ekleyebilirsiniz:

## Sonuç biçimi
Kontrol ettiğin dosyaları ve kriterleri belirt.
Her bulgu için: yer, beklenen davranış, gerekçe,
kontrol koşulları ve etkisi; önceliği açıkla.
Kodla doğrulananı, kontrol edilmemiş varsayımlardan ayır.
Sınırlamaları ve eksik verileri ayrıca belirt.
Kriterlere göre sorun bulmadıysan, bunu açıkça yaz.

Bu bir talimat parçası, eksiksiz bir subagent dosyası değil. Rolümüz yalnızca okuyup arama yapabildiği için sabit bir "değiştirilen dosyalar" alanına ihtiyacı yok. Daha kapsamlı bir raporda değişikliklerle ilgili bilgi gerçeği yansıtmalı: ne olduğundan bağımsız olarak "değiştirilen dosyalar: yok" satırını önceden şart koşamazsınız.

Brief kaydedildikten sonra ana ajana şu isteği gönderin:

reviewer'dan proje kökündeki REVIEW_BRIEF.md dosyasını okumasını
ve belirtilen dosyaları oradaki kriterlere göre kontrol etmesini iste.
Nihai raporu eksiksiz döndür.

Belgenin adını anmakla yetinmedik, onu okumasını açıkça istedik. Yine de dosyanın kendisi hiçbir şeyi garanti etmez: inceleyici bir koşulu gene atlayabilir. Kaydedilmiş brief'in faydası, sonucu onunla karşılaştırabilmeniz ve kontrolü tekrarlayabilmenizdir. Gereksinimler değiştiğinde önce belgeyi güncelleyin, yoksa sonraki tur eski görevi değerlendirir.

4. Rapor nasıl kontrol edilir

Önce gerçekte neyin kontrol edildiğine bakın. Brief'te ekleme, silme, sayaç ve aynı adlı kayıtların birbirinden bağımsızlığı vardı. Rapor yalnızca sayaçtan söz ediyorsa, bu henüz görevin tamamı için bir sonuç değildir. Tek bulgu tamamen doğru olsa bile.

Brief'teki her kriteri yanıtla karşılaştırmak işe yarar. Örneğin eğitim amaçlı kısmi bir raporda tablo şöyle çıktı:

Aynı adlarla ilgili bir satırın olmaması, hata olmadığı anlamına gelmez. Sayaçla ilgili gerekçeli tek bir bulgu da görevin atlanan kısmını kapatmaz. Raporu somut bir soruyla geri gönderin:

Brief'te aynı adlı iki kayıttan birinin silinmesi var.
Raporda bu kriter yer almıyor. Onu elindeki araçlarla kontrol et
ve sonucun gerekçesini ya da neden kontrol edemediğini belirt.
Diğer sonuçları değişiklik yoksa tekrarlamana gerek yok. Kodu değiştirme.

Önemli bulguların güvenilirliğini ayrıca değerlendirin: belirtilen yeri, gereksinimi ve sonucun gerekçesini karşılaştırın. Ayrıntılı bir örnek, inceleme raporunu okumakla ilgili makalede var. Burada iki kontrol de gerekli: görevin ne kadarının kapsandığı ve sonucun ne kadar gerekçeli olduğu. Önerilen bir çalıştırma senaryosu, yapılmış bir testle aynı şey değildir.

İlk yol ayrımında, görevimiz için yeterince şeyin kontrol edilip edilmediğine karar veriyoruz. Edilmediyse eksik olanı istiyoruz ya da yalnızca kontrol edilen kısmı, onun gerekçelerini de değerlendirerek kabul ediyoruz. İkinci yol ayrımında gerekçeli sonuçları tartışmalı ve yanlış olanlardan ayırıyoruz. Belirsiz bir gerekçeyi netleştirmek gerekir; yanlış olduğu kanıtlanmış bir yorum ya da görevle ilgisi olmayan bir öneri reddedilebilir.

Bulgusuz bir rapor da bu kontrolden geçebilir. Örneğin: "index.html ve app.js içinde ekleme ve silme yolları, aynı adlı kayıtların bağımsızlığı ve sayacın güncellenmesi kontrol edildi. Bu kriterlere göre sorun bulamadım; tarayıcıda çalıştırmadım". Böyle bir sonuç, projede hiç hata olmadığını vaat etmez. Belirtilen sınırlar içindeki sonucu bildirir; gerekirse ana yolları siz kendiniz doğrularsınız.

"app.js'yi belirtilen yolda bulamadım, silme davranışını kontrol edemedim" ise hata olmadığını değil, veri eksik olduğunu gösterir. Burada doğru yolu verip kontrole devam etmek gerekir. Kısa ve dürüst bir yanıt, boşluğun gizlendiği uzun bir rapordan daha faydalıdır.

Raporu kabul etmek, listelenen her şeyin düzeltilmesini istemek demek değildir. Kontrol sonucunu gerekçeli buldunuz; şimdi hangi değişikliklerin yapılacağına ayrıca karar verirsiniz.

5. Bir tur daha ne zaman gerekir

Raporda bir gerekçe eksikse, incelemeye baştan başlamak şart değil. Somut boşluğu geri gönderin. Örneğin sayaç bulgusunun kısaltılmış hali yalnızca hatanın adını içeriyor, çağrıların incelemesi yok. O zaman ana ajana istek şöyle olabilir:

Raporu netleştirmesi için reviewer'a geri gönder: sayaç bulgusunda
silmeden sonra sayacın hangi yolla güncellendiği belirtilmemiş.
Bu yolu kontrol etsin ve sonucun gerekçesini eklesin.
Kod değiştirilmesin.

Güncellemenin zaten başka bir fonksiyonda yapıldığı ortaya çıkarsa, yorum geri çekilmelidir. Önceki yorum sayısını korumak için yerine başka bir şey aramaya gerek yok. Hata doğrulanırsa, düzeltmeyi ana ajana ayrı bir istekle verebilirsiniz; somut bulguyu ve izin verilen değişiklik kapsamını belirterek.

Düzeltmeden sonra aynı brief ile bir tur daha yapmak faydalıdır:

reviewer'dan REVIEW_BRIEF.md dosyasını yeniden okumasını ve
silme ile sayacın güncel kodunu kontrol etmesini iste. Önceki bulgu:
silmeden sonra sayaç güncellenmiyordu.
Sorunun giderilip giderilmediğini ve sonucun neye dayandığını belirtsin,
ayrıca aynı adlı kayıtların bağımsızlığının etkilenip
etkilenmediğini kontrol etsin. Kod değiştirilmesin.

Artık somut bir sorunun yanıtını arıyoruz: sorun kapandı mı ve düzeltmenin etkileyebileceği komşu davranış bozuldu mu. Sayfadaki davranışı doğrulamak için aynı senaryoyu tarayıcıda tekrarlayın. Tekrar inceleme yalnızca kod üzerinden yapıldıysa, bu sınırlama yeni raporda da kalır.

Rapor kısalabilir, uzayabilir ya da hiç yeni bulgu içermeyebilir. Başarı bunda değil. Önemli olan, eski hatanın giderilmiş olması, sonucun güncel koda dayanması ve kontrol edilmeyen kısımların görünür kalması. Düzeltmeyi ertelemeye mi karar verdiniz? O zaman doğrulanmış bulguyu ve erteleme nedenini kaydedin; değişmemiş kodu sırf yeni bir yanıt için tekrar incelemenin anlamı yok.

6. Görevden doğrulanmış sonuca

Claude Code ile çalışırken brief, ana ajan görevi inceleyiciye aktarırken beklentinizin kaybolmamasına yardım eder. Kalıcı biçim, yanıtı okumayı kolaylaştırır. Ama yine de sizin de katılmanız gerekecek, şöyle:

• ana ajan görevi yazar ve uygun role aktarır; beklenen davranışı ve sınırları siz belirlersiniz;
• inceleyici dosyaları inceler ve sonuçların gerekçelerini döndürür; kapsamı ve önemli bulguları ise siz kontrol edersiniz;
• ana ajan ayrı bir istekle raporu netleştirebilir ya da doğrulanmış hatayı düzeltebilir; neyin değişeceğine ve sonucun nasıl doğrulanacağına siz karar verirsiniz.

Alışveriş listesi için sonuç yalnızca "bir fonksiyon çağrısı ekle" önerisi olmayacak, doğrulanmış bir açıklama olacak: hangi eylemde sayı eskiyordu, güncelleme nerede bozuluyordu ve düzeltmeden sonra ne değişti. Böyle bir sonuçla artık çalışabilirsiniz.