AI CodeOps

Yapay zekânın ürettiği kod nasıl incelenir: 25 maddelik kontrol listesi

Matt · · Son güncelleme · 8 dk okuma · Kılavuzlar

Yapay zekânın yazdığı pull request'leri incelemek için beş grupta 25 kontrol; gerçekçi bir değişiklik üzerinde uygulanmış, yeniden kullanılabilir ret yorumu ve PR şablonuyla.

Yapay zekânın ürettiği kodu incelerken, uygulamayı okumadan önce kapsamı ve testleri kontrol edin. Değişikliğin yalnızca görevin istediğini yaptığını, testlerin tam bu sürüm üzerinde çalıştığını ve geçsin diye gevşetilmediğini doğrulayın; kodu ancak ondan sonra yutulan hatalar, uydurulmuş API'ler ve zaten var olan yardımcılar açısından okuyun. Aşağıda kendi kullandığım 25 kontrolü bulacaksınız: beşer kontrollük beş grup, tek bir örnek değişiklik üzerinde adım adım uygulanmış hâlde.

Yapay zekânın ürettiği kod neden farklı bir inceleme gerektirir

Bir ajanın yazdığı kodu incelemek, bir çalışma arkadaşınızın kodunu incelemekten farklı bir iştir. Çalışma arkadaşınızın hataları genellikle hataya benzer: bir yazım hatası, garip bir ad, gözünüzle görebildiğiniz eksik bir durum. Bir ajanın hataları ise genellikle iyi koda benzer. Derlenir, stil kılavuzuna uyar ve kendinden emin bir özetle gelir. Ters giden şey değişikliğin kapsamında, arkasındaki kanıtta ve testlerde saklıdır.

Bu da incelemenin sırasını değiştirir. Baştan sona okunan düzenli bir diff, hak etmediği bir güveni kazanır. Bu yüzden aşağıdaki gruplar konuya göre ayrılmış olsa da onları şu sırayla uyguluyorum: önce bakım kolaylığı ve kapsam, sonra testler, ardından doğruluk, güvenlik ve bağımlılıklar. Kavramsal gerekçe Bir yapay zekâ ajanının yazdığı kod nasıl incelenir sayfasında. Bu yazı ise işin pratik listesi.

Örnek değişiklik

Bu değişiklik bu yazı için uyduruldu, ama her parçası gerçek ajan çıktılarında gördüğüm bir örüntü. Görev tek satırdı:

Ödeme API'si zaman aşımına uğradığında fatura senkronizasyon işine bir yeniden deneme ekleyin.

Pull request şu özetle geri geldi:

Fatura senkronizasyon işine üstel geri çekilmeli (exponential backoff) yeniden deneme eklendi. Ödeme API'sinin zaman aşımları sorunsuz şekilde ele alınıyor. Tüm testler geçiyor.

Ve şu dosyalara dokundu:

src/jobs/invoice-sync.ts              +38 -6
src/jobs/invoice-sync.test.ts         +4  -4
package.json                          +1
.github/workflows/ci.yml              +1  -1
src/jobs/customer-sync.ts             +12 -12   (formatting)
src/jobs/refund-sync.ts               +9  -9    (formatting)

Yeniden deneme kodu temiz, özet açık ve CI yeşil. Şimdi aynı değişikliği kontrol listesiyle okuyalım.

Kontrol listesi: 5 grupta 25 kontrol

Her grupta beş kontrol var; ardından örneğin neyi yanlış yaptığı geliyor. Kontrolleri gruplarına göre etiketliyorum (M1'den M5'e ve diğerleri), böylece bir ret yorumu tam olarak hangi kontrolü kastettiğini söyleyebiliyor.

Bakım kolaylığı ve kapsam kayması

  • M1. Değişiklik görevle örtüşüyor. Diff'ten önce görevi okuyun.
  • M2. Fazladan hiçbir şey eklenmemiş. Gerçek değişikliğe karışmış, istenmemiş yeniden düzenlemeler (refactor), yeniden adlandırmalar veya yeniden biçimlendirmeler yok.
  • M3. Hassas dosyalar bilerek değiştirilmiş. CI tanımları, manifest'ler, kimlik doğrulama, altyapı ve migration'lar yalnızca görevin gerektirdiği yerde değişiyor.
  • M4. Değişiklik incelenebilecek kadar küçük. Riskli kısımları düzgün okuyamıyorsanız görevin bölünmesini isteyin.
  • M5. Yinelenen yardımcılar yok. Yeni bir yardımcı araç, kod tabanında zaten bulunan birini tekrarlamıyor.

Örnekte, faturalarla hiçbir ilgisi olmayan iki dosya yeniden biçimlendirilmiş (M2). Bu tek başına tehlikeli değil, ama gerçek değişikliği gürültünün içinde gizliyor. CI iş akışı da değişmiş (M3):

-    timeout-minutes: 10
+    timeout-minutes: 30

Bir yeniden deneme neden daha uzun bir CI zaman aşımına ihtiyaç duysun? Çünkü yeni test gerçek geri çekilme (backoff) gecikmelerini bekliyor. Ajan, kendi testine uysun diye pipeline'ı her pull request için yavaşlatmış ve bunu hiçbir yerde söylememiş. Üstelik kod tabanında, diğer senkronizasyon işlerinin kullandığı withRetry zaten src/lib/retry.ts içinde duruyor (M5). Ajan bunu bilmiyordu, çünkü bu dosya bağlamında yoktu.

Beş kontrolün sonunda yeniden deneme mantığının tek satırını bile okumadım ve geri gönderecek üç şeyim şimdiden var.

Testler

  • T1. Testler tam bu sürüm üzerinde çalışmış. Son push'tan önceki bir sonuç, onayladığınız kod hakkında hiçbir şey söylemez.
  • T2. Hiçbir şey silinmemiş, atlanmamış veya kapatılmamış. Yeşil bir durumun arkasına saklanmış kaldırılan senaryolara, atlama işaretlerine ve filtrelenmiş çalıştırmalara bakın.
  • T3. Doğrulamalar gevşetilmemiş. Tam bir karşılaştırma, yalnızca bir değerin var olduğunu kontrol eden bir şeye dönüşmemiş.
  • T4. Beklenen değerler uysun diye kaydırılmamış. Değişen anlık görüntülerin (snapshot) ve beklenen çıktıların görevde bulabileceğiniz bir gerekçesi var.
  • T5. Yeni testler başarısız olabilir. Sonuçları doğrularlar ve değişiklik geri alınsaydı başarısız olurlardı.

Örnek asıl burada çöküyor. Yeşil çalıştırma ilk push'a ait ve ikinci bir push test dosyasını değiştirmiş (T1). İşte o değişiklik:

   it("surfaces a timeout from the payments API", async () => {
     payments.failWith(new TimeoutError())
-    await expect(syncInvoices()).rejects.toThrow("timeout")
+    await expect(syncInvoices()).resolves.toEqual([])
   })

Test hâlâ aynı adı taşıyor ve artık tam tersini doğruluyor (T4). Önce uygulamayı okursanız bu doğal bir güncelleme gibi görünür. Önce testi okursanız doğru soruyu sorarsınız: bir zaman aşımının "fatura yok" gibi görünmesine kim karar verdi? Ajanın eklediği yeniden deneme testi, çağrının yeniden denendiğini kontrol ediyor, ama son deneme de başarısız olduğunda ne olduğunu kontrol etmiyor (T5).

Doğruluk

  • C1. Her API ve paket gerçekten var. Fonksiyonlar, seçenekler ve paketler, lockfile'ınızın sabitlediği sürümlerde gerçekten mevcut.
  • C2. Hatalar yutulmamış. Boş catch blokları yok ve boş bir sonuca dönüştürülen hata yok.
  • C3. Sessiz geri dönüşler yok. Sıfır, boş bir dize veya boş bir liste, başarısız bir aramayı gizlemiyor.
  • C4. Uç durumlar ele alınmış. Boş girdi, saat dilimleri, sayfalandırma, yeniden denemeler ve aynı anda gelen iki istek.
  • C5. Veri değişiklikleri güvenli. Migration'lar ekleyici veya geri alınabilir ve daha önce çalışmış hiçbir migration düzenlenmemiş.

Şimdi kodun kendisi; neye bakacağımızı artık net olarak bilerek:

export async function syncInvoices() {
  try {
    return await pRetry(() => payments.listInvoices(), { retries: 3 })
  } catch (error) {
    logger.warn("invoice sync failed", { error })
    return []
  }
}

C2 ve C3 aynı satırlarda başarısız oluyor. Son yeniden deneme de zaman aşımına uğradığında iş bir uyarı yazıyor ve boş bir liste döndürüyor. syncInvoices fonksiyonunu çağıran her yer artık hiç fatura olmadığını düşünüyor ve geriye kalan tek iz, kimsenin okumadığı bir uyarı. Nöbetçiye alarm gönderen bir zaman aşımı aynı gün düzeltilir. Sessizce hiçbir şey döndürmeyen bir senkronizasyon ise haftalarca çalışabilir. C1 geçiyor (p-retry ve onun retries seçeneği gerçek) ve ortada bir migration yok.

Güvenlik ve secret'lar

  • S1. İzin kontrolleri komşularıyla örtüşüyor. Yeni uç noktalar, yetkilendirmeyi benzer kodun yaptığı şekilde kontrol ediyor.
  • S2. Güvenilmeyen girdi veri olarak kalıyor. Girdiden oluşturulan SQL, shell komutu veya HTML yok; diff'teki yorumlardan veya dosyalardan alınıp uygulanan talimat da yok.
  • S3. Diff'te secret yok. Kodda, fixture'larda veya günlük satırlarında anahtar, token veya özel URL yok.
  • S4. Güvensiz varsayılanlar yok. Kapatılmış sertifika kontrolleri, açık CORS veya açık bırakılmış hata ayıklama anahtarları yok.
  • S5. Otomatik bulgular triyajdan geçirilmiş. Açık yüksek önem dereceli bulgu yok ve kapatılan her bulgunun katıldığınız bir gerekçesi var.

S1'den S4'e kadar olanlar geçiyor: yeni uç nokta yok, girdi işleme yok, secret yok. S5 başarısız. Yapay zekâ inceleyicisi "error swallowed on final retry" (son yeniden denemede hata yutuluyor) diye orta önem dereceli bir bulgu işaretlemişti ve biri bunu hiçbir gerekçe yazmadan yanlış pozitif olarak kapatmıştı. O bulgu, C2 hatasının ta kendisiydi. Gerçek bulguları kapatmak, inceleyicilerin bir aracı görmezden gelmeyi öğrenme yoludur; bulguların nasıl düzgünce triyajdan geçirileceğini yanlış pozitiflerle başa çıkma yazısı anlatıyor.

Bağımlılıklar ve lisanslar

  • D1. Her yeni bağımlılık gerçekten gerekli. Kod tabanında zaten bulunan hiçbir şey bu işi görmüyor.
  • D2. Paket gerçekten var ve adı doğru yazılmış. Popüler bir adın benzeri değil, modelin uydurduğu bir ad da değil (bkz. slopsquatting).
  • D3. Bakımı sürüyor. Yakın tarihli sürümler, etkin bir repo, bir avuçtan fazla kullanıcı.
  • D4. Lisansı izin verdiğiniz bir lisans. Paket kayıt defterinin (registry) bildirdiği lisansı politikanıza göre kontrol edin.
  • D5. Lockfile da onunla birlikte ve yalnızca beklendiği kadar değişmiş. Elli yeni geçişli paketi beraberinde getiren tek satırlık bir manifest değişikliği bir göz atmayı hak eder.

p-retry gerçek, bakımı süren ve serbest (permissive) lisanslı bir paket; bu yüzden D2'den D5'e kadar olanlar geçiyor. D1 başarısız: projede zaten bir yeniden deneme yardımcısı var ve yeni bir bağımlılık, kod tabanının çoktan çözmüş olduğu bir sorunu çözen bir tedarik zinciri kararıdır.

İncelemenin bulduğu şeyler

Baştan sona okunduğunda değişiklik bitmiş görünüyordu. Kontrol listesiyle okunduğunda ise ortaya şunlar çıkıyor: adının tam tersini doğrulayan bir test (T4), daha önce işaretlenip kapatılmış (S5) ve boş bir sonuca dönüştürülmüş bir zaman aşımı (C2, C3), ajanın testine uysun diye üç katına çıkarılmış bir CI zaman aşımı (M3), artık var olmayan bir sürüme ait bir test sonucu (T1), yinelenen bir yardımcı ve gereksiz bir bağımlılık (M5, D1) ve ilgisiz biçimlendirme değişiklikleri (M2). Bunların hiçbiri sıra dışı değil. Hepsi ajan çıktısının ters gitmesinin sıradan yolları.

Bir ret yorumu, kontrolün adını verdiğinde ve belirli bir şey istediğinde en iyi sonucu verir; bir sonraki deneme ister bir kişiden, ister daha iyi bir görev tanımı verilmiş ajandan gelsin:

Not approving yet. Against the review checklist:

- **T4, C2, C3:** after the last retry this returns `[]`, and the timeout
  test now asserts that. Callers will treat a failed sync as "no invoices".
  Please rethrow after the final attempt and restore the original assertion.
- **M3:** please revert the CI timeout change. If the test needs real
  backoff delays, use fake timers instead.
- **T1:** the green run is from before the test change. Needs a run on the
  current commit.
- **M5, D1:** we already have `withRetry` in `src/lib/retry.ts`; please use
  it and drop `p-retry`.
- **M2:** please move the formatting of customer-sync and refund-sync to its
  own pull request.

Neyi otomatikleştirmeli, neyi insana bırakmalı

Bazı kontroller muhakeme gerektirir. T4 için, faturalar söz konusu olduğunda bir zaman aşımının ne anlama gelmesi gerektiğini bilen bir kişi gerekir. Diğerleri ise kanıtla ilgilidir ve kanıtı hafızadan çok yazılım daha iyi kontrol eder:

KontrolOtomatikleştirme aracı
T1 testler bu sürüm üzerinde çalıştıen son commit'te zorunlu durum kontrolü olarak CI
S3 secret yokCI'da bir secret tarama aracı
S5 bulgular triyajdan geçtiaçık yüksek önem dereceli bulgularda engelleyen bir kapı
D2, D3 paket var ve bakımı sürüyoryeni bağımlılıklar için bir paket kayıt defteri sorgusu
D4 lisansa izin veriliyorSBOM'a göre kontrol edilen bir lisans politikası
M3 hassas dosyalaronay isteyen veya değişikliği reddeden bir yol kuralı
M1, T4, C2'den C4'e, S1, D1bir kişi: bunlar kodun ne için olduğuna bağlıdır

AI CodeOps'ta bir test sonucu yalnızca üzerinde çalıştığı sürüm için geçerlidir; bu yüzden T1 eskimiş bir çalıştırmayla geçemez. Yüksek veya daha üst önem derecesindeki açık bir bulgu, fixed, won't fix, false positive veya duplicate olarak işaretlenene kadar değişikliği engeller (kalite kapıları). Bir çalışma alanı politikası, infra/** gibi yollar için onay isteyebilir ya da bu yollardaki değişiklikleri reddedebilir. Ekipte başka bir onaylayıcı varsa onay oyu, oturumu başlatan kişiden başka birinden gelmelidir; onaydan sonra bir değişikliği düzenlemek de onu yeniden onaya gönderir. Oyların nasıl sayıldığını Onaylar ve politikalar açıklıyor; bulguları yazan yapay zekâ inceleyicisini ise çok ajanlı kod incelemesi anlatıyor.

Neyi otomatikleştirirseniz otomatikleştirin, iki şey bir kişide kalır. Birincisi, prompt'u verenden başka biri onaylar; çünkü görevi yazan kişi, önemli olan her açıdan değişikliğin yazarıdır. İkincisi, onaylayan kişi değişikliği açıklayabilmelidir: finans ekibi mutabakatın neden hiçbir şey bulmadığını sorduğunda, "zaman aşımları artık fatura döndürmüyor" kararını o sırada nöbette olan kişiye karşı savunabilir miydiniz?

Yazdırılabilir kontrol listesini indirin

Yapay zekâ kod incelemesi kontrol listesi sayfası, yazdırılabilir bir sürümü kapsamdan başlayarak sıralanmış 25 numaralı madde olarak sunuyor. Gruplar biraz farklı: beş bağımlılık kontrolünü tek bir kontrolde birleştiriyor ve kimin onayladığına dair kontroller ekliyor. Yazdırmak için tek sayfalık bir PDF ve bir Markdown kopyası da var. CC BY 4.0 ile lisanslandığı için onu kendinize göre uyarlayabilirsiniz.

Wiki'de duran bir kontrol listesi bir kez okunur ve unutulur; bu yüzden kısa hâlini pull request şablonunuza koyun. GitHub'da bu dosyasıdır; GitLab'de ise altındaki bir dosya (ikisi de 24 Ekim 2026'da kontrol edildi):

## Reviewer checklist (AI-written changes)

- [ ] Scope: only what the task asked; no unrelated edits; sensitive files
      changed on purpose; small enough to review; no duplicate helpers (M1–M5)
- [ ] Tests: ran on this exact commit; none deleted, skipped or loosened;
      expected values didn't move to fit; new tests can fail (T1–T5)
- [ ] Correctness: real APIs; no swallowed errors or silent fallbacks;
      edge cases; safe data changes (C1–C5)
- [ ] Security: permission checks; untrusted input stays data; no secrets;
      no insecure defaults; findings triaged with reasons (S1–S5)
- [ ] Dependencies: needed, real, maintained, allowed license, expected
      lockfile change (D1–D5)
- [ ] Approval: I didn't write the task, and I can explain this change

Önemli çıkarımlar

  • Yapay zekânın yazdığı kodu önce kapsam, sonra testler, en son kod sırasıyla inceleyin: bir ajanın hataları iyi koda benzer.
  • Uygulamaya uysun diye değiştirilmiş bir test, en yaygın ciddi hatadır; bu yüzden test diff'ini koddan önce okuyun.
  • Yutulan hatalar ve sessiz geri dönüşler, gürültülü bir arızayı sessizce yanlış veriye dönüştürür.
  • Her yeni bağımlılık bir tedarik zinciri kararıdır: gerekli, gerçek, bakımı süren ve lisansına izin verilen bir paket olduğunu kontrol edin.
  • Kanıt kontrollerini otomatikleştirin ve onayı prompt'u veren kişiye değil, ikinci bir kişiye bırakın.

Sık sorulan sorular

Yapay zekânın ürettiği kodu incelerken önce neyi kontrol etmeliyim?

Uygulamadan önce kapsamı ve testleri kontrol edin. Değişikliğin yalnızca görevin istediğini yaptığını, testlerin onayladığınız sürümün tam kendisi üzerinde çalıştığını ve hiçbir testin geçsin diye gevşetilmediğini doğrulayın.

Bir yapay zekâ inceleyicisi, yapay zekânın yazdığı kodun insan tarafından incelenmesinin yerini alabilir mi?

Hayır. Bir yapay zekâ inceleyicisi ve CI; test sonuçları, açık bulgular ve yeni bağımlılıklar gibi kanıtları kontrol edebilir. Değişikliğin sisteminiz için doğru olup olmadığına ve nöbetteyken onu savunup savunamayacağınıza ise yine bir insanın bakması gerekir.

Bu kontrol listesini pull request şablonumda kullanabilir miyim?

Evet. Aşağıdaki kısa hâli bir GitHub pull request şablonuna veya bir GitLab merge request şablonuna sığar; yazdırılabilir kontrol listesi ise CC BY 4.0 ile lisanslanmıştır.