Yapay zeka gerçekten hata ayıklayabilir mi, yoksa sadece tahmin mi eder?

Bir kodlama ajanı kodu çalıştırabildiğinde gerçekten ayıklar: hatayı yeniden üretir, çıktıyı okur, log ekler ve bir hipotezi dener. Başarısız durumu çalıştırma imkânı yoksa yalnızca okuyarak tahmin eder; yanlış düzeltmelerin çoğu buradan çıkar.

Bir hatayı bildirirken ajana ne vermeliyim?

Başarısız olan tam komutu ya da testi, stack trace’iyle birlikte hatanın tamamını, bunun yerine ne beklediğini ve son zamanlarda neyin değiştiğini. Tek satırlık bir yeniden üretim, belirtinin uzun bir tarifinden daha değerlidir.

Bir ajan git bisect’i kendi başına çalıştırabilir mi?

Evet. Ona iyi ve kötü bir commit ile kod çalışınca 0, çalışmayınca 1 ile çıkan bir betik ver. git bisect run commit’leri sırayla açar ve ilk kötü commit’i bulana kadar betiği çalıştırır. 125 çıkış kodu, test edilemeyen bir commit’in atlanmasını söyler.

Yapay zekanın hatayı yalnızca gizleyen bir düzeltme yapmasını nasıl engellerim?

Kod değişmeden önce kök nedeni düz bir dille açıklamasını iste, mevcut testleri düzenlemeyi ya da atlamayı yasakla ve düzeltme olmadan kırılan bir regresyon testi şart koş. Diff’te hatayı kaynağından gidermek yerine susturan try/catch blokları, yeniden denemeler ve genişletilmiş tipler ara.

Ajanı ne zaman durdurup kendim ayıklamalıyım?

İki üç düzeltme denemesi işe yaramadığında, ilgisiz dosyaları değiştirmeye başladığında ya da bir testi veya assertion’ı gevşetmeyi önerdiğinde. Onu durdur, değişikliklerini geri al ve daha net bir yeniden üretimle ya da daha dar bir soruyla baştan başla.

Yapay zeka ile hata ayıklama: adım adım iş akışı

Yapay zeka ile hata ayıklamak için ajana hatayı yeniden üretmenin bir yolunu, hatanın ve logların tamamını ve net bir kural ver: bir şeyi değiştirmeden önce kök nedeni bul. Claude Code ya da Codex gibi bir kodlama ajanı testlerini çalıştırabilir, stack trace okuyabilir, git geçmişinde bisect yapabilir ve log ekleyebilir; bu da onu güçlü bir hata ayıklama ortağı yapar. Ama hataları da tahmin edilebilir: başarısız durumu çalıştıramadığında tahmin eder, belirtiyi ise hatayı yakalayarak ya da testleri gevşeterek “düzeltir”.

Bu rehber ilkinden yararlanıp ikincisine karşı korunan bir iş akışı: yeniden üret, kanıtı ver, daralt, açıklat, düzelt, bir testle sabitle ve ne zaman fişi çekeceğini bil.

Ajanlar hata ayıklamada neden yanılır?

Kötü yapay zeka düzeltmelerinin çoğu aynı birkaç yerden gelir:

Yeniden üretim yok. Ajan kodu okur, bir teori kurar ve yamar. Teorinin doğru olduğunu hiçbir şey kanıtlamaz.
Eksik kanıt. Hatanın son satırını yapıştırırsın. İşe yarayan satır, stack’in üç kat aşağısında, modele hiç ulaşmaz.
Belirtiyi düzeltmek. Bir null kontrolü, bir try/catch ya da bir yeniden deneme hatayı ortadan kaldırır; ama onu doğuran bozuk durum yerinde durur.
Kale direklerini oynatmak. Test kırılır, ajan da testi düzenler.
Uzun, kirlenmiş oturumlar. Beş başarısız denemeden sonra konuşma yanlış teorilerle dolar ve model onların üstüne inşa etmeye devam eder.

Aşağıdaki her adım bunlardan birini hedefliyor.

1. Adım: önce hatayı yeniden üret

Ajan koda dokunmadan önce hatayı gösteren bir komuta ihtiyacı var. Bu başarısız bir test, bir curl çağrısı, bir betik ya da tarayıcıdaki bir sayfa olabilir. Önemli olan, ajan dahil herkesin onu çalıştırıp hatayı görebilmesi.

Elinde zaten varsa prompt’un en üstüne koy:

Bu başarısız oluyor:

  pnpm vitest run src/billing/invoice.test.ts -t "applies discount once"

Beklenen toplam 90, gelen 81. Henüz hiçbir kodu değiştirme.
Testi çalıştır, aynı hatayı gördüğünü doğrula ve ne gördüğünü anlat.

Yeniden üretimin yoksa ilk görev onu yazmak olsun:

Kullanıcılar bir taslağı iki kez kaydetmenin iki taslak oluşturduğunu
bildiriyor. Bunu yeniden üreten, başarısız olan bir test yaz. Hiçbir şeyi
düzeltme. Test doğru sebepten kırıldığında dur.

“Doğru sebepten” önemli. Testteki bir yazım hatası yüzünden kırılan test hiçbir şey kanıtlamaz. Ajandan hata çıktısını göstermesini ve bunun hata bildirimiyle neden örtüştüğünü açıklamasını iste. Ara sıra ortaya çıkan hatalarda yeniden üretimi bir döngüde (örneğin 50 kez) çalıştırıp kaç kez kırıldığını raporlamasını iste; böylece bir düzeltmenin gerçekten işe yarayıp yaramadığını sonra anlayabilirsin.

2. Adım: ajana kanıtın tamamını ver

Ajanlar uzun ve gürültülü çıktıları okumakta iyidir. Onlar için kırpma. Şunları ver:

stack trace’in tamamı, yalnızca mesaj değil;
tam komut ve çıktısının tamamı;
hatanın olduğu zamana ait ilgili loglar;
son zamanlarda ne değişti: bir bağımlılık güncellemesi, bir deploy, birleştirilen bir dal;
önemli olabilecekse ortam bilgileri: işletim sistemi, çalışma zamanı sürümü, özellik bayrakları.

Her şeyi sohbete yapıştırman gerekmez. Bir dosyaya kaydedip ajanı ona yönlendir ya da doğrudan aktar. Claude Code’un print moduyla:

pnpm test 2>&1 | tail -n 200 > /tmp/test-output.txt
cat /tmp/test-output.txt | claude -p "Explain the root cause of this failure. Don't edit files."

Etkileşimli bir oturumda ! hem Claude Code’da hem Codex’te bir kabuk komutu çalıştırıp çıktısını konuşmaya ekler, örneğin !pnpm test src/billing. Çok büyük loglarda ajandan dosyanın tamamını okumak yerine istek kimliğini ya da hata kodunu grep ile aramasını iste; bu, bağlam penceresinden ciddi tasarruf sağlar.

3. Adım: git bisect ile daralt

Eskiden çalışan bir şey artık çalışmıyorsa bir teoriye ihtiyacın yok. git bisect ilk kötü commit’i ikili aramayla bulur ve tamamen otomatik çalışabilir; bu da onu bir ajan için biçilmiş kaftan yapar.

Önce kod iyiyse 0, kötüyse sıfırdan farklı bir kodla çıkan küçük bir betik yaz:

#!/bin/sh
# check.sh
pnpm install --frozen-lockfile >/dev/null 2>&1 || exit 125
pnpm vitest run src/billing/invoice.test.ts -t "applies discount once"

Sonra yürüme işini git’e bırak:

git bisect start
git bisect bad HEAD
git bisect good v2.3.0
git bisect run ./check.sh
git bisect reset

Sözleşme çıkış kodlarıdır; resmi git bisect belgeleri bunları şöyle tanımlar: 0 iyi demek, 125 hariç 1 ile 127 arasındaki her kod kötü demek, 125 “bu commit test edilemiyor, atla” demek, daha yüksek her şey ise bisect’i iptal eder. Yukarıdaki kurulum adımının 125 ile çıkmasının nedeni bu: kurulumu bile yapılamayan bir commit kötü sayılmamalı, atlanmalı.

Bütün işi ajana devreden bir prompt:

Fatura indirim testi v2.3.0 etiketinde geçiyor, main’de kırılıyor.
git bisect run için bir kontrol betiği yaz (commit derlenemiyorsa 125
ile çıksın), bisect’i çalıştır, sonra git bisect reset yap.
İlk kötü commit’i raporla ve diff’indeki hangi satırın hataya yol
açtığını açıkla. Henüz hiçbir şeyi düzeltme.

Önce çalışma ağacının temiz olduğundan emin ol ya da işi ayrı bir git worktree içinde yap ki bisect’in checkout’ları kendi çalışmanla çakışmasın. Test dosyası eski commit’lerde yoksa onu depo dışında bir yola kopyala ve betiğin o kopyayı çalıştırmasını sağla.

4. Adım: log ekle, sonra kaldır

Stack trace hataya götüren durumu açıklamıyorsa ajanın çalışma anındaki değerleri görmesi gerekir. Hedefli, geçici loglar iste:

applyDiscounts() içindeki her adımda sepet ürünlerini, indirim listesini
ve ara toplamı yazdıran geçici loglar ekle. Her satırın başına
[DEBUG-1234] koy ki sonra bulup kaldırabilelim. Başarısız testi
çalıştır ve log satırlarını göster.

İşin püf noktası önek. Hata anlaşıldığında temizlik tek bir talimatla biter:

git grep -n "DEBUG-1234"

Ajanlar betikle sürülebilen hata ayıklayıcılarla da iyi çalışır: bir terminal ajanı için node --inspect ile breakpoint koymak zahmetlidir, ama kısa bir python -m pdb oturumu, fazladan bir assertion ya da fonksiyonu başarısız girdiyle çağıran tek seferlik bir betik çoğu zaman aynı cevaba daha hızlı ulaştırır.

5. Adım: düzeltmeden önce kök neden

En önemli kural bu. Ajandan düzeltmeyi yazmadan önce hatayı açıklamasını iste ve açıklamayı oku:

Herhangi bir kodu değiştirmeden önce kök nedeni açıkla:
1. Hangi durum yanlış ve ilk nerede yanlış hâle geliyor?
2. Kod neden bu durumu üretiyor?
3. Mevcut testler bunu neden yakalamadı?
Sonra en küçük düzeltmeyi öner ve benim onayımı bekle.

İyi bir cevap belirli bir satırı ve belirli bir koşulu gösterir (“a1b2c3 commit’i çağrıyı taşıdığından beri indirim hem addItem hem checkout içinde uygulanıyor”). Zayıf bir cevap muğlaktır (“indirimlerin işlenme şeklinde bir sorun olabilir”) ya da doğrudan savunmacı bir yamaya atlar. Zayıf türünü alıyorsan ajan nedeni henüz bulmamıştır; onu 3. ya da 4. adıma geri gönder.

Claude Code’un plan modu burada işe yarar, çünkü ajan sen onaylayana kadar dosya okuyabilir ve salt okuma komutları çalıştırabilir ama düzenleme yapamaz. claude --permission-mode plan ile başlat ya da Shift+Tab ile ona geç. Claude Code plan modu yazısı bunu ayrıntılı anlatıyor. Codex’te /plan benzer bir iş görür.

6. Adım: düzelt ve bir regresyon testiyle sabitle

Şimdi ajanın düzeltmesine izin ver, kurallarla:

Düzeltmeyi uygula. Kurallar:
- Mevcut testleri düzenleme ya da atlama.
- Hatayı yakalayıp yutma.
- Hatanın adını taşıyan, düzeltme olmadan kırılan ve düzeltmeyle
  geçen bir regresyon testi ekle. İkisini de kanıtla: düzeltmeyi geri
  al, testi çalıştır, düzeltmeyi geri koy, yeniden çalıştır.
- Sonunda test paketinin tamamını çalıştır.

Testi güvenilir yapan “ikisini de kanıtla” kısmı. Düzeltmeden önce de geçecek bir regresyon testi süsten ibarettir. Bir ajandan işe yarar testler almak için yapay zeka ile test yazmak yazısına bak.

Ardından diff’i kendin incele ve alışılmış belirti düzeltmelerini ara:

Diff’teki kalıp	Neden şüpheli
Loglayıp devam eden yeni bir `try/catch`	Hata gizlenir, bozuk durum yerinde kalır
Çökme noktasına eklenen optional chaining ya da `?? default`	Eksik veriyi neden eksik olduğunu sormadan normal sayar
Yeniden denemeler ya da daha uzun zaman aşımları	Çoğu zaman bir yarış durumunu örter
`any` ya da `unknown`’a genişletilen tip	Tipi düzeltmek yerine derleyiciyi susturur
Değiştirilen test beklentisi	Kale direği oynamıştır

Bazen bunlardan biri gerçekten doğru düzeltmedir. Sorulacak soru, ajanın nedenini açıklayıp açıklamadığı.

Tarayıcı hataları: ajana bir tarayıcı ver

Arayüz hatalarını metinle anlatmak zordur: hiçbir şey yapmayan bir buton, bir tıklamadan sonra bozulan bir düzen, yalnızca konsolda görünen bir hata. Playwright MCP ile ajan sayfayı açıp kendisi bakabilir. Claude Code’a ekle:

claude mcp add playwright npx @playwright/mcp@latest

ya da Codex’e ~/.codex/config.toml içinde:

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

browser_navigate, browser_click, browser_snapshot, browser_console_messages ve browser_network_requests gibi araçlarla ajan hatayı adım adım yeniden üretir, konsol hatalarını okur ve hangi API çağrısının başarısız olduğunu görür. Bir hata ayıklama prompt’u:

Geliştirme sunucusunu başlat. http://localhost:5173/settings sayfasını
aç, görünen adı değiştir ve Kaydet’e tıkla. Konsol hatalarını ve
kaydetme isteğini durum kodu ve yanıt gövdesiyle raporla. Henüz düzeltme.

Neden netleşince ajandan adımları bir Playwright testine çevirmesini iste ki hata düzeltilmiş kalsın. Kurulumun ayrıntıları yapay zeka ajanı ile tarayıcı testi yazısında.

Yalnızca CI’da görünen hatalar

Testler yerelde geçip CI’da kırılıyorsa fark genellikle ortamdadır: saat dilimi, yerel ayar, paralellik, eksik ortam değişkenleri, farklı bir Node ya da Python sürümü veya test sırası. Ajana CI logunu ve workflow dosyasını ver; tahmin etmeden önce CI ile senin makinen arasındaki farkları listelemesini iste. Test paketini rastgele sırada ya da CI’ın saat dilimiyle (TZ=UTC pnpm test) çalıştırmak hatayı çoğu zaman yerelde de ortaya çıkarır. CI hataları düzenli bir angaryaysa CI hatasını yapay zeka düzeltsin yazısı bu döngüyü otomatikleştirmeyi anlatıyor.

Ajanı ne zaman durdurmalı?

Bir ajan durması gereken noktadan çok sonra da denemeye devam eder. Şu durumlarda fişi çek:

İki üç düzeltme başarısız oldu. Her yeni deneme aynı yanlış teorinin üstüne kurulu.
Diff yayılıyor. invoice.ts ile başladı, şimdi yapılandırmayı, ilgisiz modülleri ya da lock dosyalarını düzenliyor.
Testlere dokunuyor. Bir assertion’ı yanlış çıktıya uyacak şekilde değiştirmek asla bir hata düzeltmesi değildir.
Hatayı yeniden üretemiyor ama yine de düzeltiyor.
Açıklama yeni bir kanıt olmadan turdan tura değişiyor.

Bunun yerine şunu yap:

Turu durdur (Claude Code’da ve Codex’te Esc).
Değişikliklerini geri al. Hata ayıklamaya başlamadan önce commit at ki git restore . ya da git stash seni geri götürsün; seçenekler Claude Code değişikliklerini geri alma yazısında.
Öğrendiklerini yaz: hangi teoriler yanlış çıktı ve neden.
Yeniden üretimle, olgularla ve elenen teorilerle yeni bir oturum başlat. Üç sağlam olgu içeren temiz bir bağlam, on kötü tahmin içeren uzun bir bağlamdan iyidir.

Bazen doğru hamle daha dar bir soru sormaktır: “checkout() çağrıldığında cart.items zaten yanlış mı?” sorusunu yanıtlamak, “checkout hatasını düzelt”ten daha kolaydır.

AgentVera ile hata ayıklamak

AgentVera, Claude Code, Codex, Gemini CLI ve diğer CLI ajanlarını gerçek terminallerde yan yana çalıştıran, macOS, Windows ve Linux için bir masaüstü uygulaması. Araçlarından birkaçı yukarıdaki iş akışına oturuyor:

Ajana gönder: terminal panelindeki, tarayıcı konsolundaki ya da Docker loglarındaki bir hatayı seçip ⌘⇧L ile bir ajana gönder ya da yakalanan bir hatadaki Düzelt rozetine tıkla. Uzun loglar 12.000 karakterle sınırlanır ve stack trace’in genelde bulunduğu son kısım korunur.
Ajan tarayıcısı: ajanların Playwright MCP üzerinden kullandığı, ayrı profilli bir Chrome; sekmeler canlı yayınlanır, ajanın hatayı yeniden üretmesini izleyebilirsin.
Turlar: her tur gizli bir git ref’ine kaydedilir; başarısız bir denemenin neyi değiştirdiğini görür, dallarına ve stash’ine dokunmadan o turu geri alırsın.
Paralel iki teori: Git panelinden ayrı worktree’lerde iki ajan başlat, her birine farklı bir hipotez ver ve ayakta kalan düzeltmeyi tut.
Verify: Pro ve Team’de “regresyon testi düzeltme olmadan kırılıyor, düzeltmeyle geçiyor” gibi kriterler, ajanın turu bitince ayrı ve salt okuma yetkili bir doğrulayıcı tarafından kontrol edilir.

Hata düzeldikten sonra öğrendiklerini bir sonraki kişinin bulacağı yere yaz; o tarafı yapay zeka ile dokümantasyon yazmak yazısı anlatıyor.

Sonuç

Bir yapay zeka ajanıyla hata ayıklamak, ona keskin bir iş arkadaşı gibi davrandığında işe yarar: yeniden üretimden başla, kanıtın tamamını paylaş, aramayı git bisect ile daralt, gerçek değerleri görmek için log ekle ve düzeltmeden önce kök nedende ısrar et. Her hatayı, kırıldığını ve geçtiğini kendi gözünle gördüğün bir regresyon testiyle kapat. Ajan tahmin etmeye başladığında da onu durdur, geri al ve öğrendiklerinle temiz bir sayfa aç.