İ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

[GN⁺]

Hacker News görüşleri

• Claude bazen CLAUDE.md içindeki talimatları görmezden gelme eğiliminde oluyor
  Dosyada belirli görevle ilgisiz ne kadar çok bilgi varsa Claude’un o talimatlara uyma ihtimali o kadar azalıyor
  Bir arkadaşım Claude’a kendisine “Mr Tinkleberry” diye hitap etmesini söylemişti; Claude bunu her unuttuğunda dosyayı görmezden geldiğini anlayabiliyorduk

• Ben uzun zamandır Table-of-Contents yaklaşımını kullanıyorum
  Göreve özel yönergeleri ayrı markdown dosyalarına bölüp, CLAUDE.md içine yalnızca bunların listesini ve kısa açıklamalarını koyuyorum
  Böylece context window temiz kalıyor
  Örnek dosyamı burada görebilirsiniz

  • Ben de aynı yöntemi denedim ama sonuçlar tutarsızdı
    Claude’un diğer belge dosyalarını gerçekten okuduğu durumlar çok nadirdi

• Claude’a fazla context verince kalitenin düştüğünü hissediyorum
  Bu yüzden her zaman kodun iki sürümünü tutuyorum

  1. Yorum ve boşluk içermeyen ham kod
  2. Yorum içeren kod
     LLM’e yalnızca ilk sürümü veriyorum
     Bence mesele compute / bilgi oranı. Sonuçta hesaplama kapasitesi sınırlı
  • Ben de benzer bir şey yaşadım ama tekrar eden içerikleri Claude notes dosyasına koyunca verim arttı
    Her şeyi koymak gerekmiyor ama kritik bilgileri eklemenin ROI’si yüksekti
    Claude genel projelerde iyi çalışıyor ama yeni framework veya araçlarda sık sık kafası karışıyor
  • Kodun iki sürümünü tuttuğunu söylemişsin; bunun tutarlılığını nasıl yönettiğini merak ediyorum
    Değişiklikten sonra yorumları ve boşlukları kaldıran bir script kullanıp kullanmadığını sormak isterim
  • Belge dosyalarında bilgi yoğunluğunu yüksek tutmak gerektiğini düşünüyorum
  • LLM’e yorumlu sürümü vermediğini söyledin; bunu pratikte tam olarak nasıl uyguladığını merak ediyorum
  • Sonuçta attention sınırlı. Context’i fazla doldurunca odak dağılıyor

• Aslında bu kadar karmaşık kurulum olmadan da bir çözüm var
  O da kodu açıkça dokümante etmek
  Her dosyanın ne yaptığını kısa ve net biçimde yazarsanız bu zaten başlı başına bir prompt işlevi görür
  README.md’yi aktif şekilde kullanmak yeterli
  LLM’ler zaten kamuya açık bilgilerle eğitildiği için yeni bir şey icat etmeye gerek yok

  • Ama AI için dokümantasyon yazarken insan okuyucuya yönelik dokümandan farklı bir yaklaşım gerekiyor
    Sadece “kodu iyi dokümante edin” tavsiyesi bu bağlamda pek uygun değil
  • Ben de AI topluluğunun bazen gereksiz yere tekerleği yeniden icat ettiğini düşünüyorum
    README iyi ama CLAUDE.md’nin amacı farklı
    Örneğin Claude/agents.md, belirli bir dizine erişildiğinde context’e otomatik eklenebilen bir özellik sunuyor
    Karmaşık kod tabanlarında context yönetimi çok daha önemli
  • CLAUDE.md basit bir doküman değil, modelin başlangıç prompt’unu özelleştirme işlevi görüyor
    Bu yüzden “uygun prompt yazın” tavsiyesi asıl noktayı kaçırıyor
  • Mesela “veritabanı sorguları her zaman indeks kullanmalı” gibi bir kuralı nereye yazarsınız?
    README’ye yazarsanız sonunda yine CLAUDE.md ile aynı işleve yaklaşmış olursunuz
    CLAUDE.md’nin amacı, Claude’un her seferinde bütün dokümanları yeniden okumak zorunda kalmaması için temel bilgileri peşinen vermek
    İnsanlar hatırlar ama Claude her görevde unutuyor; bu yüzden yeniden onboarding ihtiyacını azaltan bir yapıya gerek var

• Açıkçası bu kadar AI altyapısı kurmak gerekiyorsa kodu kendim yazmam daha iyi gibi geliyor

  • Ama stil ile ilgili ayarlar bir kez yapıldıktan sonra tekrar kullanılabiliyor
    Ben ortak kuralları ve projeye özel kuralları ayrı yönetiyorum
  • Yazıda anlatılan kurulum birkaç saat içinde tamamlanabilir
    AI kullanmamak düpedüz verimlilik kaybı
  • İlk kurulumun büyük kısmı LLM’e de yaptırılabilir
  • Aslında o kadar büyük bir çaba gerekmiyor. Sorun, araçları gereğinden fazla optimize etmeye çalışmak
  • Önemli olan maliyetin tekrarlı mı yoksa tek seferlik mi olduğu
    Kurulum bir kez yapılacaksa buna yatırım yapmak fazlasıyla değer
    “Kurulumla uğraşmak istemiyorum” demek, debugger ayarından kaçınan insanların bahanesine benziyor

• Ben genelde gereken kodu kopyalayıp sohbet penceresine yapıştırıyor ve sohbet eder gibi kullanıyorum
  Modeller artık çok geliştiği için .md dosyaları olmadan da gayet iyi sonuç veriyorlar
  Bu tür dosyalar küçük iyileştirmeler sağlayabilir ama 100 kat verimlilik getiren bir sihir olduklarını sanmıyorum

  • Ama bu farklı bir kullanım senaryosu
    Burada tartışılan şey, Claude’un tam özellik geliştirme ya da hata düzeltmeyi kendi başına yapması
  • Benim deneyimim de benzer. Bir kez CLAUDE.md hazırladım ama artık kullanmıyorum
    Sadece gereken context’i vermek yeterince iyi çalışıyor. Biraz bikeshedding gibi geliyor
  • Yine de veritabanı tabloları veya sütun listeleri gibi şeyleri önceden derlemek tekrarları azaltabilir

• Ben CLAUDE.md’yi doğrudan Claude’a yazdırıyorum
  “README.md kullanıcılar için, CLAUDE.md senin için” dediğinizde
  “API dokümantasyonunu her zaman kontrol et” gibi talimatları da otomatik güncelliyor
  Sihirli prompt’ları bilmesem de sonuç iyi çıktığı sürece sorun değil

  • Ama AI’ın kendi yazdığı talimatların insanın yazdıklarından daha iyi olduğuna dair kanıt var mı emin değilim
    AI’ın kendisini en iyi şekilde prompt’laması için özel bir nedeni varmış gibi görünmüyor