İyi bir Claude.md yazma yöntemi

• LLM, durum saklamayan bir fonksiyon olduğu için CLAUDE.md, her oturumda Claude’a kod tabanını tanıtan temel belge olarak işlev görür
• Dosya; projenin WHAT (yapı), WHY (amaç) ve HOW (çalışma biçimi) unsurlarını kısa ve net biçimde içermeli, gereksiz komut fazlalığı ise performans düşüşüne yol açar
• Claude, sistem mesajındaki talimatlara göre CLAUDE.md içeriğini ilgisi düşük bulursa yok sayabilir
• Etkili bir dosya yalnızca kısa ve genel olarak uygulanabilir bilgiler içermeli; ayrıntılı yönergeler ayrı belgelere bölünerek Progressive Disclosure yaklaşımıyla yönetilmelidir
• CLAUDE.md, ajan harness’inin en yüksek etkili noktası olduğundan otomatik üretim yerine dikkatle elle yazılmalıdır

---

LLM’nin durumsuzluğu ve CLAUDE.md’nin rolü

• LLM, çıkarım anında sabitlenmiş ağırlıklar kullanır; oturumlar arasında öğrenme ya da hafıza tutmaz
  • Bu nedenle modelin kod tabanını anlayabilmesi için tüm bilgilerin giriş token’larıyla verilmesi gerekir
• Claude Code gibi kodlama ajanlarında bellek açıkça yönetilmelidir ve CLAUDE.md, tüm konuşmalara otomatik olarak dahil edilen tek dosyadır
• Bunun sonucu olarak şu üç nokta zorunludur
  1. Oturum başında Claude kod tabanı hakkında hiçbir şey bilmez
  2. Her oturumda gerekli bilgileri yeniden vermek gerekir
  3. Bunun için standart araç CLAUDE.md’dir

Kod tabanı onboarding’i: WHAT, WHY, HOW

• CLAUDE.md, Claude’un projeyi anlamasına yardımcı olan bir onboarding belgesi görevi görür
  • WHAT: Teknoloji yığını, proje yapısı, monorepo düzeni gibi bir kod haritası sunar
  • WHY: Her bileşenin amacını ve işlevini açıklar
  • HOW: Build, test, typecheck gibi gerçek işlerin nasıl yapılacağını belirtir
• Ancak tüm komutları listelemek verimsizdir; yalnızca gerekli en az bilgi yer almalıdır

Claude neden CLAUDE.md dosyasını yok sayar?

• Claude Code, kullanıcı mesajına şu tür bir sistem hatırlatıcısı ekler

  IMPORTANT: this context may or may not be relevant...
  

  • Bu yüzden Claude, ilgili bağlamın mevcut görevle alakalı olmadığını düşünürse yok sayar
• Dosyada genel geçer olmayan talimatlar arttıkça yok sayılma ihtimali de yükselir
• Anthropic’in bunu ekleme nedeni olarak, gereksiz talimatlar yok sayıldığında sonuç kalitesinin arttığının görülmüş olması tahmin ediliyor

İyi bir CLAUDE.md yazma ilkeleri

Less (instructions) is more

• LLM’ler yaklaşık 150–200 talimatı istikrarlı biçimde takip edebilir
  • Model küçüldükçe performans düşüşü keskinleşir ve çok adımlı işler için uygunluk azalır
• Claude Code’un sistem prompt’unda zaten yaklaşık 50 talimat bulunur
  • Bu yüzden CLAUDE.md içinde yalnızca genel ve zorunlu talimatlar en az düzeyde yer almalıdır
• Talimat sayısı arttıkça genel talimat uygulama kalitesi eşit biçimde düşer

Dosya uzunluğu ve kapsama alanı

• LLM’ler odaklı ve yüksek alakalı bağlamda daha iyi çalışır
• CLAUDE.md her oturuma dahil edildiğinden, yalnızca genel olarak uygulanabilir bilgiler korunmalıdır
• Genel olarak 300 satırın altında, mümkünse daha kısa tutulması önerilir
  • HumanLayer’ın örnek dosyası 60 satırın altındadır

Progressive Disclosure

• Büyük projelerde tüm bilgileri tek dosyada toplamak zor olduğundan Progressive Disclosure yaklaşımı önerilir
  • Ayrıntılı yönergeler agent_docs/ klasörü içindeki ayrı Markdown dosyalarına bölünür
  • Örneğin: building_the_project.md, running_tests.md, code_conventions.md
• CLAUDE.md yalnızca bu dosyaların listesini ve kısa açıklamasını, ayrıca Claude’un gerektiğinde bunları okumasını söyleyen talimatı içermelidir
• Kod parçaları yerine güncelliği korumak için file:line referansları kullanılmalıdır
• Bu yaklaşım Claude Skills kavramına benzer, ancak araç kullanımından çok talimat yönetimine odaklanır

Claude bir linter değildir

• Kod stili yönergelerini CLAUDE.md içine koymak verimli değildir
  • LLM’ler maliyetli ve yavaştır, ayrıca linter’lara göre daha az deterministiktir
• Stil kuralları zaten mevcut kod kalıpları üzerinden doğal olarak öğrenildiği için ayrı talimatlar gereksizdir
• Formatlama için otomatik düzeltme yapabilen linter’lar (Biome vb.) kullanılmalı, Claude’a ise yalnızca düzeltme sonuçları verilmelidir
• Gerekirse Stop Hook veya Slash Command kullanılarak formatlama ve doğrulama otomatikleştirilebilir

Otomatik üretim yasak

• /init komutu ya da otomatik üretimle oluşturulan CLAUDE.md tavsiye edilmez
  • Çünkü bu dosya tüm oturumları ve çıktıları etkileyen yüksek kaldıraçlı bir noktadır
• Yanlış yazılmış tek satırlık bir talimat bile genel kod kalitesi üzerinde zincirleme olumsuz etki yaratabilir
• Bu nedenle her cümle dikkatle gözden geçirilmeli ve elle yazılmalıdır

Sonuç

• CLAUDE.md, Claude’u kod tabanına onboard etmek için kullanılan bir belgedir ve WHY·WHAT·HOW açıkça tanımlanmalıdır
• Talimatlar en aza indirilmeli, yalnızca genel ve özlü içerik eklenmelidir
• Progressive Disclosure ile yalnızca gerekli bilgi aşamalı olarak sunulmalıdır
• Claude bir linter gibi kullanılmamalı; bunun yerine özel araçlar ile hook ve komut özellikleri birlikte değerlendirilmelidir
• Otomatik üretim yerine dikkatli manuel yazım tercih edilerek tüm harness’in kalitesi en üst düzeye çıkarılmalıdır