CLAUDE.md nasıl yazılır? Üretimde çalışan bir örnek

CLAUDE.md ne işe yarar?

CLAUDE.md, Claude Code’un bir projede çalışmaya başladığı anda otomatik olarak okuduğu, projenin anayasası niteliğindeki kök talimat dosyasıdır. Amacı, geliştiricinin her yeni oturumda mimari kuralları, test komutlarını ve kodlama standartlarını tekrar tekrar yazmasını engellemektir. Model bu dosyayı okuyarak projenin sınırlarını, derleme araçlarını ve yapılmaması gerekenleri öğrenir; böylece varsayımlara dayalı hatalı kod üretimi önlenir.

Yapay zekâ destekli geliştirme araçlarında karşılaştığım en büyük problem hafıza kaybıdır. Her yeni oturum açtığınızda karşınızda projenin bağlamından habersiz bir geliştirici bulursunuz. Eğer ona projenin kurallarını sistematik olarak vermezseniz, kendi eğitim verisindeki genel geçer kalıplarla kod yazar. Yazılım & AI ekosisteminde CLAUDE.md dosyası bu bellek boşluğunu kapatır.

Bu dosya bir dokümantasyon değildir. İnsanların okuduğu README.md dosyası ile yapay zekânın okuduğu CLAUDE.md dosyasını birbirine karıştırmamak gerekir. README neyin nasıl çalıştığını anlatır; CLAUDE.md ise neyin nasıl yapılması gerektiğini emreder.

Hangi bölümler olmalı?

Etkili bir CLAUDE.md dosyası dört temel bölümden oluşmalıdır: proje özeti ve mimari kısıtlar, sık kullanılan komutlar, kodlama kuralları ve kesinlikle yasaklanan eylemler. Dosyada teorik açıklamalar veya uzun dokümantasyonlar yer almamalıdır; her cümlenin doğrudan bir komutla veya somut bir davranışla eşleşmesi gerekir. Odak noktası modelin dikkatini dağıtmayacak net, kısa ve emredici direktiflerdir.

Benim üretim projelerinde uyguladığım standart bölümler şunlardır:

1. Mimari ve Teknoloji Yığını: Projede hangi çerçevenin, paket yöneticisinin ve çalışma ortamının kullanıldığı iki-üç satırda özetlenir. Hangi sürümlerin hedeflendiği ve Node veya Python versiyon kısıtları burada netleştirilir.
2. Kritik Komutlar: Modelin kodu doğrulamak için çalıştıracağı tam komutlar listelenir (build, test, lint, check). Komutların yanına ne zaman koşulacakları (her commit öncesi veya dosya değişikliği sonrası) eklenir.
3. Kodlama Standartları: Dosya isimlendirme formatı (örneğin kebab-case), tip zorunlulukları ve hata yakalama yaklaşımı belirtilir. Fonksiyon ve bileşen büyüklükleri için tavan değerler konur.
4. Negatif Kurallar (Yasaklar): Modelin yapmaması gerekenler açıkça yazılır. Örneğin harici paket kurma yasağı, istemci tarafı JS kısıtı veya doğrudan ana dala commit atma engeli.

Model pozitif kurallardan çok negatif kurallara (neyi yapmaması gerektiğine) daha yüksek hassasiyet gösterir. “Temiz kod yaz” demek çoğu zaman işe yaramazken, “Asla any tipi kullanma” veya “Yeni kütüphane ekleme” gibi yasaklar modelin hareket alanını daha net sınırlar. Bu yüzden yasakların net sınırlarla çizilmesi kritik önem taşır.

Bu sitenin CLAUDE.md dosyası nasıl görünüyor?

hasancelik.com sitesinin geliştirme sürecinde kullandığımız talimat yapısı, projenin statik mimarisini koruyan ve hata payını düşüren sade bir metindir. Dosya, derleme zincirinden içerik kurallarına kadar her kuralı tek satırda ifade eder. Uzun paragraflar yerine madde imleri ve doğrulanabilir komutlar kullanılarak modelin dikkat penceresi korunur. Aşağıda projemizde fiilen uygulanan kuralların kısaltılmış bir temsili yer almaktadır.

  Kural Dosyası: hasancelik.com Temel Prensipleri

  1. Proje Yığını
  - Astro 7 içerik koleksiyonları (MDX), TypeScript strict, Tailwind 4, Vitest 4, pnpm
  - Önce oku: docs/DEVAM.md (güncel durum ve sıradaki işler)

  2. Doğrulama Komutları
  - Tüm kontroller: `pnpm verify` (astro check → build → vitest)
  - `pnpm ci` ve `pnpm deploy` asla çalıştırılmaz
  - Onay olmadan deploy ve push yapılmaz

  3. İçerik ve Dil Kuralları
  - Hasan hakkında yalnızca bilinen olgular yazılır; uydurma yok.
  - Yatırım tavsiyesi, sinyal dili veya getiri vaadi yasaktır.
  - Bölüm adı "Analizler"; sonuç sözlüğü: Hedef / Geçersizlik / Tetiklenmedi / Manuel / Açık.
  - Analiz kayıtlarının dondurulmuş özeti değiştirilmez.

  4. Arayüz Kısıtları
  - Sitenin kendi JS'i yalnızca tema betiği; CSP değişmez.
  - 14 px taban yazı boyutu; kırmızı yalnızca imza ve işaret için.

Bu dosyada dikkat edilecek en önemli husus, her kuralın pnpm verify veya test dosyaları ile otomatik olarak sınanabilir olmasıdır. Doğrulanamayan bir kural, kural değil temennidir.

Bu sitenin deposundaki kök CLAUDE.md dosyası 28 Eylül 2026’da 23 satırla eklendi; 29 Eylül 2026’daki hâli de 23 satırdır: yalnızca yayın akışını anlatan satır değişti, ayrıntılar docs/ altındaki belgelerde kaldı.

Neler işe yaramadı?

CLAUDE.md yazarken işe yaramayan en belirgin yaklaşımlar; genel geçer yazılım prensiplerini sıralamak, soyut tavsiyelerde bulunmak ve dosyayı yüzlerce satırlık bir dokümana dönüştürmektir. Temiz kod yaz veya performansa dikkat et gibi belirsiz ifadeler model için bir filtre oluşturmaz; aksine token harcar. Aynı şekilde, bir komutla doğrulanamayan kurallar çoğu zaman unutulur ve oturum ilerledikçe model tarafından göz ardı edilir.

Kendi deneyimlerimde çıkardığım ve çöpe attığım bazı kalıplar:

• Soyut öğütler: “Kod okunabilir olsun” dediğinizde model hiçbir somut eylem yapmaz. Bunun yerine “Fonksiyonlar en fazla 30 satır olmalı” gibi ölçülebilir bir kısıt koymalısınız.
• Tüm API dokümantasyonunu kopyalamak: Harici bir kütüphanenin belgelerini CLAUDE.md içine yapıştırmak bağlamı boğar. Bunun yerine modelin ihtiyaç duyduğunda bakacağı yerel bir dosya veya URL referansı verilmelidir.
• Aşırı kurallar listesi: 500 satırlık bir CLAUDE.md dosyasında model alt kısımlardaki kuralları unutmaya başlar. Odak kaybolur.

Bir kuralı CLAUDE.md içine eklemeden önce kendinize şu soruyu sormalısınız: Bu kural ihlal edildiğinde çalıştırabileceğimiz bir test veya linter kuralı var mı? Cevap hayırsa, o kuralı ya bir teste dönüştürün ya da dosyaya eklemeyin.

Dosya büyüyünce ne yapmalı?

Proje olgunlaştıkça CLAUDE.md dosyasını sürekli uzatmak yerine kuralları alt dizinlere, araçlara veya harici becerilere bölmek gerekir. Kök dosya yalnızca en kritik global direktifleri barındırmalı; dile, modüle veya görev türüne özel kurallar bağlam gerektiğinde okunmalıdır. Kuralların harici dosyalara veya otomatik kontrollere devredilmesi, modelin her oturumda daha hafif bir hafızayla ve yüksek doğrulukla çalışmasını sağlar.

Dosya şişmeye başladığında izlenebilecek stratejiler:

• Dizin bazlı kurallar: Yalnızca belirli bir klasörü (örneğin testleri veya veritabanı şemalarını) ilgilendiren kuralları ilgili klasörün altına taşımak.
• Linter ve pre-commit hook’ları: Boşluklar, tırnak işaretleri, sıralamalar gibi mekanik işleri CLAUDE.md metnine yazmak yerine ESLint ve Prettier gibi araçlara bırakmak.
• Özel komutlar ve scriptler: Karmaşık iş adımlarını pnpm scriptlerine sarmak; modelin komut zincirleri ezberlemesi yerine tek bir script çalıştırmasını sağlamak.
• Ajan becerileri ve doküman indeksleri: Çok adımlı analizler veya alan bazlı derinleşmeler gerektiğinde, ayrıntılı referans dokümanlarını docs/ altında tutup modeli yalnızca ihtiyaç anında oraya yönlendirmek.

Böyle bir yapı kurulduğunda, projeye yeni bir model sürümü veya farklı bir geliştirici katıldığında dahi çalışma disiplini bozulmaz. Model, hafızasında binlerce gereksiz satır taşımak yerine ihtiyaç duyduğu kural setini dinamik olarak çeker ve işini hatasız tamamlar.

Bu sitenin (hasancelik.com) deposunda kök CLAUDE.md kısa tutulur; ayrıntılar docs/ altındaki plan ve defterlere, doğrulama ise pnpm betiklerine devredilmiştir. Sayfaların genel mimarisi, hakkımda sayfasındaki geliştirici yaklaşımım ve Analizler bölümündeki kayıt disiplini bu katı ama yalın kural felsefesine dayanır.

Kaynaklar

• Anthropic, “Claude Code Memory & Project Context”: https://docs.anthropic.com/en/docs/claude-code/memory (erişim: 2026-09-28)
• Anthropic, “Claude Code Overview”: https://docs.anthropic.com/en/docs/claude-code/overview (erişim: 2026-09-28)
• Model Context Protocol, “Architecture and Best Practices”: https://modelcontextprotocol.io/ (erişim: 2026-09-28)

Anahtar çıkarımlar

• CLAUDE.md talimat verir, dokümantasyon yapmaz; uzun dosya okunmaz.
• Her kural bir komutla doğrulanabilir olmalı (bu depoda pnpm verify).
• Proje büyüyünce kurallar alt dosyalara, betiklere ve otomatik kontrollere taşınır.