Karpathy, X'te Claude hakkında şikayette bulundu. Forrest Chang bu şikayeti dört kurala ve bir GitHub reposuna dönüştürdü. Repo haftalar içinde 120.000 yıldıza ulaştı. Bunu okuyan çoğu geliştirici hâlâ sadece bu dört kuralı kullanıyor. Sorun şu ki, bu kurallar Ocak ayında yazıldı. Şu an 2026'nın ortası ve Claude Code ekosistemi çok değişti.
Bu makale size eksiksiz 12 kurallı CLAUDE.md dosyasını, her kuralın neden var olduğunu, hangi hatayı kapattığını ve orijinal şablonun sessizce neyi yanlış yaptığını veriyor. Sonuna yapıştırın.
CLAUDE.md Nedir ve Çoğu İnsan Neden Yanlış Anlıyor?
CLAUDE.md, deponuzun köküne yerleştirdiğiniz bir dosyadır. Claude Code, her oturumdan önce onu okur. Bu bir komut istemi değildir. Bir tercih listesi değildir. Claude'un kod tabanınızda nasıl davranacağına dair bir işletim sistemidir.
Çoğu geliştirici üç yanlış şeyden birini yapar. Sahip oldukları her tercihi dosyaya tıkarlar, ta ki 4.000 token'ı geçip şişene kadar; bu noktada uyum %30'a düşer çünkü önemli kurallar gömülür. Tamamen atlarlar ve her oturumda yeniden komut verirler, bu da beş kat daha fazla token harcar ve sıfır tutarlılık üretir. Bir şablonu bir kez yapıştırır, unuturlar ve kod tabanları değiştikçe haftalar içinde sessizce bozulmasını izlerler.
Resmi Anthropic belgeleri açıktır: CLAUDE.md tavsiye niteliğindedir. Claude, 200 satırın altında yaklaşık %80 oranında uyar. 200 satırı geçince uyum keskin bir şekilde düşer. Kullanışlı CLAUDE.md dosyalarının tavanı kısa, kesin ve önerilerle değil, doğrudan kurallarla uygulanır.
Orijinal 4 Kural: Hiçbir Şeyiniz Yoksa Buradan Başlayın
Andrej Karpathy, Tesla'nın eski AI direktörü ve OpenAI'in kurucu ortağı, Ocak 2026'da Claude Code ile haftalarca yoğun çalışmanın ardından bir konu dizisi yayınladı. Bir çerçeve değil. Bir şikayet. Sürekli karşılaştığı üç başarısızlık modu: Claude sessizce sormak yerine varsayar, Claude minimumu çözmek yerine aşırı inşa eder ve Claude kendisinden istenmeyen koda dokunur.
Forrest Chang konu dizisini okudu ve kurallar halinde yazdı. Ertesi gün GitHub'da 65 satırlık bir dosya. İşte dört kural:
Kural 1 - Kodlamadan Önce Düşün
Kod yazmadan önce varsayımlarınızı belirtin. Ödünleşimleri ortaya çıkarın. Tahmin etmeden önce sorun. Daha basit bir yaklaşım mevcut olduğunda geri adım atın. Asla doğrulanmamış bir varsayım üzerine inşa etmeyin.
Kural 2 - Önce Basitlik
Sorunu çözen minimum kodu yazın. Spekülatif özellikler yok. Bir kez kullanılan kod için soyutlamalar yok. Kıdemli bir mühendis bunu aşırı karmaşık bulursa, basitleştirin.
Kural 3 - Cerrahi Müdahaleler
Yalnızca görevin gerektirdiği yere dokunun. Bitişik kodu, yorumları veya biçimlendirmeyi iyileştirmeyin. Bozuk olmayanı yeniden düzenlemeyin. Mevcut stili aynen eşleştirin.
Kural 4 - Hedef Odaklı Yürütme
Başlamadan önce başarının neye benzediğini tanımlayın. Başarı doğrulanana kadar döngü yapın. Claude'un izlemesi için adımları listelemeyin. Claude'a bitmiş halin neye benzediğini söyleyin ve yolunu bulmasına izin verin.
Bu dört kural, denetimsiz Claude Code oturumlarındaki başarısızlık modlarının kabaca %40'ını kapatır. Kalan %60, orijinal şablonun ele almadığı boşluklarda yaşar, çünkü bu sorunlar Karpathy konu dizisini yayınladığında tam olarak mevcut değildi.
Orijinal Şablonun Neden Genişletilmesi Gerekiyor?
Dört Karpathy kuralı, tek aracılı, kod yazma oturumunu düzeltmek için oluşturuldu. 2026'daki Claude Code ekosistemi, çoklu aracı kurulumları, kancaları, beceri kütüphanelerini ve oturumlar arası çok adımlı iş akışlarını çalıştırıyor. Orijinal şablonun bunların hiçbiri hakkında söyleyecek bir şeyi yok.
Orijinal kurallarda dört spesifik boşluk ortaya çıkıyor. Birincisi, aracı kavgaları: iki aracının sahiplik kuralları olmadan aynı dosyaları düzenlemesi, birbirlerinin değişikliklerinin üzerine sessizce basması. İkincisi, kanca basamakları: her araç çağrısında tetiklenen kancalar, 200 token'lık bir isteği durduracak bütçesi olmayan 8.000 token'a dönüştürür. Üçüncüsü, beceri yükleme çakışmaları: benzer açıklamalara sahip birden çok beceri, dağıtıcının kafasını karıştırır ve yanlış olanı yükler. Dördüncüsü, çok adımlı oturum kesintileri: 6 adımlı bir yeniden düzenleme 4. adımda başarısız olur, ancak 5. ve 6. adımlar yine de çalışır ve bozuk durumun üzerine inşa edilir.
Orijinal dört kural yanlış değil. Eksikler. Aşağıdaki 8 ek kural bu spesifik boşlukları kapatıyor.
8 Yeni Kural: Her Biri Neyi Kapatıyor?
Kural 5 - Modeli Dil Dışı İşler İçin Kullanmayın
Belirleyici kararlar, belirleyici koda aittir. Yeniden deneme mantığı, yönlendirme eşikleri, yükseltme kuralları, durum tabanlı dallanma: bunların hiçbiri LLM çağrısı olmamalıdır. Model, bağlam penceresinde ne varsa ona göre her hafta farklı karar verir. Tutarlı davranış gibi görünen şey, aslında henüz yüzeye çıkmamış varyanstır.
Spesifik olay: "503'te yeniden denemeye karar ver" LLM çağrısı iki hafta çalıştı, ardından model, yeniden deneme kararı için bağlam olarak istek gövdesini okumaya başladığı için rastgele davranış üretmeye başladı. Politika rastgele hale geldi çünkü etkili girdi rastgeleydi.
Bunu CLAUDE.md dosyanıza ekleyin:
yönlendirme, yeniden deneme mantığı, durum tabanlı dallanma ve eşik kararları model çağrılarına değil, koda aittir. bir kararın çıktısı ikiliyse veya sabit bir kurala uyuyorsa, kuralı kodda yazın.
Kural 6 - Sert Token Bütçeleri, İstisnasız
Her aracı döngüsünün kontrolden çıkma şansı vardır. Claude, 90 dakikalık bir hata ayıklama oturumunu kendi kendine durdurmaz. Kendisine yapması söylendiği için yinelemeye devam edecektir. Token bütçeleri, sert bir duruşu zorunlu kılan tek mekanizmadır.
Spesifik olay: 90 dakika boyunca aynı 8KB hata mesajında döngü yapan bir hata ayıklama oturumu. Sonunda Claude, iki saat önce deneyip terk ettiği düzeltmeleri öneriyordu. Bağlam o kadar doluydu ki kendi muhakemesinin izini kaybetmişti.
Bunu ekleyin:
her aracı oturumunun sert bir token bütçesi vardır. bütçeye doğrulanmış bir çözüm olmadan ulaşılırsa, bulguları bir dosyaya özetleyin ve çıkın. bütçenin ötesine geçmeyin.
Kural 7 - Bir Aracı, Bir Dizin
İki aracı aynı anda aynı dizine dokunduğunda, sessiz durum bozulması yaşarsınız. Bir aracı bir dosyayı yazarken diğeri onu okur. Sonuç, hiçbir aracının beklemediği ve fark etmediği verilerdir.
Git worktree'leri kullanın. İkinci bir aracı başlatmadan önce git worktree add ../agent-2-branch feature-branch komutunu çalıştırın. Her aracı, kendi dalına işaret eden kendi izole edilmiş çalışma dizinini alır. Aracılar asla bir dosya sistemini paylaşmaz.
Bunu ekleyin:
paralel çalışan aracılar ayrı git worktree'lerinde çalışır. hiçbir iki aracı aynı anda aynı dizine dokunmaz. her aracı kendi dalına sahiptir.
Kural 8 - Çok Adımlı İşlerde Kontrol Noktası Dosyaları Yazın
Üç adımdan uzun herhangi bir görevin bir kontrol noktası dosyasına ihtiyacı vardır. Claude, her adımdan sonra neyin tamamlandığını, neyin bulunduğunu ve sırada ne olduğunu yazar. Oturum 4. adımda ölür veya bozulursa, sonraki oturum kontrol noktasını okur ve 4. adımdan devam eder. Kontrol noktası olmadan, her yeniden başlatma 1. adıma geri döner.
Herhangi bir çok adımlı göreve başlamadan önce çalışma dizininizde PROGRESS.md adlı bir dosya oluşturun. CLAUDE.md dosyanızda Claude'a şunu söyleyin:
üçten fazla adımı olan görevler için, her adımdan sonra bir PROGRESS.md dosyası yazın. şunları ekleyin: ne yapıldı, ne bulundu, sırada ne var ve ne engellendi. bir oturum tamamlanmadan sona ererse, sonraki oturum önce PROGRESS.md dosyasını okur ve kaldığı yerden devam eder.
Kural 9 - Yüksek Sesle Başarısız Olun veya Hiç Başarısız Olmayın
Claude'un başarılı görünmeye yönelik güçlü bir eğilimi vardır. Önemsediğiniz şeyi gerçekten test etmeyen bir testi geçecektir. Hata veren dosyaları sessizce atlarken bir geçişi tamamlayacaktır. %80'i tamamlanmış bir görevde "bitti" diye rapor verecektir.
Kural: başarı kriterleri doğrulanamıyorsa, görev bitmemiştir. Bir adım başarısız olursa, devam etmeden önce durun ve başarısızlığı ayrıntılarıyla bildirin. Hataları örtbas etmeyin.
Bunu ekleyin:
başarısız olan bir adımın ötesine asla geçmeyin. bir test geçiyor ancak gerçek davranışı kapsamıyorsa, bunu söyleyin. bir geçiş dosyaları atlıyorsa, atlanan dosyaları listeleyin ve durun. başarı, rapor edilen değil, doğrulanabilir olandır.
Kural 10 - Beceri Açıklamaları Benzersiz Olmalıdır
Beceriler, açıklama eşleştirmesiyle yüklenir. İki becerinin örtüşen açıklamaları varsa, dağıtıcı keyfi olarak birini seçer. Yanlış beceri yüklenir, görev kötü talimatlarla çalışır ve hata atılmadığı için asla bir hata görmezsiniz.
Her becerinin işini, başka hiçbir beceriyle eşleşemeyecek bir dille adlandırın. "veritabanı sorgu yardımcısı" ve "veritabanı geçiş yardımcısı" çakışacaktır. "üretim veritabanına karşı salt okunur SQL sorguları yürüt" ve "geri alma ile şema geçiş komut dosyalarını çalıştır ve doğrula" çakışmayacaktır.
Bunu ekleyin:
her beceri açıklaması, işini benzersiz bir şekilde tanımlamalıdır. hiçbir iki beceri, aynı göreve uygulanabilecek açıklamalara sahip olmamalıdır. iki beceri kulağa benzer geliyorsa, dağıtılmadan önce birinin yeniden adlandırılması gerekir.
Kural 11 - Araştırmacıyı Yazardan Ayırın
Bağlam kirliliği gerçektir. Claude aynı oturumda araştırma ve yazma yaptığında, araştırma gürültüsü yazmayı bozar. Konu dışına çıkar, çitlemesi gerekmeyen sonuçları çitler ve sıfırdan başlamış olsaydı sahip olacağı temiz argüman çizgisini kaybeder.
Beşten fazla dosya okumayı veya ikiden fazla kaynağı sorgulamayı gerektiren herhangi bir görev için bir araştırma alt aracısı oluşturun. Yapılandırılmış bir rapor alın. Bağlamda yalnızca raporla birlikte yazma veya uygulama için temiz bir oturum başlatın.
Bunu ekleyin:
araştırma ve uygulama ayrı oturumlardır. bir araştırmacı alt aracısı dosyaları okur, sorguları çalıştırır ve yapılandırılmış bir özet döndürür. uygulama oturumu, tek girdisi bu özet olacak şekilde sıfırdan başlar. araştırma ve yazmayı asla tek bir oturumda birleştirmeyin.
Kural 12 - Kancaların da Bütçeye İhtiyacı Vardır
Kancalar her araç çağrısında tetiklenir. Her dosya yazımında bir linter, bir biçimlendirici, bir günlük yazıcı ve bir güvenlik taraması çalıştıran bir kanca, araç çağrısı başına dört işlem çalıştırıyor demektir. 200 araç çağrısı olan bir oturumda bu, arka planda çalışan, çoğu gereksiz ve tamamı token tüketen 800 işlemdir.
Eklediğiniz her kancanın bir kapsam koşuluna ihtiyacı vardır: yalnızca belirli dizinlere yapılan dosya yazmalarında çalıştırın, yalnızca belirli bir dosya uzantısına dokunulduğunda çalıştırın, yalnızca her araç çağrısından sonra değil, oturum sonundan sonra çalıştırın. Kapsam koşulu olmayan kancalar, oturum performansını görünmez bir şekilde düşürecektir.
Bunu ekleyin:
her kancanın açık bir kapsam koşulu vardır. hiçbir kanca, her araç çağrısında koşulsuz olarak çalışmaz. günlük kaydını oturum sonuna toplayın. linter'ları yalnızca değiştirilen dosyalarda çalıştırın. güvenlik kontrollerini yalnızca test dizini dışındaki dosyalarda çalıştırın.
Tam 12 Kurallı CLAUDE.md - Bunu Yapıştırın
Bu dosyayı deponuzun köküne kopyalayın. Köşeli parantezlerle işaretlenmiş bölümleri doldurun. Dosyanın tamamı 100 satırın altında kalır, bu da uyumu %80'in üzerinde tutar.
CLAUDE.md
Proje
[tek cümle: bu kod tabanının ne yaptığı ve hangi teknoloji yığınını kullandığı]
Davranış Kuralları
Kodlamadan Önce Düşün
Kod yazmadan önce varsayımlarınızı belirtin. Ödünleşimleri ortaya çıkarın. Mimarisi veya veriyi etkileyen herhangi bir şey hakkında tahmin etmeden önce sorun. Daha basit bir yaklaşım mevcut olduğunda geri adım atın.
Önce Basitlik
Sorunu çözen minimum kodu yazın. Spekülatif özellikler yok. Tek kullanımlık kod için soyutlamalar yok. Kıdemli bir mühendis bunu aşırı karmaşık bulursa, basitleştirin.
Cerrahi Müdahaleler
Yalnızca görevin gerektirdiği yere dokunun. İstenmeyen bitişik kodu, biçimlendirmeyi, yorumları veya adlandırmayı iyileştirmeyin. Mevcut kod stilini aynen eşleştirin.
Hedef Odaklı Yürütme
Başlamadan önce başarının neye benzediğini tanımlayın. Bu tanım karşılanıp doğrulanana kadar döngü yapın. Adım adım talimat istemeyin. Yolu bulun.
Belirleyici Kararlar İçin Model Çağrısı Yok
Yönlendirme, yeniden deneme mantığı, durum tabanlı dallanma ve eşik kararları LLM çağrılarına değil, koda aittir. Bir kural yazılabiliyorsa, yazın.
Sert Token Bütçeleri
Her oturumun sert bir token sınırı vardır: [sayınızı belirleyin, örn., 50.000 token]. Sınıra doğrulanmış bir çözüm olmadan ulaşılırsa, bulguları bir dosyaya yazın ve durun. Bütçenin ötesine geçmeyin.
Bir Aracı, Bir Dizin
Paralel çalışan aracılar ayrı git worktree'lerinde çalışır. Hiçbir iki aracı bir dizini paylaşmaz. İkinci bir aracıya ihtiyacınız varsa, şunu çalıştırın: git worktree add ../agent-2 [dal-adı]
Çok Adımlı İşleri Kontrol Noktasına Alın
Üç adımdan uzun herhangi bir görev için çalışma dizininde PROGRESS.md oluşturun. Her adımdan sonra şunu yazın: ne yapıldı, ne bulundu, sırada ne var, ne engellendi. Oturum tamamlanmadan sona ererse, sonraki oturum önce PROGRESS.md dosyasını okur.
Yüksek Sesle Başarısız Olun
Bir adım başarısız olursa, devam etmeden önce durun ve başarısızlığı ayrıntılarıyla bildirin. Bir test geçiyor ancak gerçek davranışı kapsamıyorsa, bunu söyleyin. Başarı, rapor edilen değil, doğrulanabilir olandır.
Benzersiz Beceri Açıklamaları
Her beceri tam olarak bir işi kapsar. Açıklaması, projedeki başka hiçbir beceriye uygulanamaz. İki beceri açıklama olarak örtüşüyorsa, dağıtmadan önce yeniden adlandırın.
Araştırma ve Uygulama Ayrı Oturumlardır
Beşten fazla dosya okumayı veya ikiden fazla kaynağı sorgulamayı gerektiren herhangi bir görev için bir alt aracı kullanın. Yapılandırılmış bir rapor alın. Uygulama için yalnızca bu raporu girdi olarak alan temiz bir oturum başlatın.
Yalnızca Kapsamlı Kancalar
Her kancanın açık bir koşulu vardır: dosya uzantısı, dizin yolu veya oturum olayı. Hiçbir kanca, her araç çağrısında koşulsuz olarak çalışmaz. Mümkün olduğunda günlük kaydını oturum sonuna toplayın.
Dokunulmaması Gerekenler
[Claude'un asla değiştirmemesi gereken dizinleri veya dosyaları listeleyin: örn., /sırlar, /geçişler/arşiv, /prod-yapılandırma]
Varsayılan Başarı Kriteri
Bir görevin bitip bitmediği konusunda şüpheye düştüğünüzde: test geçiyor mu, derleme başarılı mı ve çıktı Claude'un kendi yargısı dışında bir şey tarafından doğrulanabilir mi? Bunlardan herhangi birine hayır ise, bitmemiştir.
Orijinal Şablonun Sessizce Bozulduğu Dört Yer
Yalnızca orijinal dört kuralla bile, şablonun yanlış davranış ürettiği ve size söylemediği dört özel durum vardır.
Birincisi: birikmiş bağlamla uzun oturumlar. Karpathy'nin hedef odaklı yürütme kuralı, Claude'a doğrulanana kadar döngü yapmasını söyler. Uzun bir oturumda, bağlam doldukça "doğrulama" bulanıklaşır. Claude, ne yapması gerektiğine dair bozulmuş bir modele karşı doğrulama yapmaya başlar. Çözüm, sert bir duruşu zorunlu kılan kural 6'dır (token bütçesi).
İkincisi: çoklu aracı kurulumları. Cerrahi müdahaleler kuralı, her aracıya yalnızca yapması gereken yere dokunmasını söyler. Ancak iki aracı ve dizin sahipliği kuralı olmadan, "yapması gereken" örtüşür. Kural 7 (bir aracı, bir dizin) eksik parçadır.
Üçüncüsü: benzer işlere sahip paralel beceriler. Orijinal şablonun beceriler hakkında hiçbir şeyi yoktur. Kural 10 (benzersiz beceri açıklamaları) dağıtıcı belirsizliği boşluğunu kapatır.
Dördüncüsü: görev ortasında sona eren oturumlar. Hedef odaklı yürütme, oturumun tamamlanana kadar çalıştığını varsayar. Oturum 8 adımdan 4'ünde ölürse ne yapılacağına dair bir talimatı yoktur. Kural 8 (kontrol noktası dosyaları) sonraki oturuma bir başlangıç noktası verir.
Bunların hiçbiri orijinal kurallardaki hatalar değildir. Bunlar, orijinal kuralların kapsayacak şekilde yazılmadığı boşluklardır.
GitHub Yıldızlarını Açıklayan Sayı
120.000 geliştirici, 65 satırlık bir metin dosyasını yıldızladı. Kod yok. Kütüphane yok. Çerçeve yok. Dört kural içeren bir dosya.
Bunu açıklayan sayı: CLAUDE.md olmadan denetimsiz Claude Code oturumlarında %41 hata oranı. Orijinal dört kuralla %11. Tam on iki kuralla %3.
Hatalarda 38 puanlık bir azalma marjinal bir iyileştirme değildir. Claude Code'u gerçek üretim işlerinde çalıştıran herhangi bir ekip için, gece boyunca çalışmasına güvenebileceğiniz bir aracı ile göz kulak olmanız gereken bir aracı arasındaki farktır.
Bu makalenin sonundaki dosyayı yapıştırıp doldurmak beş dakika sürer. Bunu yaptıktan sonraki ilk oturum farklı hissettirecek. Model değiştiği için değil. Çünkü model nihayet dünyanızın nasıl çalıştığını biliyor.
Bunu yer imlerine ekleyin ve bu gece 12 kuralı CLAUDE.md dosyanıza yapıştırın.
Faydalı bulduysanız tekrar paylaşın.
