Kod inceleme prompt’u nasıl yazılır? Altı kural ve bir şablon

Çoğu kod inceleme prompt’u neden gürültü üretir?

Çoğu kod inceleme prompt’u bir konu listesidir: “Bu kodu incele; hatalara, güvenlik açıklarına, performansa ve okunabilirliğe bak.” Model bu listeye harfiyen uyar ve her başlığın altına bir şeyler yazar. Ortaya uzun, kibar ve çoğu işe yaramayan bir yorum çıkar. Pull request’in yazarı ya hepsini okuyup çoğunu eler ya da hiç okumaz.

Çıktıyı asıl değiştiren, kanıt şartıdır: model gösterebildiğini yazar, gösteremediğini yazmaz. diffox’ta bir pull request’i 17 uzman ajana dağıtıyoruz ve her ajanın talimatı bu şartla başlıyor (nasıl çalıştığı ayrı bir yazıda). Aşağıdaki altı kural o deneyimden ve araçların kendi belgelerinden çıkıyor.

İyi bir prompt’un altı kuralı

1. Kanıt isteyin. Bulgu, hatalı sonucu üreten somut bir girdi ya da durumla birlikte gelsin: “Liste boşken ortalama sıfıra bölünüyor.” Böyle bir senaryo kuramayan model susmalı. Bu tek cümle, “şuna da dikkat edilebilir” türü yorumların çoğunu keser.
2. Satır numarası değil, birebir alıntı isteyin. Modeller satır saymada pek güvenilir değildir; alıntıyı ise dosyada arayıp bulabilirsiniz. Anthropic’in belgesi de aynı tekniği önerir: model iddiasını destekleyen alıntıyı bulamıyorsa iddiayı geri çekmeli (kaynak).
3. Kapsamı bu değişiklikle sınırlayın. İnceleme, pull request’in eklediği ya da değiştirdiği satırlardan çıkan sorunlara bakar. Eski koddaki her kusuru bugünkü yazarın hanesine yazarsanız yorumu kimse okumaz.
4. Zevk meselelerini ve araçların işini dışarıda bırakın. Biçim, adlandırma tercihi, eksik yorum satırı bir inceleme bulgusu değildir; linter’ın ve tip denetleyicinin bildirdiğini modele yeniden yazdırmayın. Codex’in belgesi de aynı şeyi söyler: biçim ve lint denetimlerini CI’a bırakın.
5. Önem derecesini tanımlayın. “Engelleyici” ve “küçük” ne demek, siz yazın: yanlış sonuç, veri kaybı, güvenlik açığı engelleyicidir; yalnızca nadir bir durumda ortaya çıkan ya da yanıltıcı bir isimden ibaret olan sorun küçüktür. Tanım yoksa her bulgu “önemli” çıkar.
6. Çıktının biçimini sabitleyin. Her bulgu aynı alanlarla gelsin: dosya, alıntı, senaryo, yanlış sonuç, önem derecesi, tek satırlık düzeltme. Bulgu yoksa model bunu tek satırda söyleyip dursun; boş bir incelemeyi lafla doldurmasın.

Altı kuralın ortak yanı şu: her biri modelin gerçekten yapabileceği bir kontrolü tarif ediyor. “Dikkatli ol” kontrol edilemez; “alıntı dosyada var mı?” edilir.

Bu şablonu kopyalayıp kendi deponuza uyarlayın

Aşağıdaki prompt altı kuralı tek metinde toplar. İngilizce yazdık, çünkü dört araç da İngilizce talimatları sorunsuz izler; yorumların dilini son satır belirler. Uyarlamanız gereken iki yer var: önem derecesi (“Severity”) tanımı ve “Do not report” listesi.

You are reviewing a pull request. Report only defects that this
change introduces or exposes.

A finding is valid only if you can state all three:
1. the code, quoted word for word from the changed lines;
2. a concrete input or state that reaches that code;
3. the wrong result that follows, and what the right one would be.
If you cannot state all three, do not report it.

Do not report: style, formatting, naming taste, missing comments,
anything a linter or a type checker already reports, or code this
change did not touch.

Severity:
- blocking: wrong result, data loss, security hole, or a crash on
  an ordinary path
- minor: wrong only on a rare path, or a name, comment or test that
  says something the code does not do

For each finding give: file, the quoted code, the scenario, the
wrong result, severity, and a one-line fix.
If you find nothing, write "No findings" and stop.
Write the findings in Turkish.

Şablonu bilerek kısa tuttuk. Claude Code’un belgesine göre uzunluğun bir bedeli var: uzun bir talimat dosyası asıl önemli kuralları sulandırır. Kendi kurallarınızı eklerken her yeni satırın bir bulguyu değiştirip değiştirmediğine bakın.

Hangi araç hangi dosyayı okur?

Prompt’u nereye yazacağınız araca bağlıdır. Aşağıdaki tabloyu dört aracın kendi belgelerinden 15 Ekim 2026 günü derledik.

Kaynak: her aracın kendi belgesi, 15 Ekim 2026.

İki ayrıntı sık gözden kaçıyor. Claude Code’da REVIEW.md dosyasını yalnızca GitHub’daki Code Review hizmeti okur; terminaldeki /code-review okumaz. Copilot ise talimatları pull request’in head dalından, yani değişikliklerin bulunduğu daldan okur. Bu yüzden talimat dosyasını değiştiren bir pull request, kendi incelemesinin kurallarını da değiştirir.

Claude Code’da kendi prompt’unuzu komut hâline getirmek için bir skill yazın: .claude/skills/incele/SKILL.md dosyasına şablonu koyun, başına !`git diff main...HEAD` satırını ekleyin. Bu satır komutu çalıştırır ve çıktısını prompt’a yerleştirir; /incele yazdığınızda model diff’i hazır bulur (skill belgesi).

Deponuza özel kurallar nasıl yazılır?

Şablon işin genel kısmını halleder; asıl fark deponuzun kendi kurallarından gelir. Bunlar her incelemede yeniden söylediğiniz şeylerdir: hangi veri hangi katmanı geçemez, hangi yan etki tehlikelidir, hangi sözleşme bozulamaz.

İyi bir kuralın üç parçası var ve Codex’in belgesi üçünü de sayar: işaretlenecek davranış, neden önemli olduğu ve güvenli yol ya da istisna. En sık unutulan da üçüncüsü: modele doğru yolu söylemezseniz, beklenen davranışı da hata diye işaretler.

• Zayıf: “Veritabanı sorgularına dikkat et.”
• Güçlü: “Her sorgu, çağıranın tenant’ıyla sınırlı olmalı. Güvenli yol: scoped() yardımcı fonksiyonu. İstisna: yönetici raporları.”

Kanıt şartını depo düzeyinde de koyabilirsiniz. Claude Code’un belgesindeki örnek: kodun nasıl davrandığına dair bir iddia isimden tahmin yürütmemeli, kaynakta dosya ve satır göstermeli. Bu tek kural, yazarı boşuna bir tur uğraştıran yanlış alarmları azaltır.

Tek prompt yetmezse ne yapmalı?

Tek bir prompt’a güvenlik, eşzamanlılık, testler ve kural uyumunu birlikte sorduğunuzda model dikkatini böler ve her birinden biraz bulur. Büyük değişikliklerde işi bölmek daha iyi sonuç verir: her prompt tek bir şeyi arar ve aynı kanıt şartına uyar.

İkinci adım, modelin söylediğini kontrol etmek. Model ikna edici ama yanlış şeyler yazabilir: dosyada olmayan bir satırı alıntılar ya da değişikliğin dokunmadığı koda itiraz eder. Alıntı istediğiniz için bunu bir programla kontrol edebilirsiniz: alıntı gerçekten o dosyada mı, değişen satırlardan biri mi? Claude Code’un Code Review belgesi de aynı yöntemi anlatır: her ajan ayrı bir sorun sınıfına bakar, ardından bir doğrulama adımı yanlış alarmları eler.

diffox’ta bu iki adımı ürün kendisi yapar: takımdaki 17 uzman ajanın her biri tek bir şeyi arar ve bulduğunu koddan birebir alıntıyla gösterir; alıntıyı model değil, kod kontrol eder. Ajanlar ayrıca deponuzun kök kural dosyasındaki (AGENTS.md ya da CLAUDE.md) zorunluluk bildiren cümleleri inceleme kuralı olarak alır.

Kuralı gerçek bir pull request’te deneyin

Bir prompt’un iyi olup olmadığını okuyarak anlayamazsınız. En pratik tavsiye Codex’in belgesinde: deponuzu iyi yansıtan bir pull request açın, inceleme isteyin, gelen bulgulara göre kuralları düzeltin; gürültü üreten talimatı daraltın ya da silin.

• Kuralın yakalaması gereken bir ihlali içeren bir değişiklikte deneyin: yakalıyor mu?
• Güvenli yolu kullanan bir değişiklikte deneyin: susuyor mu?
• Konuyla ilgisiz bir değişiklikte deneyin: yine susuyor mu?

Aynı pull request’i iki kez incelettiğinizde iki farklı sonuç alabilirsiniz; tek bir denemeyi sonuç saymayın. Kuralı eklemeden önceki ve sonraki sonuçları aynı birkaç pull request üzerinde karşılaştırın.