CI Hataları için Claude Code: küçük düzeltmeler ve testler için istemler

CI başarısız olduğunda ve yapay zekâ tahmin yürüttüğünde neler yanlış gider\n\nBir CI hatası genellikle gizemli değildir. Log size nerede durduğunu, hangi komutun başarısız olduğunu ve hata mesajını söyler. İyi bir run, bir stack trace, dosya ve satır numarasıyla bir derleyici hatası veya hangi assertion'ın başarısız olduğunu gösteren bir test raporu içerir. Bazen expected X, got Y gibi diff tarzı bir ipucu ya da lint, build veya migrate database gibi belirgin bir başarısız adım bile alırsınız.\n\nGerçek sorun, insanların (ve AI'nın) logu arka plan gürültüsü gibi muamele etmesi. Uzun bir log yapıştırıp "bir düzeltme" istediğinizde, birçok model son anlamlı satırları okumak yerine tanıdık bir açıklamaya atlar. Hata yaygın görünüyorsa (module not found, timeout, permission denied) tahminler daha da kötüleşir. Sonuç olarak, gerçek başarısızlığa uymayan büyük bir yeniden yazım, yeni bir bağımlılık veya "her şeyi güncelleyin" gibi bir cevap alırsınız.\n\nAma amaç "her nasıl olursa geçmesini sağlamak" değil. Amaç daha basit:\n\n- Başarısız çıktıyı okuyun.\n- Başarısız adımı geçirecek en küçük değişikliği tespit edin.\n- Her şeyi olduğu gibi tutun.\n\nUygulamada, "en küçük düzeltme" genellikle şunlardan biridir: tek bir yerde birkaç satırlık kod değişikliği, eksik bir import veya yanlış yol, CI ortamı için açıkça yanlış bir konfigürasyon değeri veya yeniden tasarlamak yerine kazara yapılan bozucu bir değişikliğin geri alınması.\n\nTakip testi de önemlidir. CI bir kere geçmesi, tekrarları önlemekle aynı şey değildir. Hata bir kenar durumundan kaynaklandıysa (null girdi, zaman dilimi, yuvarlama, izinler), düzeltilmeden önce başarısız olan ve düzelttikten sonra geçen bir regresyon testi ekleyin. Bu tek seferlik kurtarmayı bir muhafaza hattına dönüştürür.\n\n## Yardım istemeden önce toplamanız gerekenler\n\nÇoğu kötü düzeltme eksik bağlamla başlar. Eğer sadece son kırmızı satırı yapıştırırsanız, model önce ne olduğunu tahmin etmek zorunda kalır ve tahminler genellikle yeniden yazımlara dönüşür.\n\nBirinin hatayı ilk gerçek hatadan sona kadar takip edebilmesi ve mümkün olduğunca az değiştirmesi için yeterli ayrıntı sağlamayı hedefleyin.\n\nMesajınıza şunları (mümkünse harfi harfine) kopyalayın:\n\n- İlk hata satırından sonuna kadar tam başarısız log (sadece son stack trace değil).\n- CI'nin çalıştırdığı tam komut (örneğin go test ./..., npm test, flutter test, golangci-lint run).\n- Hata mesajında geçen dosya yolları ve ilgili konfigürasyonlar (test konfigürasyonu, linter ayarları, build scriptleri).\n- Yakın zamanda ne değişti: PR diff özeti, dependency güncellemeleri, CI konfigürasyon düzenlemeleri.\n- Flaky mi: elinizde birkaç başarısız run ve bir başarılı run varsa bunu belirtin.\n\nKısıtları açıkça düz metinle ekleyin. Küçük bir düzeltme istiyorsanız bunu söyleyin: refactor yok, davranış değişikliği yok (zorunlu değilse), yamanın başarısız alana sınırlı olması.

\nBasit bir örnek: Bir dependency güncellemesinden sonra CI lint adımında başarısız oluyor. İlk uyarıdan itibaren lint çıktısını yapıştırın, CI'nin kullandığı komutu ekleyin ve tek paket sürüm değişikliğini belirtin. Bu, depoyu yarısını yeniden formatlamak yerine tek satırlık bir konfigürasyon düzeltmesi veya küçük bir kod değişikliği önermeye yeter.\n\nEğer kopyala-yapıştır kullanılabilir bir şey isterseniz, bu yapı genellikle yeterlidir:\n\n\n\n## Başarısız çıktıyı okumaya zorlayan istem kuralları\n\nBir model CI kırılmasında hata yaptığında genellikle bunun nedeni isteminizin ona tahmin yapma izni vermesidir. İşiniz, modelin "çalışmasını göstermesini" sağlamak için tam başarısız çıktıyı kullanmaya zorlamak ve ardından işi geçirebilecek en küçük değişikliğe bağlı kalmasını sağlamaktır.\n\n### Modeli dürüst tutan kurallar\n\nKanıt ve küçük bir plan isteyin. İyi bir istem beş şeyi zorunlu kılar:\n\n- CI logundan kullanılan kesin başarısız satırları (hatalar, stack trace, dosya:satır) alıntılayın ve açıkça "Bu satırları kullanıyorum." deyin.\n- Bir cümlelik teşhis verin, çekinmeden.\n- 1–3 düzenleme içeren minimal bir yama planı önerin, dokunacağı tam dosya yollarını adlandırın.\n- İlişkisiz değişikliklerden kaçının (formatlama, yeniden adlandırma, refactor, dependency bump) onayınız yoksa.\n- Emin olmadığı noktaları ve teşhisi doğrulayacak tek bir bilgi parçasını listeleyin.\n\nBilinmezlik sorun değil; gizlenen belirsizlik zaman kaybıdır.\n\n### Kopyala-yapıştır hazır istem parçası\n\nCI sorunuzun en üstüne bunu yapıştırın:\n\n\n\nEğer log ve bir stack trace içinde diyorsa, bu yapı yanıtı o fonksiyona ve küçük bir koruma veya hata işleme değişikliğine yönlendirir; uç noktanın yeniden tasarımına değil.\n\n## CI hataları için kopyala-yapıştır istem şablonu\n\nEn hızlı kazanımlar, logu alıntılamaya zorlayan, kısıt içinde kalan ve eksik bilgi olduğunda durdurmayı sağlayan bir istemden gelir.\n\n\n\nİki ayrıntı geri dönüşleri azaltır:\n\n- Tam başarısız komutu ve ilk hatayı ekleyin (sadece son özet değil).\n- Birden çok hata varsa, hangisini önce düzeltmek istediğinizi söyleyin (genellikle logdaki ilk gerçek hata).\n\n## En küçük düzeltmeyi sağlamak için nasıl baskı yapılır\n\nZaman kaybetmenin en hızlı yolu, beş şeyi birden değiştiren bir "temizlik" yamasını kabul etmektir. "Minimal"i baştan tanımlayın: başarısız işi geçiren en küçük diff, en düşük riskle ve doğrulaması en hızlı olanı.\n\nBasit bir kural işe yarar: önce semptomu düzeltin, sonra geniş bir refactor'ın gerekip gerekmediğine karar verin. Log bir dosyaya, bir fonksiyona, bir eksik import ya da bir kenar durumuna işaret ediyorsa oraya odaklanın. "Bu fırsattan yararlanıp" yapılan değişikliklerden kaçının.\n\nGerçekten alternatiflere ihtiyacınız varsa, iki tane ve sadece iki tane isteyin: "en güvenli minimal düzeltme" vs "en hızlı minimal düzeltme." Ticaret-off'ları istiyorsunuz, menü değil.\n\nAyrıca, CI hattının çalıştırdığı aynı komutu yerelde çalıştırarak doğrulamayı zorunlu kılın (ya da en yakın eşdeğerini):\n\n\n\nEğer yanıt büyük bir değişiklik öneriyorsa, geri çekin ve şunu isteyin: "Başarısız assertion'ı düzelten en küçük yamanın gösterimini yap, alakasız formatlama veya yeniden adlandırma yok."\n\n## Tekrarları önleyen takip testi istemek için yönlendirme\n\nBir yama test olmadan, aynı hatanın tekrar olmayacağına dair bir bahis oynarsınız. Düzeltmeden sonra her zaman bir takip testi isteyin ki eski kodda başarısız olan, yeni kodda geçen bir test olsun.\n\n"İyi"nin ne olduğuna dair net olun: \n- Eğer hata bir birim test çökmesiyse, yeni bir test veya daha güçlü bir assertion istenebilir.\n- Eğer hata build, lint veya format kuralından kaynaklıysa, aynı hatayı önleyecek bir kontrol eklemek istenir.\n\nKullanışlı bir kalıp dört şeyi şart koşar: testi nereye koymak gerektiği, ne ad vereceğiniz, hangi davranışı kapsayacağı ve neden bunun gelecekte benzer hataları yakalayacağını açıklayan kısa not.\n\nKopyala-yapıştır eklentisi:\n\n- Düzeltmeden önce main dalında başarısız olacak ve düzelttikten sonra geçen bir regresyon testi yazın.\n- Hata sınıfını hedefleyin, sadece kırılan satırı hedeflemeyin.\n- Testi şuraya koyun: <path or folder>. İsimlendirme: <your convention>.\n- Eğer bu bir lint/build kuralıysa, kuralı ekleyin veya sıkılaştırın.\n- 2-3 cümle: neden bu test benzer bir hatayı yakalar?\n\nÖrnek: CI, boş bir string ID alındığında bir panic gösteriyorsa, "bu satır için bir test" demeyin. Bunun yerine geçersiz ID'leri (boş, whitespace, yanlış format) kapsayan bir test isteyin. En küçük düzeltme muhtemelen 400 döndüren bir guard clause olur. Takip testi birden çok geçersiz giriş için davranışı doğrulamalıdır, böylece parsing'i refactor eden biri fallback'i kaldırırsa CI tekrar başarısız olur.\n\nProjede test konvansiyonlarınız varsa bunları belirtin. Yoksa yakın testlere benzer şekilde yeni testi yazmasını isteyin ve yeni testi minimal ve okunabilir tutun.\n\n## Yeniden kullanabileceğiniz adım adım iş akışı\n\n### 1) Hatayı olduğu gibi verin\n\nHata içeren CI log bölümünü (ilk hata ve 20-40 satır yukarısı dahil) yapıştırın. Ayrıca başarısız komutu ve önemli ortam detaylarını (OS, runtime sürümleri, önemli bayraklar) ekleyin.\n\nSonra ondan hatayı düz İngilizceyle tekrarlamasını ve hangi satır(lar)ın buna kanıt olduğunu belirtmesini isteyin. Eğer logu alıntılayamıyorsa, gerçekten okumamıştır.\n\n### 2) En küçük yamayı talep edin\n\nCI komutunu geçiren en küçük kod değişikliğini isteyin. Refactorlara itiraz edin. Uygulamadan önce şunları listeleyin: \n- Dokunacağı dosyalar\n- Tam olarak hangi davranışın değişeceği\n- Neyi değiştirmeyeceği\n\n### 3) Aynı komutu tekrar çalıştırın, döngüyü dar tutun\n\nYamayı uygulayın ve başarısız olan tam komutu yerelde (veya CI'de) yeniden çalıştırın. Hala başarısızsa, sadece yeni başarısız çıktıyı yapıştırın ve tekrar edin. Küçük bağlamlı yinelemeler yanıtı odaklı tutar.\n\n### 4) Hata sınıfı için bir regresyon testi ekleyin\n\nYeşil olduysa, düzeltmeden önce başarısız ve düzeltmeden sonra geçen tek bir takip testi ekleyin. Hedefe yönelik: bir test, bir neden.\n\nYeni testi de dahil ederek komutu bir daha çalıştırın, böylece hatayı sadece susturmadığınızdan emin olun.\n\n### 5) Temiz bir PR paketi ile bitirin\n\nKısa bir commit mesajı ve PR açıklaması isteyin: ne başarısız oldu, ne değişti, nasıl doğruladınız ve hangi test tekrarları önlüyor. İnceleyenler nedenleri açıkça yazıldığında daha hızlı ilerler.\n\n## Gerçekçi bir örnek: başarısız çıktısından düzeltme ve teste kadar\n\nYaygın bir senaryo: Her şey yerelde çalışıyor, sonra küçük bir değişiklik CI runner'da testleri bozar. Buradaki örnek bir Go API'sinden: handler artık sadece tarihsiz bir değer () kabul etmeye başladı ama kod hâlâ yalnızca RFC3339 zaman damgalarını parse ediyor.\n\nYapıştırılacak snippet şu şekilde (kısa tutun, ama hata satırını ekleyin):\n\n\n\nŞimdi logu kullanan, minimal düzeltme ve bir test isteyen bir istem kullanın:\n\n\n\nİyi bir yanıt parse formatı uyumsuzluğuna işaret eder ve tek bir fonksiyonda ( gibi) küçük bir değişiklik yapar: önce RFC3339'u deneyip başarısız olursa formatına düşürme. Refactor yok, yeni paket yok.\n\nRegresyon testi muhafaza hattıdır: gönderip bekleyen bir test ekleyin. Birisi daha sonra fallback'i kaldırırsa CI aynı hatayla tekrar başarısız olur.\n\n## Zaman kaybettiren yaygın hatalar (ve nasıl önlenir)\n\nSorunun faydalı kısmını gizleyen kırpılmış log göndermek saatinizi çalar. CI logları gürültülü olabilir ama işe yarayan kısım genellikle son hata öncesindeki ~20 satırdır.\n\nBir tuzak sadece son kırmızı satırı yapıştırmaktır (ör. ) ve gerçek sebebi daha erken gizlemektir (eksik env var, başarısız snapshot veya çökmeden önceki ilk test). Düzeltme: ilk gerçek hata satırını ve kullanılan komutu ekleyin.\n\nBir diğer zaman kaybı modeli “temizleme” değişiklikleriyle serbest bırakmaktır. Fazladan formatlama, dependency bump veya refactor incelemeyi zorlaştırır ve başkasını kırma riskini artırır. Düzeltme: kapsamı en küçük kod değişikliğiyle kilitleyin ve alakasız her şeyi reddedin.\n\nDikkat etmeniz gereken birkaç örüntü: \n- Sadece son hata satırını yapıştırmak: ilk hatayı ve başarısız komutu dahil edin.\n- Bağımsız dosyaları değiştirmesine izin vermek: minimal diff ve her değiştirilen dosya için gerekçe isteyin.\n- CI komutuyla doğrulanmamış bir düzeltmeyi kabul etmek: aynı komutu yeniden çalıştırın.\n- Hata geri geldiğinde hâlâ geçen bir test yazmak: eski koda karşı başarısız olan ve yeni kodda geçen bir test gerektirin.\n- Flaky testleri gerçek regresyonlarla karıştırmak: rastgelelikten şüpheleniyorsanız önce deterministik hale getirin.\n\nEğer flakiness şüphesi varsa, retry ile üstünü örtmeyin. Rastgeleliği kaldırın (sabit zaman, seedlenmiş RNG, izole temp dizinleri) ki sinyal net olsun.\n\n## Değişikliği göndermeden önce hızlı kontroller\n\nGöndermeden önce kısa bir akıl kontrolü yapın. Amaç değişikliğin gerçek, minimal ve tekrarlanabilir olduğunu doğrulamaktır, şans eseri başarılı bir run değil.\n\n- Kanıt: Açıklama logdaki tam başarısız satırları alıntılıyor mu?\n- Kapsam: Değişiklikler sadece bu hatayı durdurmak için gerekli mi?\n- Nedensellik: Değişiklik başarısızlığı nasıl geçerli bir şekilde çevirdiğini açıklıyor mu?\n- Tekrarlanabilirlik: Aynı CI komutunu yeniden çalıştırdınız mı (aynı bayraklar, aynı çalışma dizini)?\n- Regresyon: Yeni test yama öncesi başarısız mıydı ve yama sonrası geçiyor mu?\n\nSon olarak, tek başarısız işe göre daraltılmış test setinin biraz daha geniş olanını çalıştırın (ör. lint + birim testler). Yaygın bir tuzak, orijinal işi geçiren ama başka hedefi bozan bir düzeltmedir.\n\n## Sonraki adımlar: bu iş akışını alışkanlık haline getirin\n\nBunu haftadan haftaya zaman kazandırmak istiyorsanız, istemlerinizi ve yanıt şablonunuzu takım prosedürü gibi saklayın. Amaç tekrarlanabilir girdiler, tekrarlanabilir çıktılar ve daha az "gizemli düzeltmeler".\n\nEn iyi isteminizi depoda bir snippet olarak kaydedin ve ekip sohbetinde sabitleyin. Yanıt yapısını standartlaştırın: (1) kanıt, (2) bir cümlelik sebeplendirme, (3) en küçük değişiklik, (4) takip testi, (5) yerelde nasıl doğrulanacağı. Herkes aynı formatı kullandığında, inceleyenler nerelere bakacaklarını bilir ve süreç hızlanır. \nEğer sohbet-öncelikli bir iş akışını tercih ediyorsanız, aynı düzeltme-ve-test döngüsünü Koder.ai içinde çalıştırabilir, denemeler sırasında snapshot'lar kullanabilir ve repo'ya geri aktarmaya hazır olduğunuzda kaynak kodunu dışa aktarabilirsiniz.