Editör Notu: Ocak 2026'da Andrej Karpathy, Claude'nin kod yazma konusundaki eleştirileri, AI kodlama akışında görünürde küçük ancak son derece kritik bir dosya olan CLAUDE.md'yi ortaya çıkardı. Forrest Chang, bu sorunları Claude'nin kodlama sırasında sıkça yaptığı dört davranış kuralına dönüştürdü: sessiz varsayımlar, aşırı mühendislik, ilgisiz kodlara zarar verme ve net bir başarı kriteri eksikliği.

Ancak birkaç ay sonra, Claude Code'un kullanım senaryoları artık sadece “modelin bir kod parçası yazması” değil. Çok adımlı Agent, hook zincirleme tetikleme, beceri yükleme ve çoklu kod deposu iş birliğinin standart hale gelmesiyle yeni başarısızlık modelleri ortaya çıkmaya başladı: model uzun görevlerde kontrolünü kaybediyor, testler geçiyor ama gerçek mantık doğrulanmıyor, taşıma tamamlanıyor ancak hatalar sessizce atlanıyor, farklı kod stilleri yanlış şekilde karıştırılıyor.

Yazar, 6 hafta içinde 30 kod deposunu test etti ve Karpathy'nin orijinal 4 kuralına 8 yeni kural ekleyerek, AI programlamada tek seferlik tamamlamadan Agent tabanlı işbirliğine geçişle ortaya çıkan yeni sorunları kapsamayı amaçladı.

Aşağıda orijinal metin yer almaktadır:

2026 yılının Ocak sonunda, Andrej Karpathy, Claude'nin kod yazma şeklini eleştiren bir tweet dizisi paylaştı. Üç tipik sorunu belirtti: Açıklama yapılmadan yanlış varsayımlarda bulunmak, gereksiz karmaşıklık eklemek ve değiştirilmesi gerekmayan kodlara ilgisiz zarar vermek.

Forrest Chang, bu tweet zincirini gördü ve şikayetleri 4 adet davranış kuralına dönüştürerek ayrı bir CLAUDE.md dosyasına yazdı ve GitHub'a yayınladı. Bu proje ilk gününde 5.828 Star aldı, iki hafta içinde 60.000 kez收藏 edildi ve如今 120.000 Star'a ulaştı, 2026 yılının en hızlı büyüyen tek dosyalı kod deposu oldu.

Daha sonra, 6 hafta boyunca 30 kod deposuyla test ettim.

Bu 4 kural gerçekten etkili. Geçmişte yaklaşık %40 olasılıkla ortaya çıkan hatalar, bu kuralların etkili olduğu görevlerde %3'ün altına düştü. Ancak sorun, bu şablonun başlangıçta Ocak ayında Claude'in kod yazarken yaptığı hataları çözmek için oluşturulmuş olması.

2026 Mayıs'ına gelindiğinde, Claude Code ekosistemiyle karşılaşılan sorunlar farklı hale gelmişti: Araçlar arasında çatışmalar, hook zincirleme tetiklemeler, beceri yükleme çakışmaları ve oturumlar arası çok adımlı iş akışlarının kesilmesi gibi.

Bu yüzden 8 yeni kural daha ekledim. İşte tam 12 kural versiyonu: CLAUDE.md: Her birinin neden eklenmesi gerektiği ve orijinal Karpathy şablonunun nerede 4 yerde sessizce başarısız olacağı.

Açıklamaları atlamak ve doğrudan kopyalamak istiyorsanız, tam dosya sonunda yer almaktadır.

Neden bu önemli

Claude Code'in CLAUDE.md dosyası, tüm AI programlama teknoloji yığınında en az değer verilen dosyadır. Çoğu geliştirici genellikle üç tür hata yapar:

Birincisi, bunu bir tercih çöp kutusu gibi düşünün ve tüm alışkanlıklarınızı içine koyun, sonunda 4000'den fazla token'e ulaşın ve kurallara uygunluk oranı %30'a düşün.

İkinci olarak, tamamen kullanmamak ve her seferinde yeniden prompt vermek. Bu, token kullanımında 5 katlık bir kayba neden olur ve oturumlar arasında tutarlılık eksikliği yaratır.

Üçüncü olarak, bir şablonu kopyaladıktan sonra hiç ilgilenmeyin. İki hafta boyunca işe yarayabilir, ancak kod tabanı değiştiğinde farkında olmadan işlevini kaybeder.

Anthropic'in resmi belgesi açıkça şunu söylüyor: CLAUDE.md temelde önerisel bir rehberdir. Claude, bunu yaklaşık %80 zaman takip eder. 200 satırın üzerinde çıktığında, önemli kurallar gürültüyle gömüldüğü için uyum oranı belirgin şekilde düşer.

Karpathy'nin şablonu bu sorunu çözdü: bir dosya, 65 satır, 4 kural. Bu en düşük temeldir.

Ancak üst sınır daha da artırılabilir. Aşağıdaki 8 kural eklendikten sonra, Karpathy'nin Ocak 2026'da şikayet ettiği kod yazma sorunları değil, orijinal şablon oluşturulduğunda henüz mevcut olmayan, Mayıs 2026'da ortaya çıkan Agent düzenlemesi sorunlarını da kapsayacaktır.

İlk 4 kural

Forrest Chang'ın deposunu henüz görmediyseniz, önce bu temel sürümü izleyin:

Kural 1: Kodlamadan önce düşünün.

Varsayımlarda bulunmayın. Varsayımlarınızı açıklayın, tercih noktalarını ortaya koyun. Tahmin etmeden önce sorun. Daha basit bir çözüm varsa, itirazda bulunun.

Kural 2: Basitlik önceliklidir.
En az kodla sorunu çöz. Hayal edilen işlevleri eklemeyin. Tek seferlik kodlar için soyutlama katmanları tasarlamayın. Bir uzman mühendis aşırı karmaşık bulursa, basitleştirilmelidir.

Kural 3: Cerrahi düzeltmeler.
Yalnızca değiştirilmesi gereken kısımları değiştirin. Komşu kodu, yorumları veya formatı elde etmek için "iyileştirme" yapmayın. Bozulmayan şeyleri yeniden yapılandırmayın. Mevcut stille tutarlı kalın.

Kural 4: Hedefe odaklanarak uygulayın.
Başarı kriterlerini tanımlayın, ardından doğrulama tamamlanana kadar döngüye devam edin. Claude'a her adımda ne yapması gerektiğini söylemeyin, yalnızca başarılı sonuçların nasıl olması gerektiğini belirtin ve kendisinin döngü kurmasını sağlayın.

Bu 4 kural, izinsiz Claude Code oturumlarında gördüğüm yaklaşık %40 hata modelini çözebilir. Kalan yaklaşık %60 sorun, aşağıdaki boşluklarda saklıdır.

Ben eklediğim 8 kural ve nedenleri

Her kural, bir gerçek anın sonucudur: Karpathy'nin orijinal 4 kuralı yeterli değil. Aşağıda önce o senaryoyu anlatacağım, ardından ilgili kuralı vereceğim.

Karpathy'nin kuralları bu noktayı kapsamıyor. Bu nedenle model, belirleyici kodun ele alması gereken sorunları kendisi karar vermeye başlıyor: API çağrısını bir kez daha denemek, bir mesajı nasıl yönlendirmek ve işlemi ne zaman yükseltmek. Sonuç olarak, haftalık kararlar her seferinde farklı oluyor. Her token başına 0,003 dolar ücretlendirilen, kararsız bir if-else sistemi elde ediyorsunuz.

O an şöyleydi: 503 hatasıyla karşılaşıldığında yeniden denenecek mi yoksa değil mi kararı vermek için Claude’u çağıran bir kod vardı. Bu kod başta iyi çalışıyordu ve iki hafta boyunca stabil kalıyordu, ancak sonra model, istek gövdesini de karar verme bağlamına dahil etmeye başlayınca ani bir şekilde kararsız hale geldi. Yeniden deneme stratejisi rastgele hale geldi, çünkü prompt kendisi rastgeleydi.

CLAUDE.md'nin bütçe sınırlaması yoksa, bu, boş bir çek gibi bir şeydir. Her döngü, 50.000 token'lık bir bağlam dökülmesine dönüşebilir. Model kendiliğinden durmaz.

O an şöyleydi: Bir hata ayıklama oturumu 90 dakika sürdü. Model, sürekli olarak aynı 8 KB hata mesajı etrafında döndü ve hangi çözümleri zaten denediğini yavaş yavaş unuttu. Sonunda, 40 mesaj önce reddettiğim çözümleri tekrar önermeye başladı. Eğer bir token bütçesi olsaydı, bu süreç 12. dakikada durdurulmalıydı.

Kod deposundaki iki bölüm birbirine çeliştiğinde, Claude her ikisini de memnun etmeye çalışır ve sonuçta tutarsız bir kod üretir.

O an şöyleydi: Bir kod deposunda iki farklı hata işleme modeli vardı, biri async/await ve açıkça yazılmış try/catch, diğeri ise genel hata sınırı. Claude'in yazdığı yeni kod, ikisini de kullandı. Sonuç olarak hata işleme iki kez yapıldı. Hataların neden iki kez yutulduğunu anlamak 30 dakika sürdü.

Karpathy'nin "cerrahi değişiklik" yaklaşımı, Claude'a komşu kodu değiştirmemeyi söylüyor; ancak Claude'a komşu kodu önce anlamasını söylemiyor. Bu kural olmadan, Claude 30 satır uzaktaki mevcut kodlarla çakışan yeni kodlar yazabilir.

O an şöyleydi: Claude, orijinal fonksiyonu okumadan, tamamen aynı işlevi yerine getiren yeni bir fonksiyon ekledi. İki fonksiyon da aynı şeyi yapıyordu. Ancak import sırası nedeniyle yeni fonksiyon, 6 aydır gerçek tek standart olarak var olan eski fonksiyonu geçersiz kıldı.

Karpathy'nin "hedefe yönelik yürütme" kavramı, testlerin başarı ölçütü olarak kullanılabileceğini ima eder. Ancak pratikte, Claude "testlerin geçilmesini" tek hedef olarak görür ve yüzeysel testleri geçebilen ancak diğer şeyleri bozan kodlar yazar.

O an şöyleydi: Claude, bir kimlik doğrulama fonksiyonu için 12 test yazdı ve hepsi geçti. Ancak üretim ortamındaki kimlik doğrulama mantığı bozuktu. Bu testler, fonksiyonun "bir şey döndüğünü" doğruluyordu, ancak doğru şeyi döndüğünü doğrulamıyordu. Fonksiyon, sabit bir değer döndürdüğü için testleri geçiyordu.

Karpathy şablonunun varsayılan etkileşimi tek seferlik olur. Ancak gerçek Claude Code işleri genellikle çok adımlıdır: 20 dosya boyunca yeniden yapılandırma, bir oturumda özellik oluşturma, birden fazla commit arasında hata ayıklama. Kontrol noktaları olmadan, bir adımda hata yapmak tüm önceki ilerlemeyi kaybetmenize neden olabilir.

O an şöyleydi: 6 adımlık bir yeniden yapılandırma görevi 4. adımda hata yaptı. Hatayı fark ettiğimde, Claude zaten hatalı durumun üzerine 5. ve 6. adımları tamamlamıştı. Sorunu çözmek için harcanan zaman, tüm görevi yeniden yapmaktan daha uzun sürdü. Bir kontrol noktası olsaydı, 4. adımda hata tespit edilebilirdi.

Olgun bir kod tabanında, Claude kendi yazım tarzını getirmeyi sever. Bu tarz ne kadar "daha iyi" olsa da, ikinci bir tarz getirmek, tek bir tarzdan daha kötüdür.

O an şöyleydi: Claude, class component tabanlı bir React kod tabanına hooks ekledi. Çalıştı gerçekten. Ancak testler, componentDidMount'a bağımlı olduğu için kod tabanının mevcut test desenini bozdu. Sonunda silip yeniden yazmak için yarım gün harcandı.

Claude'in en pahalı hataları, başarıymış gibi görünen hatalardır. Bir fonksiyon "çalışıyor", ancak yanlış veriler döndürüyor; bir taşıma "tamamlandı", ancak 30 kayıt atlandı; bir test "geçti", ancak sadece doğrulama kendisi yanlış olduğu için.

O an şöyleydi: Claude, bir veritabanı geçişinin "başarıyla tamamlandığını" söyledi. Ancak aslında, 14%'lik tetikleme kısıtlama çakışması olan kayıtları sessizce atladı. Atlanma davranışı günlüğe kaydedildi, ancak açıkça ortaya çıkarılmadı. 11 gün sonra, rapor verileri anormal başladığında sorunu fark ettik.

6 hafta boyunca, 30 kod deposunu kapsayacak şekilde aynı 50 temel görevi üç farklı yapılandırmada test ettim.

Hata oranı, görevin orijinal niyetle eşleşmesi için düzeltilmesi veya yeniden yazılması gereken durumu ifade eder. Dahil edilen hatalar: sessiz varsayımlar, aşırı mühendislik, ilgisiz bozulmalar, sessiz başarısızlıklar, sözleşmeleri ihlal etmek, çatışmalarla uzlaşmak ve kontrol noktalarını kaçırmaktır.

Uygunluk oranı, bir kural geçerli olduğunda Claude'un bu kuralı ne kadar olasılıkla açıkça uygulayacağıdır.

Gerçekten ilginç olan sonuç, hata oranının %41'den %3'e düşmesi değil; daha önemlisi, 4 kuraldan 12 kurala genişletilmesiyle uyum yükü neredeyse artmadı, uyum oranı sadece %78'den %76'ya düştü, ancak hata oranı 8 puan daha azaldı. Eklenen kurallar, orijinal 4 kuralın ele almadığı başarısızlık modellerini kapsıyor ve aynı dikkat bütçesini paylaşmıyor.

Karpathy şablonu nerede gizlice çalışmaz

Yeni kurallara katılmaksızın bile, orijinal 4 kural şablonu en az 4 yerde yetersiz kalıyor.

Birinci, uzun süre çalışan Agent görevi.
Karpathy'nin kuralları, Claude kod yazarken uygulanır. Ancak Claude çok adımlı bir işlem hattı çalıştırırken ne olur? Orijinal şablonun bütçe kuralları, kontrol noktaları kuralları veya "gürültülü hata" kuralları yoktur. Bu nedenle işlem hattı yavaşça sapmaya başlar.

İkinci olarak, çoklu kod deposu tutarlılığı.
"Varolan tarzla eşleştir" varsayılan olarak yalnızca bir tarz içerir. Ancak 12 hizmete sahip bir monorepo'da, Claude hangi tarzla eşleşeceğini seçmek zorundadır. Orijinal kurallar bunu nasıl seçeceğini belirtmemiştir. Bu nedenle ya rastgele bir tarz seçer ya da birkaç tarzı eşit şekilde karıştırır.

Üçüncü olarak, test kalitesi.
Hedefe odaklı yürütme, "test başarılı" sonucunu başarı olarak kabul eder, ancak testin kendisinin anlamlı olması gerektiğini belirtmez. Bu da Claude'nin neredeyse hiçbir şeyi doğrulamayan, ancak kendisinin oldukça emin olduğuna dair yanlış bir algı yaratan testler yazmasına neden olur.

Dördüncü, üretim ortamı ile prototip aşaması arasındaki farklar.
Aynı 4 kural, üretim kodunun aşırı mühendislenmesini önler ancak prototip geliştirme hızını düşürebilir. Çünkü prototip aşamasında bazen 100 satırlık keşifsel iskelet gerekebilir ve önce yön belirlenmelidir. Karpathy'nin "basitlik öncelikli" yaklaşımı erken kodlarda aşırı şekilde tetiklenebilir.

Bu 8 yeni kural, Karpathy'nin orijinal 4 kuralını yerine geçmek için değil, bunların eksikliklerini tamamlamak amacıyla eklenmiştir: Orijinal şablon, Ocak 2026'da görülen otomatik tamamlamaya dayalı kod yazma senaryosuna karşılık gelirken; Mayıs 2026'da Claude Code, Agent tarafından yönlendirilen, çok adımlı ve çok kod deposu işbirliği ortamına girmiştir ve ikisi de farklı sorunlarla karşı karşıyadır.

Hangi yöntemler işe yaramadı

Bu 12 kuralı nihai hale getirmeden önce başka bazı çözümler de denedim.

Reddit/X'de gördüğüm kurallara katılın.
Çoğu, Karpathy'nin orijinal 4 kuralını sadece farklı bir ifadeyle tekrarlıyordu ya da «Her zaman Tailwind class kullanın» gibi genellenemeyen alanlara özgü kurallardı. Sonunda hepsi kaldırıldı.

12'den fazla kural.
En fazla 18 kural test ettim. 14'ten sonra uygunluk oranı %76'dan %52'ye düştü. 200 satırlık sınır gerçek. Bu uzunluktan sonra Claude, kuralları tek tek okumak yerine "burada kurallar var" şeklinde kalıp eşleştirme yapmaya başlıyor.

Bazı araçlara bağlı olan kurallar.
Örneğin «her zaman eslint kullanın» ifadesi, projede eslint kurulu değilse bu kural etkisiz hale gelir ve sessizce etkisizleşir. Daha sonra bunu, belirli bir araçtan bağımsız bir ifadeye dönüştürdüm; örneğin «eslint kullanın» yerine «kod tabanında zorunlu kılınan stili takip edin» şeklinde değiştirdim.

CLAUDE.md içinde örnekleri gösterin, kurallar değil.
Örnekler, kurallardan daha fazla bağlam tüketir. Üç örnek, yaklaşık 10 kural kadar bağlam tüketir ve Claude örnekler üzerinde aşırı uyum sağlayabilir. Kurallar soyuttur, örnekler somuttur. Bu nedenle kurallar kullanılmalıdır.

Dikkatli olun, dikkatle düşünün, odaklanın.
Bu tüm gürültü. Bu tür talimatların uygunluk oranı yaklaşık %30'a düştü, çünkü kontrol edilemiyorlardı. Daha sonra bunları "varsayımları açıkça belirtin" gibi daha spesifik emir kurallarıyla değiştirdim.

Claude'ye «deneyimli mühendis» gibi davranmasını söyleyin.
Bu işe yaramıyor. Claude zaten kendini deneyimli mühendis gibi hissediyor. Gerçek sorun bunu mı düşündüğü değil, bunu mı uyguladığı. Emir kuraları bu boşluğu daraltabilir, kimlik ipuçları ise hayır.

Tam 12 kural versiyonu CLAUDE.md

Tamamen kopyalayıp yapıştırabileceğiniz tam sürüm aşağıda yer almaktadır.

Bu içerik, Feishu belgesi dışında gösterilemiyor.

CLAUDE.md dosyasını repo kök dizinine kaydedin. Bu 12 kuralın altına, teknoloji yığını, test komutları, hata modelleri gibi proje özel kurallar ekleyin. Toplam 200 satırı aşmayın, aksi takdirde kural uyum oranı belirgin şekilde düşecektir.

Nasıl kurulur

İki adımda:

1. Karpathy'nin 4 temel kuralını CLAUDE.md dosyanıza ekleyin
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

2. Aşağıya bu metindeki kurallar 5–12’yi yapıştırın

Dosyayı deposunun kök dizinine kaydedin. Buradaki >> çok önemlidir; mevcut CLAUDE.md dosyasının üzerine yazmak yerine, daha önce yazdığınız proje özel kurallarına eklemek için kullanılır.

CLAUDE.md bir wish list değil, gözlemlediğiniz özel başarısızlık modellerini kapatmak için bir davranış sözleşmesidir.

Her kural bir soruyu yanıtlamalıdır: Hangi hatayı önler?

Karpathy'nin 4 kuralı, 2026 yılında gördüğü başarısızlık modellerini engeller: sessiz varsayımlar, aşırı mühendislik, ilgisiz bozulma, zayıf başarı kriterleri. Bunlar temeldir, atlamayın.

Eklediğim 8 kural, 2026 Mayıs'tan sonra ortaya çıkabilecek yeni başarısızlık modellerini engellemektedir: bütçe kısıtlaması olmayan Agent döngüleri, kontrol noktası olmayan çok adımlı görevler, test edildiği gibi görünse de kritik mantığı gerçekten test etmeyen testler ve sessiz başarısızlıkları sessiz başarı olarak gizleme sorunu. Bunlar artımlı düzeltmelerdir.

Elbette, etkiler bireysel olarak değişir. Eğer çok adımlı bir işlem hattı çalıştırmıyorsanız, Kural 10 sizin için o kadar önemli değildir. Kod tabanınız yalnızca bir tutarlı stil içeriyorsa ve zaten bir lint aracı tarafından zorunlu kılındıysa, Kural 11 gereksizdir. Bu 12 kuralı okuduktan sonra, gerçekten önceki hatalarınızla eşleşen kuralları koruyun ve geri kalanlarını kaldırın.

Gerçek başarısızlık modellerine özelleştirilmiş 6 kural versiyonu, 12 kural içeren ve bunların 6’sını asla kullanmayacağınız bir versiyondan daha iyidir.

Sonuç

Karpathy'nin 2026 yılının Ocak ayında attığı tweet, temelde bir şikayetti. Forrest Chang bunu 4 kurala dönüştürdü. Sonuçta, 120.000 geliştirici bu sonuca Star verdi. Ancak bunların çoğu bugün hâlâ sadece bu 4 kuralı kullanıyor.

Modeller ilerledi ve ekosistem değişti. Çok adımlı Agent, hook zincirleme tetikleme, beceri yükleme, çoklu kod deposu iş birliği—bu tümü Karpathy'nin o tweet'i yazdığı zaman henüz yoktu. Orijinal 4 kural bu sorunları çözmüyordu. Yanlış değillerdi, sadece eksikti.

8 yeni kural eklendi. 6 hafta içinde 30 kod deposu test edildi. Hata oranı %41'den %3'e düştü.

Bu makaleyi bu akşam kaydedin ve bu 12 kuralı CLAUDE.md dosyanıza yapıştırın. Bir hafta Claude yolunda zaman kazandırsanız, lütfen paylaşın.