CLAUDE.md En İyi Uygulamalar: Claude'u Dinletecek 9 Kural (2026)

CLAUDE.md En İyi Uygulamalar: Claude'u Dinletecek 9 Kural (2026)

CLAUDE.md en iyi uygulamaları hakkındaki yazıların büyük çoğunluğu size bir şablon verip bırakır — ama geçen hafta yazdığınız dosya muhtemelen zaten görmezden geliniyor ve siz bunun farkında bile değilsiniz. Çözüm nadiren "daha fazla kural eklemek"tir; çoğunlukla tam tersidir. Son dönemde her müşteri projemizde Claude Code kullandık ve bu 9 kural gerçekten fark yaratıyor: Claude'un dosyaları yükleme biçimiyle uyumlu hiyerarşi, kıramayacağınız bir talimat bütçesi, AGENTS.md kararı ve Claude'un oturum ortasında dosyanızı sessizce bırakmasının altı nedeni.

Temel Çıkarımlar

• CLAUDE.md, Claude Code'un bağlamına yüklenen proje belleği — 200 satırın altında tutun yoksa kurallar düşmeye başlar.
• Dosyalar yukarıdan aşağıya yüklenir: global, proje kök, alt dizin (tembel yükleme) ve CLAUDE.local.md (kişisel, gitignored).
• Cursor veya Copilot da kullanıyorsanız AGENTS.md tercih edin; CLAUDE.md'yi AGENTS.md'ye symlink yaparak her ikisini de hedefleyin.
• Claude dosyanızı görmezden geliyorsa bu %90 ihtimalle uzunluk, belirsizlik ya da eksik "neden" yüzündendir.

CLAUDE.md Gerçekte Ne Yapar? (Ve Neden Önemlidir?)

Kısaca: CLAUDE.md, Claude Code'un her oturumun başında proje belleği olarak okuduğu bir markdown dosyasıdır. Sistem istemi, hook ya da skill değildir — Claude'u takımınızın kurallarına yönlendiren danışsal bir bağlamdır. Bunu dokümantasyon olarak değil, yapay zeka çift programcınızın gerçekten okuduğu bir config dosyası olarak düşünün.

Pek çok takım CLAUDE.md'yi bir README gibi yazar. Bu ilk hatadır. README, atlayıp geçebilen insanlara projeyi açıklar. CLAUDE.md ise Claude Code tarafından oturum başında bütünüyle tüketilir; her satır token ve uyum maliyeti doğurur. Dokümantasyondan çok bir config dosyasına ya da test fixture'larına benzer.

Üstelik Claude'u yönlendirmenin tek yolu da değildir. Hook'lar deterministik eylemler çalıştırır (biçimlendirme, commit engelleme). Skill'ler yeniden kullanılabilir iş akışlarını bir araya getirir. CLAUDE.md bu ikisinin arasında danışsal bağlam olarak yer alır — Claude onu değerlendirir, bazen geçersiz kılar ve çok fazla yazarsanız kesinlikle bazı bölümlerini unutur. Bu ayrım aşağıdaki her şeyin temelidir; CLAUDE.md, bağlam mühendisliği adı verilen geniş pratiğin bir aracıdır, tek başına bir çözüm değil.

Kural 1: Dokümantasyon gibi değil, kod gibi davranın. Sürümlendirin. PR'larda inceleyin. Şişirilmiş bir modülü refactor eder gibi kırpın. Anthropic'in CLAUDE.md rehberine göre dosya, sistem talimatlarıyla aynı öncelikte yüklenir — yani altı ay önce yazdığınız eski bir kural bugün hâlâ her yanıtı şekillendiriyor.

CLAUDE.md Nasıl Yüklenir: 4 Katmanlı Hiyerarşi

Kısaca: Claude Code, CLAUDE.md'yi dört katmandan yükler: global (~/.claude/CLAUDE.md), proje kök, kişisel geçersiz kılmalar için CLAUDE.local.md ve yalnızca Claude o dizindeki dosyaları açtığında tembel yüklenen alt dizin dosyaları. Kardeş alt dizinler birbirinin CLAUDE.md'sini asla görmez; bu da claude code belleğini dar kapsamlı tutar.

Hiyerarşi, CLAUDE.md'nin en yanlış anlaşılan kısmıdır ve ilk 5 SERP sonucundan hiçbirinin derinlemesine ele almadığı yerdir. Başlığın altında gerçekte neler olduğu:

Bilinmesi gereken iki kavram: tembel yükleme ve kardeş izolasyonu.

Tembel yükleme şu anlama gelir: bir alt dizin CLAUDE.md'si, Claude o dizinde bir dosya açana kadar bağlama girmez. "Giriş hatasını düzelt" deyip Claude yalnızca backend/ dizinine dokunuyorsa frontend/CLAUDE.md asla yüklenmez. Bu iyi bir şey — bağlam penceresini temiz tutar — ama kritik kuralları alt dizinlere koyup her zaman uygulanacağını bekleyen takımları şaşırtır.

Kardeş izolasyonu bunun doğal sonucudur: frontend/CLAUDE.md ile backend/CLAUDE.md birbirini asla yüklemez. Yalnızca proje kökündeki dosyayı paylaşırlar. Frontend kurallarınız backend kurallarınızla çelişiyorsa sorun yok. Bir kuralı paylaşmaları gerekiyorsa onu kök dosyaya taşıyın.

CLAUDE.local.md kaçış kapısıdır. Yüklenir ama commit edilmez; "Ben pnpm tercih ediyorum ama takım npm'de standardize oldu" gibi kişisel geçersiz kılmalar için idealdir. Bir uyarı: otomatik olarak gitignored değildir. Kendiniz eklemeniz gerekir. Unutursanız kişisel kurallarınızı takımın repo'suna commit edersiniz.

Kural 4: Talimatları Claude'un gerçekten okuduğu yere yerleştirin. React bileşenlerine ait stil kuralları frontend/CLAUDE.md'ye, veritabanı migration kuralları backend/'e ait. Anthropic Memory belgeleri (Kasım 2025'te güncellendi) bunu doğruluyor — tembel yükleme davranışı kasıtlıdır ve kritik önem taşır.

CLAUDE.md'ye Ne Koymalı? (Ve Ne Dışarıda Bırakmalı?)

Kısaca: CLAUDE.md'ye, Claude'un kodunuzdan çıkaramayacağı şeyler girer: build komutları, isimlendirme kuralları, takımın daha önce yakıldığı anti-pattern'lar ve her kuralın nedeni. README'deki her şey, package.json'daki her şey ve haftada değişen her kural dışarıda kalır. claude code talimatları test edilebilir ve özgül olmalıdır.

İşte gerçekten değer taşıyan minimal bir CLAUDE.md:

# Proje: techsy-app

## Komutlar
- Build: `pnpm build` (Turbopack — Webpack bayrakları geçerli değil)
- Test: `pnpm test --run` (Vitest kullanıyoruz, Jest değil)
- Lint: `pnpm lint` (Yalnızca hatalarda değil, uyarılarda da CI başarısız olur)

## Kurallar
- Varsayılan olarak Server Components kullanın. `'use client'` yalnızca gerçekten gerektiğinde ekleyin.
  Neden: geçen çeyrek aşırı istemcileme yüzünden 8s LCP'ye çarptık.
- Veritabanı erişimi yalnızca `lib/db/` helper'ları üzerinden — route'larda ham SQL yasak.
  Neden: satır düzeyi güvenlik politikaları bu helper'larda yaşıyor.
- Testler, test ettiği dosyanın yanına `*.test.ts` olarak yerleştirilir.

## Yasaklar
- Yeni bağımlılık eklemeden önce PR yorumu açın.
- `any` kullanmayın — `unknown` kullanıp daraltın.

## Nereye Bakmalı
- Şema: `db/schema.ts`
- Auth akışı: `lib/auth/README.md`

Şimdi bunu çoğu takımın gönderdiği anti-pattern versiyonuyla karşılaştırın:

# Proje Kuralları

- Temiz, sürdürülebilir kod yazın.
- En iyi pratikleri uygulayın.
- TypeScript'i doğru kullanın.
- Testlerin geçtiğinden emin olun.
- Mevcut pattern'larla tutarlı olun.
- Karmaşık mantığı belgeleyin.

İkinci dosya yanlış değil. Sadece işe yaramıyor. Claude zaten temiz kod yazmak istiyor. "Tutarlı ol" Claude'a hangi pattern'la tutarlı olacağını söylemiyor. Anthropic mühendisi Boris Cherny'nin kamuya açık örnekleri ilk tarz üzerine yoğunlaşır — somut komutlar, adlandırılmış araçlar ve yalnızca koddan anlaşılmayan kararların nedeni.

Kural 2: Özlemsel değil, özgül olun. "Temiz kod yaz" özlemseldir. "Varsayılan olarak server components kullan; 'use client' yalnızca gerçekten gerektiğinde ekle" test edilebilir. Aynı disiplin iyi prompt engineering'in de temelini oluşturur: özgül, test edilebilir talimatlar, ister bir promptta ister bir CLAUDE.md'de olsun, muğlak özlemlere üstün gelir.

Kural 3: Her kuralın neden önemli olduğunu açıklayın. "Neden" süsleme değildir — Claude'un sınır durumlarında karar vermesinin yoludur. Gerekçeli bir kural ("aşırı istemcileme yüzünden 8s LCP'ye çarptık") benzer durumlara genelleşir. Gerekçesiz bir kural ise bağlam değiştiği anda görmezden gelinir. Bu pattern aynı zamanda Builder.io'nun CLAUDE.md rehberinde de belgelenmiştir.

Claude Neden CLAUDE.md'nizi Görmezden Geliyor? Talimat Bütçesi

Kısaca: Claude kötü niyetli değil — dikkati tükeniyor. Yaklaşık 80 satırı geçtikten sonra kuralların düştüğü fark edilmeye başlanır; 200 satırı geçince büyük bloklar tamamen görmezden gelinir; 500 kelimelik yoğun kuralların ardından uyum tamamen çöker. Çözüm bir talimat bütçesidir. Her satırı claude code belleği ve kural başına uyum üzerinde bir maliyet olarak değerlendirin.

Son araştırmalar, üretim kullanıcılarının sürekli karşılaştığı durumu doğruluyor: kural sayısı arttıkça talimat uyumu doğrusal olmayan biçimde bozuluyor. Talimat takip kapasitesi üzerine yapılan arxiv makalesi 2507.11538, kural sayısı arttıkça kural başına uyumun düştüğünü gösteriyor; HumanLayer'ın üretimdeki CLAUDE.md analizi de aynı bulguyu paylaşıyor.

Kısacası: her eklediğiniz kural, diğer tüm kuralların biraz daha az uyulma ihtimalini düşürüyor. Dolayısıyla 400 satırlık bir CLAUDE.md, 100 satırlık olandan 4 kat etkili değildir. Çoğunlukla daha az etkilidir — çünkü önem verdiğiniz kurallar, üç ay önce yazdığınız ve hiç silmediğiniz kuralların arasında seyrelmektedir.

Kendi CLAUDE.md dosyalarımızda 150. satırdan sonra uyumun gözle görülür biçimde düştüğünü fark ettik. 250. satıra gelindiğinde Claude'un tüm bölümleri atladığını gördük. Bu yüzden bir sınır koyuyoruz.

wc -l CLAUDE.md

Araç bu kadar basit. Çalıştırın. 200'ün üzerindeyseniz bütçeyi aştınız. Müşterilerimize gönderdiğimiz katı kural şu:

CLAUDE.md'yi 200 satırlık bir bütçe gibi ele alın. Her satır uyum maliyetidir. En önemli yere harcayın.

Kural 1 pekiştirildi: Kısa tutun. 200 satırın altında, 500 kelimeden az yoğun kural. Otomasyon kuralları eklemek istiyorsanız ("her düzenleme sonrası prettier çalıştır"), bunlar büyük olasılıkla Claude Code hook'larına ait — hook'lar deterministiktir ve talimat bütçesi token'ı tüketmez.

CLAUDE.md mi, AGENTS.md mi, .cursorrules mi, copilot-instructions mı?

Kısaca: Yalnızca Claude Code kullanıyorsanız CLAUDE.md yeterlidir. İki veya daha fazla agent CLI kullanıyorsanız (Codex, Cursor, Copilot, Sourcegraph) AGENTS.md'ye geçin ve CLAUDE.md'yi AGENTS.md'ye symlink yapın. AGENTS.md, 2025'in sonlarında çapraz araç standardı olarak ortaya çıktı — modern agent'ların çoğu ona geri düşüyor ve tek dosya her ekosistemi besliyor.

İlk 5 sonucun gerçekten yanıtlamadığı soru bu. İşte matrix:

Çift hedefleme hilesi tek satırdır:

ln -s AGENTS.md CLAUDE.md

Hepsi bu. Artık Claude Code, Codex ve AGENTS.md'yi destekleyen her araç aynı dosyayı okur. Bir kez güncelleyin, her agent alır. AGENTS.md spesifikasyonu açık kaynaklı ve kasıtlı olarak minimaldir — yalnızca geleneksel bölümlere sahip markdown'dır.

Dikkat edilmesi gereken iki gerçek dünya ayrıntısı. Birincisi: takımınızda Cursor yoğun kullanan biri varsa Cursor'ın .cursorrules kuralları farklı bir yaklaşım benimser — tek dosya, hiyerarşi yok, daha katı format. Bazı takımlar ikisini bir arada tutar: paylaşılan kurallar için AGENTS.md, Cursor'a özgü ayrıntılar için .cursorrules. İkincisi: Copilot'ın .github/copilot-instructions.md'si AGENTS.md'ye geri düşmez, dolayısıyla Copilot ağırlıklı takımların ayrı bir dosyaya ihtiyacı vardır.

Sıfırdan bir agent stack seçiyorsanız, Claude Code vs Cursor vs Copilot karşılaştırmamız harness düzeyindeki trade-off'ları ele alıyor. Kısaca: Claude Code'un hiyerarşisi monorepo'lar için en güçlüsü, Cursor'ın UX'i bireysel çalışmada öne çıkıyor, Copilot'ın IDE entegrasyonu hâlâ kademeli benimseme için en akıcısı.

Kural 9: Birden fazla agent CLI kullanıyorsanız AGENTS.md tercih edin. Aynı şeyi söyleyen iki dosya tutmayın. Stack'inizin büyük çoğunluğunun okuduğu dosyayı seçin, geri kalanını symlink yapın.

CLAUDE.md vs Hook'lar vs Skill'ler: Karar Üçgeni

Kısaca: CLAUDE.md = danışsal bağlam. Hook'lar = deterministik eylemler. Skill'ler = paketlenmiş yetenekler. Yanlısını seçerseniz bir hook'un halletmesi gereken bir şey için talimat bütçesi harcarsınız ya da yalnızca skill'in sunabileceği bir şey için CLAUDE.md kuralı yazarsınız. Üçgen, CLAUDE.md'yi sade tutmanın en ucuz yoludur.

Üç araç, üç iş. En sık gördüğümüz hata: CLAUDE.md'ye "her düzenleme sonrası prettier çalıştır" koymak. Claude okuyor. Claude bazen prettier çalıştırıyor. Siz sinirleniyorsunuz. Çözüm o satırı CLAUDE.md'den çıkarıp hook'a taşımak — çünkü hook'lar danışsal esneklik olmadan her seferinde deterministik biçimde çalışır.

Bir kuralın her zaman çalışması gerekiyorsa hook'a aittir. Bağlama karşı değerlendirilebilecek bir stil tercihiyse CLAUDE.md'ye aittir. Şablonlar, script'ler, prompt'lar gibi paketlenmiş varlıklara sahip çok adımlı bir iş akışıysa skill'e aittir.

Kural 8: CLAUDE.md vs hook'lar vs skill'ler arasında doğru seçim yapın — bir hook'u CLAUDE.md'ye koymak, talimat bütçesinin en yaygın israfıdır. Deterministik eylemleri Claude Code hook'larıyla yapılandırın ve yeniden kullanılabilir iş akışlarını Claude skill'leri olarak paketleyin. CLAUDE.md kısalır, koruma katmanlarınız sertleşir ve Claude önemli kuralları "unutmayı" bırakır.

Monorepo Pattern'ları: İç İçe CLAUDE.md, @import ve .claude/rules/

Kısaca: Bir monorepo'da kök CLAUDE.md'yi küçük tutun — yalnızca işaretçiler ve paylaşılan kurallar. Özgülleştirmeleri apps/*/CLAUDE.md içine taşıyın ki her alt ağaç kapsamlı kurallara sahip olsun. Modüler kural dosyalarını .claude/rules/ üzerinden paylaşmak için @import kullanın. Bu aşamalı açıklama — Claude her parçayı yalnızca ilgili olduğunda alır.

Tipik bir monorepo CLAUDE.md ağacı:

.
├── CLAUDE.md                        # 30 satır — alt dizinlere ve paylaşılan kurallara işaret eder
├── .claude/
│   └── rules/
│       ├── style.md
│       ├── testing.md
│       └── security.md
├── apps/
│   ├── web/
│   │   └── CLAUDE.md                # Next.js'e özgü kurallar
│   └── api/
│       └── CLAUDE.md                # Fastify'a özgü kurallar
└── packages/
    └── shared/
        └── CLAUDE.md                # Kütüphane yazar kuralları

@import sözdizimi kök dosyanın paylaşılan kural parçalarını yeniden yazmadan çekmesine olanak tanır:

# Kök CLAUDE.md

Bu bir Turborepo'dur. Uygulamaya özgü kurallar için alt dizin CLAUDE.md'sine bakın.

@import .claude/rules/style.md
@import .claude/rules/testing.md
@import .claude/rules/security.md

## Üst düzey komutlar
- `pnpm dev` tüm uygulamaları paralel çalıştırır
- `pnpm test` her workspace'in test script'ini çalıştırır

Bu pratikte aşamalı açıklamadır. Kök dosya 30 satırlık bir işaretçi. Her alt dizin CLAUDE.md'si 50–80 satırlık odaklanmış kurallar ekler. .claude/rules/ dosyaları birden fazla alt dizinin çekebileceği kural parçalarını barındırır. Hiçbir şey tekrarlanmıyor, hiçbir şey gözden kaçmıyor ve tek bir dosya talimat bütçesini aşmıyor.

Önceki tembel yükleme kuralı burada daha da kritik önem kazanır: Claude apps/web/Button.tsx üzerinde çalışırken kök dosyayı, apps/web/CLAUDE.md'yi ve @import ile dahil edilen kural dosyalarını görür. apps/api/CLAUDE.md'yi görmez. Tam da istenen bu — backend kuralları frontend bağlamını kirletmez ve bağlam pencereniz kullanılabilir kalır.

Kural 6: Kök dosyayı 200 satırın altında tutmak için @import kullanın. Anthropic'in Claude Code için En İyi Uygulamalar rehberi bunu standart monorepo pattern'ı olarak ele alıyor. Subagent'lar üst CLAUDE.md bağlamını miras alır; iç içe geçmiş iş akışları kullanıyorsanız bunu bilmek faydalı — subagent tasarımıyla nasıl etkileştiği için bağlam mühendisliğine bakın.

Claude Dosyanızı Neden Görmezden Geliyor? 6 Neden ve Çözümü

Kısaca: Claude CLAUDE.md'yi görmezden geldiğinde neredeyse her zaman altı nedenden biri vardır: dosya çok uzun, ifadeler belirsiz, "neden" eksik, bağlam sıkıştırma, çelişen üst dosya ya da yanlış dosya adı. Her birinin 60 saniyelik çözümü var. Her değişiklikten sonra yeni oturumda test edin — bu Kural 7.

1. Dosya çok uzun (>200 satır / >500 kelime)

wc -l CLAUDE.md çalıştırın. 200'ün üzerindeyse agresif biçimde kırpın. Otomasyon kurallarını hook'lara taşıyın. İş akışlarını skill'lere aktarın. Paylaşılan parçaları .claude/rules/ içine bölün ve @import ile çekin. Claude'un kurallarınızı "takip etmeyi bırakmasının" en yaygın nedeni, dosyanın zamanla çok uzaması ve uyumun sessizce çökmesidir.

2. Belirsiz ifadeler ("temiz kod yaz")

Her özlemsel kuralı özgül, test edilebilir bir kuralla değiştirin. "Tutarlı ol" Claude'a görünmezdir. "Varsayılan olarak server components kullan; yalnızca form veya etkileşimli UI için 'use client' ekle" ise Claude'un gerçekten uygulayabileceği bir kuraldır.

3. "Neden" eksikliği

Gerekçesiz kurallar genelleşmez. Claude, kuralın neyi koruduğunu bilmediğinden ne zaman esnetmesi gerektiğini çıkaramaz. Açık olmayan her kurala tek satırlık gerekçe ekleyin: "geçen çeyrek any olarak türlendirilmiş API yanıtlarından üç çalışma zamanı çökmesi yaşadığımız için any yerine unknown kullanıyoruz."

4. Bağlam sıkıştırması sildi

Uzun oturumlar sıkıştırmayı tetikler — Claude pencereye sığdırmak için önceki bağlamı özetler ve CLAUDE.md içeriği bazen bu özetleme sürecinde yok olur. Çözüm: büyük bağlam tükenmelerinin ardından /clear komutunu kullanın ya da oturumu tamamen yeniden başlatın. Bu durum GitHub Issue #17530'da defalarca gündeme geliyor.

5. Çelişen üst CLAUDE.md

Global dosya "4 boşluk kullan" diyor. Proje kökü "2 boşluk kullan" diyor. Alt dizin hiçbir şey demiyor. Claude birini seçiyor — bazen yanlısını. ~/.claude/CLAUDE.md ile proje kökünü çelişkiler açısından denetleyin. Daha özgül olan kazanmalı; ama bunu yalnızca açıkça belirtirseniz.

6. Yanlış dosya konumu veya adı büyük-küçük harf sorunu

Claude.md ile CLAUDE.md Linux ve macOS'ta farklı dosyalardır. claude.md ile CLAUDE.md da öyle. Yolun tam olarak ./CLAUDE.md (tümü büyük harf) olduğunu ve Claude Code'un onu içeren dizinden başlatıldığını doğrulayın. GitHub Issue #668 dosyanın var olduğu ama Claude'un yol sorunu nedeniyle göremediği vakalarla dolu.

Kural 7: Yeni oturumda test edin. Herhangi bir CLAUDE.md değişikliğinin ardından yeni bir oturum açın ve Claude'dan "CLAUDE.md'deki kuralları özetle" demesini isteyin. Özet bir şeyi atlarsa dosya işini yapmıyordur.

10 Dakikada İlk CLAUDE.md'niz: 5 Adımlı Başlangıç

Kısaca: /init ile bir taslak oluşturun, onu gerekçeli 6–10 gerçek kurala indirgeyin, Claude'un bilmesi gereken 3 komut ekleyin, takımınızın yaşadığı 2 anti-pattern ekleyin, sonra Claude'dan dosyayı özetlemesini isteyerek yeni oturumda test edin. Toplam süre yaklaşık 10 dakika. Her yeni repo'nun ilk gününde bu 5 adımlı tarifi kullanıyoruz.

1. /init ile taslak oluşturun. Claude Code'un /init komutu repo'nuzu tarar ve bir başlangıç CLAUDE.md yazar. Yazdığını olduğu gibi göndermeyin. /init çıktısı bir başlangıç noktasıdır, bitmiş bir dosya değil — açıkçası ürettiğinin büyük bölümü kaldırılabilir.

2. Gerekçeli 6–10 gerçek kurala indirgeyin. Genel olan her şeyi silin. README'deki her şeyi silin. Yalnızca Claude'un koddan çıkaramayacağı kuralları tutun.

3. Claude'un bilmesi gereken 3 komutu ekleyin. Build, test, lint. Tam komutu ve dikkat çeken bayrakları ekleyin. Vitest kullanıyorsanız Jest değil, bunu belirtin.

4. Bu takımın yaşadığı 2 anti-pattern ekleyin. Gerçek olanları. "Üç çalışma zamanı çökmesi yaşadığımız için any kullanmayın" ifadesi "TypeScript'i doğru kullan" ifadesini her zaman geçer.

5. Yeni oturum açın ve doğrulayın. Claude'dan "CLAUDE.md'deki kuralları özetle" demesini isteyin. Bir şeyi atlarsa dosya çok uzun, çok belirsiz ya da "neden" eksiktir. Düzeltin ve tekrarlayın.

Kural 5: Yalnızca /init çıktısını göndermeyin. /init bir başlangıç noktasıdır. Kırpıp "neden" satırları eklerken geçirdiğiniz 8 dakika, dosyanın gerçekten işe yaradığı andır.

SSS

CLAUDE.md dosyası nedir?

CLAUDE.md dosyası, Claude Code'un her oturumun başında proje belleği olarak okuduğu bir markdown dosyasıdır. Claude'a kurallarınızı, komutlarınızı ve anti-pattern'larınızı söyler; Claude'un tahmin yürütmesi gerekmez. Dört seviyede çalışır: global, proje kök, alt dizin (tembel yükleme) ve gitignored tuttuğunuz kişisel CLAUDE.local.md.

CLAUDE.md dosyası ne kadar uzun olmalı?

200 satırın altında ve 500 kelimeden az yoğun kural. Bu eşiklerin ötesinde Claude'un talimat uyumu bozulur — eklediğiniz her kural diğer tüm kuralların biraz daha az uyulma ihtimalini düşürür. Sabit bir bütçe gibi ele alın. Daha fazlasına ihtiyaç duyuyorsanız alt dizin CLAUDE.md dosyalarına bölün ve paylaşılan parçalar için @import kullanın.

CLAUDE.md nereye koyulmalı?

Ana dosya proje köküne (./CLAUDE.md) gider ve commit edilir. Monorepo'larda uygulamaya özgü kurallar için alt dizin CLAUDE.md dosyaları ekleyin. Projeler arası tercihler için ~/.claude/CLAUDE.md kullanın. Commit etmek istemediğiniz kişisel geçersiz kılmalar için CLAUDE.local.md kullanın — ama elle gitignore etmeyi unutmayın.

Claude neden CLAUDE.md'mi görmezden geliyor?

%90 ihtimalle üç şeyden biri: dosya çok uzun (200 satırı aşıyor), kurallar belirsiz ("temiz kod yaz") ya da kuralların Claude'un onları uygulayacağı bir "neden"i yok. wc -l CLAUDE.md çalıştırın, özgüllük açısından denetleyin. Değişiklikleri Claude'dan dosyayı özetlemesini isteyerek yeni oturumda test edin.

CLAUDE.md mi yoksa AGENTS.md mi kullanmalıyım?

Takımınız yalnızca Claude Code kullanıyorsa CLAUDE.md'de kalın. İki veya daha fazla agent CLI (Codex, Cursor, Sourcegraph) kullanıyorsanız AGENTS.md'ye geçin ve CLAUDE.md'yi ona symlink yapın: ln -s AGENTS.md CLAUDE.md. Modern agent CLI'larının büyük çoğunluğu AGENTS.md'ye geri düşer; tek dosya her araca hizmet eder.

CLAUDE.md oluşturmak için /init çalıştırmalı mıyım?

Taslak olarak evet, bitmiş dosya olarak hayır. /init repo'nuzu tarar ve bir başlangıç üretir; ama ayrıntılı ve geneldir. Anthropic ve HumanLayer'ın ikisi de /init çalıştırdıktan sonra agresif biçimde kırpılması gerektiğini önerir. Kesip "neden" satırları eklerken geçirdiğiniz 8 dakika, dosyanın gerçekten kullanışlı hale geldiği andır.

Monorepo'da CLAUDE.md dosyaları nasıl çalışır?

Kök CLAUDE.md küçük kalır — yalnızca işaretçiler ve paylaşılan kurallar. Her uygulama kapsamlı kurallarla kendi apps/*/CLAUDE.md'sini alır. Alt dizin dosyaları yalnızca Claude o alt ağaçtaki dosyaları açtığında tembel yüklenir; kardeşler izole kalır. Uygulamalar arasında çoğaltmadan modüler kural parçalarını paylaşmak için @import .claude/rules/style.md kullanın.

CLAUDE.md, hook'lar ve skill'ler arasındaki fark nedir?

CLAUDE.md danışsal bağlamdır — Claude okur ve genellikle uygular. Hook'lar her zaman çalışan deterministik eylemlerdir (biçimlendirme, commit engelleme). Skill'ler, varlıklarla birlikte yeniden kullanılabilir iş akışları için paketlenmiş yeteneklerdir. Stil rehberi için CLAUDE.md, sert kurallar için hook'lar, birden fazla projede tekrarlayacağınız çok adımlı işler için skill'ler kullanın.

Techsy Bu Konuya Nasıl Yaklaşıyor?

Techsy'de gönderdiğimiz her Claude Code projesinde 150 satırın altında CLAUDE.md ve bir AGENTS.md symlink var. Dosyayı kod gibi ele alıyoruz — sürümlendiriyoruz, PR'larda değişiklikleri inceliyoruz ve merge etmeden önce yeni oturumlarda yeniden test ediyoruz. AI agent'larını geliştirme iş akışınıza entegre etmek için yardım ister misiniz? Ücretsiz danışmanlık alın.