Bir sürü Claude Code yapılandırması denedim.
Çıktımı gerçekten değiştiren tek şey: CLAUDE.md adlı 60 satırlık bir dosya.
Burayı yer imlerine ekleyin 🔖
İşte tam olarak nasıl çalıştığı, çoğu insanın neden tamamen gözden kaçırdığı ve bugün kopyalayabileceğiniz eksiksiz şablon:
Claude Code hakkında kimsenin size söylemediği şey
İlk komutunuzdan önce. Tek bir satır koddan önce. Oturumunuzda herhangi bir şey olmadan önce.
Claude bir dosya okur. Sadece bir tane.
CLAUDE.md.
Ve bu dosyayı tüm oturum boyunca mutlak gerçek olarak kabul eder. Bir öneri olarak değil. Diğerleri arasında bir bağlam olarak değil. Vereceği her kararı şekillendiren kesin brifing olarak.
İşte bu yüzden bu dosya, tüm Claude Code yığınındaki en hafife alınan değişkendir.
Çoğu insanın hiç yoktur. Olanlar ise iki hatadan birini yapmıştır: ya dosya özden yoksundur ya da "adım adım düşünen deneyimli bir kıdemli mühendis ol" gibi 300 satırlık bir metindir.
İkisi de işe yaramaz. Farklı nedenlerle.
Çoğu CLAUDE.md dosyası neden çalışmaz: 3 gerçek neden
Neden 1: Çok uzun
Claude, oturum başına güvenilir bir şekilde yaklaşık 150 ila 200 talimatı takip edebilir. Bu yapısal bir kısıtlama, iyi niyet meselesi değil.
Sorun: Claude Code'un dahili sistem istemi zaten yaklaşık 50 talimat içeriyor. Yani CLAUDE.md dosyanızın, Claude bunları düşürmeye başlamadan önce aslında 100 ila 150 talimat yuvası var.
Dosyanız 200 satır uzunluğundaysa, Claude kurallarınızı kasten görmezden gelmiyor. Mekanik olarak unutuyor. Bir uyum sorununuz yok. Bir dikkat bütçesi sorununuz var.
Neden 2: Kötü içerik
CLAUDE.md dosyalarının çoğu, Claude'un kendi başına çıkarabileceği veya davranışını ölçülebilir bir şekilde değiştirmeyen şeylerle doludur.
"Kıdemli bir mühendis gibi davran." → Claude bunun ne anlama geldiğini zaten biliyor ve belirli bir davranışı sabitlemez. "Adım adım düşün." → Bu zaten eğitiminde var. Bir satırı boşa harcıyorsun. "Temiz ve bakımı kolay kod yaz." → Somut bir kriter yok. Claude sizin özel bağlamınızda "temiz"in ne anlama geldiğini bilmiyor.
Belirli, somut bir hatayı engellemeyen her satır, gerçekten önemli olan talimatlardan çalınmış bir satırdır. Test basit: bu satırı silerseniz, Claude belirli bir şeyi yanlış yapacak mı? Cevap hayırsa, satır orada olmamalı.
Neden 3: Sıfır hiyerarşi
Çoğu insan, Claude Code'da üç düzeyde talimat olduğunu görmezden gelir ve her şeyi aynı yere tıkıştırır.
~/.claude/CLAUDE.md → Genel (tüm projeleriniz için geçerlidir)
.claude/CLAUDE.md → Proje (ekiple paylaşılır, git'te)
./CLAUDE.local.md → Yerel (kişisel geçersiz kılmalar, gitignore)
Genel düzey, her projede tekrarlayacağınız kurallar içindir. Proje düzeyi, yığınınıza ve ekibinize özel bağlam içindir. Yerel düzey ise paylaşılması gerekmeyen kişisel tercihleriniz içindir.
Üç düzeyi doğru kullanmak, her dosyayı kısa, odaklı ve gerçekten etkili tutar. Her şeyi tek bir dosyaya koymak, önemli kurallarınızı gürültü altında boğmak için bir huni inşa etmek gibidir.
Etkili bir CLAUDE.md'yi oluşturan 5 bölüm
Prodüksiyonda düzinelerce CLAUDE.md dosyasını taradıktan sonra—açık kaynak projeler, resmi Anthropic dokümanları, topluluk en iyi uygulama depoları—işte tüm etkili dosyaların ortak olarak sahip olduğu 5 bölüm:
Bölüm 1: Kritik komutlar
Claude her oturuma, projenizi nasıl oluşturacağınızı, testlerinizi nasıl çalıştıracağınızı veya lint hatalarını nasıl düzelteceğinizi bilmeden başlar. Tahmin edecektir. Ve tahminleri size turlara mal olacaktır.
Tam olarak ne yazması gerektiğini söyleyin:
Komutlar
- Derleme:
npm run build - Geliştirme:
npm run dev - Tek dosya testi:
npm test -- dosya/yolu - Tam test:
npm test - Lint + düzelt:
npm run lint:fix - Tip kontrolü:
npx tsc --noEmit
Kısa. Kesin. Doğrudan kullanılabilir.
Bu bölüm olmadan, projeniz pnpm vitest ile çalışırken Claude npm test'i dener. Hiçbir zaman çalışmayacak bir komut sorununu ayıklamak için üç tur harcar. Gerçek iş için kullanabileceğiniz üç tur.
Bölüm 2: Mimari haritası
Claude her oturuma, kod tabanınız hakkında sıfır bilgiyle başlar. Sıfır. İş mantığınızın nerede olduğunu bilmez. Bileşenlerinizin durumsuz olması gerekip gerekmediğini bilmez. API rotalarınızın iş mantığı içermemesi gerektiğini bilmez.
Ona bir harita verin:
Mimari
- src/lib/services/ → tüm iş mantığı
- src/components/ → yalnızca durumsuz UI bileşenleri
- src/lib/store/ → genel durum (Zustand)
- src/app/api/ → API rotaları, burada iş mantığı yok
- DB'ye yalnızca Server Actions veya API rotaları üzerinden erişim
Ağaç yapınızın ayrıntılı bir listesi değil. Sadece Claude'un şeylerin nerede olduğunu ve daha da önemlisi, nereye gitmemeleri GEREKTİĞİNİ bilmesi için yeterli.
Bu ayrım... nereye gittiği vs. nereye gitmediği... en sık yapılan mimari hataları önleyen şeydir.
Bölüm 3: Kesin kurallar
Bu, tüm dosyanın en önemli bölümüdür. İstisnasız.
Buradaki her kural tek bir soruyu yanıtlamalıdır: "Bu satırı silersem, Claude somut bir hata yapacak mı?"
Evet → kural kalır. Hayır → orada olması için hiçbir sebep yok.
Yüksek değerli kurallara örnek:
Kurallar
- .env dosyalarını veya sırları ASLA commit etme
- Tüm async çağrılar try/catch ile sarılmalıdır
- Yalnızca fonksiyonel bileşenler, sıfır sınıf bileşeni
- Zorunlu commit önekleri: feat:, fix:, docs:, refactor:
- Her PR, birleştirmeden önce
npm run verify'ı geçmelidir - Yalnızca statik dışa aktarım, SSR yok (S3'te dağıtılır)
- ÖNEMLİ: her kod değişikliğinden sonra tip kontrolü yap
Bu listede dikkat edilmesi gereken iki şey var.
Birincisi, olumsuz kurallar olumlu kurallar kadar önemlidir. ".env dosyalarını asla commit etme", yalnızca Claude'un bunu yaptığı güne kadar açık görünen bir kuraldır. Ekleyin.
İkincisi, ÖNEMLİ veya YAPMALISIN gibi vurgu belirteçleri gerçekten işe yarar.
Bu anekdot değil. Anthropic bunu kendi dokümantasyonunda onaylıyor: bir kuralın önüne ÖNEMLİ veya YAPMALISIN eklemek, Claude'un o kurala uyma oranını ölçülebilir şekilde artırıyor.
Bunları idareli kullanın: en ciddi sonuçları olan kurallar için saklayın.
Bu bölümde 15 kuralın altında kalın. Bunun ötesinde, önemli olanlara olan dikkati dağıtırsınız.
Bölüm 4: İş akışı tercihleri
Bunu deneyimlediniz. Claude'dan bir satırı düzeltmesini istersiniz. Üç dosyayı yeniden yazar, fonksiyonlarınızı yeniden adlandırır ve isteğinizle hiçbir ilgisi olmayan bir sınıfı yeniden düzenler.
Bu bölüm bunu önler:
İş Akışı
- Karmaşık görevlere başlamadan önce açıklayıcı sorular sor
- Minimum değişiklik yap, ilgisiz kodu yeniden düzenleme
- Her değişiklikten sonra testleri çalıştır, başarısızlıkları devam etmeden düzelt
- Mantıksal değişiklik başına ayrı commit'ler oluştur, tek bir dev commit yapma
- İki yaklaşım arasında belirsizlik durumunda, her ikisini de açıkla ve seçmeme izin ver
Buradaki her satır somut bir sorunu yanıtlıyor. 47 dosyalık dev commit. İstenmeyen tam yeniden yazma. Claude'un size sorması gerekirken tek başına verdiği mimari karar.
Bölüm 5: CLAUDE.md dosyanıza NE KOYULMAMALI
Bu bölüm diğerleri kadar önemlidir. Belki daha da fazla.
Şunları DAHİL ETME:
- Kişilik talimatları ("kıdemli bir mühendis ol")
- Linter'ınızın zaten hallettiği biçimlendirme kuralları
- Her oturuma tüm dokümanları çeken @ içe aktarmaları
- Yinelenen kurallar (genel "testleri çalıştır" diyorsa, proje tekrarlamaz)
- Claude'un otomatik bellek yoluyla kendi başına öğrendiği herhangi bir şey
Bu son nokta yaygın olarak hafife alınır.
Claude, ~/.claude/projects/<proje>/memory/ içinde kendi notlarını tutar. Oturumunuzda /memory komutunu çalıştırarak projeniz hakkında zaten ne öğrendiğini görün. Birkaç oturumdan sonra, Claude'un CLAUDE.md dosyanıza elle yazmayı planladığınız bilgileri zaten yakaladığını fark edeceksiniz.
Sınırlı talimatlarınızı Claude'un kendi başına hatırladığı şeyler için harcamayın.
Kullanıma hazır, 60 satırın altında eksiksiz şablon
Projenize uymayan bölümleri silin. Amaç her şeyi doldurmak değil. Amaç, Claude'un davranışını ölçülebilir bir şekilde değiştiren şeyleri tutmaktır.
Çıktımda en büyük etkiye sahip olan satırlar: somut sonuçlar
Düzinelerce yapılandırmayı test ettikten sonra, işte en görünür farkı yaratan beş satır:
ÖNEMLİ: her kod değişikliğinden sonra tip kontrolü yap → Claude'un açıkça kontrol etmesi istenmeden algılayamadığı bozuk tiplere sahip kod teslim etmesini önler.
Minimum değişiklik yap, ilgisiz kodu yeniden düzenleme → Tüm dosyaların tam ve istenmeyen yeniden yazılmasını önler.
Mantıksal değişiklik başına ayrı commit'ler oluştur, tek bir dev commit yapma → 47 karışık dosyadan oluşan okunamaz canavar commit'i önler.
İki yaklaşım arasında belirsizlik durumunda, her ikisini de açıkla ve seçmeme izin ver → Claude'un size ait olması gereken mimari kararları tek başına vermesini önler.
Yalnızca statik dışa aktarım, SSR yok → Claude'un S3'te statik olarak dağıtılan bir projeye sunucu kodu eklemesini önler.
Bu beş satırın ortak noktası: her biri, hata ayıklama süresinde belirli, sık ve maliyetli bir hatayı önler.
Bu, CLAUDE.md dosyanızdaki her satır için nihai testtir.
Temel hata ve neden bu kadar yaygın
İnsanlar CLAUDE.md dosyalarına bir dilek listesi veya kişilik komutu gibi davranıyor.
"Kıdemli ol." "Detaylı ol." "Bir uzman gibi düşün."
Bu bir brifing değil. Sihirli düşünce.
CLAUDE.md dosyanız teknik bir belge olmalı, motive edici bir konuşma değil. Yığın, komutlar, mimari, somut kurallar, iş akışı. Geri kalan her şey, gerçekten önemli olan talimatlarla rekabet eden gürültüdür.
Dosyayı 80 satırın altında tutun. Claude'un önleyebileceğiniz bir hata yaptığı her seferde gözden geçirin.
Ve hepsinden önemlisi: bu dosyanın zaman içinde neye dönüştüğünü anlayın.
İlk ayda iyi bir CLAUDE.md, her oturumda size zaman kazandırır. Üçüncü aya gelindiğinde, kurallarınızı ve yığınınızı Claude'un neredeyse bir ekip üyesi gibi çalışacağı kadar kesin bir şekilde yakalamıştır.
Altıncı ayda, Claude'un bu projede yaptığı her hatayı içerir ve hepsini otomatik olarak önler.
Dosya birikir. Her düzeltmeyle gelişir. Aşamalı olarak şimdiye kadar yazdığınız en iyi işe alım brifingi haline gelir.
Claude için değil. Sizin için.
