Kod İncelemesi Becerisi

Bu beceri, bu depo içindeki otomasyonlu ve etkileşimli kod incelemeleri için kanonik rehberdir. LLM inceleyicileri (CI botları ve yerel ajanlar) için yazılmıştır.

Hızlı Başlangıç

• PR açıklamasını okuyun ve .github/pull_request_template.md ile eşleştiğinden emin olun.
• Diff'i invaryanlar, doğruluk ve performans açısından kritik noktalar odağında gözden geçirin.
• Komutları yerel olarak çalıştırabileceğiniz durumlarda hedefli doğrulamayı tercih edin:
  • ato dev test --llm -k <area> (hızlı filtre)
  • ato dev compile (Zig/bindings değiştiyse)
  • ato dev flags (davranış ConfigFlags'e bağlıysa)
• Hata/regresyon özetlerinde HTML yerine artifacts/test-report.json tercih edin.

Önceliklendirilecek Konular (Sırayla)

1. Doğruluk + invaryanlar

   • Değiştirilen kodun koruması gereken invaryanları tanımlayın ve bunları uygulayan kodu kontrol edin.
   • Kodda veya testlerde bir invaryant bulamazsanız, bunu "eksik invaryant kapsamı" olarak işaretleyin.

2. Performans / ölçeklenebilirlik

   • Bu dal hız ve bakım kolaylığını önceliklendirir; istemeden oluşan O(n^2) geçişleri, tekrarlanan grafik geçişlerini, aşırı ayırmaları veya hot path'lerdeki debug günlüğünü izleyin.
   • Zig/Python sınırı değişiklikleri özellikle hassastır (sahiplik, yaşam döngüsü, deinit).

3. Bakım kolaylığı

   • Küçük, iyi adlandırılmış birimler ve net sınırları tercih edin (derleyici vs grafik vs çözücü vs kütüphane).
   • Repo zaten bu deseni kullanmıyorsa yeni "mini framework" eklemeyin.

4. Test kapsamı

   • Davranış değiştiyse, bir test gerektirin (veya test edilememesi için güçlü bir neden).
   • Modülün yakınına hedefli testler tercih edin; gerekli olmadıkça geniş uçtan uca testlerden kaçının.

Depoya Özgü İnceleme Noktaları

• Geliştirici iş akışı + raporlar: ato dev test --llm artifacts/test-report.json ve artifacts/test-report.llm.json yazarken, isteğe bağlı olarak artifacts/test-report.html yazar (bkz. test/runner/main.py).
• ConfigFlags: ato dev flags aracılığıyla envanter; el ile tutulan docslar yerine kod odaklı keşfi tercih edin.
• Grafik/fabll yeniden tasarımı: gözden geçirdiğiniz alan için AGENTS.md ve ilgili .claude/skills/* doçlarına bakın.
• Çözücü invaryanları: src/faebryk/core/solver/README.md + src/faebryk/core/solver/symbolic/invariants.py.

---

PR İnceleme Çıktısı Biçimi

CI inceleme yorumu yazarken, tam olarak bu yapıyı ve başka hiçbir şeyi üretin. Amaç, bir insanın saniyeler içinde bakabileceği minimal ve taranabilir bir özettir.

İncelemenin tek bir güncellenmiş yorumda kalması için gh pr comment --edit-last --create-if-none kullanın.

Şablon

## <niyetin tek satırlık özeti>

| Metrik | Puan |
|--------|------|
| **Etki** | X/10 |
| **Test kapsamı** | X/10 |

<details>
<summary>🔴 Yüksek önem düzeyindeki sorunlar (N bulundu)</summary>

### 1. <kısa başlık>
<details>
<file:line — açıklama>
</details>

</details>

Etki Puanlaması Nasıl Yapılır (0–10)

Etki, bir insanın bu PR'ı manuel olarak gözden geçirmesi ne kadar önemli olduğunu ölçer. Düşünün: "bu PR'ı gözden geçirmeyeceğim olsaydı, en kötü ne olabilirdi?"

Puan	Anlam	Örnekler
0–1	No-op, yazım hatası düzeltme, yalnızca yorum, CI konfigürasyonu tweeti	Bir README'deki yazım hatasını düzeltme, versiyon pini yükseltme
2–3	Düşük risk, kullanıcılar üzerinde davranışsal etkisi olmayan izole değişiklik	İç değişkeni yeniden adlandırma, günlük satırı ekleme
4–5	Normal özellik veya hata düzeltmesi, sınırlı etki alanı	Yeni bir CLI bayrağı ekleme, ayrıştırıcı kenar durumunu düzeltme
6–7	Paylaşılan altyapıya dokunma, genel API yüzeyini değiştirme veya birden fazla modülü etkileme	Derleyici geçişini yeniden düzenleme, grafik geçiş mantığını değiştirme
8–9	Yüksek risk: API/ABI değişikliği, güvenliğe duyarlı, eşzamanlılık/yaşam döngüsü değişiklikleri, modül sınırları arasında büyük yeniden düzenleme	Zig↔Python sahiplik semantiğini değiştirme, çözücü kısıt yayılımını değiştirme
10	Kritik: veri kaybı riski, kimlik doğrulama baypası veya hot path'te sessiz doğruluk regressyonu	Bağlayıcıda güvenlik kontrolünü kaldırma, deinit sırasını değiştirme

Emin değilseniz, yukarı yuvarlayın — aşırı işaretlemek bir şeyi kaçırmaktan daha ucuzdur.

Test Kapsamı Puanlaması Nasıl Yapılır (0–10)

Test kapsamı, değiştirilen davranışın mevcut veya yeni testler tarafından ne kadar iyi alıştırıldığını ölçer. Hem doğrudan test kapsamını HEM DE değiştirilen kodun geçişsel olarak test edilen bir hot path'te oturması durumunu göz önünde bulundurun.

Puan	Anlam	Örnekler
0–1	Hiçbir test bu kod yolunu doğrudan veya geçişsel olarak dokunmaz	Hiçbir test eklenmemiş yeni modül
2–3	Bazı geçişsel kapsamlar ancak değiştirilen davranış için doğrudan testler yoktur	Test edilen koddan çağrılan yardımcı işlev, ancak belirli yeni dal alıştırılmamıştır
4–5	Kısmi kapsamı: bazı durumlar test edilmiş, diğerleri değil	Yeni işlevin mutlu yolu testi vardır ancak kenar durum veya hata yolu testleri yoktur
6–7	İyi kapsamı: çoğu dal alıştırılmıştır, veya değişiklik çok sayıda entegrasyon testinin geçtiği bir çok hot path'tedir	Grafik geçiş işlevini değiştirme (her derleme testi bunu alıştırır)
8–9	Güçlü kapsamı: adanmış testler artı değiştirilen davranış için entegrasyon kapsamı	Adanmış testleri olan yeni çözücü kuralı VE mevcut uçtan uca derlemelerde çalışır
10	Kapsamlı veya önemsiz derecede güvenli: değişiklik tamamen mekanikse, veya her dal test edilmişse	Değişkeni yeniden adlandırma (önemsiz derecede güvenli), veya %100 dal kapsamına sahip yeni işlev

Davranış değiştiği halde test eklenmemiş veya güncellenmediyse, geçişsel kapsamadan bağımsız olarak puan ≤5 olmalıdır.

Yüksek Önem Düzeyinde Saymak Ne İçerir

Yalnızca bu kategorilerdeki sorunları işaretleyin — diğer her şey PR yorumu için gürültüdür:

• Hatalar: mantık hataları, kenar durumu, null/None referansı, use-after-free, yanlış dönüş değeri, yarış durumu
• Performans regressyonları: O(n²) mümkünse O(n), hot loop'larda gereksiz ayırmalar, tekrarlanan grafik geçişleri, önceki kodun sahip olduğu önbelleği eksik
• API/ABI uyumluluğu kırmaları: genel sembolü kaldırma veya yeniden adlandırma, aşağı akış kodunun bağlı olduğu işlev imzasını değiştirme, serileştirme biçimini göç olmadan değiştirme
• Kullanılabilirlik regressyonları: mevcut bir iş akışını kırma, bir özelliği yeterlendirme olmadan kaldırma, varsayılan davranışı sessizce değiştirme
• Anlaşılması zor kod hakkında eksik doçlar: değiştirilen kod açık değilse (karmaşık algoritma, ince invaryant, hileli yaşam döngüsü yönetimi) ve hiçbir açıklayan yorumu yoksa, bunu işaretleyin — ancak yalnızca gerçekten kafa karıştırıcı kod için, kendi kendini açıklayan değişiklikler için değil

Sıfır sorun bulunursa, detaylar bloğunun içinde "Hiçbiri" yazın. Stil nitleri veya nice-to-have'lerle doldurmayın.

Kurallar

• Özet satırı ≤120 karakter olmalı ve PR'ın amacını/niyetini açıklamalıdır.
• Her yüksek önem düzeyindeki sorun spesifik bir file:line referansı olmalı ve eylem alınabilir olmalıdır.
• Stil nitleri, nice-to-have'leri veya düşük önem düzeyindeki önerileri PR yorumuna EKLEMEYIN.
• Bütün yorumu mümkün olduğunca kısa tutun. Kısa olmak bir özelliktir.

---

Etkileşimli İnceleme (CI Olmayan)

Etkileşimli olarak gözden geçirirken (CI'da değil), daha konuşkan olabilirsiniz, ancak yine de her önemsiz olmayan iddianın temelini diff veya bir repo yoluna dayandırın (dosya + sembolü açıkça belirtin).

Geri bildirimi şu şekilde ayırın:

• Düzeltilmesi gereken (doğruluk/güvenlik/regresyon riskleri)
• Düzeltilmesi gereken (bakım kolaylığı/perf iyileştirmeleri)
• Hoş olabilir (stil/ergonomi)

Eylem alınabilir önerileri tercih edin (ne değiştirecek + neden + nerede). Emin değilseniz, somut bir soru sorun ve belirsiz koda işaret edin.