diffox’un mimarisi: 17 uzman ajan, dört aşama, tek inceleme
diffox, yapay zekâ kod incelemesini 17 uzman ajana böler. Her bulgu koddan alıntıyla gelir; alıntıyı model değil, kod kontrol eder.
Özet. diffox, GitHub’daki pull request’leri inceleyen bir yapay zekâ kod inceleme aracıdır. Her inceleme dört aşamadan geçer; bu yazı her aşamada ne olduğunu ve nedenini anlatıyor. Sonuçları ilk iki yazıda ölçtük: diffox ultra, Martian benchmark’ında 23 araç arasında birinci; bir diffox incelemesinin ücreti $0,41.
- Bağlam ve yönlendirme. diffox değişikliği, dosyaların önceki ve sonraki hâlini ve yazdığınız kuralları bir araya getirir. Değişikliğin türü ve riski, onu hangi uzman ajanların okuyacağını belirler.
- Uzman incelemesi. Takımda 17 uzman ajan var. Her biri tek bir şeyi arar ve bulduğunu koddan birebir alıntıyla gösterir.
- Kanıt kontrolleri. Her bulguyu model değil, kod kontrol eder. Alıntılanan kod gerçekten o dosyada mı? Bulgu, bu pull request’in değiştirdiği bir yerle mi ilgili? Aynı sorun iki kez mi yazılmış?
- Seçim ve yayın. Her bulgunun bir sınıfı var: Kritik, Uyarı ya da Öneri. Pull request’e düzeltmeniz gerekenler yazılır: kritik bulgular ve uyarılar. Öneriler kaybolmaz, Bulgular sayfasında bekler. İnceleme merge’i hiçbir zaman engellemez.
Bir inceleme nasıl işler?
Bir değişikliği incelemenin en kısa yolu, bir modele “bunda hata var mı?” diye sormaktır. diffox bunu yapmaz. Aynı değişikliği ayrı uzman ajanlara okutur: biri mantık hatalarına bakar, biri eşzamanlılığa, biri testin gerçekten bir şeyi sınayıp sınamadığına. Her ajanın işi dar ve net tanımlıdır. Ardından iki adım daha gelir. Kontroller, bulguyu modelin sözüne değil dosyanın kendisine bağlar. Seçim de hangi bulguların yazılacağına karar verir.
Bu yapının sonuçlarını ilk yazıda ölçtük: Martian’ın 50 pull request’lik kıyaslamasında diffox ultra 158 bilinen hatanın 119’unu, diffox 106’sını yakaladı. Kaça mal olduğu ikinci yazıda. Aşağıda dört aşamayı sırayla anlatıyoruz.
Ajanlar neyi görür, hangileri çalışır?
İnceleme siz istemeden başlar: pull request açıldığında ve her yeni push’ta. diffox önce pull request’e incelemenin başladığını söyleyen bir yorum yazar; inceleme bitince aynı yorum sonuca dönüşür. Uzman ajanlar değişikliği görmeden önce iki soru cevaplanır: Önlerine ne konacak? Hangileri çağrılacak?
Dört parçanın her biri ayrı bir soruya cevap verir. Diff neyin değiştiğini söyler. Dosyaların önceki ve sonraki hâli, değişikliğin nereye oturduğunu gösterir. Başlık, açıklama ve commit mesajları ne yapılmak istendiğini anlatır. Deponuzda AGENTS.md ya da CLAUDE.md dosyası varsa, o da ekibinizin hangi kurallara uyduğunu söyler.
Kural dosyası pull request’in kendi dalından değil, birleşeceği daldan okunur. Böylece bir pull request, kendi incelemesinin kurallarını değiştiremez; kural dosyasındaki bir değişiklik merge edildikten sonra geçerli olur. Lock dosyaları, vendor/ ve node_modules/ gibi dışarıdan gelen kod ve minify edilmiş dosyalar incelenmez.
Sonra yönlendirme gelir. diffox değişikliğin türünü belirler (hata düzeltmesi, yeni özellik, refactoring, migration, test…) ve riskine bakar: kaç dosyaya dokunuyor, başka dosyaları etkiliyor mu, yanında test var mı. Ajanların bir kısmı her değişikliği okur; bir kısmı yalnız konusu geçtiğinde çalışır. Hiçbir satır silinmediyse, kaldırılan davranışı arayan ajana iş düşmez. Hiçbir teste dokunulmadıysa, boş testleri arayan ajana da.
Aynı pull request’e yeni bir push geldiğinde diffox yalnız yeni değişikliği okur.
Her uzman ajan tek bir şeyi arar
İkinci aşamada değişikliği uzman ajanlar okur. Takımda 17 ajan var; aradıkları şeye göre iki türe ayrılırlar.
12 ajan hata arar: çalıştığında yanlış sonuç veren kod. 5 ajan çelişki arar: kodla yanındaki yorumun, testin ya da belgenin birbirini tutmadığı yerler. Her ajanın kendi talimatı vardır; hepsi aynı değişikliği ve aynı bağlamı okur.
Bir bulgunun sayılması için üç şey söylemesi gerekir: iddiasını, hangi durumda neyin yanlış çıkacağını ve iddianın dayandığı kodu, birebir kopyalanmış bir alıntıyla. Çelişki bulgusunda iki alıntı olur: kod ve onunla çelişen metin. Bunlardan biri eksikse bulgu sayılmaz.
Ajanlar satır numarası vermez. Dil modelleri satır saymakta güvenilir değildir; bu yüzden diffox modelden satır numarasını değil alıntıyı ister, satırı da alıntıyı dosyada arayarak kendisi bulur. Böylece bulgunun doğru satırın altına düşmesi, modelin ne dediğine bağlı olmaz.
Uzman ajanların yanında kural tabanlı dedektörler de çalışır. Bunlar model kullanmaz; kesin kurallarla arar: koda sızmış bir kimlik bilgisi, aynı sınıfta iki kez tanımlanmış bir metot, hiçbir zaman ulaşılamayan bir dal.
Takımın tamamı ve her ajanın aradığı şey:
| Ajan | Tür | Ne arar |
|---|---|---|
| ➗ Logic | Hata | Off-by-one hatalarını, sınır koşullarını, ters çevrilmiş koşulları, yanlış operatörleri ve çiğnenen fonksiyon sözleşmelerini arar. |
| ⭕ Null Path | Hata | Yok olabilecek bir değerin varmış gibi okunduğu yerleri arar: bir şey tutuyormuş gibi kullanılan None, null ya da boş sonuç. |
| 🔀 Race | Hata | Yarış durumlarını, deadlock'ları, atomik olmayan oku-değiştir-yaz işlemlerini, korumasız paylaşılan durumu ve kilit sırası hatalarını arar. |
| 🔇 Silent Failure | Hata | Yutulan exception'ları, fazla geniş catch bloklarını, yok sayılan dönüş değerlerini ve hatayı saklayan sahte fallback'leri arar. |
| 💾 Data Integrity | Hata | Şema uyuşmazlıklarını, geriye uyumsuz migration'ları, kaybolan yazmaları ve idempotent olmayan işlemleri arar. |
| 🔓 Security | Hata | Injection'ı, bozuk kimlik doğrulama ve yetkilendirmeyi, sızan sırları, SSRF'i ve güvensiz deserialization ya da dosya yolu işlemeyi arar. |
| 💥 Blast Radius | Hata | Kırılan çağıran kodu arar: imzası ya da dönüş tipi değişip başka dosyaları bozan fonksiyonlar ve API'ler. |
| 🐛 Regression | Hata | Bu dosyalarda daha önce düzeltilmiş hata kalıplarının geri gelmesini arar. |
| 🥅 Safety Net | Hata | Değişiklikle testler arasındaki uyumsuzluğu arar: bir testin doğruladığı davranışı, testi güncellemeden değiştiren bir diff. |
| 🔥 Hot Path | Hata | N+1 sorgularını, sık çalışan kodda gereksiz bellek ayırmayı ve algoritmik yavaşlamaları arar. |
| 🏷️ Naming | Hata | Yalnızca kanıtlanabilir dört durumu arar: aynı diff'teki benzerlerine göre yanlış yazılmış bir tanımlayıcı, aynı anahtarın iki ayrı yazılışı, yanlış şeyi adlandıran bir etiket ve hiç çalıştırmadığı şeyin adını taşıyan test. |
| 📐 House Rules | Hata | Reponun kendi yazdığı inceleme kurallarını (AGENTS.md ya da CLAUDE.md, varsa) çiğneyen satırları bu diff'te arar. |
| 💬 Broken Promise | Çelişki | Kodun tutmadığı bir söz veren metni arar: kodun yapmadığı bir şeyi söyleyen yorum, docstring ya da README. |
| 🪦 Dead Code | Çelişki | Etkisi gözlenemeyen kodu arar: bu değişiklikten sonra ulaşılamayan ya da tekrarlanan kod. |
| 📜 Stale Contract | Çelişki | Burada değişen bir tanımı, başka bir yer hâlâ eski haliyle kullanıyorsa yakalar. |
| 🗑️ Lost Behaviour | Çelişki | Bu değişikliğin yerine bir şey koymadan sildiği davranışı arar ve ona hâlâ bağlı olan var mı diye sorar. |
| 📭 Empty Test | Çelişki | İddia ettiği şeyi gerçekten çalıştırmayan testi arar: kod ne yaparsa yapsın geçecek bir test. |
Her bulgunun yorumunda, onu bulan ajanın işareti ve adı yer alır; örneğin ➗ Logic Agent.
Bir bulgu kodla nasıl kontrol edilir?
Bir dil modeli ikna edici ama yanlış bir şey yazabilir: dosyada olmayan bir satırı alıntılar, bu pull request’in dokunmadığı bir koda itiraz eder, aynı sorunu üç ayrı cümleyle üç kez söyler. Üçüncü aşamanın işi, her bulguyu modelin sözüne değil dosyanın kendisine bağlamaktır.
Bu kontroller bir model çağrısı değil, düz koddur: aynı girdiye her seferinde aynı cevabı verir.
- Anchor Verifier. Bulgunun alıntısı dosyada aranır. Bulunamayan alıntının gösterebileceği bir satır yoktur. Bulunan satır bu pull request’in değiştirdiği yerde değilse bulgu kapsam dışıdır.
- Second Witness. Aynı yere aynı itirazı yapan bulgular tek bulguda birleştirilir; aynı sorun size iki kez yazılmaz. Birden çok kaynak aynı yeri gösteriyorsa, bu bulgunun lehine sayılır.
- Verbatim Matcher. Çelişki bulgusunun ikinci alıntısı da kelimesi kelimesine aranır: değişiklikte, dosyalarda, pull request’in açıklamasında, commit mesajlarında ve kural dosyanızda. Model, bir yorumun söylemediği bir şeyi söylediğini öne sürerse burada ortaya çıkar.
Bir kontrol daha var: bir değerin boş olabileceğini söyleyen bulgu, o değerin tipi ya da birkaç satır yukarıdaki bir kontrol bunu zaten dışlıyorsa çürütülür.
Hangi bulgular yazılır?
Kontrollerden sonra elde bir aday listesi vardır. Dördüncü aşama, bu adaylardan hangilerinin pull request’e yazılacağına karar verir.
Attention Ranker her aday için tek bir soruya cevap verir: bu bulgunun gerçek bir hata olma ihtimali ne kadar? Puana şunlar girer: bulgunun ciddiyeti ve türü, kanıt kontrollerinin sonucu ve aynı yeri başka bulguların da gösterip göstermediği. Yakın satırlara düşen bulgulardan yalnız en güçlüsü yazılır.
Pull request’te yalnız düzeltilmesi gerekenleri görürsünüz: kritik bulgular ve uyarılar. Öneriler Bulgular sayfasında bekler; bunun için bir ayar yapmanız gerekmez.
Aşağıdaki sayıları aynı kıyaslamada üç duyarlılık ayarıyla ölçtük. Bu ayar bir puan eşiğiydi. Yüksek en çok hatayı yakaladı. Orta ve Düşük eşiği yükseltti: diffox daha az bulgu yazdı, yazdıklarından da daha emindi.
| Duyarlılık | diffox | diffox ultra | ||
|---|---|---|---|---|
| Gerçek hata | Yanlış alarm | Gerçek hata | Yanlış alarm | |
| Yüksek | 106 | 132 | 119 | 144 |
| Orta | 89 | 55 | 98 | 51 |
| Düşük | 59 | 19 | 70 | 19 |
Martian’ın kıyaslaması: 50 pull request, 158 bilinen hata, hakem Claude Opus 4.5. Yüksek duyarlılık: herkese açık koşumuz, 7 Ekim 2026. Orta ve Düşük: aynı 50 pull request’teki iç ölçümümüz, diffox ultra için 5, diffox için 2 koşunun ortalaması.
Pull request’e yazılmayan bulgular kaybolmaz: 30 gün boyunca konsoldaki Bulgular sayfanızda bekler, istediğinizi oradan yayımlayabilirsiniz.
Yayın iki parçadan oluşur: pull request’e tek bir özet yorumu ve her bulgu için, ilgili satırın tam altında bir yorum. Düzeltilebilecek bir bulguda, GitHub’ın tek tıkla uyguladığı bir düzeltme önerisi olur; commit sizin adınızla atılır. Başlıklar ve düzeltme önerileri seçimden sonra, yalnız yazılacak bulgular için üretilir. İnceleme ekibinizin dilinde gelir. Özetin son satırında o incelemenin ücreti, süresi ve okuduğu commit yazar.
diffox’un pull request’teki durumu hiçbir zaman kırmızıya dönmez: merge kararı ekibinizindir. Yorumlara verdiğiniz 👍 ve 👎 ile diffox sizi ve deponuzu daha iyi tanır; incelemeleri zamanla ekibinize daha çok uyar.
diffox ultra neyi farklı yapar?
diffox ultra aynı dört aşamadan geçer; fark ikinci ve dördüncü aşamadadır. Değişikliği iki ayrı model okur; her biri baştan sona ayrı bir inceleme yapar. İki inceleme yan yana çalışır ve tek inceleme olarak yayımlanır. Seçim adımında üçüncü, küçük bir karar modeli de çalışır: metin yazmaz, her bulgu hakkında evet/hayır sorularına cevap verir. Seçim, iki incelemenin bulgularını bu cevaplarla birlikte puanlar. İki model aynı yeri gösteriyorsa, bu bulgunun lehine sayılır. Seçimden sonra karar modeli, aynı kök nedene giden bulguları bulur ve tek bulguya indirir.
Sonuç ilk iki yazıda: diffox ultra 158 bilinen hatanın 119’unu yakaladı, diffox 106’sını; diffox ultra’nın incelemesi ortalama $1,64, diffox’unki $0,41.
Sıkça sorulan sorular
diffox neden uzman ajanlar kullanıyor?
“Bunda hata var mı?” sorusu geniştir; cevabı da öyle olur. Her uzman ajan tek bir şeyi arar ve bulduğunu koddan alıntıyla göstermek zorundadır. Böylece her bulgunun hangi ajandan geldiği bellidir.
Kendi inceleme kurallarımı verebilir miyim?
Evet. Deponuzun kökündeki AGENTS.md ya da CLAUDE.md dosyasına yazdığınız kurallar her incelemede okunur ve bu kurallara uymayan satırları ayrı bir ajan arar. Kurallar pull request’in birleşeceği daldan okunur; kural dosyasını değiştiren bir pull request, merge edildikten sonra geçerli olur.
👍 ve 👎 vermek ne işe yarar?
Verdiğiniz her tepkiyle diffox sizi ve deponuzu daha iyi tanır: sizin için neyin önemli, neyin gürültü olduğunu öğrenir. İncelemeleri zamanla ekibinize daha çok uyar.
diffox merge’i engeller mi?
Hayır. diffox’un pull request’teki durumu hiçbir zaman kırmızıya dönmez ve zorunlu bir kontrol değildir; ekibiniz ne zaman isterse merge eder.
Her push’ta pull request’in tamamı yeniden mi incelenir?
Hayır. diffox her push’u kendiliğinden inceler ama yalnız yeni değişikliği okur. İlk 5 push’tan sonra siz istediğinizde inceler; bu sayıyı konsoldan değiştirebilirsiniz.
Öneriler neden pull request’e yazılmıyor?
Ölçümlerimizde önerileri de yazmak, pull request’teki yorumları çoğalttı ve gerçek hataların payını düşürdü. Bu yüzden pull request’e kritik bulgular ve uyarılar yazılır. Öneriler kaybolmaz: Bulgular sayfasında 30 gün bekler, istediğinizi oradan yayımlarsınız.
diffox kodumu saklar mı?
Hayır. diffox incelediği kodun kopyasını tutmaz; deponun kopyası inceleme bitince silinir. Hangi hizmetlerin kullanıldığı gizlilik sayfamızda yazar.
Devamı: karar modeli
Dördüncü yazıda diffox ultra’nın o zaman dördüncü aşamada kullandığı karar modelini ve ölçümlerimizden çıkan kuralı anlattık: Jev’i kod incelemede iki iş için nasıl kullanıyoruz.