Yazmadığınız hata raporlarını ayıklayın: pratik bir iş akışı

Bu hata raporlarını zorlaştıran (ve kontrolünüzde olan) şeyler

Başkasının yazdığı bir hata raporunu ayıklamak zor çünkü orijinal geliştiricinin zihinsel haritası eksik. Hangi şeylerin kırılgan olduğunu, neyin "normal" olduğunu ya da hangi kestirme yolların alındığını bilmiyorsunuz. Küçük bir belirti (bir buton, bir yazım hatası, yavaş bir ekran) API, veritabanı veya arka plan işiyle ilgili daha derin bir sorundan kaynaklanabilir.

Yararlı bir hata raporu size dört şey verir:

• tam eylem
• tam veri
• beklenen sonuç
• gerçek sonuç

Çoğu rapor yalnızca sonuncusunu verir: "Kaydetme çalışmıyor", "bozuk", "rastgele hata." Eksik olan, tekrarlanabilir yapan bağlamdır: kullanıcı rolü, spesifik kayıt, ortam (prod vs staging) ve bir değişiklikten sonra başlayıp başlamadığı.

Amaç, belirsiz bir semptomu güvenilir bir çoğaltıma çevirmektir. Bir kere isteğiniz üzerine bunu üretebiliyorsanız, gizemli olmaktan çıkar. Bu, bir dizi kontroldür.

Hemen kontrol edebileceğiniz şeyler:

• problemi tetikleyen en küçük adım seti
• tam test verisi (ID'ler, e-posta, payload, filtreler)
• ortam ve sürüm (build, feature flag'ler, tarayıcı/cihaz)
• olayın kanıtı (zaman damgası, ekran görüntüsü, hata metni, log snippet'i)
• tekrar çalıştırılabilir açık bir geç/geçmez sonucu

"Bitti" demek "sanırım düzelttim" demek değildir. Bitti: çoğaltım adımlarınız küçük bir değişiklikten sonra geçiyor ve hızlıca etkilenmiş olabilecek yakın davranışları yeniden test edebiliyorsunuz.

Hiçbir şeye dokunmadan önce stabil bir temel kurun

Zaman kaybetmenin en hızlı yolu birden fazla şeyi aynı anda değiştirmektir. Başlangıç noktanızı dondurun ki her test sonucu bir şey ifade etsin.

Bir ortam seçin ve problemi çoğaltana kadar orada kalın. Rapor prod'dan geldiyse önce orada doğrulayın. Riskliyse staging kullanın. Yerel ortam, verileri ve ayarları yakından eşleştirebiliyorsanız uygundur.

Sonra hangi kodun gerçekten çalıştığını sabitleyin: sürüm, build zamanı ve akışı etkileyen feature flag'ler veya konfigürasyon. Küçük farklar (devre dışı bırakılmış entegrasyonlar, farklı API base URL, eksik arka plan işleri) gerçek bir hatayı hayalete çevirebilir.

Temiz, tekrarlanabilir bir test altyapısı oluşturun. Yeni bir hesap ve bilinen veriler kullanın. Mümkünse her denemeden önce durumu sıfırlayın (çıkış yap, cache temizle, aynı kayıttan başla).

Varsayımlarınızı yazın. Bu meşguliyet değil; sonra kendinizle tartışmayı engeller.

Bir temel not şablonu:

• Ortam: prod, staging veya local
• Sürüm/build: commit, tag veya build zaman damgası
• Konfig: feature flag'ler, entegrasyonlar, test anahtarları
• Test kimliği: hesap e-posta/rol, izinler
• Veri: kayıt ID'leri, seed'lenmiş öğeler, beklenen başlangıç durumu

Eğer çoğaltma başarısız olursa, bu notlar sıradaki hangi düğmeyi birer birer çevireceğinizi söyler.

Raporu test edilebilir adımlara ve girdilere çevirin

Hızlı kazanım, belirsiz bir şikayeti bir komut dosyası gibi çalıştırılabilir bir şeye çevirmektir.

Başlangıç olarak raporu kısa bir kullanıcı hikâyesi olarak yeniden yazın: kim ne yapıyor, nerede ve ne bekliyordu. Sonra gözlenen sonucu ekleyin.

Örnek yeniden yazım:

"Bir faturalama yöneticisi olarak, bir fatura durumunu Paid'e değiştirip fatura sayfasında Kaydet'e tıkladığımda, durum kalıcı olmalı. Bunun yerine sayfa aynı kalıyor ve yenilemeden sonra durum değişmemiş durumda."

Sonra raporu doğru yapan koşulları yakalayın. Hatalar genellikle tek bir eksik detaya bağlıdır: rol, kayıt durumu, locale veya ortam.

Tıklamadan önce yazılacak ana girdiler:

• Kullanıcı rolü ve hesap tipi (admin vs standart, deneme vs ücretli)
• Veri durumu (kayıt ID, durum, gerekli ilişkili veri)
• İstemci detayları (OS, tarayıcı/uygulama sürümü)
• Locale ve zaman ayarları (dil, saat dilimi, tarih aralığı)
• Ortam ve build (prod vs staging, sürüm, feature flag'ler)

Orijinal davranışı kaydederken kanıt toplayın. Ekran görüntüleri yardımcıdır ama kısa bir kayıt zamanlama ve tam tıklamaları yakaladığı için daha iyidir. Her zaman bir zaman damgası (zaman dilimiyle) not edin ki loglarla eşleştirebilesiniz.

En çok tahminleri ortadan kaldıran üç netleştirici soru:

• Bu hangi kesin kullanıcı hesabı ve rolde oldu, bir örnek kayıt ID'si paylaşabilir misiniz?
• Eylemden hemen sonra ne görmeyi bekliyordunuz ve gerçekte ne gördünüz?
• Aynı adımlarla her zaman oluyor mu yoksa sadece belirli veriyle (durum, tarih aralığı, locale, büyük girdiler) mı?

Sorunu güvenilir şekilde çoğaltın

Nedeni tahmin ederek başlamayın. Problemi bilerek, aynı şekilde, birden fazla kez meydana getirin.

Önce raporlayanın adımlarını tam olarak çalıştırın. Onları "iyileştirmeyin." Deneyiminizin ilk saptığı farklılığı not edin; küçük bir farklılık bile (farklı buton etiketi, eksik alan, hafifçe farklı hata metni) ipucu olabilir.

Çoğu uygulamada işe yarayan basit bir iş akışı:

• Bilinen bir başlangıç durumuna sıfırlayın (temiz yükleme, aynı hesap, aynı izinler, aynı flag'ler).
• Adım adım takip edin ve kullandığınız kesin girdileri kaydedin (ID'ler, tarih aralıkları, filtreler).
• Bozulan adımda beklenen vs gerçek sonucu yazın.
• Tekrar ederek tekrarlanabilir olduğunu doğrulayın.
• Hâlâ tetikleyen en küçük adım setine daraltın.

Tekrarlanabilir olduktan sonra bir seferde bir şeyi değiştirin. Genelde işe yarayan tek değişken testleri:

• aynı adımlar, farklı rol
• aynı adımlar, farklı kayıt (yeni vs eski)
• aynı adımlar, farklı tarayıcı/cihaz
• aynı adımlar, temiz oturum (gizli pencere, cache temiz)
• aynı adımlar, farklı ağ

Sonunda başkası 2 dakikada çalıştırabilecek kısa bir repro betiği bırakın: başlangıç durumu, adımlar, girdiler ve ilk başarısız gözlem.

Hangi katmanın başarısız olduğunu izole edin: UI, API veya DB

Tüm kod tabanını okumadan önce hangi katmanın başarısız olduğuna karar verin.

Soru: belirti sadece UI'da mı, yoksa veri ve API yanıtlarında da mı var?

Örnek: "Profil adım güncellenmedi." Eğer API yeni adı döndürüyorsa ama UI hâlâ eskiyi gösteriyorsa UI durum/önbellek sorumlusu olabilir. API hiç kaydetmiyorsa API veya DB tarafındasınız demektir.

Birkaç dakikada cevaplanabilecek hızlı triage soruları:

• Birden fazla tarayıcı/cihazda yeniden üretebiliyor musunuz?
• Sert bir yenileme (hard refresh) bir şey değiştiriyor mu?
• Butona tıkladığınızda bir ağ isteği tetikleniyor mu?
• API yanıtı zaten yanlış görünüyor mu?
• Eylem sonrası veritabanı beklenen satırı gösteriyor mu?

UI kontrolleri görünürlükle ilgilidir: console hataları, Network sekmesi ve eski durum (UI kaydettikten sonra yeniden çekmiyor veya eski önbellekten okuyor olabilir).

API kontrolleri sözleşmeyle ilgilidir: payload (alanlar, tipler, ID'ler), status kodu ve hata gövdesi. Beklenmeyen bir gövde ile gelen 200, 400 kadar önemlidir.

DB kontrolleri gerçektir: eksik satırlar, kısmi yazımlar, kısıt hataları, WHERE koşulunun eşleşmemesinden dolayı 0 satır güncelleme.

Yönünüzü korumak için küçük bir harita çizin: hangi UI eylemi hangi endpoint'i tetikliyor ve hangi tablo(lar)ı okuyor/yazıyor.

İsteği uçtan uca loglar ve zaman damgaları ile takip edin

Netlik genellikle tıkladığınız istekten veritabanına ve geri dönen yolun izlenmesinden gelir.

Rapor veya repro için üç çapaç (anchor) yakalayın:

• kesin zaman (zaman dilimi ile)
• kullanıcı tanımlayıcısı (hesap/e-posta/dahili ID)
• korelasyon ID'si (request ID/trace ID/session ID)

Korelasyon ID'si yoksa, gateway/backend'inize bir tane ekleyin ve yanıt başlıklarına ile loglara dahil edin.

Gürültüye boğulmamak için sadece "Nerede başarısız oldu ve neden?" sorusunu cevaplamak için gerekenleri yakalayın:

• zaman damgası aralığı (örneğin, olaydan 1 dakika önce ile 1 dakika sonra)
• bir kullanıcı ID'si (ve gerekiyorsa tenant/org ID)
• korelasyon ID
• metod, path, status kodu, gecikme
• ilk anlamlı hata mesajı (binlerce satırlık stack trace değil)

İzlemeniz gereken sinyaller:

• Zaman aşımı/uzun gecikme: yavaş sorgular, dış çağrılar, kilitler.
• 401/403: izin veya tenant bağlamı problemleri.
• 400 doğrulama hataları: genellikle UI payload uyumsuzluğu.

Eğer "dün çalışıyordu ama bugün çalışmıyor" ise ortam kayması şüphelenin: değişen flag'ler, döndürülen sırlar, eksik migration'lar veya durmuş işler.

Küçük bir minimal repro oluşturun (böylece düzeltmeler küçük kalır)

En kolay düzeltilecek hata, küçük ve tekrarlanabilir bir denemedir.

Her şeyi küçültün: daha az tıklama, daha az alan, hatayı hâlâ tetikleyen en küçük veri seti. Eğer sadece "çok kayıtlı müşterilerde" oluyorsa, yine de tetikleyen minimal bir örnek oluşturun. Oluşturamıyorsanız bu, hatanın veri hacmiyle ilgili olabileceğine işaret eder.

"Kötü durum" ile "kötü kod"u ayırmak için durumu kasıtlı olarak sıfırlayın: temiz hesap, yeni tenant veya veri seti, bilinen build.

Repro'yu net tutmanın pratik yollarından biri kompakt bir giriş tablosu tutmaktır:

Repro'yu taşınabilir yapın ki başkası da hızlıca çalıştırsın:

• Temiz başlangıçtan 3 ila 6 adım
• Yeniden kullanılabilir bir test kaydı (veya bir request body)
• Bir açık başarı sinyali (UI mesajı, HTTP kodu, DB satır sayısı)
• Kesin ortam detayları (build/sürüm, rol, flag'ler)

Zaman kaybettiren ortak tuzaklar

En hızlı yol genellikle sıkıcıdır: bir şeyi değiştir, gözlemle, not al.

Yaygın hatalar:

• Yüzeysel semptomu düzeltmek (gerçek API/DB hatasını maskelemek).
• Aynı anda birden çok değişkeni değiştirmek (bağımlılık güncellemeleri + konfigürasyon değişiklikleri + refactor).
• Raportörün kullandığı temel ile farklı bir temelde test etmek (ortam, veri, build, tarayıcı).
• İzinleri ve rolleri unutmak (admin vs normal kullanıcı).
• Akışı değiştiren feature flag'leri veya deneyleri gözden kaçırmak.
• Doğrulama yapmadan zafer ilan etmek (çoğaltımı yeniden çalıştırmamak, yan etki kontrolü yapmamak).

Gerçekçi bir örnek: bir ticket "CSV dışa aktarım boş" diyor. Siz admin hesabıyla test edip veri görürsünüz. Kullanıcının kısıtlı bir rolü varmış ve API izin filtresi nedeniyle boş liste dönüyor. UI'yı sadece "Satır yok" diye yamalarsanız gerçek soru kaçırırsınız: o rolün dışa aktarmaya izin verilip verilmemesi mi yoksa ürünün neden filtrelediğini açıklaması mı gerekir?

Her düzeltmeden sonra aynı çoğaltımı yeniden çalıştırın, sonra etkilenebilecek bir yakın senaryoyu test edin.

Hızlı kontrol listesi: bir düzeltme istemeden önce

Tek bir paket halinde: tekrar edilebilir adımlar, muhtemel başarısız katman ve kanıtla gelin; böylece ekipten daha iyi cevap alırsınız.

Kodu kimse değiştirmeden önce doğrulayın:

• Aynı girdilerle (aynı kullanıcı, aynı veri, aynı ortam) iki kez çoğaltabiliyorsunuz.
• Başarısız katmanı (UI, API veya DB) adlandırabiliyor ve bir neden verebiliyorsunuz.
• Kanıt yakaladınız: istek, yanıt/hata, ilgili loglar ve eşleşen zaman damgası.
• Repro'yu olabildiğince küçülttünüz.
• Kabul kriterini bir cümlede yazdınız (örnek: "Kaydetme kaydı günceller ve 2 saniye içinde başarı gösterir").

Sonra hızlı bir regresyon turu yapın: farklı bir rol, ikinci tarayıcı/gizli pencere, aynı endpoint/tabloyu kullanan yakın bir özellik ve bir uç durum girdisi (boş, uzun metin, özel karakterler).

Gerçekçi bir örnek: "Kaydet butonu hiçbir şey yapmıyor" hatasını daraltma

Destek mesajı: "Düzenle Müşteri formunda Kaydet butonu hiçbir şey yapmıyor." Sonraki sorular, bunun sadece geçen aydan önce oluşturulmuş müşterilerde ve fatura e-postasını değiştirdiğinizde olduğunu ortaya çıkarır.

UI ile başlayın ve en basit hata varsayımıyla ilerleyin. Kaydı açın, düzenlemeyi yapın ve "hiçbir şey" aslında bir şey mi diye işaretlere bakın: devre dışı buton, gizlenmiş toast, render olmayan doğrulama mesajı. Ardından tarayıcı konsolunu ve Network sekmesini açın.

Burada Kaydet tıklaması bir isteği tetikliyor, ama frontend sadece 200'ü başarı kabul edip 400'leri yok saydığı için UI sonucu hiç göstermiyor. Network sekmesi 400 yanıtı ve şu şekil bir JSON gövdesi gösteriyor: {\\\"error\\\":\\\"billingEmail must be unique\\\"}.

Şimdi API'nin gerçekten başarısız olduğunu doğrulayın: isteğin tam payload'unu alın ve UI dışında yeniden çalıştırın. Eğer orada da başarısız oluyorsa frontend durum hatalarını takip etmeyi bırakın.

Sonra veritabanını kontrol edin: neden yalnızca eski kayıtlar için benzersizlik başarısız oluyor? Eski müşterilerin yıllar önce placeholder billing_email paylaştığını keşfedersiniz. Yeni bir benzersizlik kontrolü artık o placeholder'a sahip herhangi bir müşterinin kaydedilmesini engelliyor.

Bırakılabilecek minimal repro:

• billing_email = [email protected] olan bir legacy müşteri seçin.
• Herhangi bir alanı değiştirin ve Kaydet'e tıklayın.
• API'nin billingEmail must be unique ile 400 döndürdüğünü gözlemleyin.
• UI'nın hata göstermeyip formu olduğu gibi bıraktığını gözlemleyin.

Kabul testi: API bir doğrulama hatası döndürdüğünde UI mesajı gösterir, kullanıcının düzenlemelerini korur ve hatayı hangi alanın başarısız olduğu ile açıklar.

Sonraki adımlar: test edebileceğiniz küçük bir düzeltme isteyin

Hata çoğaltılabilir ve muhtemel katmanı belirledikten sonra, küçük ve güvenli bir yama üretecek şekilde yardım isteyin.

Basit bir "vaka dosyası" paketleyin: minimal repro adımları (girdiler, ortam, rol), beklenen vs gerçek, neden UI/API/DB olduğunu düşündüğünüz ve hatayı gösteren küçük log kesiti.

Sonra isteği daraltın:

• Repro'yu düzeltmek için en küçük kod değişikliğini önerin
• Refactor'lardan kaçının, gerekmedikçe
• Nedeni basitçe açıklayın
• Küçük bir test planı ekleyin (düzeltmeyi doğrulama ve yakın neler kırılabilir)

Eğer Koder.ai (koder.ai) gibi bir vibe-coding platformu kullanıyorsanız, bu vaka-dosyası yaklaşımı öneriyi odaklı tutar. Snapshot ve rollback de küçük değişiklikleri güvenle test etmenize ve bilinen bir baseline'a dönmenize yardımcı olur.

Güvenlik, ödemeler, veri migration'ları veya üretim verisini bozabilecek her şey için deneyimli bir geliştiriciye devredin. Ayrıca değişiklik küçük bir yamadan büyümeye başlıyorsa ya da riski basitçe açıklayamıyorsanız devredin.