CLAUDE.md, projenizin kök dizinine koyduğunuz ve Claude Code’un her oturumda otomatik olarak okuduğu bir talimat dosyasıdır. CLAUDE.md sayesinde Claude, projenizin mimarisini, kodlama standartlarını, yasaklı operasyonları ve iş akışı kurallarını oturumdan oturuma yeniden anlatmanıza gerek kalmadan bilir. Kurumsal yazılım takımları için bu dosya, bir yeni geliştiriciye verilen ekip rehberinin AI versiyonudur.
CLAUDE.md nasıl çalışır
Claude Code bir oturum başlattığında mevcut dizinde ve üst dizinlerde CLAUDE.md dosyası arar. Bulursa içeriği sistem bağlamına yükler. Bu, her oturum başında “bu proje React + TypeScript kullanıyor, testleri Jest ile yaz, hiçbir zaman production veritabanına doğrudan bağlanma” gibi bilgileri tekrar girmenizi önler.
Dosya sıradan bir Markdown belgesidir. Özel bir sözdizimi yoktur. Claude bu dosyayı okur ve içeriklere göre davranışını ayarlar.
CLAUDE.md dosyasının gücü, bireysel kullanımdan çok takım kullanımında ortaya çıkar. Tek bir geliştirici için hatırlatıcı işlevi görürken, beş kişilik bir ekipte herkesin Claude’a aynı kurallara göre çalışmasını sağlar.
Temel CLAUDE.md yapısı
İyi bir CLAUDE.md dört temel bölümü kapsar: proje bağlamı, teknik yığın, kodlama standartları ve yasaklı operasyonlar.
Proje bağlamı Claude’a ne üzerinde çalıştığınızı anlatır. Şirketi, ürünü ve sistemin mimarisini özetleyen 3-5 cümle yeterlidir. Bu bağlam olmadan Claude, “cart service” ya da “notification worker” gibi proje-spesifik isimleri tanımaz.
Teknik yığın hangi dillerin, framework’lerin ve araçların kullanıldığını tanımlar. Açık olmak önemlidir: “JavaScript” değil, “TypeScript 5.3, React 18, Vite 5, Vitest” gibi versiyon bilgisi içeren tanımlar daha güvenilir sonuç verir.
Kodlama standartları hangi stil kurallarının geçerli olduğunu belirtir: lint yapılandırması, naming convention, dosya organizasyonu, yorum yazma politikası.
Yasaklı operasyonlar Claude’un yapmamasını kesinlikle istediğiniz eylemleri listeler. Bu bölüm, takımların production ortamında yaşadığı en önemli güvenlik katmanıdır.
Gerçek bir CLAUDE.md örneği
Aşağıda orta ölçekli bir B2B SaaS şirketi için yazılmış örnek bir CLAUDE.md dosyası yer alıyor:
# Proje: OrderFlow Backend
## Bağlam
OrderFlow, B2B e-ticaret şirketleri için sipariş yönetimi platformudur.
Bu repository backend API'yi içerir. Frontend ayrı bir repo'da (orderflow-ui).
Mikro servis mimarisine geçiş sürecindeyiz; mevcut monolith ve yeni servisler
paralel çalışıyor.
## Teknik yığın
- Runtime: Node.js 20, TypeScript 5.3
- Framework: Express 4 (yeni servisler için Fastify 4)
- ORM: Prisma 5 (PostgreSQL)
- Test: Vitest + Supertest
- Queue: BullMQ (Redis üzerinde)
- Konteyner: Docker + Compose
## Mimari kurallar
- Her servis kendi veritabanına sahip; başka servisin DB'sine doğrudan bağlanma
- Event-driven iletişim için BullMQ kuyruğu kullan
- Tüm dış API çağrıları services/ klasöründe, controller doğrudan HTTP istek atmaz
- Error handling için src/utils/errors.ts'deki sınıfları kullan
## Kodlama standartları
- Naming: camelCase değişken/fonksiyon, PascalCase sınıf, UPPER_SNAKE_CASE sabit
- Her fonksiyon JSDoc ile belgelenmeli
- Bir dosya 300 satırı aşarsa bölümlere ayır
- async/await tercih et, raw Promise zinciri yazma
## Test kuralları
- Her yeni endpoint için en az 1 başarı + 1 hata senaryosu testi yaz
- Unit testler __tests__/ klasöründe, integration testler test/integration/ altında
- Test DB için .env.test dosyasını kullan, asla production connection string kullanma
## YASAK OPERASYONLAR
- Production veritabanına (DATABASE_URL_PROD) hiçbir zaman bağlanma
- Mevcut migration dosyalarını düzenleme, yeni migration ekle
- node_modules/ içinde hiçbir şeyi değiştirme
- .env.production dosyasını okuma veya değiştirme
## Faydalı bağlamlar
- Sipariş durumları: PENDING → CONFIRMED → SHIPPED → DELIVERED → CANCELLED
- Tüm tarihler UTC olarak saklanıyor
- Müşteri ID'leri UUID, sipariş ID'leri ORD- prefix'li (örn: ORD-2025-001)Takım için CLAUDE.md yazmak: bireysel kullanımdan farkları
Tek bir geliştirici için CLAUDE.md kişisel tercihleri yansıtır. Takım için CLAUDE.md ise herkesin mutabık kaldığı standartları yansıtmalıdır ve bu süreç, dosyanın teknik içeriğinden önce gelmesi gereken bir anlaşmayı gerektirir.
Pratik yaklaşım şudur: önce ekipteki en deneyimli 2-3 kişi projenin en kritik kurallarını listeler. Bu liste CLAUDE.md’ye dönüştürülür, birkaç sprint boyunca kullanılır ve ekibin geri bildirimleriyle güncellenir. Dosya bir kez yazılıp unutulan bir belge değil, projeyle birlikte gelişen yaşayan bir dokümandır.
CLAUDE.md’yi version control’e ekleyin. Bu dosyanın git geçmişi, projenin kodlama standartlarının nasıl evrildiğini gösterir ve yeni katılan geliştiriciler için değerli bir kaynak olur.
Subagent sistemleriyle CLAUDE.md kullanımı
Claude Code 2026 itibarıyla paralel subagent desteği sunuyor. Karmaşık görevlerde Claude, alt görevleri birden fazla subagent’e dağıtıp paralel çalıştırabiliyor. Bu mimaride CLAUDE.md’nin rolü daha da kritik hale geliyor: her subagent aynı dosyayı okuyarak aynı kurallara göre davranıyor.
Büyük projelerde her servis veya alt modül için ayrı CLAUDE.md dosyaları yazılabilir. Ana dizindeki CLAUDE.md genel kuralları içerirken, örneğin services/payment/CLAUDE.md sadece ödeme servisine özgü kuralları barındırır. Claude bu hiyerarşiyi anlayarak bağlama göre doğru dosyayı önceliklendirir.
Bu yapıyı ve agentic yazılım geliştirmenin diğer katmanlarını (MCP entegrasyonu, plan modu, hook’lar) sistematik olarak öğrenmek isteyenler için Claude Code ile Agentic Yazılım Geliştirme Eğitimi programı hem kurulum hem de kurumsal ölçek konularını kapsıyor.
Sık yapılan hatalar
CLAUDE.md yazarken takımların en çok düştüğü hatalardan biri, dosyayı çok genel tutmaktır. “İyi kod yaz”, “performanslı ol” gibi tanımlar Claude’a yol göstermez. Bunun yerine “her veritabanı sorgusu için index kontrolü yap, N+1 sorgularından kaçın” gibi spesifik yönergeler çok daha işlevseldir.
Bir diğer hata, yasaklı operasyonlar bölümünü boş bırakmaktır. Bu bölüm olmadan Claude, production veritabanını değiştirme girişimi gibi geri dönüşü zor operasyonlar yapabilir. Güvenlik kritik eylemleri için bu bölümü her zaman doldurun.
Son olarak, CLAUDE.md’yi bir kez yazıp güncellememek de sık karşılaşılan bir sorundur. Proje değiştikçe, yeni servisler eklendikçe ve ekip büyüdükçe bu dosya da güncellenmelidir.
