Ajanla kod incelemesi nasıl yapılır

Bir alışveriş listesi sayfası düşünün: açılıyor, öğeler ekleniyor, düğmeler düzgün görünüyor. Ama ekranın hazır olması, koddaki her şeyin düşünüldüğü anlamına gelmez. Geliştiriciler gözden kaçan hataları bulmak ve kararları tartışmak için kodu ayrıca gözden geçirir. Bu işi bir ajana verebilirsiniz, üstelik ajan bunun gayet iyi altından kalkar. Sadece ona görevi anlatmanız gerekir.

1. Kod ekipte nasıl kontrol edilir

Küçük bir ekipte bir geliştiriciye görev verilir: kayıt eklenebilen ve kayıtları tek tek silinebilen bir alışveriş listesi yapmak. Geliştirici kodu yazar, ekmek ve süt eklemeyi dener, ekmeği siler. Her şey çalışır. İşi devretmeden önce değişikliklerini bir kez daha okur: unutulmuş bir parçayı kaldırır, anlaşılmayan bir adı düzeltir. Buna öz kontrol denir.

Ardından bir meslektaşından koda bakmasını ister. Meslektaş programlama dilini bilir ve kodu okuyarak eklemenin nasıl yapıldığına, programın silinecek kaydı nasıl seçtiğine, listenin geri kalanına ne olduğuna bakar. Bu tür incelemeye kod incelemesi ya da code review, kontrol eden kişiye de inceleyici (reviewer) denir.

Meslektaş şunu fark eder: program silinecek ürünü adına göre seçiyor. Listede iki "Süt" kaydı olursa, birine tıklamak ikisini birden silebilir. Yazar ekmek ve sütle denemişti. Böyle bir durum sadece karşısına çıkmamıştı.

İnceleyici, kodun ilgili kısmının yanına bir yorum bırakır: "Şu an bu ada sahip bütün ürünler siliniyor. Aynı kayıtlara izin veriyor muyuz? Veriyorsak sadece seçilen kayıt silinmeli". Yazar gereksinimi netleştirir: aynı kayıtlara izin var, çünkü farklı kişiler için eklenmiş olabilirler. Tartışmanın ardından kaydı seçme şeklini değiştirir. Meslektaş düzeltmeye bir kez daha bakar ve yorumun dikkate alındığından emin olur.

Şemada yorumlu bir inceleme turu gösteriliyor: kod yazardan meslektaşa geçer, sonra düzeltme için geri döner. Tekrar bakıldıktan sonra hâlâ soru kalırsa tartışma ve düzeltmeler tekrarlanır. Önemli bir yorum kalmadığında meslektaş değişikliği onaylar.

Olağan çalışma döngüsü budur: yazdı, gösterdi, yorum aldı, tartıştı, düzeltti. Bazen birkaç yorum çıkar, bazen hiç çıkmaz. Yazarın kararını açıkladığı ve meslektaşın sorusunu geri çektiği de olur. İnceleme, her yoruma katılmayı gerektirmez.

Bu tür bir incelemede kodun anlaşılırlığı da konuşulur: sonraki geliştirici onu anlayabilecek mi, tek bir kural için birkaç yerde değişiklik yapmak gerekiyor mu? Meslektaş bu arada programın yeni kısmının nasıl çalıştığını da öğrenir. Proje bilgisi yavaş yavaş ekibe yayılır, sadece yazarda kalmaz.

Burada incelemeyi test ile karıştırmak kolaydır. Biri iki ürün ekleyip düğmeye bastığında çalışan programın davranışını kontrol eder. Silme kodunu okuyup hangi kayıtları seçeceğini anlamaya çalıştığında ise inceleme yapar. İnceleme sırasında bir tahmini doğrulamak için programı çalıştırmak da mümkündür. Bu yöntemler birbirini tamamlar.

2. İncelemeyi bir ajana nasıl verirsiniz

Şimdi alışveriş listesini sizin tarifinize göre Claude Code'un yazdığını düşünün. Sayfada ne olması gerektiğini anlatabiliyorsunuz, ama programın mantığını okuyamıyorsunuz. İncelemenin teknik kısmını da ajana bırakabilirsiniz: dosyaları okur ve yorumları sade bir dille anlatır.

Ekip hikayesindeki roller aynen kalır. Kodun bir yazarı ve ayrı bir görev verilmiş bir kontrol edeni vardır. Claude Code'da bunun için bir subagent kullanabilirsiniz: ana ajanın belirli bir işi verdiği yardımcı. Bizim durumumuzda kodu okur ve yorumları geri döndürür.

Yazardan kendi işini tekrar kontrol etmesini istemek de faydalıdır. Ayrı bir inceleyici ise başka bir bakış açısı getirir: onun görevi sonucu değerlendirmektir. Hangi çözümlerin kabul edilebilir olduğunu anlaması için ona gereksinimleri verin. Örneğin aynı ada sahip ürünleri yasaklamak silme sorununu görünürde ortadan kaldırır, ama sayfanın tasarlanan davranışını değiştirir.

Claude Code'un inceleme önerilerinde ayrı bir kontrol eden ve açık kriterler öneriliyor. Aynı yerde, programın doğru çalışmasını ve gereksinimleri etkileyen yorumlara odaklanılması tavsiye ediliyor. Bunu projenin küçük bir parçasına uygulayalım.

İncelemeyi düzenlemek için sizden çok şey gerekmiyor: istenen davranışı tarif etmek ve doğrulanan sorunlardan hangilerinin düzeltileceğini seçmek. Programın mantığını okumak, nedeni bulmak ve teknik itirazları tartmak ajanlara bırakılabilir.

Şemada üç rol var: siz gereksinimleri belirler ve düzeltmeleri seçersiniz, ana ajan işi düzenler ve kodu düzeltir, kontrol edenler kodu ve yorumları inceler. Ana ajan onlara gereken malzemeyi iletir ve sonuçları size getirir. Doğrulanan bir sorun yoksa düzeltme adımları atlanır. Aşağıda bu sırayı üç istekle uygulayacağız.

Sonunda elinizde sorunun anlaşılır bir açıklaması, yeniden kontrolünün sonucu ve düzeltme raporu olur. Yorum hatalı çıksa bile faydalı bir sonuç var: gereksiz bir değişiklikten kaçınmış olursunuz.

Bu tür incelemeler için kalıcı bir yardımcı kurmak isterseniz subagent oluşturma ve çalıştırma hakkındaki yazı işinize yarar. Ona daha ayrıntılı bir görevi nasıl hazırlayacağınız brief ve sonuç formatı hakkındaki makalede anlatılıyor.

İstek 1. Yazılan kodu kontrol ettirin

Claude Code'u proje klasöründe başlatın. Sonraki üç isteği ana oturuma gönderin: işi yardımcılara ana ajanın kendisi dağıtır. Burada ve devamında eğitim amaçlı alışveriş listesini kullanıyoruz; kendi projeniz için davranış tarifini değiştirin.

Mevcut projedeki alışveriş listesi kodunun incelemesini ayrı
bir subagent'a ver. Kayıt ekleme ve silmeyi kontrol et.
Gereksinimler: aynı adlara izin var; sadece seçilen
kayıt silinir; boş bir ürün eklenemez.

Mevcut kodu ve onunla ilişkili proje kısımlarını oku.
Bu gereksinimleri ihlal eden hataları ara.
Kodu değiştirme. Yeni özellikler ekleme.
Her yorum için basit kelimelerle açıkla:
ne ters gidebilir, hangi işlemde ve neden böyle düşündün.
Başka bir ajanın sonra kontrol edebilmesi için koddaki yeri belirt.
Sorun bulunmazsa bunu açıkça yaz. Neyin kontrol edildiğini
ve neyin bilinmediğini sırala. Raporu REVIEW_REPORT.md dosyasına kaydet.
Programlama dilini bilmiyorum: sonucu kod okumamı gerektirmeden açıkla.

REVIEW_REPORT.md sıradan bir metin raporu olacak. Adını biz seçtik, başka herhangi bir ad da olur: bir sonraki istekte hangi yorumların yeniden kontrol edileceği anlaşılsın diye gerekli. "Kodu değiştirme" şartı incelemeyi düzeltmeden ayırır; raporu dosyaya yazmaya ise izin var.

Örneğimizde işe yarar bir cevap şöyle olabilirdi: "Aynı ada sahip iki ürün eklerseniz, birini silmek ikisini birden kaldırır. Kod kayıtları ada göre seçiyor, bu yüzden iki eşleşmeyi de etkiliyor". Bu, eğitim amaçlı bir cevap örneğidir, sizin projenizin kontrol sonucu değildir.

Sonuç sizin için anlaşılır: kişi saklamak istediği kaydı kaybeder. Dosya adı ve koddaki yer, nedeni bulabilmesi için sonraki ajana gerekir. Bu kısmı kendiniz incelemek zorunda değilsiniz.

3. Yorumlar nasıl yeniden kontrol edilir

İnceleyici ajan da hata yapabilir. Örneğin şöyle yazar: "Listeye boş bir ürün eklenebiliyor". Kulağa inandırıcı geliyor. Ama boş giriş kontrolü, programın ajanın okumadığı başka bir kısmında zaten var. Yorum, var olmayan bir sorunu anlatıyor.

Böyle kendinden emin ama uydurma bir iddiaya genellikle yapay zekanın halüsinasyonu denir. İncelemede bu özellikle can sıkıcıdır: ajan bir düzeltme önerebilir, siz de zaten doğru çalışan kodu değiştirmek için zaman harcarsınız. Bu yüzden hem yazıldıktan sonra kodun kendisini hem de onun hakkındaki yorumları yeniden kontrol etmek faydalıdır.

İlk adımı zaten attık: yazarın işine bakılmasını istedik. Şimdi raporu, mevcut projeyle birlikte başka bir kontrol edene vereceğiz. Onun görevi: her yorumun doğrulanıp doğrulanmadığını ortaya çıkarmak. İlk inceleyiciye katılmama hakkı da var.

İstek 2. İnceleyicinin raporunu kontrol ettirin

Başka bir subagent'a REVIEW_REPORT.md dosyasını mevcut proje
koduna ve önceki istekteki gereksinimlere göre yeniden kontrol ettir.
Bu gereksinimleri ona açıkça ilet.

Her yorum için, anlatılan sorunun gerçekten var olup olmadığını bul.
İlgili kod kısımlarını kontrol et: gereken işlem zaten olabilir.
İlk raporu kanıt sayma. Sonuca varmak için çalıştırarak kontrol
gerekiyorsa, bunu elindeki araçlarla yap.
Proje kodunu değiştirme.

Her madde için belirt: doğrulandı, çürütüldü
ya da henüz belirlenemedi. Gerekçeyi anlaşılır bir dille açıkla.
Kod okumaya dayanan sonuçları ve yapılan kontrollerin sonuçlarını ayır.
Yapılmamış bir kontrolü yapılmış gibi gösterme.
Sonucu REVIEW_CHECK.md dosyasına kaydet ve bana kısaca açıkla.

Bundan sonra elinizde yeniden kontrolün sonucunu içeren REVIEW_CHECK.md olur. Eğitim örneğimizde ikinci ajan aynı adlar sorununu doğrulayabilir, boş giriş yorumunu ise çürütebilir: "Boş satır, kayıt eklenmeden önce reddediliyor. İlk inceleyici bu kontrolü gözden kaçırmış".

Bu, sonraki adımı seçmeye zaten yardımcı olur. Silme sorunu düzeltmeye gönderilebilir. Boş giriş konusunda bu yorum yüzünden bir şey değiştirmeye gerek yok. Ajan "henüz belirlenemedi" yazarsa, hangi bilginin eksik kaldığını açıklamasını isteyin. Bazen bu size yöneltilmiş bir sorudur: örneğin aynı kayıtlar tek bir ürün mü sayılmalı, yoksa iki ayrı ürün mü.

Yeniden kontrol uydurma yorumları elemeye yardımcı olur, ama tamamen ortadan kalkacaklarını garanti etmez. İki ajan aynı hatayı tekrarlayabilir. Bu yüzden cevapta gerekçe olmalı: kontrol eden projede tam olarak ne buldu ya da çalıştırınca hangi sonucu aldı. Sadece "önceki ajana katılıyorum" demek yetmez.

4. Düzeltme ve yeniden inceleme

Şimdi neyin düzeltileceğini seçin. Bunun için sorunun sayfanın tasarlanan çalışmasını nasıl etkilediğini anlamak yeterli. Örneğimizde fazladan bir ürünün silinmesi açıkça sorun, bu yüzden bu maddeyi alıyoruz. Sıralama ekleme önerisi sonraya kalabilir. silmenin düzeltilmesiyle zaten bir ilgisi yok.

Seçtiğiniz yorumu ajana eksiksiz verin, böylece "ilk hatayı düzelt" derken ne kastettiğinizi tahmin etmek zorunda kalmaz. Değişiklikten sonra sonucu yeniden kontrol etmesini isteyin. Bu, ekip hikayesinin devamı: meslektaş artık düzeltilmiş sürüme bakıyor.

İstek 3. Düzeltip sonucu kontrol ettirin

REVIEW_CHECK.md dosyasındaki doğrulanmış sorunu düzelt:
bir ürün silinince aynı ada sahip bütün kayıtlar kayboluyor.
Sadece seçilen kayıt silinmeli. Aynı adlara izin var.
İncelemedeki diğer önerileri şimdilik uygulama.

Düzeltmeden sonra ürün ekleme ve silmeyi elindeki araçlarla
kontrol et, aynı ada sahip iki ürün dahil.
Sonra düzeltilmiş kodun yeniden incelemesini ayrı bir subagent'a ver:
hatanın nedeni giderildi mi, ekleme ve silmenin çalışması bozuldu mu.
Ona ilk gereksinimleri ve düzeltilen sorunun tarifini ilet.

Bana basit kelimelerle neyin değiştiğini, hangi kontrollerin
yapıldığını ve yeniden incelemenin ne gösterdiğini açıkla.
Kontrol edilemeyen bir şey olduysa, onu ayrıca belirt.
Görevi yeni iyileştirmelerle genişletme.

Kendi projeniz için ürünlerle ilgili paragrafı kendi raporunuzdaki doğrulanmış yorumla değiştirin. Sıranın geri kalanını koruyabilirsiniz: düzeltme, kontrol, sonucun ayrıca incelenmesi.

İyi bir sonuç somut bir şey söyler: "Artık her kayıt ayrı ayrı siliniyor. Aynı ada sahip iki kayıtla yapılan kontrolde ikinci kayıt yerinde kaldı. Yeniden inceleme hatanın önceki nedenini bulmadı". Bunu ancak ilgili kontroller yapıldıktan sonra yazmak mümkündür. Ajan kodu sadece okuduysa, bunu belirtmelidir.

Sayfayı açıp alıştığınız işlemleri kendiniz de deneyebilirsiniz. Bunun için dil bilmek gerekmez. Bu, görünen sonucun ek bir kontrolüdür; düzeltmenin teknik incelemesini yine ajan yapar. Ajanın çalıştırma imkanları yetmediyse, raporda "kesin çalışıyor" vaadi yerine anlaşılır bir sınırlama yer alır.

Her turu bitmeyen bir iyileştirmeye çevirmek zorunda değilsiniz. Seçilen sorun giderildiyse, kontrol edildiyse ve yeniden inceleme ilişkili bir hata bulmadıysa, bu görevi bitirebilirsiniz. Hepsi bu. Yeni istekler ayrı bir konuşmayı hak eder.