Claude Code PR incelemesi: ön-inceleme diff'lerini daha hızlı ve güvenli hale getirin

Neden PR inceleme süresi uzar

PR incelemeleri nadiren “zor” olduğu için uzun sürer. Uzun süren neden, inceleyenin niyet, risk ve etkiyi bir diff'ten —değişiklikleri gösteren ama bütün hikâyeyi anlatmayan— yeniden kurmak zorunda kalmasıdır.

Küçük bir düzenleme gizli bağımlılıkları tetikleyebilir: bir alanın adını değiştirin ve bir rapor bozulur, bir varsayılan değeri değiştirin ve davranış kayar, bir koşulu değiştirin ve hata yakalama farklı çalışır. İnceleme süresi, inceleyenin bağlam için tıklayıp gezinmesi, uygulamayı yerelde çalıştırması ve PR'in ne yapması gerektiğini anlamak için ek sorular sorması gerektiğinde artar.

Ayrıca insana özgü bir örüntü sorunu var. İnsanlar diff'leri öngörülebilir şekillerde tarar: “ana” değişikliğe odaklanırız ve hataların gizlendiği sıkıcı satırları kaçırırız (sınır kontrolleri, null işleme, loglama, temizlik). Ayrıca görmeyi beklediklerimizi okuma eğilimindeyiz; bu yüzden copy-paste hataları ve ters koşullar gözden kaçabilir.

İyi bir ön-inceleme hüküm vermek değildir. Hızlı, yapılandırılmış ve insanın nerede yavaşlaması gerektiğini gösteren ikinci bir çift gözdür. En iyi çıktı şunları verir:

• ne değiştiğinin düz İngilizce (ya da buradaki dilde) özeti
• belirli risk noktaları (dosyalar, fonksiyonlar, varsayımlar)
• okunabilirlik notları (isimlendirme, kafa karıştıran kontrol akışı)
• doğruluk endişeleri (mantık, hata işleme, veri tutarlılığı)
• test edilmeye değer kenar durumları (girdiler, zaman, izinler, boş durumlar)

Ne yapmamalı: PR'i “onaylamak”, gereksinimler uydurmak veya diff'te kanıt yoksa çalışma zamanını tahmin etmektir. Eğer diff yeterli bağlam sağlamıyorsa (beklenen girdiler, kısıtlar, çağıran sözleşmeler gibi), ön-inceleme bunu belirtmeli ve tam olarak neyin eksik olduğunu listelemelidir.

Yapay zekâ yardımı, anlamın kaybolabileceği iş mantığını veya yeniden düzenlemeleri (refactor) içeren orta büyüklükteki PR'lerde en güçlüdür. Derin organizasyon bilgisine (miras davranışlar, üretim performans incelikleri, iç güvenlik kuralları) bağlı doğru cevabın gerektiği durumlarda zayıftır.

Örnek: “sadece sayfalamayı güncelliyor” görünen bir PR genellikle bir-eksi-bir sayfa hatalarını, boş sonuçları ve API ile UI arasındaki sıralama uyumsuzluklarını gizler. Bir ön-inceleme, insanın 30 dakika harcamadan önce bu soruları gündeme getirmelidir.

Ön-inceleme için Claude'dan ne istemelisiniz

Claude’ı karar veren değil, hızlı ve titiz bir ilk geçiş yapan inceleyici gibi değerlendirin. Amaç, kafa karıştıran kodu, gizli davranış değişikliklerini, eksik testleri ve yakın olduğunuzda unuttuğunuz kenar durumları daha erken ortaya çıkarmaktır.

Adil bir insan inceleyicinin ihtiyaç duyacağı bilgileri verin:

• PR amacını (1–3 cümle)
• bozulmaması gerekenler (API şekli, geriye dönük uyumluluk, performans bütçesi, güvenlik kuralları)
• özel kısıtlar veya takaslar (son teslim tarihleri, kısmi dağıtım)
• niyeti anlamak için yeterli çevresel kodla birlikte ilgili diff hunk'ları

PR bilinen yüksek riskli bir alanı etkiliyorsa, bunu baştan belirtin (auth, faturalama, migration'lar, eşzamanlılık).

Sonra uygulanabilir çıktılar isteyin. Güçlü bir istek şu örneğe benzer:

• Ne değiştiğini düz metinle özetle.
• Okunabilirlik sorunlarını işaretle (isimlendirme, yapı, sürprizler, tutarsız desenler).
• Doğruluk risklerini belirle (null işleme, hata yolları, bir-eksi-bir, veri şekli uyumsuzlukları).
• Test edilmesi gereken kenar durumlarını ve hata modlarını listele (zaman aşımı, yeniden deneme, boş girdiler, kısmi güncellemeler).
• Eksik testleri ve her bir testin neyi kanıtladığını öner.
• Kısa bir inceleyici kontrol listesi ve merge öncesi sorulacak 5–10 soru üret.

İnsanı kontrolün sahibi yapın: belirsizliği zorunlu kılın. Claude'dan bulguları “diff'ten kesin” veya “doğrulama gerekiyor” olarak etiketlemesini ve her bir endişeyi tetikleyen satırları tam olarak alıntılamasını isteyin.

Promptlamadan önce diff ve bağlamı hazırlayın

Claude, gösterdiğiniz kadardır. Çok büyük bir diff'i hedef veya kısıt belirtmeden yapıştırırsanız, genel tavsiye alırsınız ve gerçek riskleri kaçırırsınız.

Somut bir hedef ve başarı kriteriyle başlayın. Örneğin: “Bu PR login endpoint'ine rate limiting ekliyor ve suistimali azaltmalı. Yanıt şeklini değiştirmemeli. Ortalama gecikmeyi 50 ms altında tutmalı.”

Sonra sadece önemli olanı ekleyin. 20 dosya değiştiyse ama mantığı yalnızca 3 dosya etkiliyorsa, odaklanmanız gerekenler onlar olsun. Bir snippet yanıltıcı olabileceğinden çevreleyen bağlamı ekleyin: fonksiyon imzaları, önemli tipler veya davranışı değiştiren konfigürasyon gibi.

Son olarak test beklentileri hakkında açık olun. Kenar durumları için birim testleri, kritik yol için entegrasyon testi veya manuel UI kontrolleri istiyorsanız belirtin. Testler kasıtlı olarak yoksa nedenini yazın.

İyi çalışan basit bir “bağlam paketi”:

• PR amacı: ne değişiyor, kullanıcı ne görüyor, ne iyileşmeli
• İlgili diff parçaları: yalnızca ana dosyalar, niyeti anlamak için yeterli çevre kodla
• Sert kısıtlar: performans bütçeleri, uyumluluk gereksinimleri, güvenlik/mahremiyet kuralları
• Test beklentileri: nelerin kapsanması gerekir, neler eklendi, nasıl çalıştırılır
• “Değişmemesi gereken” öğeler: açık API sözleşmeleri, veritabanı şeması, UX davranışı, log/audit formatı

Adım adım: tekrarlanabilir bir ön-inceleme akışı

İyi bir Claude Code PR incelemesi sıkı bir döngü şeklinde çalışır: yeterli bağlam verin, yapılandırılmış notlar alın, sonra bunları eylemlere dönüştürün. İnsanların yerini almaz; bir ekip arkadaşının uzun süre okuyup yeniden keşfetmesini gerektirmeden önce basit hataları yakalar.

5 geçişli akış

Her seferinde aynı geçişleri kullanın ki sonuçlar öngörülebilir olsun:

1. Değişikliği sade bir dille açıklayın. Claude'dan PR'in ne yaptığını, hangi dosyaların değiştiğini ve değişikliğin muhtemel amacını özetlemesini isteyin. Basitçe açıklayamıyorsa, PR muhtemelen daha net bir açıklama veya daha küçük bir kapsam gerektirir.
2. Önce doğruluğu kontrol edin. Mantık hataları, bozulmuş varsayımlar ve sessiz davranış değişikliklerine (varsayılanlar, hata işleme, izinler, saat dilimleri, bir-eksi-bir) bakın.
3. Eksik durumları tarayın. Hem kullanıcı hem de üretim gözüyle düşünün: boş girdiler, null'lar, yeniden denemeler, kısmi hatalar, eşzamanlılık, geriye dönük uyumluluk.
4. Okunabilirlik ve sürdürülebilirliği gözden geçirin. Kafa karıştıran isimler, uzun fonksiyonlar, çoğaltılmış mantık, belirsiz yorumlar ve gelecekteki inceleme süresini artıracak küçük refactor fırsatlarını belirtin.
5. İnceleme yorumlarını gösterir şekilde taslak oluşturun. Yorumları dosya bazında gruplayın ve bir fonksiyon adı veya alıntılanmış snippet ekleyin ki insan ilgili yeri hızlıca bulabilsin.

Notları aldıktan sonra bunları kısa bir merge gate'e dönüştürün:

Birleştirme kontrol listesi (kısa tutun):

• Yeni davranışı ve en az bir kenar durumunu kapsayan testler mevcut
• Hatalar tutarlı şekilde ele alınıyor (gerekirse loglanıyor)
• Net açıklaması olmayan kırıcı değişiklik yok veya net bir migration yolu var
• İsimlendirme ve yapı yakın kodla uyumlu
• Riskli parçalar için geri alma planı var

Son olarak, birleştirmeden önce açıklığı zorlayan 3–5 soru isteyin, örneğin “API boş liste döndürürse ne olur?” veya “Bu eşzamanlı isteklerde güvenli mi?” gibi.

Basit bir rubrik kullanın (okunabilirlik, doğruluk, kenar durumları)

Claude, sabit bir mercek verildiğinde en yararlı olur. Bir rubrik yoksa, genellikle ilk gözüne çarpanı (çoğunlukla stil nit'leri) yorumlar ve en riskli sınır durumunu kaçırabilir.

Pratik bir rubrik:

• Okunabilirlik: açık isimler, sade akış, küçük fonksiyonlar, nedenini açıklayan yorumlar, ölü kod veya debug artıkları yok.
• Doğruluk: temel invarianlar korunuyor, hatalar tutarlı ele alınıyor, null/boş güvenli, sınırlar doğru (bir-eksi-bir, yuvarlama).
• Kenar durumları: boş/çok büyük girdiler, eksik opsiyonel alanlar, saat dilimleri ve yaz saati uygulamaları, yeniden denemelerin çift yazma riski, eşzamanlılık yarışları.
• Güvenlik ve gizlilik: izin kontrolleri doğru yerde, kodda/loglarda gizli bilgi yok, loglar token veya hassas yükü sızdırmıyor.
• Uyumluluk ve dağıtım güvenliği: eski istemci ve saklı veriler bozulmaz, migration'lar güvenli, geri alma planı var.

Prompt attığınızda kategori başına bir kısa paragraf ve “en yüksek riskli sorun önce” isteyin. Bu sıralama insanları odaklı tutar.

Yararlı inceleme notları üreten prompt şablonları

Tekrar kullanılabilir bir temel prompt kullanın ki her PR'de çıktı benzer olsun. PR açıklamasını, sonra diff'i yapıştırın. Davranış kullanıcıya yönelikse, beklenen davranışı 1–2 cümleyle ekleyin.

Bir pull request ön-incelemesi yapıyorsun.

Bağlam
- Repo/servis: <isim>
- Değişiklik amacı: <1-2 cümle>
- Kısıtlar: <performans, güvenlik, geriye dönük uyumluluk, vb>

Girdi
- PR açıklaması:
<...>
- Diff (unified diff):
<...>

Çıktı formatı
1) Özet (en fazla 4 madde)
2) Okunabilirlik notları (nits + önerilen yeniden yazımlar)
3) Doğruluk riskleri (ne bozulabilir ve neden)
4) Test edilmesi gereken kenar durumları (spesifik senaryolar)
5) İnceleyici kontrol listesi (5-10 madde)
6) Merge öncesi yazara sorulacak sorular (3-7)

Kurallar
- İlgili diff satırlarını alıntılayarak kanıt göster (dosya + fonksiyon adı ile).
- Emin değilsen, hangi bilgiye ihtiyaç duyduğunu söyle.

Yüksek riskli değişiklikler (auth, ödemeler, izinler, migration'lar) için başarısızlık ve geri alma düşüncesini açıkça ekleyin:

Bu inceleme için ekstra odak:
- Güvenlik/gizlilik riskleri, izin atlama, veri sızıntısı
- Para/hesap doğruluğu (çifte ücretlendirme, idempotentlik)
- Migration güvenliği (kilitler, backfill, aşağı yön uyumluluğu)
- İzleme/alert'ler ve geri alma planı
“Merge engeli” (stop-ship) bölümü döndür ve birleştirmeyi engelleyecek maddeleri listele.

Refactor'lar için “davranış değişikliği yok” kuralını katı tutun:

Bu PR bir refactor. Davranışın aynı kalması beklenir.
- Küçük bile olsa herhangi bir davranış değişikliğini işaretle.
- Korunması gereken invarianları listele.
- Davranışı değiştirebilecek diff hunk'larını tam olarak göster.
- Eşdeğerliği doğrulamak için minimal bir test planı öner.

Hızlı bir tarama istiyorsanız, “200 kelimenin altında cevap ver” gibi limit ekleyin. Derinlik istiyorsanız “10 bulguya kadar nedenleriyle” isteyin.

Çıktıyı inceleyici kontrol listesine dönüştürme

Claude’ın notları, insanların kapatabileceği kısa bir kontrol listesine dönüştürüldüğünde faydalı olur. Diff'i tekrarlamayın. Riskleri ve alınan kararları yakalayın.

Öğeleri iki kovaya ayırın ki tartışma tercih meselelerine dönmesin:

Düzeltilmesi gerekli (merge engeli)

• Doğruluk: beklenen sonuç bir cümlede yazılı ve ticket ile eşleşiyor
• Kenar durumları: null/boş girdiler ve hata yolları açıkça ele alınıyor veya reddediliyor
• Veri güvenliği: yazmalar ve migration'lar mevcut veri ve eski kod için güvenli
• Testler: ana davranışı gösteren en az bir test ve en riskli hata için bir test
• Gözlemlenebilirlik: debug için yeterli log/metric (request id, user id, job id)

İyi-olur (takip maddeleri)

• Okunabilirlik: en kafa karıştıran identifier yeniden adlandırılsın veya kısa bir “neden” yorumu eklensin
• Tutarlılık: hatalar, isimlendirme ve dosya düzeni için mevcut desenlerle eşleş
• Performans: sıcak yolları not edin ve mevcut ölçekte önem taşıyıp taşımadığını belirtin
• Dokümantasyon: yeni bir seçenek/flag eklendiyse inline doküman güncellensin

Ayrıca dağıtım hazırlığını da yakalayın: en güvenli dağıtım sırası, sürüm sonrası neler izlenecek ve değişikliği nasıl geri alırsınız.

Birleştirmeden önce sorulacak sorular

Ön-inceleme, küçük bir netlik sorusu kümesiyle bitmelidir.

Davranış ve doğruluk

• Hangi kullanıcıya görünür davranış değişiyor ve neyin aynı kalması gerekiyor?
• “Davranış değişikliği yok” ise, çıktıların aynı olduğunu gösteren kanıt nedir?
• En olası üretim hatası nedir ve nerede görünür (UI, API, veri)?
• Kod girdiler, sıralama, zaman veya ağ çağrıları hakkında hangi varsayımlara dayanıyor?
• Hataların üzeri kapatılıyor mu yoksa sessiz varsayılanlara mı dönüştürülüyor?

Kenar durumları, testler ve operasyon

• En kötü gerçek girdiler nelerdir (boş, çok büyük, bozuk, tekrar), ve ne olması bekleniyor?
• Hangi yaygın akış bunu iki kez tetikleyebilir (yeniden deneme, çift tıklama, arka plan işler) ve güvenli mi?
• Hangi test ana davranışı kanıtlar, hangi test en riskli kenar durumu kapsar?
• Eksik bir test varsa, yazması mı zor yoksa kod test edilemeyecek kadar mı karmaşık?
• Operasyon ekibinin ihtiyaç duyacağı şeyler: anlamlı loglar, metrikler, alert'ler, konfig varsayılanları ve geri alma adımları?

Eğer bu soruları açıkça cevaplayamıyorsanız, merge'i durdurun ve kapsamı daraltın veya kanıt ekleyin.

Yaygın tuzaklar (ve nasıl kaçınılır)

Çoğu hata süreç kaynaklıdır, model kaynaklı değil.

• Büyük diff'leri odak olmadan atmak. İnceleme isteğini 1–3 riskli alana indirip sadece ilgili hunk'ları ve bağlı oldukları imzaları yapıştırın.
• Niyet ve beklenen davranışı atlamak. Bir hedef olmadan inceleme sürüklenir. İki satır ekleyin: ne değişiyor ve ne değişmemeli.
• Özgüvenli tahminlere inanmak. Kanıt olarak diff'te alıntı zorlayın. Kanıt gösteremiyorsa, hipotez olarak değerlendirin.
• Stilde boğulmak. “Düzeltilmesi gerekli” vs “İyi-olur” deyin ve stil notlarını sınırlayın.
• Takım standartlarını görmezden gelmek. Ekibin konvansiyonları varsa (erken dönüşler, hata tipleri, log formatı), bunları ekleyin.

Örneğin bir PR yeni bir checkout endpoint'i ekliyorsa, tüm servisi yapıştırmayın. Handler, doğrulama, DB yazma ve varsa şema değişikliklerini ekleyin. Sonra: “Amaç: çift ücretlendirmeyi önlemek. Amaç değil: isimlendirme refactor'ı.” Bu, daha az ve doğrulanması kolay yorum getirir.

Gerçekçi bir örnek: küçük bir PR ön-incelemesi

Küçük bir PR: ayarlar ekranına “görünen ad” alanı ekleme. Sunucu tarafında doğrulama ve istemci tarafında UI metni etkiliyor. Mantığı etkileyebilecek yerler var ama yine de küçük.

Yapıştıracağınız diff snippet'leri (ve beklenen davranış ile ilgili 2–3 cümle):

- if len(name) == 0 { return error("name required") }
+ if len(displayName) < 3 { return error("display name too short") }
+ if len(displayName) > 30 { return error("display name too long") }

- <TextInput label="Name" value={name} />
+ <TextInput label="Display name" value={displayName} helperText="Shown on your profile" />

Örnek bulgular:

• Okunabilirlik: “displayName” ile “name” dosyalar arasında karışıyor. Gelecekte zihinsel çeviri gerekmemesi için tek bir terim seçin.
• Doğruluk: Sunucu uzunluk doğrulaması yapıyor ama istemci yapmıyor. Kullanıcı 1–2 karakter yazıp sadece gönderince hata görebilir.
• Kenar durum: Sadece boşluklardan oluşan string'ler len(displayName) kontrolünden geçebilir. Doğrulamadan önce trim edin.

Bunu bir kontrol listesine çevirin:

• İsimlendirme API, veritabanı alanları ve UI etiketlerinde tutarlı olsun.
• İstemci tarafı kontroller sunucu kurallarıyla (min/max, zorunlu) eşleşsin.
• Girdi trimlensin (Unicode/emoji davranışı kabul edilebilir olmalı).
• Hata mesajları sunucu ve istemci arasında net ve uyumlu olsun.

Hızlı kontroller, ölçüm ve sonraki adımlar

Bir Claude Code PR incelemesi şu hızlı kontrollerle bitmeli:

• Davranış: kullanıcı için ne değişiyor ve ne değişmemeli
• Testler: neler kapsanmış, neler eksik, hangi testler flaky olabilir
• Loglar ve hatalar: hatalar açık ve mesajlar anlaşılır mı
• Performans: yeni döngüler, N+1 sorgular, büyük payload'lar, ekstra ağ çağrıları
• Güvenlik: doğrulama, izin kontrolleri, secret'lar, riskli varsayılanlar

Kazancı görmek için 2–4 hafta boyunca iki basit metriği izleyin: inceleme süresi (açılıştan ilk anlamlı yoruma ve açılıştan merge'e kadar) ve yeniden çalışma (inceleme sonrası takip commit'leri veya kaç yorumun kod değişikliği gerektirdiği).

Standartlaştırma mükemmel prompt'tan iyidir. Bir şablon seçin, kısa bir bağlam bloğu (ne değişti, neden, nasıl test edilir) zorunlu kılın ve “tamamlandı” ne demek anlaşın.

Eğer ekibiniz sohbete dayalı geliştirme ile özellikler inşa ediyorsa, aynı iş akışını Koder.ai içinde uygulayabilirsiniz: değişiklikleri oluşturun, kaynak kodunu dışa aktarın, ve sonra PR'e ekleyeceğiniz ön-inceleme kontrol listesini iliştirin ki insan incelemesi en riskli parçalara odaklansın.