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

Adres: https://agentvera.dev/blog/yapay-zeka-ile-hata-ayiklamak/ · Yayın: 2026-10-27

Yapay zeka ile hata ayıklama: hatayı yeniden üret, ajana başarısız testi ve logları ver, git bisect ile daralt, kök nedeni bul ve düzeltmeyi testle sabitle.

**Kısaca:**

- Bir yapay zeka ajanı hatayı kendisi çalıştırabildiğinde iyi ayıklar: belirtinin tarifinden değil, yeniden üretimden, başarısız bir testten ya da tam bir komuttan başla.
- Ona tam stack trace’i ve logları ver, git bisect run ile aramayı yaptır, geçici loglar ekletip her düzeltmeden önce kök nedeni açıklamasını iste.
- İşi düzeltmeden önce kırılan, sonra geçen bir regresyon testiyle bitir; ajan tahmin etmeye ya da testleri gevşetmeye başladığında onu durdur.

**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:

```text
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:

```text
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:

```bash
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](/sozluk/baglam-penceresi/ "Bağlam penceresi nedir") 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:

```bash
#!/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:

```bash
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:

```text
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](/blog/git-worktree-paralel-gelistirme/ "Git worktree ile paralel geliştirme") 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:

```text
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:

```bash
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:

```text
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](/blog/claude-code-plan-modu/ "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:

```text
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](/blog/yapay-zeka-ile-test-yazmak/ "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](https://github.com/microsoft/playwright-mcp "Playwright MCP") ile ajan sayfayı açıp kendisi bakabilir. Claude Code’a ekle:

```bash
claude mcp add playwright npx @playwright/mcp@latest
```

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

```toml
[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:

```text
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](/blog/yapay-zeka-ajani-tarayici-testi/ "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](/blog/ci-hatasini-yapay-zeka-duzeltsin/ "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:

1. Turu durdur (Claude Code’da ve Codex’te Esc).
2. 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](/blog/claude-code-degisiklikleri-geri-alma/ "Claude Code değişikliklerini geri alma") yazısında.
3. Öğrendiklerini yaz: hangi teoriler yanlış çıktı ve neden.
4. 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](/indir/ "AgentVera’yı indir"), 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](/ozellikler/ajana-gonder/ "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ı](/ozellikler/ajan-tarayicisi/ "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](/ozellikler/turlar-ve-oturum-tekrari/ "Turlar ve oturum tekrarı"):** 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](/ozellikler/git-ve-github/ "Git ve GitHub") ayrı worktree’lerde iki ajan başlat, her birine farklı bir hipotez ver ve ayakta kalan düzeltmeyi tut.
- **[Verify](/ozellikler/verify/ "AgentVera 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](/blog/yapay-zeka-ile-dokumantasyon-yazmak/ "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ç.

## Sık sorulanlar

**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.

---

**AgentVera hakkında.** AgentVera, Solviera Teknoloji tarafından geliştirilen macOS, Windows ve Linux masaüstü uygulamasıdır. 18 yapay zeka kodlama ajanını (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) proje bazında, gerçek terminallerde ve kullanıcının kendi CLI kurulum ve girişleriyle yan yana çalıştırır. Ücretsiz planda sınırsız ajan vardır. İndir: https://agentvera.dev/indir/ · Fiyatlar: https://agentvera.dev/fiyatlar/