CLAUDE.md bellek, disk değil

Birçok Claude Code projesinde, sürekli büyüyen devasa bir CLAUDE.md dosyası görmekteyiz. Bu dosya üç yüz satıra kadar çıkabiliyor ve genellikle iki yüzüncü satırdan sonra asistanın performansı pek iyi olmuyor. Bu kötü şans değil. Dosya, oturumun başında bağlam olarak yükleniyor ve orada kalıyor, bu yüzden eklediğiniz her satır, Claude’un takip eden her adımda önünde taşıdığı bir satır oluyor — asıl görevinize ulaşmadan önce okuduğu bağlam. Çözüm daha uzun bir dosya değil. Çözüm, CLAUDE.md dosyasını RAM gibi, diğer belgelerinizi disk gibi ele almak.

Buradaki temel fikir kısa bir cümleyle: CLAUDE.md çalışma belleğidir, sürekli yüklenir ve sürekli ödenir, bu nedenle küçük kalmalıdır; docs/ klasörü ise uzun vadeli bellek olup, yalnızca bir şey ona işaret ettiğinde yüklenir. Bu ayrım oturduğunda, bir bilginin nerede bulunması gerektiği konusundaki her karar kendiliğinden açıklanır.

Uzun Dosyanın Zararları

Claude Code, her oturumun başında otomatik olarak CLAUDE.md dosyasını okur ve bunu sürekli bağlamda tutar. Bu, Claude’un her görevde ihtiyaç duyduğu birkaç şey için tam olarak istediğiniz şeydir: yığın, komutlar, daima geçerli olmalıdır kurallar. Ancak, Claude’un haftada bir ihtiyaç duyduğu şeyler için tam tersi bir durumdur. CLAUDE.md içerisinde yer alan uzun bir alan tanımı ya da tam yapılandırma yazısı, Claude’u daha akıllı yapmaz. Görevinizle ilgili olmayan detaylarla bağlamı kalabalıklaştırır ve onu kullanıp kullanmadığınızdan bağımsız olarak her adımda size token kaybettirir.

Kullandığım test basit. Claude buna her seferde ihtiyaç duyuyor mu, yoksa sadece bazen mi? Her seferde kullanılması gerekenler CLAUDE.md dosyasına gelir. Bazen ihtiyaç duyulanlar ise docs/ klasörüne gider, oradan CLAUDE.md içinde bir satırlık bir işaret ile ulaşılarak uygun dosyaya yönlendirilir.

RAM’de Ne Bulunmalı

CLAUDE.md dosyası, onu bir dakikadan daha kısa sürede okuyabileceğiniz kadar kısa olmalıdır. Bir Laravel projesi için benim dosyamda beş şey bulunuyor:

• Projenin ne olduğu hakkında iki veya üç cümlelik bir özet.
• Versiyonları belirtilmiş yığın: “Laravel” yeterli değildir. “Laravel 11, PHP 8.3, Pest 3” olmalıdır.
• Tam komutlar: test, lint, statik analiz, geliştirme sunucusu. Claude asla bunları tahmin etmemelidir.
• Her değişiklikte geçerli olması gereken kurallar. Benim için bu, önce Pest ile TDD, KISS, gereken yerlerde Spatie üzerinden olay kaydı, alan mantığının çerçeve kodundan bağımsız tutulması ve envaudit ile .env dosyasının CI’de doğrulanmasıdır.
• Yönlendirmeler. Her biri bir satırlık: mimari docs/DESIGN.md dosyasında, mevcut çalışma docs/PLAN.md dosyasında, kararlar docs/DECISIONS.md dosyasında.

Son grup işin püf noktasıdır. CLAUDE.md mimariyi içermez. Mimarinin adresini içerir. Claude, bir görev ihtiyaç duyduğunda detayı talep eder ve diğer zamanlarda o detay bağlamı yakmaz.

Diskte Ne Bulunmalı

docs/ klasörü, uzun materyallerin yaşadığı yerdir ve talep üzerine yükleneceğinden ihtiyaç duyduğu kadar uzun olabilir. Çoğu projeyi kapsayan üç dosya vardır:

DESIGN.md mimariyi ve alan modelini içerir. Sınırlı bağlamlar, toplu veriler, her birinin kaydettiği olaylar, korudukları invariants. Bu, düşüncelerinizi bir kez yazılı hale getirir, böylece Claude her oturumda yeniden icat etmez ve “bu mantık nereye ait” sorusu bu dosyadan türeyebilir.

PLAN.md işlerin aşamalı, plan odaklı ayrıştırmasını içerir. Küçük aşamalar, her biri tamamlanabilir ve doğrulanabilir, belirlenerek alt alta yazılır ve oturumlar arasında ilerleme kalır.

DECISIONS.md hafif bir karar kaydıdır. Anlamlı her seçime dair kısa bir giriş: bağlam, karar, ticari denge. Bu dosya, sizin ve Claude’un aynı sorunu üç oturum sonra tekrar gündeme almasını önler.

Gerçek bir ihtiyaç ortaya çıkana kadar daha fazlasını eklemeyin. Test stratejiniz gerçekten belirgin olmadığında bir TESTING.md dosyası, terminoloji DESIGN.md dosyasını aştığında ayrı bir DOMAIN.md dosyası. Önce değil. Boş yapı, sadece Claude’un okuması için daha fazlasıdır.

Çoğu Kurulumun Göz Ardı Ettiği Püf Noktası: İç İçe Dosyalar

Claude Code sadece kök CLAUDE.md dosyasını okumaz. Çalıştığı dizinde, kök dosyanın üzerine katmanlı olarak bir CLAUDE.md dosyası daha okur. Bu, yalnızca bir klasör içinde geçerli olan kuralların o klasörde yaşamalarını sağlar ve kök dosyayı kabarık hale getirmez.

Gerçek bir alan katmanına sahip bir Laravel projesinde, app/Domains içinde bir CLAUDE.md dosyası bulunduruyorum: burada çerçeve alıntıları yoktur, toplu veriler yalnızca Spatie’nin AggregateRoot sınıfını genişletir ve yalnızca olay kaydedilir; olaylar değişmez ve geçmiş zamanla yazılır ve her değişiklik önce bir Pest testi ile başlar. Bunun kök dosyada yer almasına gerek yok, çünkü bir kontrolör ya da Blade görünümü düzenlerken ilgisizdir. Alan katmanına geçtiğinde tam olarak yüklenir, öncesinde değil.

Başlangıç

Tüm bunları doğrudan projeye kopyalayabileceğiniz küçük bir şablon deposu haline getirdim: claude-code-laravel-starter. Yukarıda verilen yapı ve her dosya doldurulabilir bir şablon olarak, Laravel ve olay kaydı kuralları önceden yerleştirilmiş olup, iç içe bir alan katmanı CLAUDE.md dosyası ile birlikte mevcut, böylece model somutlaşır.

claude-code-laravel-starter/
├── CLAUDE.md              # her oturumda otomatik olarak yüklenen küçük dosya
├── README.md
├── docs/
│   ├── DESIGN.md         # alan modeli, toplu veriler, olaylar
│   ├── PLAN.md           # aşamalı, plan odaklı uygulama
│   └── DECISIONS.md      # hafif ADR kaydı
└── app/
    └── Domains/
        └── CLAUDE.md     # yalnızca alan katmanı kuralları

Yeni bir Laravel uygulamasına kopyalayın, gerçek yığınızı ve komutlarınızı doldurun, örnek alanı kendinizle değiştirin ve kök dosyayı sıkı tutun.

Üç Kural

Eğer Claude her zaman buna ihtiyaç duyuyorsa, dosya CLAUDE.md içinde yer alır. Sadece bazen ihtiyaç duyuyorsa docs/ içinde yer alır. Üç dosya ile başlayın ve yalnızca gerçek bir ihtiyaç ortaya çıktığında daha fazlasını ekleyin. Bir klasör kendi kurallarını içeriyorsa, kök dosyadan uzatarak değil, kendi CLAUDE.md dosyasını verin.

Küçük başlayın, çalışma belleğini sıkı tutun, ve geri kalanını diskin tutmasına izin verin.