CLAUDE.md, Claude Code’a proje kurallarını ve çalışma biçimini anlatmak için kullanılan bir Markdown dosyasıdır. Her yeni görevde aynı bilgileri tekrar yazmak yerine, projenin kalıcı talimatlarını bu dosyada toplarsınız. Örneğin hangi test komutunun kullanılacağını, Türkçe arayüz metinlerinin nasıl yazılacağını ve hangi dosyaların otomatik değiştirilmemesi gerektiğini belirtebilirsiniz.[1]
Dosyanın adı onu bir güvenlik duvarına dönüştürmez. Anthropic belgeleri, bu talimatların modelin bağlamına girdiğini; teknik olarak zorunlu uygulanan izin ayarlarından farklı olduğunu açıkça belirtiyor. Dolayısıyla “şifre dosyasını okuma” cümlesini yazmakla işletim sistemi veya araç düzeyinde erişimi engellemek aynı şey değildir.[1][2]
CLAUDE.md ne işe yarar?
Bir projede yalnızca kod bulunmaz; ekip alışkanlıkları, ürün tercihleri ve daha önce öğrenilmiş istisnalar da vardır. Koddan anlaşılması zor bu kararları görünür kılmak, yeni görevlerin aynı hatalarla başlamasını azaltabilir. Talimat dosyasının işlevi, modelin işi doğru çerçevede yürütmesine yardımcı olmaktır.[1]
Örneğin bir formun bütün hata mesajlarının Türkçe olması ürün kararıdır. Bir tarih alanının gün, ay ve yıl sırasıyla gösterilmesi de benzer bir beklentidir. Bunları yalnızca “iyi kullanıcı deneyimi sun” diye tarif etmek yerine ayrı ve kontrol edilebilir cümlelerle yazabilirsiniz.
Claude Code’u henüz kurmadıysanız önce kurulum rehberimize bakın. Buradaki adımlar, uygulamanın kurulmasından sonra proje talimatlarını hazırlama ve kontrol etme aşamasına odaklanır.
Dosya nereye konur?
Proje talimatları için çalışma klasöründeki CLAUDE.md veya .claude/CLAUDE.md kullanılabilir. Kişisel tercihler için kullanıcı dizinindeki ~/.claude/CLAUDE.md ayrı bir kapsama sahiptir. Alt klasörlerdeki talimatların yüklenme davranışı da klasör hiyerarşisiyle ilişkilidir; bütün kuralları aynı dosyaya rastgele doldurmak gerekmez.[1]
| Yer | Hangi tür bilgiye uygun? | Örnek |
|---|---|---|
| Proje kökündeki CLAUDE.md | Ekipçe paylaşılan proje kuralları | Test komutu, ürün dili |
| Kullanıcı CLAUDE.md | Kendi projelerinizdeki kişisel tercihler | Yanıt biçimi tercihi |
| Alt klasör talimatı | Belirli bölümün yerel kuralları | API hata yapısı |
| Ayar dosyaları | Teknik davranış ve izinler | Araç erişim kuralları |
Ekipçe kullanılacak dosyayı sürüm kontrolüne alırken kişisel notları ayırın. “Benim bilgisayarımda şu klasörü kullan” gibi bir yol bütün ekibin ortamında geçerli olmayabilir. Paylaşılan talimatlar mümkün olduğunca proje içinde doğrulanabilir bilgiler içersin.
İlk dosya nasıl oluşturulur?
Claude Code içinde /init komutu başlangıç dosyasının hazırlanmasına yardımcı olabilir. Araç projeyi inceleyerek komutlar ve mevcut gelenekler için taslak çıkarır. Bu taslağı doğrudan doğru kabul etmek yerine projenin gerçek yapılandırmasıyla karşılaştırın. Özellikle test ve derleme komutlarını kendi dosyalarınızdan doğrulayın.[1]
Elle hazırlamak isterseniz düz metin düzenleyicide yeni dosya açın ve adını tam olarak CLAUDE.md yapın. Windows’ta bilinen uzantılar gizliyse dosyanın yanlışlıkla CLAUDE.md.txt adını almadığını kontrol edin. Markdown olması, karmaşık biçimlendirme gerektirmez; birkaç açık başlık ve madde yeterlidir.
İlk sürüm için dört soru sorun: Bu proje ne yapıyor? Bir değişiklikten sonra nasıl kontrol edilir? Hangi ürün kararları korunmalı? Modelin koddan kolayca çıkaramayacağı hangi istisna var? Yanıtı bulunmayan alanı tahminle doldurmayın; proje dosyasını inceleyerek tamamlayın.
Kopyalanabilir Türkçe başlangıç şablonu
# Proje talimatları
## Ürün ve dil
- Bu proje küçük işletmeler için teklif hazırlama uygulamasıdır.
- Kullanıcıya görünen metinler Türkçe olmalıdır.
- Mevcut alan adlarını ve veri biçimlerini gerekçe olmadan değiştirme.
## Çalışma yöntemi
- Önce ilgili dosyaları ve mevcut davranışı incele.
- Değişikliği istenen sorunla sınırlı tut.
- Varsayım gerekiyorsa açıklamasını görev notuna ekle.
- Yeni bir bağımlılık önermeden mevcut araçlarla çözüm olup olmadığını kontrol et.
## Doğrulama
- Gerçek test ve derleme komutlarını proje yapılandırmasından doğrula.
- Çalıştırmadığın bir kontrolü başarılı olarak raporlama.
- Form değişikliğinde boş alan, geçersiz değer ve başarılı gönderimi değerlendir.
- Kullanıcıya görünen düzen değişikliğinde dar ekran görünümünü kontrol et.
## Hassas işlemler
- Gerçek kullanıcı verilerini örnek dosyalara taşıma.
- Parola ve erişim anahtarlarını rapora veya kod örneğine yazma.
- Yayına alma ve veri silme işlemlerini görev kapsamına göre değerlendir.
## Teslim notu
- Değişen davranışı kısa ve somut açıkla.
- Yapılan doğrulamayı ve kalan sorunu belirt.
- Dosya veya komut adı bilinmiyorsa tahminle doldurma.
Bu şablon bir ürün örneğidir. Kendi projenizde gereksiz maddeleri çıkarın ve doğruladığınız komutları ekleyin. Her projeye aynı dosyayı yapıştırmak yerine gerçekten geçerli beklentileri yazmak daha faydalıdır. Örneğin bir içerik sitesinin form doğrulama ihtiyaçlarıyla bir API projesinin kontrolleri farklı olabilir.
İyi talimat nasıl yazılır?
İyi talimat gözlenebilir davranışa işaret eder. “Temiz kod yaz” yerine “Aynı hesaplamayı ikinci kez eklemeden mevcut yardımcı fonksiyonu kontrol et” daha somuttur. “Her şeyi test et” yerine hangi davranışın hangi koşulda kontrol edileceğini anlatmak, sonucun değerlendirilmesini kolaylaştırır.[3]
Yine de dosyayı bir test planının tamamına dönüştürmeyin. Her küçük göreve uygulanmayan yüzlerce madde, önemli kuralları görünmez hale getirebilir. Genel dosyada kalıcı beklentiler bulunsun; o güne özgü görev ayrıntılarını görev mesajında veya ilgili belge içinde tutun.
Bir talimatın yararlı olup olmadığını anlamak için şu soruyu sorun: Bu satırı silersem modelin koddan çıkaramayacağı bir bilgi kayboluyor mu? Yanıt hayırsa satırı kısaltabilir veya kaldırabilirsiniz. Dosyanın değeri uzunluğundan değil, eksik bağlamı tamamlamasından gelir.
Dosyaya neler yazılmamalı?
Parola, API anahtarı ve gerçek kullanıcıya ait hassas veriler talimat dosyasına konmamalıdır. Dosya ekipçe paylaşılıyorsa içeriği sürüm kontrolü geçmişinde de kalabilir. Örneklerde gerçek erişim bilgileri yerine açıklayıcı yer tutucular kullanın ve gerekli teknik erişimi uygun yapılandırma mekanizmasıyla yönetin.[4]
Eski komut ve artık kullanılmayan klasör adları da ayrı bir sorundur. Geçersiz talimat, dosya bulunmadığında gereksiz arama ve yanlış değişikliklere yol açabilir. Projede paket yöneticisi değiştiyse doğrulama komutunu güncelleyin; eski ve yeni komutu açıklamasız yan yana bırakmayın.
Birbiriyle çelişen cümleleri de ayıklayın. “Yeni bağımlılık ekleme” ile “Gerekli gördüğün her paketi yükle” aynı kapsamda bulunursa karar belirsizleşir. İstisna gerekiyorsa koşulunu yazın: mevcut çözüm yetersizse gerekçeyi açıkla ve görev yetkisine göre ilerle.
CLAUDE.md, hafıza ve ayarlar arasındaki fark
Talimat dosyasını siz yazarsınız; otomatik hafıza ise aracın çalışma sırasında tuttuğu notlarla ilişkilidir. Ayarlar, model seçimi veya izin davranışı gibi teknik yapılandırmaları kontrol eder. Bu katmanların görevlerini karıştırırsanız yanlış yere yazılmış bir kuraldan beklediğiniz sonucu alamayabilirsiniz.[1][2]
Örneğin bütün projelerde Türkçe yanıt istemek kişisel tercih olabilir. Belirli projenin test komutu proje talimatına uygundur. Bir araç veya dosya yoluna erişimin teknik olarak kısıtlanması ise izin yapılandırmasıyla ele alınmalıdır. Aynı cümleyi dört dosyaya kopyalamak yerine doğru kapsama yerleştirin.
Uzun konuşmalarda kararların neden kaybolabildiğini bağlam penceresi rehberimizde açıklıyoruz. Kalıcı bir talimat dosyası bağlamı düzenlemeye yardımcı olur; bütün proje bilgisinin her an kusursuz kullanılmasını garanti etmez.
Dosyanın işe yaradığını nasıl kontrol edersiniz?
Önce aracın ilgili talimat dosyasını yüklediğini kontrol edin. Claude Code’un hafıza yönetimi ekranı ve komutları bu incelemeye yardımcı olur. Ardından zararsız ve küçük bir görev seçin: örneğin tek bir hata mesajını düzeltmek veya bir açıklama satırını güncellemek.[1]
Sonucu dosyadaki iki somut kuralla karşılaştırın. Kullanıcı metni Türkçe kaldı mı? Gerçekten çalıştırılan kontrol doğru raporlandı mı? Yalnızca “talimatları okudun mu?” sorusuna verilen olumlu cevabı kanıt saymayın. Asıl değerlendirme davranış üzerinden yapılmalıdır.
Başarısızlık durumunda aynı dosyaya daha fazla genel kural eklemeden önce nedeni ayırın. Dosya yüklenmedi mi? Kural belirsiz mi? Başka talimatla çelişiyor mu? İstenen iş bu kuralın kapsamına girmiyor mu? Her sebep farklı düzeltme gerektirir.
Ekip için küçük bir bakım düzeni
Talimat dosyasını kod değişiklikleri gibi gözden geçirin. Bir komut değiştiğinde, yeni bir ürün kuralı kabul edildiğinde veya aynı hata tekrarlandığında güncelleyin. Her başarısız denemenin bütün konuşmasını dosyaya yapıştırmak yerine, gelecekteki işe yarayacak kısa kuralı çıkarın.
Örneğin “dünkü testte tarih alanı yanlış oldu” notu kısa ömürlüdür. “Kullanıcıya görünen tarih alanlarında gün/ay/yıl düzenini koru; veri saklama biçimini ayrı değerlendir” daha kalıcı bir ürün beklentisidir. Bu satırın projeye uygunluğunu yine siz doğrulamalısınız.
Bakım sırasında bir kişi dosyadaki her komutun hâlâ çalıştığını, başka bir kişi ürün beklentilerinin güncel olduğunu kontrol edebilir. Dosyanın uzunluğu belirgin biçimde arttığında her bölümün bütün görevlerde gerekli olup olmadığını inceleyin. Bölüme özel kuralları ilgili kapsamda tutmak, ana dosyanın okunmasını kolaylaştırır.
Talimatı örnek görevle sınama
Talimatı somutlaştırmak için küçük bir örnek görev hazırlayın. Örneğin bir iletişim formunda boş telefon alanının nasıl ele alınacağını sorun. Kuralınız “zorunlu olmayan alanları zorunlu yapma” ise sonuçta telefon alanının davranışı korunmalı. Model alanı zorunlu yapmışsa yeni bir uzun uyarı eklemek yerine mevcut cümlenin kapsamını ve yüklenmesini inceleyin.
Aynı görev için eski ve yeni talimat dosyasıyla ayrı denemeler yapmak, değişikliğin etkisini anlamayı kolaylaştırır. Bu denemede üretim verisi kullanmanız gerekmez; birkaç hayalî kayıt yeterlidir. Sonuç notunda hangi dosyanın kullanıldığını ve hangi davranışın kontrol edildiğini yazın. Bir denemenin başarılı olması bütün görevlerde garanti oluşturmaz, ancak belirsiz bir talimatı iyileştirmek için somut başlangıç sağlar.
Ekip dosyasında yaptığınız değişikliğin gerekçesini de kısa tutun. “Formdaki isteğe bağlı alanların korunması için eklendi” açıklaması, aylar sonra dosyayı düzenleyen kişinin bu satırı neden silmemesi gerektiğini anlamasına yardımcı olur. Böylece talimat dosyası, geçmişteki hataların yığını yerine bakım yapılabilen bir proje parçası olarak kalır.
Deneme tamamlandığında dosyanın doğru klasörde bulunduğunu ve değişikliğin ekip arkadaşlarına hangi sürümle ulaştığını da kaydedin.
Sık sorulan sorular
CLAUDE.md zorunlu mu?
Her görev için zorunlu değildir. Aynı proje üzerinde tekrar çalışıyorsanız kalıcı kuralları aktarmak için yararlıdır. Basit ve tek seferlik bir işte gereksiz kapsam oluşturmak yerine ihtiyaca göre kullanın.
Bu dosya kod çalıştırır mı?
Markdown talimat dosyası bir program değildir. Ancak içerdiği yönergeler aracı belirli işlemlere yönlendirebilir. Bu nedenle bilmediğiniz bir projedeki talimatları da diğer proje dosyaları gibi inceleyin.[1][4]
CLAUDE.md güvenlik ayarının yerini tutar mı?
Hayır. Talimatlar davranışı yönlendirir; teknik izin ve erişim sınırları ayrı yapılandırmalardır. Hassas kaynakları korumak için yalnızca doğal dildeki uyarıya güvenmeyin.[2][4]
Aynı dosyayı her projede kullanabilir miyim?
Ortak başlangıç şablonu kullanabilirsiniz ama proje adı, komutlar ve istisnalar uyarlanmalıdır. Başka projeden kalan yanlış kural, hiç talimat olmamasından daha fazla karışıklık yaratabilir.
Kaynaklar ve hazırlama notu
Bu rehber resmî belgeler ve aşağıdaki birincil kaynaklar incelenerek hazırlandı. Uygulama örnekleri Dijipedya tarafından açıklama ve karşılaştırma amacıyla kurgulandı; ölçülmüş performans sonucu olarak sunulmaz. Özellik ve plan koşulları değişebilir.
- Anthropic, How Claude remembers your project. Bilginin alındığı tarih: 5 Kasım 2026.
- Anthropic, Settings files and precedence. Bilginin alındığı tarih: 5 Kasım 2026.
- Anthropic, Best practices for Claude Code. Bilginin alındığı tarih: 5 Kasım 2026.
- Anthropic, Security. Bilginin alındığı tarih: 5 Kasım 2026.
