En İyi CLAUDE.md Nasıl Yazılır: Claude Code için Eksiksiz Kılavuz

Claude Code'un sistem istemi, oturumunuz başlamadan önce zaten yaklaşık 50 talimat kaplıyor. Sınır LLM’ler üzerine araştırmalar, talimat takibinin toplam yaklaşık 150–200 talimatta bozulmaya başladığını gösteriyor; bu da projeyle ilgili Claude’un bilmesini istediğiniz her şey için size 100–150 civarı bir alan bırakıyor. 

CLAUDE.md bu alanları dolduran dosyadır. Her oturumun başında Claude Code tarafından okunan, sizin kendinizi tekrar etmeden kod tabanınıza kalıcı bağlam sağlayan bir markdown dosyasıdır. Ancak Claude, mevcut göreve ilgisiz gördüğü içeriği aktif olarak filtreler. Şişkin bir dosya yalnızca yer israfı değildir; gerçek kurallarınızla rekabet eder.

Bu eğitim, her satırı işe yarayan bir CLAUDE.md nasıl oluşturulur konusunu kapsar: ne girer, ne dışarıda kalır, ekipler için nasıl yapılandırılır ve zaman içinde nasıl faydalı tutulur.

Ayrıca yakın tarihli diğer Claude Code rehberlerimize de göz atmanızı öneririm:

• Claude Code Plan Mode
• Docker’da Claude Code
• Claude Code Eklentileri Nasıl Geliştirilir
• Claude Code’u Ollama Yerel Modellerle Kullanma

CLAUDE.md Dosyası Nedir?

CLAUDE.md, Claude Code’un her konuşmanın başında otomatik olarak yüklediği bir markdown dosyasıdır. Proje kökünüzde bulunur ve Claude’a aşağıdaki gibi pek çok ilgili bilgi için kalıcı talimatlar verir: 

• Kullandığınız teknoloji yığını
• Testleri nasıl çalıştırdığınız
• Hangi geleneklerin önemli olduğu
• Dokunulmaması gerekenler

Bu dosya olmadan her oturum sıfırdan başlar. Aynı bağlamı tekrar açıklarsınız, aynı varsayımları düzeltirsiniz ve Claude’un dün yaptığı aynı hataları yaptığını izlersiniz. CLAUDE.md, proje bilginizi bir kez kodlayarak bunu düzeltir.

Bu, Claude Code’un kullandığı birkaç bağlam sisteminden biridir ve her biri farklı işleri üstlenir:

/init çalıştırmak, kod tabanınızı analiz ederek, derleme sistemlerini, test çerçevelerini ve kod örüntülerini tespit ederek başlangıç niteliğinde bir CLAUDE.md üretir. Zaten bir dosya varsa, üzerine yazmak yerine iyileştirmeler önerir. Makul bir başlangıç noktasıdır, ancak dosya otomatiğe bırakılmayacak kadar önemlidir.

Bilmeniz gereken önemli bir nokta da CLAUDE.md içeriğinin /compact sonrasında da korunmasıdır. Bağlam oturum ortasında sıkıştırıldığında, Claude dosyayı diskten yeniden okur ve taze şekilde tekrar enjekte eder.

Dosya konumları ve öncelik

CLAUDE.md dosyaları en genişten en özeline doğru dört yerde bulunabilir:

• Yönetilen ilke (kurum genelinde): macOS’te /Library/Application Support/ClaudeCode/CLAUDE.md. Makinedeki tüm kullanıcılara uygulanır ve herhangi bir ayarla hariç tutulamaz. Linux/WSL’de /etc/claude-code/CLAUDE.md, Windows’ta C:\Program Files\ClaudeCode\CLAUDE.md.

• Kullanıcı düzeyi: ~/.claude/CLAUDE.md. Makinenizdeki tüm projelerde geçerli kişisel talimatlar.

• Proje düzeyi: Depo kökünde ./CLAUDE.md veya ./.claude/CLAUDE.md. Git’e işleyip ekibinizle paylaştığınız dosya budur.

• Alt dizin: ./subdir/CLAUDE.md. O dizin kapsamındadır ve oturum başında değil, Claude oradaki dosyaları okuduğunda talep üzerine yüklenir.

Daha spesifik dosyalar daha geniş olanlara göre önceliklidir. Proje CLAUDE.md dosyanız “sekme kullanın” diyor, kullanıcı düzeyi dosyanız “boşluk kullanın” diyorsa, proje dosyası kazanır.

Sürüm kontrolüne girmemesi gereken kişisel tercihler için bir CLAUDE.local.md oluşturun ve .gitignore’a ekleyin. Editör tuhaflıkları, tercih edilen commit stilleri veya geçici geçersiz kılmalar ortak dosyayı kirletmek yerine burada dursun.

Dosyanın nerede yaşadığını ve nelerle yarıştığını bildiğinize göre, sıradaki soru içine gerçekten nelerin girmesi gerektiğidir.

CLAUDE.md İçinde Neler Olmalı

Bir CLAUDE.md üç katmana ayrılır: 

1. Projenin ne olduğu
2. Neden bu şekilde çalıştığı
3. Claude’un bunun içinde nasıl çalışması gerektiği

Eğer Claude Code En İyi Uygulamalar yazısını okuduysanız, bunun daha dar bir yüzeye uygulanan aynı ilke olduğunu fark edeceksiniz. (Okumadıysanız, bu makaleden sonra mutlaka göz atın!)

Yüksek sinyalli proje özeti

Bir ya da iki satırlık proje tanımı ve sürüm numaralarıyla teknoloji yığınınızla açın. Claude kodunuzu okuyarak çok şey çıkarabilir, ancak Next.js 14 yerine 15 kullandığınızı ya da Prisma yerine Drizzle’ı seçtiğinizi tahmin etmeyecektir.

Bir dizin yapısı haritası ekleyin. Her dosya değil, yalnızca üst düzey yerleşim ve kısa açıklamalar:

src/
  data/        # Data loading and preprocessing pipelines
  models/      # Model definitions and training loops
  evaluation/  # Metrics, validation, experiment tracking
  api/         # FastAPI endpoints for model serving
  tests/       # Co-located with source, test_*.py

Ortak komutları kod bloklarına koyun. Derleme, test, lint ve geliştirme sunucusu başlatma. Bir kod çiti içinde verilen komut Claude tarafından kelimesi kelimesine çalıştırılır. Cümle içinde yazılan komut ise Claude’un doğaçlama yapabileceği bir öneridir.

Amaç ve kısıtlar

Mimari kararlarınız dosyada yer almalı; aksi takdirde Claude kendi kararlarını verir. Bir nedenle SQLite’ı Postgres’e tercih ettiyseniz, belirtin. API katmanınız belirli bir örüntüyü izliyorsa, gerekçesini açıklayın.

Gerekçe burada gerçek iş görür. “Asla force push yapma” baskı altında Claude’un görmezden gelebileceği düz bir talimattır. “Asla force push yapma. Bu, paylaşılan geçmişi yeniden yazar ve ekip arkadaşları için geri döndürülemez,” Claude’a genelleme yapacak kadar bağlam verir. Sadece git push --force’tan kaçınmakla kalmaz. Paylaşılan bir daldaki git reset --hard işleminde de tereddüt eder.

Claude için çalışma talimatları

Bu bölüm, Claude’un yalnızca kodu okuyarak kavrayamayacağı gelenekleri kapsar. Conventional Commits (feat:, fix:, docs:) kullanıyorsanız, belirtin. Dallar initials/description gibi bir adlandırma örüntüsünü izliyorsa, yazın.

Tuhaflıklar ve tuzaklar da buraya aittir. Her kod tabanında vardır: Derlemelerden önce çalıştırılması gereken göç (migration) betiği, testler geçmeden önce belirli bir değeri alması gereken ortam değişkeni, sıradışı şekilde içe aktarılırsa bozulan modül. Claude her oturumda yeni bir ekip üyesidir ve bunlar, bir yeni başlayan kişinin ilk gününde tökezleyeceği şeylerdir.

Atlayabileceğiniz şeyler: dilin kendisinden Claude’un zaten bildikleri. Modern JavaScript’te async/await kullanmasını ya da Python 3’te pathlib’i tercih etmesini söylemenize gerek yok. Bir gelenek dilin varsayılanıysa, bunu yazmak aslında önemli talimatları kalabalıklaştıran gürültüdür.

CLAUDE.md Dosyası Nasıl Yazılır

İçeriği doğru almak işin daha kolay yarısıdır. Zor olan, Claude’un gerçekten takip edeceği talimatları yazmak ve neyi keseceğini bilmektir.

Etkili talimatlar yazma

Belirlilik, niyeti her zaman yener. “Kodu düzgün biçimlendir” Claude’a hiçbir şey söylemez. “2 boşluk girintisi, noktalı virgül yok, tek tırnak” tam olarak ne yapacağını söyler ve doğrulanabilir bir temel verir.

Her satıra şu testi uygulayın: “Bunu kaldırmak Claude’un hata yapmasına neden olur mu?” Yanıt hayırsa, o satır gider. Resmi öneri dosya başına 200 satırın altıdır ve deneyimli bazı ekipler 60’ın altında çalışır. Bu salt minimalizm için değil: daha kısa dosyanın daha büyük kısmı okunur.

Başlık düzeylerini en fazla üçte tutun. README geleneklerinden ajanların tanıdığı bölüm adlarını kullanın: Commands, Structure, Conventions, Testing. Bölüm adlarında yaratıcı olmak sürtünme yaratır; çünkü Claude milyonlarca README görmüştür ve neyin nerede bulunacağına dair güçlü beklentileri vardır.

Bir kural dosyada olmasına rağmen sürekli göz ardı ediliyorsa, etrafına daha fazla kelime eklemeyin. Başına IMPORTANT: veya YOU MUST ekleyin. Ancak bunu cimri kullanın; çünkü vurgu ölçeklenmez. Her kural önemli olarak işaretlenirse vurgu görünmez olur.

Neleri dışarıda bırakmalı

Kod stilinin zorlanması en büyük tuzaktır. Biçimlendirme, girinti, içe aktarma sıralaması: bunlar belirlenimli çözümleri olan belirlenimli sorunlardır. Biome, ESLint veya Ruff gibi linters ve formatlayıcılar bunları daha hızlı, daha ucuza ve %100 tutarlılıkla halleder. Talimat bütçesini stil kurallarına harcamak ölü yüktür: aynı işi bir pre-commit kancası bedavaya yapar.

Standart dil gelenekleri de dışlama listesinde olmalı; zira Claude zaten TypeScript örüntülerini ve Python deyimlerini bilir. Tam API dokümantasyonu gömülmek yerine bağlantı verilmelidir. Yalnızca belirli iş akışlarına uygulanan göreve özel talimatlar, her oturumda yer kaplamak yerine talep üzerine yüklenen yeteneklere (skills) aittir.

Bahsetmeye değer bir örüntü: yalnızca olumsuz kısıtlar. “Asla --legacy-peer-deps kullanma” Claude’u bir bağımlılık çatışmasına çarptığında kilitler. Her yasağı bir yönlendirmeyle eşleyin: “Asla --legacy-peer-deps kullanma; çatışmaları paketi uyumlu bir sürüme güncelleyerek çöz.” Cursor Kuralları veya benzeri AI yapılandırma dosyalarıyla çalıştıysanız, bu ilkenin araçlar arasında geçerli olduğunu göreceksiniz.

Öncesi ve sonrası: minimal gerçek bir örnek

Farkın pratikte nasıl göründüğü burada. Solda, Claude’un zaten bildiği genel tavsiyelerle dolu tipik bir otomatik üretilmiş CLAUDE.md bölümü. Sağda, belirginlik testinin uygulanmasından sonra aynı bölüm: yalnızca projeye özgü gerçekler kaldı.

İkinci sürüm daha kısadır ve Claude’a kod tabanından çıkaramayacağı şeyleri söyler.

Dosyayı sıfırdan oluşturma

Proje kökünüzde /init çalıştırarak üretilmiş bir başlangıç noktası alın. Her satırı okuyun, bariz olanı kesin ve ekibinizin gerçekte nasıl çalıştığından eksik olanı ekleyin. /init çıktısından başlamak boş bir dosyadan daha hızlıdır, ancak otomatik üretilen içerik asla incelemesiz gönderilmemelidir.

Sıfırdan yazmayı tercih ediyorsanız, beş bölümle başlayın: 

1. Proje özeti
2. Dizin haritası
3. Komutlar
4. Gelenekler
5. Tuhaflıklar

Dosyayı daha sonra her zaman büyütebilirsiniz ve minimal başlamak, eklediğiniz her satırın varsayımdan değil gerçek bir hatadan kaynaklanması anlamına gelir.

Dosyanın bakıma ihtiyaç duyduğunu gösteren iki sinyal: 

• Claude, zaten orada olan bir talimatı kaçırdığı için özür diliyor: İfadede belirsizlik var; talimatı yeniden yazın.
• Aynı kural birden çok oturumda ihlal ediliyor: Dosya çok uzun; Claude onu filtreliyor; kısaltın.

İkisi de aynı çözüme işaret eder: daha az kelime, daha net yapı.

Ekipler için CLAUDE.md Dosyalarını Ölçeklemek

Tek geliştiricilik bir dosya süresiz bu kadar yalın kalabilir. Bir ekip işin içine girdiğinde ise dosyanın farklı bir yapıya ihtiyacı olur.

Sürüm kontrolü ve paylaşılan sahiplik

Proje düzeyindeki CLAUDE.md dosyanız git’te olmalıdır. Ekip arkadaşlarının kendi hatalarından getirdikleri kurallarla daha iyi hale gelen paylaşılan dokümantasyondur. Değişikliklerine kod PR’ları gibi muamele edin: gözden geçirin, her yeni satırın yerini hak edip etmediğini sorgulayın.

Gelenekler tek bir dosyaya sığmayacak kadar biriktiğinde, onları .claude/rules/ dizinine taşıyın. Her Markdown dosyası açıklayıcı dosya adlarıyla bir konuyu kapsasın: testing.md, api-design.md, database-migrations.md. Claude bu dosyaları özyinelemeli olarak keşfeder ve ana CLAUDE.md ile aynı öncelikle yükler.

Yol kapsamlı kurallar bunu daha da hedefli hale getirir. YAML ön bilgisi (frontmatter) ekleyin; kural yalnızca Claude eşleşen dosyalarla çalışırken yüklensin:

---
paths:
  - "src/api/**/*.ts"
---
# API conventions go here

Ön uç gelenekleriniz arka uçta çalışırken talimat bütçesini yakmayacak; tersi de geçerli.

Takımın çelişen geleneklere sahip olduğu monorepolarda, claudeMdExcludes belirli dosyaların yüklenmesini engeller:

{
  "claudeMdExcludes": [
    "**/other-team/.claude/rules/**"
  ]
}

Bunu sürüm kontrolü dışında tutmak için .claude/settings.local.json içine koyun.

Aşamalı açıklama ve modülerleştirme

Bir CLAUDE.md’yi ölçeklemek genellikle merkezileştirme dürtüsünü tetikler: her şeyin olduğu tek büyük dosya. Bu yanlış yön. Bir monorepo’nun CLAUDE.md’sini servis düzeyi dosyalara bölmek toplam kelime sayısını %80 azaltabilir ve Claude’un kurallara uyumunu iyileştirebilir; oturum başına daha az okunacak şey, daha az filtrasyon demektir.

İlke: göm değil, işaret et. @path/to/big-doc.md (her oturuma tüm dosyayı yükler) yazmak yerine “Geçiş (migration) prosedürleri için bkz. docs/migrations.md.” yazın. Claude bilgiye ihtiyaç duyduğunda okur. @ içe aktarma söz dizimi küçük dosyalar için çalışır, ancak hatırı sayılır her şey gömmektense referans verilerek daha iyi kullanılır.

Alt dizin CLAUDE.md dosyaları bu deseni tamamlar. React gelenekleri içeren bir frontend/CLAUDE.md yalnızca Claude o dizindeki dosyalara dokunduğunda yüklenir. Arka uç kuralları, ön uç iş sırasında aradan çekilir.

CLAUDE.md Dosyanızı Sürdürme

Primitifleri öğrendikten sonra ölçeklenebilir yapı büyük ölçüde çözülmüş bir problemdir. Ancak projeler değişir, gelenekler evrilir. Altı ay önce mantıklı olan kurallar, artık önemli olanları gölgeleyen gürültüye dönüşebilir. Süregelen zorluk dosyayı zaman içinde dürüst tutmaktır.

Dosyayı güncel tutma

Kuralları düşündüğünüzden daha yavaş ekleyin. Yeni bir satır ancak Claude’un o satırın önleyeceği gerçek bir hata yaptığında dosyada yerini almalı. Her kural gerçek bir vakaya geri izlenebilmelidir, uydurma bir duruma değil.

Tersi yön de en az bu kadar önemlidir: Claude bir geleneğe söylenmeden zaten uyuyorsa, o kural ölü yüktür. Kaldırın ve davranışı değiştiren kurallar için talimat bütçesini serbest bırakın.

Düşük çabalı bir bakım alışkanlığı, her birkaç haftada bir Claude’a “Bu CLAUDE.md’yi gözden geçir ve iyileştirme öner” demektir. Kurallar arasındaki çelişkileri saptar, örtüşen talimatları işaretler ve daha sıkı hale getirilebilecek ifadeleri belirler. 

Ayrıca dosyanın kendisine de kalıcı bir talimat ekleyebilirsiniz: “Bir oturumda kötü bir varsayımla karşılaştığında, bir CLAUDE.md düzeltmesi öner.” Bu, dosyanın normal kullanım içinde iyileştiği bir geri bildirim döngüsü oluşturur.

Kaçınılacak anti‑örüntüler

En yaygın başarısızlık modu birikimdir. Her can sıkıcı oturumdan sonra kurallar yığılır, artık önemli olmayanları kimse kaldırmaz ve sonunda dosya o kadar uzar ki Claude yarısını filtreler. Claude bir kuralı göz ardı etmeye devam ettiğinde, şişkin bir dosyada vurguyu artırmak sorunu çözmez. Budama çözer.

Büyük dosyalar için @ içe aktarmaları kullanıyorsanız, kontrol edilecek ikinci sorun budur. @ ile içe aktarılan 500 satırlık bir mimari belge, ilk gerçek kuralınızı işlemeden talimat bütçenizi yakarak, her oturuma tüm belgeyi gömer. Bunun yerine referans verin.

/init ile otomatik üretip çıktıyı asla derlememek, her alanda kötü davranış almanın güvenilir bir yoludur. CLAUDE.md’deki yanlış bir talimat yalnızca tek bir yanıtı etkilemez. Birisi fark edene kadar her oturumda Claude’un araştırmasını, planlamasını ve uygulamasını şekillendirir.

Birden çok dosyadaki çelişkili kurallar öngörülemez davranışlara neden olur. İki kural çakıştığında Claude hangisini seçtiğini söylemeden birini seçer. Bu, kök bir CLAUDE.md’nin birkaç .claude/rules/ dosyayla birleştirildiği projelerde daha da kötüleşir. Tüm talimat dosyaları arasında periyodik inceleme tek önlemdir.

Her hata yeni bir kuralı hak etmez. Bazı başarısızlıklar tek seferliktir. Her uç durum için eklenen bir kural, çoğu oturumda yardımcı olmaktan çok zarar veren, koşullu talimatlarla dolu bir dosya yaratır. Baştan beri hedef aynıydı: her satırın davranışı değiştirdiği kısa bir dosya.

Sonuç

CLAUDE.md, bir Claude Code projesindeki en yük taşıyan dosya olabilir. Tek bir komut yazılmadan önce her oturumu şekillendirir ve iyi bakımı yapılan bir dosya, haftalar süren çalışmalarda bileşik etki yaratır.

Henüz yoksa /init çalıştırın, çıkanları okuyun ve gerçek bir hatayı önlemeyecek her satırı kesin. Varsa, şimdi açın ve aynı testi uygulayın. Projenizi açıklamak için CLAUDE.md’nizin devasa olması gerekiyorsa, bu daha büyük bir dosyaya ihtiyacınız olduğunun değil, projenin araç setinin fazla karmaşık olduğunun sinyalidir.

Doğru sonraki adım: deponuzu denetleyin ve bugün bir temel taslak çıkarın. Beş bölümle başlayın, 60 satırın altında tutun ve buradan itibaren her eklemeyi gerçek hatalar yönlendirsin.

Eğer Anthropic API’yi kullanan araçlar geliştirmek istiyorsanız, Introduction to Claude Models kurusu tüm model ailesini kapsar ve onları etkili şekilde nasıl kullanacağınızı öğretir.