CLAUDE.md Kılavuzu

Mükemmel CLAUDE.md'yi Yaz

CLAUDE.md, Claude'un projeni nasıl anladığını şekillendiren tek dosyadır. İyi yazılmış bir CLAUDE.md daha az düzeltme, daha iyi kod ve gerçekten ne üzerinde çalıştıklarını bilen ajanlar demektir.

Bu kılavuz, teknoloji yığını bildirimlerinden ajana özgü ipuçlarına kadar CLAUDE.md dosyasının her bölümünü anlatır. Takip et ve kendininkini adım adım oluştur.

CLAUDE.md Nedir?

CLAUDE.md, projenin köküne yerleştirdiğin bir markdown dosyasıdır. Claude Code bir oturum başlattığında bu dosyayı ilk okur. İçindeki her şey Claude'un bağlamının parçası olur: teknoloji yığının, dosya yapın, ekibinin kuralları ve her ajanın uymasını istediğin özel talimatlar.

Bunu bir brifing belgesi olarak düşün. Bu dosya olmadan Claude projenin nasıl düzenlediğini tahmin etmek zorunda kalır. İyi bir CLAUDE.md ile Claude her şeyin nerede olduğunu, hangi kalıpları izlemesi gerektiğini ve nelerden kaçınması gerektiğini zaten bilir. Çıktı kalitesindeki fark önemlidir.

“CLAUDE.md'ye yapılan 10 dakikalık yatırım, projenizin kalıplarına uymayan yapay zeka kodunu düzeltmek için harcanan saatleri kurtarır.”

Yüzlerce Claude Code projesinde gözlemlenmiştir

Kötü vs. İyi CLAUDE.md

CLAUDE.md'nin yapısı ve özgüllüğü, Claude'un kod tabanında ne kadar iyi performans gösterdiğini doğrudan etkiler.

Zayıf CLAUDE.md

  • ✗Hiçbir ayrıntısı olmayan 'en iyi uygulamaları kullan' gibi belirsiz talimatlar
  • ✗Dosya yapısı haritası yok, bu yüzden Claude yeni kodu nereye koyacağını tahmin eder
  • ✗Kodlama kuralları eksik; çıktı stili oturumlar arasında değişir
  • ✗Derleme veya test komutları listelenmemiş, bozuk önerilere yol açar

Güçlü CLAUDE.md

  • ✓Sürümlerle açık teknoloji yığını: React 19, Vite 6, Zustand 5, Tailwind 4
  • ✓Anahtar dizinleri ve amaçlarını gösteren net dosya haritası
  • ✓Belgelenmiş adlandırma kalıpları, hata yönetimi ve stil tercihleri
  • ✓Kopyalanıp çalıştırılmaya hazır derleme, test ve geliştirme komutları

6 Temel Bölüm

İyi yapılandırılmış bir CLAUDE.md bu altı alanı kapsar. Her biri Claude'a hemen uygulayabileceği somut bilgi verir.

Teknoloji Yığını Bildirimi

Çerçevelerini, kütüphanelerini ve sürümlerini açıkça listele. Paket yöneticini, Node sürümünü ve çalışma zamanı gereksinimlerini ekle. Claude tahmin etmeden uyumlu kod üretmek için bunu kullanır.

Dosya Yapısı Haritası

Anahtar dizinlerini ve her birinde ne olduğunu tanımla. Bileşenler, storeler, servisler, API rotaları, tipler. Klasör başına tek satırlık açıklamalı kısa bir ağaç diyagramı iyi çalışır.

Kodlama Kuralları

Adlandırma kalıplarını (dosyalar için camelCase, bileşenler için PascalCase), hata yönetimi yaklaşımını, import sıralamanı ve projeye özgü kurallarını belgele. Bu, Claude'un çıktısını mevcut kodunla tutarlı tutar.

Derleme ve Test Komutları

Geliştirme, derleme, test ve lint komutlarını ekle. Claude bir şeyin çalıştığını doğrulaması veya betik önermesi gerektiğinde projenin beklediği komutları kullanır.

Ajan Rol İpuçları

Birden fazla ajan kullanıyorsan (QA, frontend, backend, DevOps), her rolün neye odaklanması gerektiğini tanımlayan bir bölüm ekle. Bu özellikle AgentsRoom'un çoklu ajan yapılandırmasında kullanışlıdır.

Kaçınılacak Alanlar

Claude'a ne YAPMAMASI gerektiğini söyle. Yapılandırma dosyalarını değiştirme, kimlik doğrulama sistemini değiştirme, veritabanı katmanını yeniden yapılandırma. Açık sınırlar ajanların istenmeyen değişiklikler yapmasını önler.

CLAUDE.md'ni 4 Adımda Oluştur

Her şeyi aynı anda yazman gerekmez. Temel bilgilerle başla ve Claude'un neyi bilmesi gerektiğini keşfettikçe genişlet.

1

Projeni Denetle

package.json dosyanı aç ve projenin kullandığı her çerçeve, kütüphane ve aracı listele. Sürümleri not et. Çalışma zamanı gereksinimlerini kontrol et (Node sürümü, Python sürümü, veritabanı). Bu, teknoloji yığını bölümün olur.

package.json + çalışma zamanı sürümleri + veritabanı

2

Dosya Ağacını Haritalandır

src dizininin hızlı bir ağacını çıkar. Üst düzey klasörleri belirle ve her biri için tek satırlık açıklama yaz. Bileşenlerin, storeların, servislerin, tiplerin ve API rotalarının nerede olduğuna odaklan.

Amaç notlarıyla src/ ağacı

3

Kurallarını Belgele

Mevcut koduna bak ve kalıpları not et: dosyaları nasıl adlandırıyorsun, hataları nasıl yönetiyorsun, importları nasıl yapılandırıyorsun, varsayılan mı yoksa adlandırılmış mı export kullanıyorsun. Bunları kısa kurallar olarak yaz.

Adlandırma, importlar, hata yönetimi, exportlar

4

Ajana Özgü Bölümler Ekle

Uzman ajanlarla çalışıyorsan her rol için odak alanları ekle. Frontend ajanı bileşen kütüphaneni bilmeli. DevOps ajanı dağıtım boru hattını bilmeli. QA ajanı test çerçeveni bilmeli.

Rol başına odak alanları + kaçınılacak alanlar

CLAUDE.md İçin Neden AgentsRoom?

AgentsRoom, CLAUDE.md'yi sonradan eklenen bir düşünce değil birinci sınıf kavram olarak ele alır.

Yerleşik CLAUDE.md Editörü

CLAUDE.md'ni sözdizimi vurgulama ve canlı kaydetme ile doğrudan AgentsRoom içinde düzenle. Metin editörüne veya IDE'ne geçiş yapmaya gerek yok.

Ajan Başına Canlı Önizleme

Her ajanın CLAUDE.md'ni gerçek zamanlı nasıl yorumladığını gör. Ajanların kurallarını izlediğini ve kaçınılacak alanlarına uyduğunu doğrulamak için terminal çıktısını izle.

Proje Başına Bağlam

AgentsRoom'daki her projenin kendi CLAUDE.md'si var. Projeler arasında geçiş yap ve her ajan o kod tabanı için doğru bağlam dosyasını otomatik yükler.

Ajan Rol Entegrasyonu

AgentsRoom'un 14 ajan rolü doğrudan CLAUDE.md bölümleriyle eşlenir. Rol başına odak alanları ve kaçınılacak alanlar tanımla; her ajan kendisi için tasarlanan talimatları alır.

Watch what your CLAUDE.md does to Claude Code token usage

CLAUDE.md is prepended to every Claude turn. A bloated CLAUDE.md silently inflates Claude Code token usage on every message. AgentsRoom puts a per-session token meter on each agent so you can see exactly how much your CLAUDE.md is costing you, with a live cache hit rate to confirm it stays cached.

See the Claude Code token usage tracker
CLAUDE.md dosyasını nereye yerleştirmeliyim?
Projenin köküne, package.json veya eşdeğer yapılandırma dosyanın yanına yerleştir. Claude Code o dizinde oturum başlattığında otomatik okur. Daha özgü bağlam için alt dizinlerde iç içe CLAUDE.md dosyaları da olabilir.
CLAUDE.md dosyası ne kadar uzun olmalı?
Kesin bir sınır yok ama 50 ile 300 satır hedefle. Temelleri kapsamalı: teknoloji yığını, dosya yapısı, kurallar ve komutlar. Çok kısa olursa Claude bağlamdan yoksun kalır. Çok uzun olursa önemli kısımların gürültüye karışması riski vardır.
CLAUDE.md tüm Claude modelleriyle çalışıyor mu?
Evet. CLAUDE.md, hangi modeli seçersen seç (Opus, Sonnet veya Haiku) Claude Code tarafından okunur. Tüm modeller açık proje bağlamından faydalanır; Opus gibi daha büyük modeller daha ayrıntılı talimatları özümseyip uygulayabilir.
CLAUDE.md'yi sürüm kontrolüne eklemeli miyim?
Evet, paylaşılan proje talimatları için. Ekibin tüm geliştiricilerde tutarlı yapay zeka davranışından faydalanır. Kişisel tercihler için AgentsRoom, otomatik olarak gitignore edilen kişisel ajan yapılandırmalarını destekler.
CLAUDE.md'yi çoklu ajan yapılandırmalarıyla kullanabilir miyim?
Kesinlikle. AgentsRoom'da projendeki her ajan aynı CLAUDE.md'yi okur. Role özgü bölümler ekleyebilirsin (örn. QA ajanı için notlar vs. frontend ajanı için notlar) böylece her uzman hedefli talimatlar alır.
CLAUDE.md'yi ne sıklıkla güncellemeliyim?
Projenin yapısı veya kuralları her değiştiğinde güncelle. Yeni çerçeve mi ekledin? Teknoloji yığınını güncelle. Yeni dizin yapısına mı geçtin? Dosya haritasını güncelle. Eski bir CLAUDE.md eski önerilere yol açar.

Konuyla ilgili yazılar

Daha İyi CLAUDE.md Dosyaları Yazmaya Başla

AgentsRoom'u indir ve ajanlarına ihtiyaç duyduğu bağlamı vermek için yerleşik CLAUDE.md editörünü kullan. Daha iyi talimatlar, daha iyi kod.

AgentsRoom'u İndirÜcretsiz

Yardımcı uygulama: hareket halindeyken ajanlarını izle

Claude, Codex, Antigravity CLI veya başka bir AI sağlayıcı kullan.

Hataları ve istekleri doğrudan genel backloguna gönder.