CLAUDE.md Dosyanız Muhtemelen Yanlış: Boris Cherny'nin Yapmadığı 7 Hata

Boris Cherny'nin dosyası 2.5 bin token. Benimki 15 bindi. İş akışını 3 hafta boyunca inceledikten sonra, çoğu geliştiricinin gözden kaçırdığı kalıpları ve bunları nasıl hızlıca düzeltebileceğinizi buldum.

Benim CLAUDE.md dosyam 847 satırdı. Bununla gurur duyuyordum — her uç durum belgelenmiş, her kural açıklanmış, her takım tercihi titizlikle kaydedilmişti.

Sonra Boris Cherny'nin dosyasını gördüm: 2.5 bin token.

Bu kabaca 100 satır demek. Onun ekibi bizzat Claude Code'u geliştiriyor. Benimki ise 8 kat daha uzundu ve daha kötü sonuçlar veriyordu.

CLAUDE.md ile Hatalardan Kaçının | Görsel Gemini 3 Pro ile oluşturulmuştur

Not: Araştırma ve düzenleme süreçlerinde yapay zeka araçlarından destek alınmıştır. Testler, yeniden yapılandırma ve gerçek dünya örnekleri kendi iş akışımdan alınmıştır.

Üç hafta boyunca Boris'in iş akışı hakkında paylaştıklarını inceledim. Herkesin bahsettiği gösterişli kısımları değil — 5 paralel oturum, terminaller arası ışınlanma gibi. Sıkıcı kısımları. Ekibinin CLAUDE.md dosyasını gerçekte nasıl yapılandırdığını.

Bulduğum şey şu: çoğumuz aynı hataları yapıyoruz. Ve çözümler hiç de karmaşık değil.

İnterneti Sallayan İş Akışı

Ocak 2026'nın başlarında, Anthropic'te Kıdemli Mühendis ve Claude Code'un yaratıcısı olan Boris Cherny, X'te geliştirme kurulumu hakkında bir dizi paylaşım yaptı. Basit bir terminal turu olarak başlayan şey, yılın en çok incelenen geliştirici iş akışı haline geldi.

Jeff Tang, "Eğer Claude Code en iyi uygulamalarını doğrudan yaratıcısından okumuyorsanız, bir programcı olarak geride kalmışsınız demektir," diye yazdı. Kyle McNease bunu Anthropic'in "ChatGPT anı" olarak adlandırdı.

Ancak çoğu kişinin kaçırdığı bir nokta vardı.

Viral olan kısımlar paralel oturumlar ve sistem bildirimleriydi. Önemli olan kısım ise paylaşımların arasına gizlenmiş tek bir satırdı:

"Kurulumum şaşırtıcı derecede sade olabilir! Claude Code kutudan çıktığı gibi harika çalışıyor, bu yüzden şahsen çok fazla özelleştirmiyorum."

Ekibinin CLAUDE.md dosyası? 2.5 bin token. Git'e yüklenmiş. Tüm ekip katkıda bulunuyor. Hepsi bu.

Karmaşık konfigürasyonlar yok. 50 sayfalık manifestolar yok. Sadece her satırının hakkını veren odaklanmış bir dosya.

Çoğumuz onun kaçındığı şeyi yapıyoruz.

7 Anti-Desen

1. Bağlam Doldurma Tuzağı

Çoğu geliştiricinin yaptığı: Her şeyi CLAUDE.md'ye tıkıştırmak. Her uç durum, her geçmiş karar, "ne olur ne olmaz" diye eklenen her talimat. 10.000'den fazla token'a ulaşan dosyalar gördüm.

Boris'in yaptığı: Toplam 2.5 bin token. Kısa. Öz.

Neden önemli: Bağlam çürümesi gerçektir. NoLiMa kıyaslamasına göre, 32.000 token seviyesinde, test edilen 12 modelden 11'inin hatırlama görevlerindeki doğruluğu %50'nin altına düştü. CLAUDE.md dosyanız her konuşma başlangıcında yüklenir. Şişkin bir dosya, siz daha soru sormadan token'ları tüketir.

Çözüm utandırıcı derecede basit:

Kötü (uzun uzadıya): "Kimlik doğrulama uygularken, giriş doğrulama, uygun hata yönetimi, güvenli token saklama ve auth/ dizinindeki yerleşik kalıplarımızı takip etme dahil olmak üzere her zaman güvenlik en iyi uygulamalarını izlediğinizden emin olun..."

İyi (kısa ve öz): "Auth: girişleri doğrula, hataları güvenli yönet, auth/ kalıplarını izle"

Aynı bilgi. %80 daha az token.

CLAUDE.md dosyamı 847 satırdan 127'ye düşürdüm. Token yükü ~15.000'den ~2.400'e düştü. Oturumlar daha hızlı başladı. Claude konuşmanın ortasında talimatları "unutmayı" bıraktı.

2. Statik Bellek Sorunu

Çoğu geliştiricinin yaptığı: Proje kurulumu sırasında bir kez CLAUDE.md oluşturmak. Bir daha asla dokunmamak.

Boris'in yaptığı: İş arkadaşlarının PR'larında öğrendiklerini eklemek için @.claude etiketini kullanır. Dosya her kod incelemesiyle birlikte gelişir.

Neden önemli: Kod tabanınız değişir. Statik talimatlar yanlış hale gelir. Daha kötüsü — Claude hatalardan ders çıkarmadığı için aynı hatalar tekrarlanır.

Geçen ay, ekibim dört ayrı PR'da aynı TypeScript katı mod (strict mode) ihlaliyle karşılaştı. İnceleyenler her seferinde aynı düzeltmeyi önerdi. Bu kalıbın ilk seferden sonra CLAUDE.md'ye eklenmiş olması gerekirdi.

Çözüm:

• PR incelemelerinden beslenen bir "Öğrenilenler" bölümü ekleyin
• Oturumlar sırasında anlık güncellemeler eklemek için # kısayolunu kullanın (# Yardımcı programlar için her zaman adlandırılmış dışa aktarmaları kullan yazın ve belleğe eklensin)
• Aylık CLAUDE.md denetimleri planlayın — eskimiş olanları silin, eksik olanları ekleyin

CLAUDE.md dosyanız bir zaman kapsülü değil, yaşayan bir belge olmalıdır.

3. Solo Konfigürasyon

Çoğu geliştiricinin yaptığı: CLAUDE.md'yi kişisel bir dosya olarak tutmak. Belki .gitignore dosyasına eklemek.

Boris'in yaptığı: "Anthropic'teki her ekip, git'te bir CLAUDE.md tutar."

Neden önemli: Farklı ekip üyeleri tutarsız Claude davranışlarıyla karşılaşır. Yeni geliştiricileri dahil etmek, bağlamı sıfırdan oluşturmak demektir. Bir kişi tarafından keşfedilen en iyi uygulamalar yayılmaz.

Bir kıdemsiz mühendisin, üç kıdemli mühendisin zaten bozuk olduğunu bildiği bir test kurulumunu hata ayıklamak için iki saat harcadığını izledim. Çözüm mevcuttu — birinin kişisel Claude konfigürasyonunda. Paylaşılmamıştı. Keşfedilebilirdi.

Çözüm:

proje-kök-dizini/
├── CLAUDE.md           # Paylaşılan, git'e eklenmiş
├── CLAUDE.local.md     # Kişisel tercihler, .gitignored
└── .claude/
    └── commands/       # Ekip eğik çizgi komutları

Bir ekip ritüeli oluşturun: CLAUDE.md'yi güncellemek PR sürecinin bir parçası olsun. Bir püf noktası mı buldunuz? Belgeleyin. Tekrarlayan bir sorunu mu çözdünüz? Kalıbı ekleyin.

4. Plan Modunu Atlamak

Çoğu geliştiricinin yaptığı: Doğrudan düzenlemeleri otomatik kabul etme moduna atlamak. Claude'un hemen kod yazmaya başlamasına izin vermek.

Boris'in yaptığı: "Eğer hedefim bir Pull Request yazmaksa, Plan modunu kullanırım ve Claude'un planını beğenene kadar onunla istişare ederim. Oradan düzenlemeleri otomatik kabul etme moduna geçerim ve Claude genellikle tek seferde işi bitirir."

Kendi sözleriyle: "İyi bir plan gerçekten önemlidir!"

Neden önemli: Planlama yapmadan otomatik kabul etmek, yanlış yönlerde bağlam tüketmek demektir. Sonunda 15 dosyanın değiştiğini, mimarinin yanlış olduğunu anlar ve baştan başlamak zorunda kalırsınız.

Planlama, hataları düzeltmenin ucuz olduğu aşamada yakalar.

Çözüm:

• Varsayılan olarak Plan modunu kullanın (Shift+Tab iki kez)
• Plan zihinsel modelinizle eşleşene kadar üzerinde çalışın
• Ancak o zaman otomatik kabule geçin
• CLAUDE.md'ye planlama talimatları ekleyin:

## İş Akışı
- Karmaşık görevlere Plan modunda başla
- Uygulamadan önce plan onayı al
- Büyük değişiklikleri incelenebilir parçalara böl

5. Eksik Doğrulama Döngüsü

Çoğu geliştiricinin yaptığı: Claude'un kod yazmasına izin vermek, çıktıya şöyle bir bakmak ve yayına almak.

Boris'in yaptığı: "Claude Code'dan harika sonuçlar almanın muhtemelen en önemli yolu: Claude'a çalışmasını doğrulayabileceği bir yol vermektir."

Abartmıyor. Claude Code'un kendisi Claude tarafından test ediliyor — kullanıcı arayüzünü test etmek için tarayıcı otomasyonu kullanarak, kod çalışana ve kullanıcı deneyimi doğru hissedilene kadar tekrarlıyor.

Neden önemli: Boris, doğrulamanın nihai kaliteyi "2-3 kat" artırdığını iddia ediyor. Bu olmadan Claude, kodun çalışıp çalışmadığını tahmin eder. Bununla ise kodun çalıştığını kanıtlar.

Çözüm — CLAUDE.md'ye doğrulama gereksinimleri ekleyin:

## Doğrulama Gereksinimleri
- Kod değişikliklerinden sonra `npm test` çalıştır
- Tamamlamadan önce `npm run typecheck` çalıştır
- API değişiklikleri için `curl` veya Postman ile test et
- UI değişiklikleri için taahhüt etmeden önce tarayıcıda doğrula

O zaman Claude bu kontrolleri gerçekten yapacaktır. Sadece komut satırında söylediğiniz için değil — proje bağlamına işlendiği için.

6. Tehlikeli İzinler Kısayolu

Çoğu geliştiricinin yaptığı: İzin istemleri can sıkıcı olduğu için --dangerously-skip-permissions kullanmak.

Boris'in yaptığı: "Bunun yerine, ekip genelinde paylaşılan, yaygın güvenli komutlara önceden izin vermek için /permissions kullanır."

Neden önemli: İzinleri atlamak tüm güvenlik bariyerlerini kaldırır. Tek bir kötü komut ve veritabanınızın neden silindiğini hata ayıklarken bulursunuz kendinizi. Boris, izinleri bir ekip varlığı olarak görür — paylaşılan, incelenebilir, sürümlenmiş.

Onun çerçevesi: "Otomatik olarak geçmekten pişman olmayacağınız sınırlar tasarlayın."

Çözüm: --dangerously-skip-permissions yerine, şunlara izin vermek için /permissions kullanın:

• npm run test:*
• npm run build:*
• git commit:*
• git push:*
• bun run format

Güvenli olanlara önceden izin verin. Geri kalan her şey için güvenlik bariyerlerini koruyun. Tehlikeli modu yalnızca uzun süreli otonom görevler için korumalı alan (sandbox) ortamlarında kullanın.

7. Format Sapması

Çoğu geliştiricinin yaptığı: Otomatik formatlama yok. Yapay zeka tarafından oluşturulan dosyalar arasında tutarsız kod stili. Linting sorunları nedeniyle CI hataları.

Boris'in yaptığı: Her düzenlemeden sonra otomatik formatlama için PostToolUse kancası (hook).

Neden önemli: Claude'un kodu genellikle iyi formatlanmıştır, ancak tutarsızlıklar sızabilir. Manuel formatlama akışı böler. Ve hiçbir şey ivmeyi bir formatlama kuralı nedeniyle oluşan CI hatası kadar bozamaz.

Çözüm — bir PostToolUse kancası ekleyin:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "npm run format || true"
      }]
    }]
  }
}

Artık Claude'un dokunduğu her dosya otomatik olarak formatlanır. || true kısmı, format hatalarının oturumu engellemesini önler.

Neleri Değiştirdim

İşte benim CLAUDE.md dönüşümüm:

Önce (alıntı):

## Kimlik Doğrulama Kuralları
Kimlik doğrulamayla ilgili kodlar üzerinde çalışırken, lütfen yerleşik güvenlik uygulamalarımızı takip ettiğinizden emin olun. Bu, bunlarla sınırlı olmamak üzere şunları içerir: işlemeden önce tüm kullanıcı girişlerini doğrulamak, hassas bilgileri sızdırmayan uygun hata yönetimi uygulamak, /docs/security/ adresinde bulunan güvenlik belgelerimizde tanımlanan güvenli token saklama mekanizmalarını kullanmak...
[sadece auth üzerine 40 satır daha devam ediyor]

Sonra (alıntı):

## Auth
- Girişleri doğrula, çıktıları temizle
- Hatalar: mesajlarda hassas veri olmasın
- Tokenlar: /lib/auth/tokenStore kullan
- Uç durumlar için /docs/security belgesine bak

Aynı rehberlik. %90 daha az token.

Gerçek Verimlilik Kazancı

Neyin değiştiği ve neyin değişmediği konusunda dürüst olmak istiyorum.

Gerçekten iyileşenler:

• Ekip genelinde tutarlılık
• Daha az tekrarlanan hata
• Daha hızlı adaptasyon (yeni geliştiriciler bağlamı devralır)
• Daha az "Claude bunu neden yaptı?" hata ayıklaması

Çok değişmeyenler:

• Ham kodlama hızı (Claude zaten hızlıydı)
• Bireysel çıktıların kalitesi (model, konfigürasyondan daha önemlidir)

Asıl değer: bileşik öğrenme.

Her PR, CLAUDE.md'yi daha akıllı hale getirir. Her ekip üyesinin keşfi paylaşılan bir bilgiye dönüşür. Haftalar geçtikçe, "Claude kod tabanımızı anlıyor" ile "Claude tahmin yürütüyor" arasındaki fark açılır.

Boris'in iş akışı sihir değil. Disiplin.

Dosya küçük çünkü her satır yerini hak ediyor. Ekip katkıda bulunuyor çünkü sistem katkıyı ödüllendiriyor. Doğrulama döngüsü var çünkü bozuk kod göndermek pahalıdır.

Bunların hiçbiri zor değil. Sadece bilinçli.

---

Alireza Rezvani (Reza), mühendislik ekipleri için yapay zeka geliştirme sistemleri kuran bir CTO'dur.