CLAUDE.md Açıklaması: Claude Code'a Projeni Bir Kez Öğret

Claude Code'un her yeni oturumu boş bir kafayla başlar. Ona npm değil pnpm kullanmasını söylersin. Testlerin nerede durduğunu söylersin. Üretilmiş klasöre dokunmamasını söylersin. Yarın bunların hepsini yeniden söylersin.

Markdown biçiminde düz bir metin dosyasıdır. Claude Code onu her oturumun başında okur, yani içindeki her şey ilk promptundan önce zaten bilinir. Bu rehber dosyanın nereye gittiğini, Claude'un uyacağı bir dosyanın nasıl yazılacağını ve nelerin dışarıda bırakılacağını gösterir.

CLAUDE.md nedir, ne değildir

Her Claude Code oturumu taze bir bağlam penceresiyle başlar. Bilgiyi bir oturumdan ötekine iki mekanizma taşır:

İkisi de bağlam olarak yüklenir. Bu sözcük önemli: Claude, CLAUDE.md'yi okur ve ona uymaya çalışır, ama bu zorla uygulanan bir ayar değildir. Belirsiz ya da çelişkili bir satır yok sayılabilir. Dosyayı nasıl yazman gerektiğini bu belirlediği için sorun giderme bölümünde buna döneceğiz.

Dosya nereye konur

Dört yer var ve üst üste biner. Claude onları en genel kapsamdan en özele doğru yükler, yani projene daha yakın olan en son okunur.

Kullanacağın ikisi proje dosyası ve kullanıcı dosyasıdır.

• Proje dosyası. CLAUDE.md dosyasını projenin köküne ya da kökteki bir .claude klasörüne koy. Commit et; böylece projede çalışan herkes aynı yönergeleri alır. Herkes için doğru olanı yaz: derleme komutları, kurallar, proje düzeni.
• Kullanıcı dosyası. ~/.claude/CLAUDE.md seni her projeye kadar izler. Açıklamaların nasıl ifade edilmesini istediğin gibi kişisel alışkanlıklar için kullan.
• Yerel dosya. CLAUDE.local.md, bir sandbox adresi gibi sana ait ve tek bir projeye özel notlar içindir. Commit edilmesin diye onu .gitignore dosyana ekle.

Claude ayrıca başlattığın klasöre ve onun üstündeki her klasöre bakar. foo/bar/ içinde başlatırsan foo/bar/CLAUDE.md ve foo/CLAUDE.md yüklenir. Altındaki klasörlerde bulunan dosyalar daha sonra, Claude o alt klasördeki bir dosyayı ilk okuduğunda ya da düzenlediğinde, gerektikçe yüklenir.

/init ile başla

İlk sürümü elle yazman gerekmez. Bir oturumun içinde şunu çalıştır:

> /initKod tabanın analiz ediliyor...Bulduğu derleme komutları, test yönergeleri ve kurallarla CLAUDE.md oluşturuldu.

Claude Code projeni okur ve keşfettiği derleme ve test komutlarıyla kuralları içeren bir CLAUDE.md yazar. Zaten bir CLAUDE.md varsa /init üzerine yazmak yerine iyileştirmeler önerir. Sonucu ilk taslak say. Senin işin, Claude'un kendi başına bulamayacağı şeyleri eklemek.

Dosyanın yüklendiğini doğrulamak için bir oturumda /context çalıştır ve Memory files altına bak.

Dosyaya ne girer

Herhangi bir satırı yazmadan önce iyi bir sınama, iki sorudur:

İki yanıt da evetse satırı dışarıda bırak. Geriye kalan, koda hiç girmemiş ya da yeniden keşfedilmesi gerçekten zaman alan bilgidir:

Claude aynı hatayı ikinci kez yaptığında, bir kod incelemesi onun bilmesi gereken bir şeyi yakaladığında ya da geçen oturumda yazdığın düzeltmeyi yine yazdığında bir satır ekle. Bu, bilginin dosyaya ait olduğunun işaretidir.

Kopyalamaya değer bir örnek

İşte kısa bir proje dosyası. Her satırın doğrulayabileceğin bir şey olduğuna ve mimariyi ne kadar az anlattığına dikkat et.

# Project notes

## Commands
- Install: pnpm install (never npm or yarn)
- Dev server: pnpm dev (port 3000)
- Tests: pnpm test -- --run, run before every commit
- Typecheck: pnpm typecheck, must pass before a pull request

## Conventions
- 2-space indentation, double quotes
- API handlers live in src/api/handlers/
- Do not edit anything in src/gen/, it is generated by pnpm codegen

## Gotchas
- Integration tests need a local Redis: docker compose up redis
- Dates are stored in UTC, formatted only in the UI layer

Bu 15 satır ve her biri yerini hak ediyor.

Claude'un uyacağı satırlar nasıl yazılır

CLAUDE.md yapılandırma değil bağlam olduğundan, bir satırı nasıl ifade ettiğin ona uyulup uyulmayacağını belirler. Yönergeleri kontrol edilebilecek kadar somut yaz.

Sonra dosyayı formda tut:

• Kısa. Dosya başına 200 satırın altını hedefle. Daha uzun dosyalar daha çok bağlam harcar ve Claude onlara daha az güvenilir biçimde uyar.
• Düzenli. İlgili satırları Markdown başlıkları ve madde işaretleri altında grupla. Claude, yoğun paragraflardan çok yapıya daha iyi uyar.
• Tutarlı. İki satır birbiriyle çelişirse Claude rastgele birini seçebilir. Dosyalarını, alt klasörlerdekiler dahil, ara sıra oku ve güncelliğini yitirmiş her şeyi sil.

Claude'un yönerge dosyalarını güncelliğini yitirmiş ya da çelişen satırlar için denetlemesini istiyorsan /doctor prompt-audit çalıştır. Bulgularını raporlar ve düzenleme önerir, sen isteyene kadar hiçbir şeyi değiştirmez. Claude Code 2.1.283 veya üstü gerekir.

Başka dosyaları içe aktarmak

CLAUDE.md, yolun önüne @ koyarak başka dosyaları çekebilir. İçe aktarılan dosya, onu anan CLAUDE.md ile birlikte yüklenir.

See @README for the project overview and @package.json for the npm commands.

# Additional instructions
- git workflow: @docs/git-instructions.md

Göreli yollar, içe aktarmayı içeren dosyadan çözülür. İçe aktarılan dosyalar da başka dosyaları içe aktarabilir, en fazla dört düzey derinliğe kadar. @ yalnızca kod aralıklarının dışında okunur; bu yüzden bir yoldan içe aktarmadan söz etmek istiyorsan onu ters tırnak içine al.

İçe aktarmalar düzen için iyidir, ama bağlamı küçültmez: içe aktarılan dosyalar yine de tamamen yüklenir. Aynı deponun birkaç kopyasında istediğin kişisel yönergeler için ana klasöründen bir dosya içe aktar, örneğin @~/.claude/my-project-instructions.md. Bir proje çalışma dizininin dışından bir dosyayı ilk kez içe aktardığında Claude Code onayını ister.

Tek dosya çok uzadığında

Bir noktada dosya, her oturumun ihtiyacından fazla büyür. Dört aracın var, her biri farklı bir iş için.

Belirli dosyalara kapsamlanmış kurallar

.claude/rules/ içine her konu için bir Markdown dosyası koy, örneğin testing.md ya da api-design.md. Bir kuralın yalnızca belirli dosyalara uygulanması için en üste bir paths alanı ekle:

---
paths:
  - "src/api/**/*.ts"
---

# API rules

- Every endpoint validates its input
- Use the standard error response format

paths olmayan bir kural her oturum yüklenir. Kapsamlı olan, Claude eşleşen bir dosyayı okuduğunda ya da düzenlediğinde yüklenir; böylece yönergeler diğer zamanlarda yoldan çekilir.

CLAUDE.md içindeki bir blok, bir sürümün nasıl hazırlanacağı gibi çok adımlı bir prosedürse onu bir skill'e taşı. Skill'ler yalnızca kullanıldıklarında yüklenir.

Otomatik hafıza: Claude'un kendisi için tuttuğu notlar

Senin yazdığın dosyanın yanı sıra Claude Code kendi başına da not tutabilir. Otomatik hafıza yerel oturumlarda varsayılan olarak açıktır. Claude çalışırken dört tür not kaydeder: seninle ilgili (rolün ve tercihlerin), geri bildirim (düzeltmelerin ve onayladığın yaklaşımlar), proje (kodda görünmeyen kararlar ve son tarihler) ve referanslar (projenin dışında bir şeyleri nerede bulacağı).

Koddan okuyabildiği şeyleri ya da CLAUDE.md'nin zaten söylediklerini kaydetmez. Oturumda "Saved 2 memories" gibi mesajlar göreceksin. Notlar ~/.claude/projects/ altında düz Markdown'dır ve dizin dosyasının ilk 200 satırı ya da 25 KB'ı her oturumun başında yüklenir.

Tüm yönerge dosyalarını ve otomatik hafıza klasörünü görmek, herhangi birini editöründe açmak ve otomatik hafızayı açıp kapatmak için /memory çalıştır. Claude'a "her zaman npm değil pnpm kullan" dersen bunu otomatik hafızaya kaydeder. Bir şeyi bunun yerine CLAUDE.md'ye koydurmak için açıkça söyle: "bunu CLAUDE.md'ye ekle".

Claude Tutorial içinde

Aksi hâlde tekrarlayacağın şeyi yazıya dökmek

Aynı düzeltmeyi kalıcı bir yönergeye dönüştürmek, Claude ile yapılan her tür işte karşılığını veren bir alışkanlıktır, yalnızca kodda değil; uygulama bunu adım adım öğretir.

Çok yakında

Şuradan indir:App Store

BURADAN İNDİR:Google Play

Claude buna uymadığında

Bunları sırayla uygula. Çoğu durumu çözerler.

Bilmeye değer iki ek durum var. Bir /compact sonrasında proje kökündeki CLAUDE.md diskten yeniden okunur, yani hayatta kalır. Yalnızca konuşmada verdiğin bir yönerge hayatta kalmaz, bu yüzden onu dosyaya taşı. Bir alt klasördeki CLAUDE.md çok uzunsa (daha küçük bir bağlam penceresinde yaklaşık 40.000 karakterden fazla), Claude yalnızca başını alır; bu yüzden onları kısa tut.

Sık sorulan sorular

CLAUDE.md'yi nereye koyarım?

Projenin köküne (./CLAUDE.md) ya da ./.claude/CLAUDE.md içine. Tüm projeler için kişisel tercihleri ~/.claude/CLAUDE.md içine koy. Tek bir proje hakkındaki özel notlar için .gitignore dosyasına eklenmiş ./CLAUDE.local.md kullan.

Bir CLAUDE.md ne kadar uzun olmalı?

200 satırın altını hedefle. Aşarsan Claude Code açılışta ve /status içinde bir uyarı gösterir. Alana özgü kısımları kapsamlı kurallara taşı ve Claude'un koddan okuyabildiğini çıkar.

CLAUDE.md bir sistem promptu ile aynı şey mi?

Hayır. CLAUDE.md, sistem promptundan sonra bir mesaj olarak iletilir. Claude ona uymaya çalışır, ama kesin uyum garantisi yoktur. Her seferinde geçerli olması gereken yönergeler için bir hook ya da izin kuralı kullan.

CLAUDE.md'yi git'e commit etmeli miyim?

Proje dosyası için evet; böylece tüm ekip paylaşır ve her düzeltmeyle gelişir. Kişisel olan CLAUDE.local.md için hayır.

Claude alt klasörlerdeki CLAUDE.md'yi okur mu?

Evet, gerektikçe. Bir alt klasörün dosyasını, Claude o klasördeki bir dosyayı ilk okuduğunda ya da düzenlediğinde yükler ve yolu içeren bir Loaded satırı gösterir.

CLAUDE.md ile skill arasındaki fark nedir?

CLAUDE.md, her oturumda gereken bilgiler içindir. Skill ise yalnızca çağrıldığında ya da ilgili olduğunda yüklenen bir prosedür veya rehberdir; bu yüzden diğer zamanlarda yer harcamaz.

CLAUDE.md kontrol listen

Okumaya devam et

• Yeni Başlayanlar İçin Claude Code: Kur, Giriş Yap ve İlk Görevini Çalıştır: henüz bir oturum başlatmadıysan.
• Claude Code En İyi Uygulamalar: Daha İyi Sonuç Getiren Alışkanlıklar: promptlar, kontroller ve bağlam yönetimi için.
• Claude Code İzin Modları ve Plan Modu Açıklaması: Claude'un sormadan neler yapabileceğine karar vermek için.
• Claude Projects: Kalıcı Bağlam: Claude uygulamasındaki aynı fikir için: bir projeyle birlikte tutulan kalıcı yönergeler.