CLAUDE.md Dosyası Nasıl Yazılır? Claude Code İçin Dikkat Edilmesi Gerekenler

Claude Code ile çalışırken yapay zekânın projenizi her oturumda baştan tanıması ne kadar yorucu, değil mi? İşte tam bu noktada devreye giren CLAUDE.md dosyası, asistana projenizin kurallarını, komutlarını ve mimari kararlarını kalıcı olarak öğreten bir not defteri görevi görür. Bu rehberde, etkili bir bellek dosyasının nasıl yazıldığını, nereye konması gerektiğini ve sık yapılan hataları sizler için adım adım derledik.

Doğru kurgulanmış bir dosya, Claude’un yanlış varsayımlar yapmasını engeller ve her oturumda aynı açıklamaları tekrar yazma zahmetinden sizi kurtarır. Gelin önce temelden başlayalım.

CLAUDE.md Dosyası Nedir?

CLAUDE.md, projenizin kök dizininde tutulan ve Claude Code’un her oturumun başında otomatik olarak okuduğu bir Markdown dosyasıdır. İçine yazdığınız her şey, siz konuşmaya başlamadan önce modelin bağlamına (context) yüklenir. Yani asistan, projenize dair sizin önceden tanımladığınız kurallarla işe başlar.

En sade ifadeyle bu dosya, ekibe yeni katılan bir geliştiriciye uzatacağınız bir tanıtım (onboarding) rehberidir. Fark şu: Claude her oturuma “sıfır kilometre” gelir, dolayısıyla bu rehbere her seferinde ihtiyaç duyar.

Burada kritik bir ayrımı bilmek gerekir. CLAUDE.md içeriği, sistem talimatı (system prompt) gibi katı bir kural katmanı değildir; Anthropic’in resmi belgelerine göre içerik, model için bağlam olarak sunulur. Yani talimatlarınız ne kadar net ve kısa olursa, Claude onlara o kadar tutarlı uyar. Bu yüzden “yazdım ve bitti” değil, “yazdım ve özenle düzenliyorum” mantığıyla yaklaşmak gerekir.

Claude Code’a yeni başlıyorsanız, bu dosyayı yapılandırmadan önce aracın temel kullanımını öğrenmek işinizi kolaylaştırır. Bu konuda hazırladığımız Claude Code nasıl kullanılır adlı başlangıç rehberimize göz atmanızı öneririz.

CLAUDE.md Dosyası Nasıl Oluşturulur?

En hızlı yol, projenizin kök dizininde Claude Code içinde /init komutunu çalıştırmaktır. Bu komut kod tabanınızı analiz eder; derleme (build) komutlarını, test betiklerini ve dizin yapısını tespit ederek size bir başlangıç şablonu üretir.

/init mükemmel bir taslak verir ama bitmiş bir ürün değildir. Asıl değer, komutun keşfedemeyeceği bilgileri sizin eklemenizdedir: ekibinizin tercih ettiği isimlendirme kuralları, tuzaklar (gotchas) ve mimari kararlar gibi.

Oturum sırasında hızlı bir not eklemek isterseniz, mesaj kutusuna # karakteriyle başlayan bir satır yazabilirsiniz. Claude bunu doğrudan belleğe kaydeder. Yüklü dosyaları görmek ve düzenlemek içinse /memory komutunu kullanabilirsiniz.

CLAUDE.md Bellek Hiyerarşisi Nasıl İşler?

Tek bir CLAUDE.md ile sınırlı değilsiniz. Claude Code, geniş kapsamdan dara doğru farklı konumlardaki dosyaları sırayla yükler ve hepsini bağlamda birleştirir. Bu katmanlı yapıya Claude Code bellek hiyerarşisi denir.

Anthropic’in Claude Code bellek (memory) dokümantasyonuna göre dosyalar şu öncelik sırasıyla okunur (en genel kapsamdan en özele):

• Yönetilen politika (managed policy): Kurum genelinde IT/DevOps tarafından dağıtılan, kullanıcıların hariç tutamadığı talimatlar (örneğin Windows’ta C:\Program Files\ClaudeCode\CLAUDE.md).
• Kullanıcı talimatları: ~/.claude/CLAUDE.md — bilgisayarınızdaki tüm projelere uygulanan kişisel tercihleriniz.
• Proje talimatları: Proje kökündeki ./CLAUDE.md (veya ./.claude/CLAUDE.md) — ekipçe sürüm kontrolü üzerinden paylaşılan standartlar.
• Yerel talimatlar: ./CLAUDE.local.md — yalnızca size özel, repoya girmemesi gereken notlar.

Bu dosyalar birbirini ezmez; hepsi peş peşe bağlama eklenir. Ayrıca alt dizinlerdeki CLAUDE.md dosyaları başta yüklenmez, yalnızca Claude o dizindeki bir dosyaya eriştiğinde devreye girer. Bu da büyük projelerde (monorepo) bağlamı gereksiz yere şişirmeden bölge bölge kural tanımlamanıza imkân verir.

CLAUDE.local.md ve Kişisel Tercihler

Sandbox URL’leriniz, tercih ettiğiniz test verileri ya da geçici notlar gibi yalnızca sizi ilgilendiren ayarları takımın ortak dosyasına yazmak doğru değildir. Bunun yerine proje kökünde bir CLAUDE.local.md oluşturun ve bu dosyayı .gitignore içine ekleyin. Böylece kişisel notlarınız repoya karışmaz, ekibin ortak CLAUDE.md dosyası temiz kalır.

İçe Aktarma (@path) Sözdizimi

Dosyanızı bölmek isterseniz, başka dosyaları @yol/dosya söz dizimiyle içe aktarabilirsiniz. Örneğin @README.md ya da @docs/git-talimatlari.md yazdığınızda, bu dosyalar başlangıçta CLAUDE.md ile birlikte bağlama dahil edilir. İçe aktarmalar özyinelemeli (recursive) çalışır ve en fazla dört kademe derinliğe izin verilir. Not: İçe aktarma yapmadan bir dosya yolundan yalnızca bahsetmek istiyorsanız, yolu tırnak içine (`backtick`) alın.

Etkili Bir CLAUDE.md Yazarken Nelere Dikkat Edilmeli?

Dosyanın varlığı tek başına yeterli değildir; içeriğin nasıl yazıldığı, Claude’un talimatlara ne kadar uyacağını doğrudan belirler. İşte uymanız gereken temel ilkeler:

• Kısa ve odaklı tutun. Anthropic, dosya başına 200 satırın altını hedeflemenizi önerir. Uzun dosyalar daha fazla bağlam tüketir ve önemli kuralların gürültü içinde kaybolmasına yol açar.
• Spesifik olun. “Kodu düzgün biçimlendir” yerine “2 boşluklu girinti kullan”; “testleri çalıştır” yerine “commit öncesi npm test çalıştır” yazın. Doğrulanabilir, somut talimatlar her zaman daha iyi sonuç verir.
• Yapı kullanın. İlgili kuralları Markdown başlıkları ve madde işaretleriyle gruplayın. Claude da insanlar gibi düzenli bölümleri yoğun paragraflardan daha kolay tarar.
• Yasakla birlikte çözüm verin. “Şunu asla kullanma” deyip bırakmayın; alternatifini de belirtin. Aksi halde asistan bir engelle karşılaştığında çıkış yolu bulamaz.
• Vurgu ekleyin. Kritik kuralların başına büyük harfle ÖNEMLİ (IMPORTANT) ya da MUTLAKA (YOU MUST) gibi ifadeler koymak, modelin o talimata uyumunu artırır.
• Çelişkiden kaçının. Farklı dosyalarda birbiriyle çelişen iki kural varsa, Claude bunlardan birini rastgele seçebilir. Dosyalarınızı periyodik olarak gözden geçirip eskiyen kuralları temizleyin.

Pratik bir öz-denetim hilesi olarak, eklediğiniz her satır için kendinize şunu sorun: “Bu satırı silsem, Claude hata yapar mıydı?” Yanıt hayırsa, o satır muhtemelen gereksizdir. Anthropic’in Claude Code en iyi uygulamalar belgesinde de vurgulandığı gibi, şişkin bir dosya asıl talimatlarınızın göz ardı edilmesine neden olur.

CLAUDE.md Dosyasına Ne Yazılmalı, Ne Yazılmamalı?

Doğru içeriği seçmek, dosyayı kısa tutmanın da anahtarıdır. Genel kural şudur: Claude’un kodu okuyarak çıkaramayacağı, projeye özgü bilgileri yazın; geri kalanı dışarıda bırakın.

Yazılması önerilenler:

• Claude’un tahmin edemeyeceği terminal (Bash) komutları.
• Dilin varsayılanından farklı kod stili kuralları.
• Test çalıştırma talimatları ve tercih edilen test aracı.
• Depo görgü kuralları (dal/branch isimlendirme, PR kuralları).
• Projeye özgü mimari kararlar ve geliştirme ortamı tuhaflıkları (gerekli ortam değişkenleri gibi).
• Sık karşılaşılan tuzaklar ve aşikâr olmayan davranışlar.

Yazılmaması gerekenler:

• Claude’un kodu okuyarak zaten çıkarabileceği her şey.
• Modelin bildiği standart dil kuralları.
• Ayrıntılı API dokümantasyonu (bunun yerine resmi dokümana link verin).
• Sık değişen bilgiler ve dosya dosya kod açıklamaları.
• “Temiz kod yaz” gibi aşikâr, genel-geçer öğütler.

Yalnızca belirli durumlarda gereken alan bilgisi ya da uzun iş akışları için CLAUDE.md yerine beceriler (skills) veya .claude/rules/ dizinindeki yol-kapsamlı kuralları kullanmak daha doğrudur; böylece bu içerik yalnızca gerektiğinde yüklenir. İstisnasız her seferinde çalışması gereken işlemler içinse, tavsiye niteliğindeki CLAUDE.md yerine deterministik kancalar (hooks) tercih edilmelidir.

CLAUDE.md Yazarken Sık Yapılan Hatalar Nelerdir?

İyi bir dosyayı bozan birkaç tipik tuzak vardır. Bunları baştan bilmek, sonradan yaşanacak hayal kırıklıklarını önler:

• Aşırı uzun dosya: En yaygın hata budur. Dosya şişince Claude kuralların yarısını atlar, çünkü önemli talimatlar gürültü içinde kaybolur. Acımasızca budayın.
• Belirsiz ifadeler: Claude, dosyada yanıtı olan soruları size soruyorsa, ifadeleriniz muhtemelen muğlaktır. Net ve somut yazın.
• Yaşayan doküman olarak görmemek: CLAUDE.md bir kez yazılıp unutulan bir belge değildir. Claude, bir satırın önleyebileceği bir hatayı tekrar yaptığında o satırı ekleyin; birkaç hafta içinde dosya, deponuzun en isabetli rehberine dönüşür.
• Git’e eklememek: Proje düzeyindeki CLAUDE.md’yi sürüm kontrolüne dahil edin ki ekibiniz katkı verebilsin ve kuralların evrimi takip edilebilsin.
• Yanlış araçtan beklenti: CLAUDE.md bir davranış rehberidir, garantili bir uygulama katmanı değildir. Bir adımın istisnasız çalışması şartsa, çözümü kanca (hook) yazmaktır.

Son bir not: Eğer deponuz başka yapay zekâ araçları için AGENTS.md kullanıyorsa, Claude Code yalnızca CLAUDE.md okur. Bu durumda CLAUDE.md içine @AGENTS.md satırını ekleyerek her iki aracın da aynı talimatları görmesini sağlayabilirsiniz.

Claude Code ekosistemini daha verimli kullanmak istiyorsanız, hazır yapılandırmalardan da faydalanabilirsiniz. Bu noktada Claude Code skill’leri için en popüler GitHub repolarını derlediğimiz yazımız ve farklı araçları karşılaştırdığımız yazılımcılar için en iyi AI kod asistanları içeriğimiz başvurabileceğiniz iyi kaynaklardır.

Sonuç

İyi yazılmış bir CLAUDE.md, Claude Code’dan alacağınız verimi belirleyen en yüksek kaldıraçlı adımdır. Kısa, spesifik, yapısal ve yaşayan bir dosya; asistanın yanlış varsayımlarını azaltır, tekrarları ortadan kaldırır ve zamanla ekibinizin en doğru tanıtım belgesine dönüşür. /init ile başlayın, sonra projeye özgü bilgileri ekleyerek dosyayı kendi ihtiyaçlarınıza göre olgunlaştırın.

Yapay zekâ destekli kod yazımı ve bu yeni geliştirme kültürü ilginizi çekiyorsa, sitemizde yer alan “Vibe Coding Nedir? Yapay Zeka ile Kod Yazma Nasıl Yapılır?” adlı yazımıza da göz atabilirsiniz.