Tekrarlanabilir bir döngüyle Claude Code ile hata triyajı: yeniden üretme, küçültme, olası nedenleri belirleme, regresyon testi ekleme ve kontrollerle dar kapsamlı düzeltme yayınlama.
Her rapor birer tekil gizem haline geldiğinde hatalar rastgeleymiş gibi gelir. Koda dokunur, birkaç fikri dener ve umarsınız sorun kaybolur. Bazen kaybolur, ama çok şey öğrenmezsiniz ve aynı sorun farklı bir biçimde tekrar ortaya çıkar.
Hata triyajı bunun tam tersidir. Belirsizliği hızlıca azaltmanın bir yoludur. Amaç her şeyi hemen düzeltmek değildir. Amaç, muğlak bir şikayeti net, test edilebilir bir ifadeye çevirmek ve sonra o ifadeyi yanlışlayan en küçük değişikliği yapmaktır.
İşte bu yüzden döngü önemlidir: yeniden üret, küçült, kanıtla destekli olası nedenleri belirle, bir regresyon testi ekle, dar kapsamlı bir düzeltme uygula ve doğrula. Her adım spesifik bir tahmin türünü ortadan kaldırır. Adımları atlayın, sonra genellikle daha büyük düzeltmeler, yan etkiler veya aslında hiç düzeltilmemiş "düzeltildi" denilen hatalarla ödersiniz.
Gerçekçi bir örnek: Bir kullanıcı der ki: “Kaydet düğmesi bazen hiçbir şey yapmıyor.” Döngü yokken UI kodunda kazı yapıp zamanlama, durum veya ağ çağrılarında değişiklik yapabilirsiniz. Döngüyle önce “bazen”i şu hâle getirirsiniz: “bu tam koşullar altında her seferinde oluyor”, örneğin: “Başlığı düzenledikten sonra hızlıca sekme değiştirirsem, Kaydet devre dışı kalıyor.” O tek cümle zaten ilerleme demektir.
Claude Code düşünme kısmını hızlandırabilir: raporları net hipotezlere çevirir, nerelere bakılacağını önerir ve başarısız olması gereken minimal bir testi sunar. Kod, log ve son difleri tarayarak makul açıklamalar üretmede özellikle yardımcı olabilir.
Yine de önemli olanı siz doğrulamalısınız. Hatanın ortamınızda gerçek olduğunu teyit edin. İyi görünen bir hikayedense kanıta (loglar, izler, başarısız testler) öncelik verin. Düzeltmeyi olabildiğince küçük tutun, bunu bir regresyon testiyle kanıtlayın ve bir hatayı diğerine değiş tokuş etmemek için net kontrollerle doğrulayın.
Karşılığında savunabileceğiniz, açıklayabileceğiniz ve geri dönüşü engelleyebileceğiniz küçük, güvenli bir düzeltme elde edersiniz.
İyi düzeltmeler temiz bir çalışma alanı ve tek, net bir problem ifadesiyle başlar. Claude'a soru sormadan önce bir rapor seçin ve şu cümleyi şu biçimde yeniden yazın:
“Quando ben X yapınca Y bekliyorum, ama Z alıyorum.”
Bu cümleyi yazamıyorsanız henüz bir hata yoktur; bir gizeme sahipsiniz.
Önceden temel bilgileri toplayın ki sürekli geri dönmeyin. Bu ayrıntılar önerileri muğlaklıktan çıkarıp test edilebilir kılar: uygulama sürümü veya commit (ve yerel, staging veya prod olduğu), ortam ayrıntıları (OS, tarayıcı/cihaz, feature flagleri, bölge), kesin girdiler (form alanları, API payload, kullanıcı eylemleri), kim görüyor (herkes, bir rol, tek bir hesap/tenant), ve “beklenenin” ne anlama geldiği (yazım, UI durumu, durum kodu, iş kuralı).
Sonra kanıtı taze iken saklayın. Tek bir zaman damgası saatler kazandırabilir. Olay çevresindeki logları yakalayın (mümkünse istemci ve sunucu), ekran görüntüsü veya kısa kayıt, request ID veya trace ID, kesin zaman damgaları (zaman dilimi ile) ve sorunu tetikleyen en küçük veri snippet'ini kaydedin.
Örnek: Koder.ai tarafından oluşturulmuş bir React uygulaması “Ödeme başarılı” gösteriyor ama sipariş "Beklemede" kalıyor. Kullanıcı rolünü, tam sipariş ID'sini, API yanıt gövdesini ve o request ID için sunucu log satırlarını not edin. Artık Claude'dan elveda el hareketleriyle değil, tek bir akışa odaklanmasını isteyebilirsiniz.
Son olarak bir durdurma kuralı belirleyin. Koda başlamadan önce neyin düzelme sayılacağını kararlaştırın: belirli bir testin geçmesi, bir UI durumunun değişmesi, loglarda hatanın artık görünmemesi ve her seferinde çalıştıracağınız kısa bir doğrulama kontrol listesi. Bu, semptomu “düzeltip” yeni bir hata yayınlamaktan sizi alıkoyar.
Karışık bir hata raporu genelde gerçekleri, varsayımları ve hayal kırıklığını karıştırır. Yardım istemeden önce bunu Claude'un kanıtla cevap verebileceği net bir soruya dönüştürün.
Bir cümlelik özetle başlayın: özelliğin adını ve başarısızlığı isimlendiren bir cümle. İyi: “Taslağı kaydetme mobilde bazen başlığı siliyor.” Kötü: “Taslaklar bozuk.” O cümle tüm triyaj dizisinin çapa noktası olur.
Sonra gördüğünüzü beklentiğinizden ayırın. Sıkıcı ve somut tutun: tıkladığınız tam buton, ekrandaki mesaj, log satırı, zaman damgası, cihaz, tarayıcı, branch, commit. Eğer bunlar yoksa belirtin.
Yapıştırılabilir basit bir yapı:
Eksik detaylar varsa, insanların hızlı cevaplayabilmesi için bunları evet/hayır soruları olarak sorun: Temiz bir hesaptan oluyor mu? Sadece mobilde mi? Sadece yeniledikten sonra mı başladı? Gizli sekmede yeniden üretilebilir mi?
Claude aynı zamanda iyi bir “rapor temizleyici”dir. Orijinal raporu (screenshot'tan kopyalanmış metinler, loglar, sohbet parçaları dahil) yapıştırın, sonra şöyle deyin:
“Bunu yapılandırılmış bir kontrol listesi olarak yeniden yaz. Çelişkileri işaretle. En önemli 5 eksik bilgiyi evet/hayır soruları olarak listele. Henüz neden tahmin etme.”
Eğer bir ekip arkadaşı “rastgele başarısız oluyor” diyorsa, onu test edilebilir bir şeye ittirin: “iPhone 14, iOS 17.2'de 10 denemeden 2'sinde, Save'e hızlıca iki kere tıkladığımda başarısız oluyor.” Artık kasıtlı olarak yeniden üretebilirsiniz.
Hatayı talep üzerine oluşturamıyorsanız, sonraki her adım tahmine dayanır.
Sorunu gösterebilecek en küçük ortamda yeniden üretmeye başlayın: local dev build, minimal branch, küçük bir veri seti ve mümkün olduğunca az servis açık.
Kimsenin soru sormadan takip edebilmesi için tam adımları yazın. Kopyala-yapıştır dostu olsun: komutlar, ID'ler ve örnek payload'lar tam olarak kullanıldığı gibi dahil edilmeli.
Basit bir yakalama şablonu:
Sıklık stratejinizi değiştirir. "Her zaman" hataları hızlı yineleme için iyidir. "Bazen" hatalar genellikle zamanlama, cache, yarış durumu veya gizli durumlara işaret eder.
Yeniden üretme notlarına sahip olduktan sonra, Claude'dan uygulamayı yeniden yazmadan belirsizliği azaltacak hızlı kontroller isteyin. İyi kontroller küçük olmalıdır: başarısız sınırda bir log satırı (girdiler, çıktılar, ana durum), tek bir bileşen için debug flag, deterministik davranış zorlaması (sabit rastgele/saati sabitleme, tek worker), sorunu tetikleyen küçük seed veri seti veya tek bir istek/yanıt çiftini yeniden oynatma.
Örnek: bir kayıt akışı "bazen" başarısız oluyor. Claude, üretilen kullanıcı ID'sini, e-posta normalizasyon sonucu ve unique constraint hata detaylarını loglamanızı; aynı payload'ı 10 kez tekrar etmenizi önerebilir. Hata sadece deploy sonrası ilk çalıştırmada oluyorsa, migration'ları, cache warmup'u veya eksik seed veriyi kontrol etme yönünde güçlü bir ipucu verir.
İyi bir yeniden üretme faydalıdır. Minimal bir yeniden üretme güçlüdür. Hatanın anlaşılmasını hızlandırır, debug edilmeyi kolaylaştırır ve kazara "düzeltilmeyi" daha az muhtemel kılar.
Gerekmeyen her şeyi çıkarın. Hata uzun bir UI akışı sonrası ortaya çıkıyorsa, hâlâ tetikleyen en kısa yolu bulun. Opsiyonel ekranları, feature flagleri ve alakasız entegrasyonları kaldırın; hata kaybolursa (önemli bir şeyi çıkardınız) veya kalıyorsa (gürültüyü buldunuz).
Sonra veriyi küçültün. Hata büyük bir payload gerektiriyorsa, hâlâ kıran en küçük payload'ı deneyin. Sepet 500 öğe gerektiriyorsa, 5 ile deneyin, sonra 2, sonra 1. Alanları teker teker çıkarın. Amaç, hatayı hâlâ üreten en az hareketli parçadır.
Pratik bir yöntem “yarıya indir ve yeniden test et”tir:
Örnek: bir ödeme sayfası kupon uygulandığında "bazen" çöküyor. Minimal durumda hatanın en az bir indirimli ürün, kuponun küçük harf içerdiği ve kargolamanın "pickup" olarak seçildiği durumlarda gerçekleştiğini keşfedersiniz. Bu sizin minimal case'iniz olur: bir indirimli ürün, küçük harf kupon, pickup seçeneği.
Minimal durum netleşince Claude'dan bunu küçük bir yeniden üretme iskeletine dönüştürmesini isteyin: başarısız fonksiyonu en küçük girdilerle çağıran minimal bir test, tek bir endpoint'e azaltılmış payload ile vuran kısa bir script veya tek bir route'u ziyaret eden ve tek bir eylem yapan küçük bir UI testi.
Sorunu yeniden üretebiliyor ve küçük bir test vakası elde etmişken tahmin yürütmeyi durdurun. Amaç, makul nedenlerden kısa bir listeye ulaşmak ve sonra her birini kanıtlayıp çürütmektir.
Yararlı bir kural üç hipotezle sınırlı tutmaktır. Daha fazlası olduğunda test vakası muhtemelen hâlâ çok büyük veya gözlemler çok belirsizdir.
Gördüğünüzü nerede olabileceğine çevirin. Bir UI semptomu her zaman bir UI hatası anlamına gelmez.
Örnek: bir React sayfası “Kaydedildi” toast'ı gösteriyor ama kayıt daha sonra eksik. Bu (1) UI durumu, (2) API davranışı veya (3) veritabanı yazma yoluna işaret edebilir.
Claude'dan muhtemel hata modlarını düz dilde açıklamasını isteyin, sonra her birini doğrulayacak kanıtın ne olacağını sorun. Amaç “belki”yi “şunu kontrol et”e çevirmektir.
Üç yaygın hipotez ve toplanacak kanıtlar:
Notlarınızı sıkı tutun: semptom, hipotez, kanıt, karar. Bir hipotez gerçeklerle uyuştuğunda, regresyon testini kilitleyip yalnızca gerekli olanı düzeltmeye hazırsınız.
İyi bir regresyon testi emniyet kemerinizdir. Hatanın var olduğunu kanıtlar ve gerçekten düzeltip düzeltmediğinizi gösterir.
Önce hataya uyan en küçük testi seçin. Hata sadece birden fazla parçanın bir araya gelmesine bağlıysa unit testi kaçırabilir.
Tek bir fonksiyon yanlış değer döndürüyorsa unit test kullanın. Parçalar arasındaki sınır sorunları için integration test, tam kullanıcı akışı gerekiyorsa end-to-end kullanın.
Claude'dan bir şey yazmasını istemeden önce minimalize edilmiş durumu katı beklenen davranış olarak yeniden ifade edin. Örnek: “Kullanıcı boş başlık kaydetmeye çalıştığında API 400 döndürecek ve mesaj 'title required' olacak.” Şimdi testin net bir hedefi vardır.
Sonra Claude'dan önce başarısız olan bir test taslağı isteyin. Kurulumu minimal tutun ve hatayı tetikleyen veriyi aynen kopyalayın. Testin adını kullanıcının deneyimini yansıtacak şekilde koyun, iç fonksiyon ismine göre değil.
Hızlı bir kontrol yapın:
Test doğru nedenle başarısız oluyorsa, dar kapsamlı bir düzeltme uygulamak için hazırsınız.
Küçük bir repro ve başarısız bir regresyon testiniz varken "temizleme" dürtüsüne karşı koyun. Amaç, testi doğru nedenle geçiren en küçük değişikliği yapmaktır.
İyi bir dar düzeltme en küçük yüzey alanını değiştirir. Hata bir fonksiyondaysa o fonksiyonu düzeltin, tüm modülü değil. Bir sınır kontrolü eksikse, zincirin tamamında değil, sınırda kontrol ekleyin.
Claude'dan yardım alıyorsanız iki düzeltme seçeneği isteyin ve kapsam ile risk açısından karşılaştırın. Örnek: React formu bir alan boşken çökerse:
Seçenek A genelde daha küçük, incelemesi kolay ve başka bir şeyi kırma olasılığı daha düşüktür.
Düzeltmeyi dar tutmak için mümkün olduğunca az dosyaya dokunun, yerel düzeltmeleri refaktordan önce tercih edin, kötü değer girilen sınırda gard ve validasyon ekleyin ve davranış değişikliğini tek açık before/after ile bırakın. Sebep açık değilse yorum ekleyin.
Somut örnek: Go API endpoint'i opsiyonel query parametresi eksik olduğunda panic yapıyorsa, dar düzeltme handler sınırında boş string'i ele almak (varsayılanla parse etmek veya 400 dönmek) olur. Paylaşılan parsing yardımcılarını değiştirmekten kaçının; eğer regresyon testi hatanın paylaşılan koddaki olduğunu kanıtlıyorsa refactor düşünün.
Değişiklikten sonra başarısız testi ve bir iki yakın testi yeniden çalıştırın. Düzeltmeniz birçok alakasız testi güncellemeye zorluyorsa, bu değişiklik çok geniş demektir.
Doğrulama, tek bir testi geçen ama yakın yolları bozan, hata mesajını değiştiren veya yavaş sorgu ekleyen küçük sorunları yakaladığınız yerdir.
Önce eklediğiniz regresyon testini tekrar çalıştırın. Geçerse, komşu testleri çalıştırın: aynı dosya, aynı modül ve aynı girdileri kapsayan testler. Hatlar genelde paylaşılan yardımcılar, parsing, sınır kontrolleri veya cache içinde saklanır; bu yüzden en alakalı başarısızlıklar genelde yakın çevrede görünür.
Ardından orijinal rapordaki adımları kısa ve spesifik şekilde manuel olarak kontrol edin: aynı ortam, aynı veri, aynı tıklama/sekans. Rapor muğlaksa, yeniden üretirken kullandığınız tam senaryoyu test edin.
Odaklanmanızı korumak isterseniz, Claude'dan değişikliğiniz ve başarısız senaryoya göre kısa bir doğrulama planı isteyin. Hangi dosyayı değiştirdiğinizi, amaçladığınız davranışı ve nelerin etkilenebileceğini paylaşın. En iyi planlar kısa ve yürütülebilirdir: dakikalar içinde bitirebileceğiniz her biri net pass/fail olan 5–8 kontrol.
Son olarak, neyi doğruladığınızı PR veya notlarda kaydedin: hangi testleri çalıştırdınız, hangi manuel adımları denediniz ve neleri test etmediğiniz. Bu, düzeltmenin güvenilirliğini artırır.
Zaman kaybetmenin en hızlı yolu, hatayı talep üzerine yeniden üretemeden bir “düzeltmeyi” kabul etmektir. Hata güvenilir olarak tekrarlanamıyorsa, neyin gerçekten iyileştiğini bilemezsiniz.
Pratik kural: tekrarlanabilir bir kurulum (kesin adımlar, girdiler, ortam ve "yanlış" ne demek) tanımlamadan düzeltme istemeyin. Rapor muğlaksa, ilk dakikalarınızda onu iki kez çalıştırıp aynı sonucu alabileceğiniz bir kontrol listesine çevirin.
Tekrarlanabilir vaka olmadan düzeltme yapmak. Minimum “her seferinde başarısız olan” bir script veya adımlar isteyin. Eğer sadece "bazen" oluyorsa, zamanlama, veri boyutu, feature flag ve logları yakalayana kadar devam edin.
Çok erken küçültme. Orijinal başarısızlığı doğrulamadan vakayı fazlaca küçültürseniz sinyali kaybedebilirsiniz. Önce baz hattı kilitleyin, sonra birer birer küçültün.
Claude'a tahmin yaptırmak. Claude muhtemel nedenler önerebilir ama yine de kanıt gerekir. 2–3 hipotez isteyin ve her biri için doğrulayacak gözlemi (bir log satırı, breakpoint, sorgu sonucu) belirtmesini sağlayın.
Yanlış nedenle geçen regresyon testleri. Bir test, başarısız yoluna asla girmediği için “geçiyor” olabilir. Testin düzeltmeden önce başarısız olduğundan ve beklenen mesaj/asseration ile başarısız olduğundan emin olun.
Belirtilen semptom yerine tetikleyeni düzeltmek. Eğer null kontrolü ekliyorsanız ama gerçek sorun "bu değerin asla null olmaması gerektiği" ise, daha derin bir hatayı gizleyebilirsiniz. Kötü durum yaratan koşulu düzeltmeyi tercih edin.
Yeni regresyon testini ve orijinal yeniden üretme adımlarını değişiklikten önce ve sonra çalıştırın. Örneğin bir checkout hatası yalnızca bir promosyon kodu uygulandıktan sonra kargo değiştirilince oluyorsa, tam o diziyi "gerçek" olarak saklayın, minimalist testiniz ne kadar küçük olursa olsun.
Doğrulama "şimdi iyi görünüyor"ye dayanıyorsa, bir log, bir metrik veya belirli bir çıktı gibi somut bir kontrol ekleyin ki bir sonraki kişi hızlıca doğrulayabilsin.
Zaman baskısı altındayken küçük, tekrarlanabilir bir döngü kahramanca debuggingden daha iyidir.
Son kararı birkaç satırda yazın ki sonraki kişi (çoğu zaman gelecekteki siz) güvenebilsin. Kullanışlı format: “Kök neden: X. Tetikleyici: Y. Düzeltme: Z. Neden güvenli: W. Değiştirilmeyenler: Q.”
Sonraki adımlar: otomatikleştirebileceğiniz ne varsa otomatikleştirin (kaydedilmiş repro scripti, standart test komutu, kök-neden notları için bir şablon).
Eğer Koder.ai ile uygulamalar geliştiriyorsanız (Koder.ai), Planning Mode değişiklik öncesi adımları taslaklamanıza yardımcı olabilir ve anlık görüntüler/geri alma deney sırasında güvenle deneme yapmayı kolaylaştırır. Düzeltme doğrulandıktan sonra kaynak kodunu dışa aktarabilir veya güncellenmiş uygulamayı dağıtıp barındırabilirsiniz; gerektiğinde özel bir alan adıyla paylaşma seçeneği de vardır.
Hata triyajı, muğlak bir bildirimi açık, test edilebilir bir ifadeye dönüştürme ve sonra o ifadenin artık doğru olmadığını gösteren en küçük değişikliği yapma alışkanlığıdır.
Bu, "her şeyi düzeltmek"ten çok belirsizliği adım adım azaltmakla ilgilidir: yeniden üretme, küçültme, kanıta dayalı hipotez kurma, regresyon testi ekleme, dar kapsamlı düzeltme ve doğrulama.
Çünkü her adım farklı bir tür tahmini ortadan kaldırır.
Şunu şu şekilde yeniden yazın: “When I do X, I expect Y, but I get Z.”
Ardından test edilebilir kılmak için gereken kadar bağlam toplayın:
Genellikle sorunu gösterebilecek en küçük ortamda yeniden üretebildiğinizi doğrulayın (çoğunlukla local dev ve küçük bir veri seti).
Eğer "bazen" oluyorsa, değişkenleri kontrol altına alarak deterministik hale getirmeye çalışın:
Talimat: talimatı değiştirmeden önce talimatı tekrarlanabilir hale getirin; aksi halde sadece tahmin ediyorsunuz demektir.
Kısaltma, hatayı korurken gereksiz olan her şeyi çıkarmak demektir.
Pratik yöntem: "yarıya indir ve yeniden test et":
Hem adımları (kısa kullanıcı akışı) hem de veriyi (daha küçük payload, daha az item/alan) küçültün.
Claude Code'u analiz hızlandırmak için kullanın, yerine geçirmesine izin vermeyin.
İyi istekler şöyle görünür:
Sonra doğrulayın: localde yeniden üretin, log/trace kontrolü yapın ve testin doğru nedenle başarısız olduğunu onaylayın.
Üç hipotezle sınırlayın. Daha fazlası genellikle repro'nun hâlâ çok büyük olduğunu veya gözlemlerin çok belirsiz olduğunu gösterir.
Her hipotez için şunu yazın:
Hatanın gerektirdiği minimum test seviyesini seçin:
İyi bir regresyon testi:
Testi geçiren en küçük değişikliği yapın.
İpuçları:
Kısa bir kontrol listesi kullanın ve hızlıca uygulayın:
Yaptıklarınızı PR veya notlara kaydedin: hangi testleri çalıştırdınız, hangi manuel adımları denediniz ve neleri test etmediğiniz gibi bilgiler güveni artırır.
Bu, ilerlemeyi zorlar ve sonsuz "belki X'tir" hata ayıklamayı durdurur.
