CLAUDE.md Dosyasına Ne Yazılır?

Claude Code'a proje kurallarını sürekli yeniden anlatıyorsanız, bunları CLAUDE.md dosyasına yazın. Bu, Markdown biçiminde sıradan bir metin dosyasıdır. Claude Code oturumun başında dosyayı okur ve diğer bağlamla birlikte sizinle kararlaştırılan kuralları da alır.

Başlangıç için birkaç doğrulanmış satır yeter: nerede çalışılacağı, sonucun nasıl kontrol edileceği ve değişiklikler sırasında nelerin korunacağı.

CLAUDE.md Örneği

Basit bir kart sayfası düşünelim. İşaretleme, stiller ve JavaScript tek bir index.html dosyasındadır; sayfayı doğrudan tarayıcıda açabilirsiniz. Böyle bir projede talimat dosyası şöyle görünebilir:

# CLAUDE.md

## Proje
- Sayfa, stiller ve JavaScript `index.html` dosyasındadır.

## Kontrol
- `index.html` dosyasını tarayıcıda açın.
- Sayfayı geniş ve dar ekranda kontrol edin.

## Kurallar
- Kartların mevcut renklerini ve stilini koruyun.
- Onay almadan tamamlanmış blokları silmeyin.
- İşiniz bitince değişiklikleri ve kontrolleri listeleyin.

Burada üç grup var: projenin yapısı, sonucun kontrolü ve üzerinde anlaşılan kurallar. Artık "bir kart daha ekle" dediğinizde tüm kuralları baştan sıralamanız gerekmez. Yine de sayfayı kendiniz kontrol edebilirsiniz: talimat dosyası, ajanın böyle bir aracı yoksa ona tarayıcı erişimi sağlamaz.

Bu, tek bir dosya için örnek; evrensel bir şablon değil. Projenizde ayrı klasörler ve başlatma komutları olabilir. Dosyaya da kendi projenizdekileri yazın; test yoksa sırf eksiksiz görünsün diye komut uydurmayın.

Neleri Yazmalı?

Önce şu soruyu sorun: Bu bilgi sonraki görevlerde de işe yarayacak mı? Doğrulanmış komutlar, önemli yollar ve ajanın koddan güvenilir biçimde çıkaramayacağı anlaşmalar faydalıdır. Özellikle de daha önce tekrar tekrar anlatmak zorunda kaldıklarınız.

Kuralı, ajandan beklenen eylem açık olacak şekilde ifade edin:

• "her şeyi kontrol et" → "kartları değiştirdikten sonra sayfayı geniş ve dar ekranda kontrol et";
• "önemli şeylere dokunma" → "içerikleri üzerinde zaten anlaşıldığı için tamamlanmış blokları onay almadan silme".

İlk örnek kontrolü, ikincisi ise sınırın kapsamını ve nedenini belirtiyor. Bu, "dikkatli çalış" gibi uzun bir dilek listesinden daha yararlı.

README.md, projeyi okuyan kişiye tanıtır ve işe nasıl başlanacağını anlatır. CLAUDE.md ise ajana yönelik talimatları toplar. README'nin tamamını burada tekrarlamanız gerekmez. "Kartın genişliği yüzünden başlık kayıyor olabilir" gibi bir varsayımı da PROJECT_NOTE.md gibi mevcut göreve ait bir notta tutun. Bu, adını sizin seçtiğiniz sıradan bir dosyadır; göreve devam ederken ajandan dosyayı okumasını isteyin.

Varsayımı doğrulanmış bir gerçek gibi yazmayın; parolaları veya erişim anahtarlarını da burada saklamayın. Ekipteki diğer kişilerin de aynı talimatları proje ile birlikte alması için genel CLAUDE.md dosyası genellikle Git'e eklenir.

Dosya Nasıl Oluşturulur ve Kontrol Edilir?

Önceden netleşmiş kurallarla başlayın. Uzun bir hata listesi birikene kadar beklemeniz veya olası her durumu baştan tarif etmeniz gerekmez.

1. Projede hazır bir CLAUDE.md olup olmadığına bakın. Varsa okuyup tamamlayın. Yeni dosya için projenin kök dizinini seçin; .claude/CLAUDE.md konumu da desteklenir, ancak iki kopya oluşturmanız gerekmez.
2. Birkaç satırı elle yazın ya da proje klasöründe açtığınız Claude Code içinde /init komutunu girin. Komut projeyi inceler ve bir taslak hazırlar; dosya zaten varsa iyileştirme önerir.
3. Sonucu okuyun. Komutları ve yolları projeyle karşılaştırın, varsayımları silin. Örneğin ajan, sizde olmayan bir test komutunu eklediyse kaldırın. Yalnızca sizin bildiğiniz kısıtlamaları kendiniz ekleyin.
4. Dosyayı kaydedin ve proje klasöründe yeni bir oturum açın. /context yazın: Memory files bölümünde CLAUDE.md dosyanızın yolu görünmelidir.

Ardından küçük bir değişiklik deneyin: örneğin bir kart eklemesini isteyin, renklerin korunduğuna ve kontrollerin raporlandığına bakın. Dosya listede görünmüyorsa önce adını ve oturumu başlattığınız klasörü kontrol edin. Görünüyor ama sonuç kuralla uyuşmuyorsa ifadenizi ve olası çelişkileri gözden geçirin.

Diğer Bilgiler Nereye Yazılır?

İlk proje için tek bir CLAUDE.md yeter. Kişisel yönergeler veya çok sayıda genel kural ortaya çıktığında, bu şema nereye yazacağınıza karar vermenize yardımcı olur:

Genel bir kural yalnızca tek bir klasörü ilgilendirse bile tüm ekip için gerekli olabilir. .claude/rules/ bu talimatları konularına göre ayırmaya yardımcı olur; belirli yollarla sınırlama ayrıca yapılandırılır. Yalnızca birkaç kural için yapıyı karmaşıklaştırmayın.

CLAUDE.local.md, örneğin kısa yanıtları tercih etmeniz gibi, bu projeye yönelik kişisel yönergeler için uygundur. Commit etmemek için dosyayı .gitignore'a ekleyin. Yerel dosyayı da ajan okur; sırlar orada da tutulmamalı.

Auto memory, mekanizma açıksa Claude'un çalışma sırasında kaydettiği ayrı notlardır. Önemli bir kuralı yalnızca Claude'un takdirine bırakmayın: CLAUDE.md dosyasına eklemesini doğrudan isteyin. Bir hatayla ilgili geçici varsayım ise görev notunda kalır.

Projede zaten AGENTS.md varsa içeriğini ikinci bir dosyaya kopyalamayın. CLAUDE.md içine @AGENTS.md satırıyla yanındaki dosyayı dahil edebilirsiniz. Bu, özellikle CLAUDE.local.md eklerken yararlıdır: kişisel dosya AGENTS.md'nin doğrudan okunmasını etkileyebilir. Diğer seçenekler belgelerde açıklanıyor.

Kurallar Ne Zaman Güncellenmeli?

Dosyayı projeyle birlikte güncelleyin. Stilleri index.html'den ayrı bir dosyaya taşıdıysanız yapı hakkındaki satırı düzeltin. Kontrol yöntemini değiştirdiyseniz eski talimatı yenisiyle değiştirin. Yeni kuralı, onunla çelişen eskisinin üzerine eklemeyin.

Tekrarlanan bir düzeltmeyi ajana yaptırabilirsiniz: "Tamamlanmış bir bloğu silmeden önce onayımı alman gerektiğini CLAUDE.md dosyasına ekle." Ardından değişikliği okuyun: sizin anlaşmanızı aktarmalı, kendi başına yeni kısıtlamalar eklememeli. Çoğu zaman tek satır yeter.

Bir kural ihlal edildiyse, üç kez daha tekrarlamak yerine önce nedenini bulun. Güncelliğini yitirmiş kayıtları kaldırın ve yalnızca sonraki göreve yardımcı olanları saklayın.