Nasıl çalıştığını gerçekten anlatan bir CLAUDE.md nasıl yazılır

Ahmet Karaca · 2026-10-12

Ne işe yarıyor

Claude Code oturumun başında CLAUDE.md'yi okuyor — ev klasöründekini her proje için, proje klasöründekini o proje için. İşe başlamadan gördüğünden emin olduğun tek şey bu; o yüzden doğru yazmaya da kısa tutmaya da değer.

İçine ne girer

• Birden fazla kez düzelttiğin şeyler. İki kez "hayır, önce sor" dediysen o bir kuraldır.
• Sınırlar: sormadan asla olmaması gerekenler — silmek, göndermek, ödemek, yayınlamak.
• Cevapları nasıl istediğin: uzunluk, biçim, dil, neyin şişirilmemesi gerektiği.
• Bir kez bir saatine mal olmuş tuzaklar: ortam değişkeninin biçimi, derleme bayrağı, platformun bir tuhaflığı.
• Tahmin edemeyeceği komutlar: testler nasıl çalışır, nasıl derlenir, örnek veriler nereden gelir.

Kuralın yanına nedenini yaz. Silmeden önce neden sorduğunu bilen bir model, üzerine yazmadan önce de sorar; yalnız "asla silme"yi bilen sormaz.

# Nasıl çalışırım

- Dosya silmeden ya da sıfırlama komutu çalıştırmadan önce sor.
  (Bir temizlikte çizimlerin olduğu klasör gitti.)
- Üçten fazla dosyaya dokunacaksan önce birkaç satırlık plan yaz.
- Sabit sayı değil formül: 340 değil, taban * seviye^2,2.
- Kısa cevap. Kapanış cümlesi yok.

# Tuzaklar
- Railway ortam değişkenleri Section__Key, çift alt çizgi.
- Flutter web, index.html'e yönlendiren bir vercel.json istiyor.

Dışarıda ne kalır

• Kodun zaten söylediği her şey. Kodu okuyabiliyor.
• Dilekler. "Temiz kodu önemserim" hiçbir şeyi değiştirmez; "bir dosyayı 400 satırı geçmeden böl" değiştirir.
• Gelecek ay eskiyecek proje durumu. Değişmesi beklenen bir yere koy.
• Uzun yazılar. Her satır her oturumda yükleniyor; bir sayfalık düz yazının bedeli her seferinde ödeniyor.

Zor olan doğru tutmak

İlk sürüm kolay, çünkü aklında olanı yazıyorsun. En önemli kurallar ise aklında olmayanlar: onları ancak bir şey ters gidince fark ediyorsun ve o anda dosyayı değil sorunu düzeltiyorsun. Böylece dosya bariz olanı topluyor, gerçek olanı kaçırıyor.

Sonra eskiyor. Geçen bahardan kalma bir tercihe, fikrini değiştirdikten sonra da uyuluyor. İki satır sessizce birbiriyle çelişiyor, model birini seçiyor. Dosyada hangi kuralın hâlâ doğru olduğunu ya da neye dayandığını söyleyen bir şey yok.

İşe yarayan bir alışkanlık: Claude'u düzelttiğinde bunun bir kural olup olmadığını sor. Dosyayı açtığında artık sana ait olmayan bir satırı sil.