cn claudenews Ara /

Lesson 06 · 24 dk okuma

CLAUDE.md Hiyerarşisi ve Path-Specific Rules

User/project/directory seviyelerinde CLAUDE.md, @path syntax ile modüler import, .claude/rules/ dizini ve YAML frontmatter paths glob ile conditional loading.

Öğreneceklerin

  • 3 CLAUDE.md seviyesini (user/project/directory) ve hangi sırayla yüklendiğini bilmek
  • @path import syntax'ını ve max nesting (5) sınırını uygulamak
  • .claude/rules/ + YAML paths glob ile conditional loading mantığını kavramak
  • Yeni ekip üyesinin user-level vs project-level'a ne koyması gerektiğini kararlaştırmak
  • Token/context tasarrufu için path-specific rules stratejisi tasarlamak

CLAUDE.md Hiyerarşisi ve Path-Specific Rules

Bu derste Claude Code’un “context layering” mekanizmasının en alt katmanını — kalıcı kural dosyaları sistemini — sınav perspektifinden açıyoruz. CLAUDE.md tek dosya değil, üç seviyeli bir hiyerarşi; yanına @path import ve .claude/rules/ ile path-specific yükleme geliyor. Yanlış katmana yazarsan kural ya görmezden gelinir (user-level’a repo-specific kural koymak), ya da her oturumu gereksiz şişirir (project-level’a kişisel tercih yazıp 50K token context harcatmak). Sınav bu ikisini de sorar.

Neden bu konu sınavda çıkıyor

Domain 3’ün ağırlığı %20. Bu domain içinde “configuration” maddesinin yaklaşık yarısı doğrudan context layering + rules ile ilgili. Tipik sınav sorusu: “Bir ekibin 12 geliştiricisi var. Test convention’ları sadece test dosyaları düzenlenirken yüklensin, kalan context kirletmesin. Hangi mekanizma doğru?” Cevap her zaman .claude/rules/ + YAML paths glob. Bir başka klasik: “CLAUDE.md’den başka bir markdown dosyasını içeri almak için hangi syntax kullanılır?” → @path. Bu ders bu iki soruya hazırlık.

Temel kavramlar

1. Üç seviye ve yükleme sırası

Claude Code her oturum açılışında bu üç dosyayı şu sırayla yükler:

  1. User-level: ~/.claude/CLAUDE.md (senin kişisel makinende, tüm projelerde geçerli)
  2. Project-level: <repo>/.claude/CLAUDE.md veya <repo>/CLAUDE.md (ekibin tamamı, git’e commit edilir)
  3. Directory-level: Claude’un o an üzerinde çalıştığı dizine en yakın ek CLAUDE.md (monorepo’larda sık kullanılır)

📝 Rehber kapsamı dışında (pratik gözlem): Aynı konuda çakışma varsa bazı kullanıcılar “üst seviye önce yüklenir ama alt seviye kazanır” diye bir precedence gözlemi paylaşıyor. Sınav bu iddiayı teyit etmez; rehberin verdiği kesin kural daha sade: directory-level CLAUDE.md yalnızca o dizindeki dosyalarla çalışırken geçerlidir (rehber 5.1), ve yaygın hata ekibin proje konvansiyonunu user-level (~/.claude/CLAUDE.md) yerine project-level (.claude/CLAUDE.md) koymamaktır — yeni katılan ekip üyesi talimatı görmez (rehber 5.1 “Common mistake”).

İkilik: CLAUDE.md (root) ile .claude/CLAUDE.md aynı sayılır, ikisi de project-level. Tercih genelde .claude/CLAUDE.md — çünkü diğer Claude konfigürasyon dosyalarıyla (commands/, skills/, hooks/, settings.json) aynı yerde gruplanır.

2. @path import — modüler CLAUDE.md

200 satır sınırını aşmamak için CLAUDE.md’i parçalara bölersin, sonra ana dosyadan import edersin:

# .claude/CLAUDE.md

# Proje kuralları — ana dosya

## Genel
- TypeScript strict, ESM modules, vitest
- PR'da `pnpm test && pnpm typecheck` geçmeli

## Detaylı kurallar
- @.claude/rules/testing.md
- @.claude/rules/git-workflow.md
- @.claude/rules/style.md

Her import modülerdir: içerik çağrıldığı dosyanın context’ine eklenir. Rehber 5.2’ye göre @ kuralları: dosya yolundan hemen önce boşluksuz @ kullanılır, göreli/absolute path desteklenir, göreli path import’u barındıran dosyaya göre çözülür ve maximum import nesting depth 5’tir. Sınav tuzağı: “sınırsız” cevabı. Sınırsız değil, 5.

3. .claude/rules/ + YAML paths glob

Klasik soru: “Test convention’ları sadece test dosyalarına dokunulduğunda yüklensin.” Çözüm:

# .claude/rules/testing.md
---
paths:
  - "**/*.test.ts"
  - "**/*.test.tsx"
  - "**/*.spec.ts"
  - "src/test/**"
---

Test yazma kuralları:
- Her describe bloğunda setup/teardown ayrı
- Mock'lar `vi.mock` ile module seviyesinde
- Integration test'lerde gerçek DB kullanma, fixture'dan oku

paths frontmatter alanı glob listesi alır. Eğer aktif dosya bu glob’lardan birine eşleşirse rule yüklenir, yoksa hiç inject edilmez. Bu sayede:

  • 50 satırlık test konvansiyonu context’e sadece test dosyası açtığında girer
  • Diğer dosyalarda tam 0 token harcar
  • Büyük monorepo’larda (örn. backend + frontend + infra) her alt dizin kendi kurallarını sadece ilgili dosyalarda yükler

Sınavda göreceğin varyasyon: paths: ["src/api/**/*.ts"] gibi alt-dizin kısıtı. Rehber 5.3’teki glob örnekleri pozitif pattern’lerdir; negation glob (!**/foo/**) konusunda rehber sessiz.

4. Hangi katmana ne yazılır — karar matrisi

İçerikNereye?Neden?
Dil tercihi (Türkçe yanıt)~/.claude/CLAUDE.md (user)Kişisel, her projede geçerli
”Kod yorumu yazma, sadece neden”user-levelSenin tarzın, takıma bağlı değil
Tech stack bilgisi (Next.js 15, tRPC)project-level .claude/CLAUDE.mdEkip kararı, commit edilir
Test framework + çalıştırma komutuproject-level veya .claude/rules/testing.mdTest convention’ı ekip standardı
Sadece *.test.ts dosyaları için convention.claude/rules/testing.md + paths globContext tasarrufu
Monorepo’da apps/web/ kurallarıapps/web/CLAUDE.md (directory)Sadece o sub-tree için geçerli
DB şifresi, API key, kişi listesiHiçbir zaman CLAUDE.mdGizli bilgi + context şişirir

Sınav tuzağı: “Test convention’larını user-level’a koyalım, her yerde geçerli olsun” → yanlış, çünkü user-level tüm projelerde yüklenir, gereksiz context harcatır. Doğrusu: project-level + path-specific rules.

Sınav tuzakları

  1. “CLAUDE.md sınırsız import derinliğine izin verir” — Yanlış. Rehber 5.2 “Maximum import nesting depth is 5” der. Beş seviyeyi aşan import için rehber ek davranış tanımlamaz; sınav bu detayı sormaz.
  2. “User-level CLAUDE.md, project-level’dan daha önceliklidir” — Yanlış. Rehber 5.1’in vurguladığı yaygın hata: ekibin proje konvansiyonunu user-level yerine project-level’a koymamak, yeni katılan üye talimatı görmez. Precedence’ı sınav bu çerçevede sorar, “alt seviye kazanır” gibi kesin bir formül vermez.
  3. “Path-specific rules her dosyada yüklenir ama görünmez olur” — Yanlış. Rehber 5.3: kural, paths pattern’iyle eşleşen dosya düzenlenirken yüklenir; eşleşmezse yüklenmez — yani token bile harcamaz. “Görünmez yükleme” gibi ara bir mod yok.
  4. “@.claude/rules/testing.md ile import ettiğin dosya ayrıca paths glob kontrolünden geçer” — Yanlış/kesin değil. Rehber 5.2 import edilen dosyanın paths glob’la ilişkisini tanımlamıyor; sınavda bu detay beklenmez. Import edilen içerik çağrıldığı dosyanın context’ine eklenir.

Hands-on

Senaryo: Yeni başlayan bir geliştirici repoya katılıyor. Aşağıdaki yapıyı kur.

# 1. Dizinleri oluştur
mkdir -p .claude/rules

# 2. Ana CLAUDE.md
cat > .claude/CLAUDE.md <<'EOF'
# Proje: claudenews

- Astro 5 + TypeScript strict
- pnpm ile paket yönetimi
- PR açmadan önce: pnpm test && pnpm typecheck

## Detaylı kurallar
- @.claude/rules/testing.md
- @.claude/rules/git-workflow.md
EOF

# 3. Test kuralları (sadece test dosyaları için)
cat > .claude/rules/testing.md <<'EOF'
---
paths:
  - "**/*.test.ts"
  - "**/*.test.tsx"
  - "**/*.spec.ts"
---

Test yazma standartları:
- vi.mock module seviyesinde
- Her describe kendi setup/teardown'una sahip
- Coverage threshold: lines 80%, branches 70%
EOF

# 4. Kişisel user-level (sadece senin makinende)
cat > ~/.claude/CLAUDE.md <<'EOF'
# Kişisel tercihlerim
- Türkçe yanıt ver
- Kod yorumu yazma, sadece "neden" ise yaz
- Plan mode'da başla (karmaşık işler için)
EOF

Doğrulama:

# Test dosyası açınca rules/testing.md yüklü mü?
claude
> "src/lib/auth.test.ts dosyasına bir unit test ekle"
# → "vi.mock module seviyesinde" kuralı geldi mi? EVET

# Production dosyasında rules/testing.md yüklenmemeli
> "src/lib/auth.ts dosyasına rate limiting ekle"
# → "coverage threshold" kuralı geldi mi? HAYIR (doğru, context tasarrufu)

Token tasarrufu hesabı: rehber kesin rakam vermez, niteliksel konuşur. Pratik gözlem — path-specific rules her oturumda yüklendiğinde context’e yüzlerce token ekler (dosya uzunluğuna ve path eşleşme sıklığına bağlı). Sadece eşleşen dosyalarda yüklemek, monorepo’da yoğun test dosyası açan bir geliştirici için yüzlerce token × dosya sayısı mertebesinde tasarruf sağlar. Küçük gibi ama context window’un başına gelen “system + claude.md + project rules + memory” yükünün anlamlı bir yüzdesi olabilir.

Özet

  • 3 seviye: user (~/.claude/CLAUDE.md) → project (.claude/CLAUDE.md veya root) → directory (monorepo sub-tree). Directory-level yalnızca o dizindeki dosyalarla çalışırken geçerlidir.
  • @path import: 5 seviye max, modüler kuralları ana dosyaya gömer.
  • .claude/rules/ + paths glob: dosya-spesifik kurallar sadece glob eşleşirse yüklenir, context tasarrufu sağlar.
  • Karar kuralı: kişisel → user-level, ekip standardı → project-level, dosya-spesifik → rules/ + paths.
  • Yasak: gizli bilgi, repo’ya bağlı olmayan kişisel tercih project-level’a; sık erişilmeyen convention user-level’a yazılmaz.
  • Sınav formülü: “Conditional loading = .claude/rules/ + paths glob. Modüler import = @path (max nesting 5). Directory-level = o dizinle sınırlı. Yaygın hata = proje konvansiyonunu user-level yerine project-level’a koymamak.”

Kaynaklar