CLAUDE.md — Proje Kuralları Şablonu

AI destekli geliştirmede projeye bağlayıcı mühendislik kuralları tanımlayan kapsamlı CLAUDE.md şablonu: mimari, güvenlik, veritabanı, test, git ve daha fazlası.

# CLAUDE.md

Bu dosya, projede çalışırken uyman gereken kuralları içerir. Kurallar bağlayıcıdır.
Bir kuralı esnetmen gerekiyorsa önce gerekçeni belirt ve onay iste.

Bu kurallar **teknolojiden bağımsız** prensiplerdir. Parantez içindeki araç isimleri
yalnızca örnektir; projenin seçtiği dil, framework, veritabanı ve araçlara göre uygulanır.

---

## Git Kuralları
- Her kod değişikliğinden sonra commit yap
- *git add -A KULLANMA* — sadece değiştirdiğin dosyaları git add <dosya1> <dosya2> ile ekle
- Commit öncesi git diff --stat ile hangi dosyaların değiştiğini kontrol et, görevle ilgisiz dosya varsa ekleme
- Commit mesajı: ne değiştiğini kısaca açıkla (Türkçe)
- Birden fazla dosya değiştiysen tek commit yeterli
- Secret yada api key gibi gizli bilgiler publish edilmemeli.

## 1. Genel Prensipler

- Tip güvenliğini en üst düzeyde tut; dilin sunduğu en katı modu kullan. Kaçış tipi (örn. `any`) kullanma; bilinmeyen için güvenli/daraltılabilir tip kullan.
- Her dosya tek sorumluluk taşır. Dosyalar makul boyutta kalsın.
- Magic string / magic number yasaktır. Sabitleri isimlendir ve merkezi tut.
- Kod İngilizce yazılır (değişken, fonksiyon, yorum). Kullanıcıya dönen metinler ayrı bir katalogda.
- Çalışan koda dokunurken davranışı koruduğundan emin ol; ilgili testleri çalıştır.
- Açıklık (explicit) örtüklüğe (implicit) tercih edilir; "akıllı" kısa yollar yerine okunabilir kod.

## 2. Sektör Standartlarına Uyum

- Bu dosyada açıkça belirtilmemiş her durumda yerleşik sektör standardını ve yaygın kabul görmüş best practice'i takip et; kendi ad-hoc çözümünü uydurma.
- Dil, framework ve kütüphane idiomlarına uy. Topluluğun beklediği konvansiyon ile bizim kuralımız çelişirse, çelişkiyi belirt ve onay iste; sessizce sapma.
- Tekerleği yeniden icat etme: olgun, bakımlı ve yaygın kullanılan bir çözüm işi görüyorsa onu tercih et. Yeni bağımlılık eklemeden önce gerekçeni sun.
- "Herkes böyle yapıyor" tek başına gerekçe değildir; standardın bizim bağlamımıza (ölçek, güvenlik, performans) uyduğundan emin ol. Uymuyorsa nedenini açıkla.
- Standartlar zamanla değişir; bir pratiğin güncel olup olmadığından emin değilsen varsayım yapma, doğrula.

## 3. Klasör ve Dosya Yapısı

- Özellik (feature) bazlı organizasyonu tercih et: her özellik kendi klasöründe, ilgili tüm parçalarıyla (giriş noktası, iş mantığı, veri erişimi, tipler, testler) birlikte dursun.
- Modüller arası ortak parçalar (middleware, base sınıflar, ortak hatalar) ayrı bir paylaşılan alanda toplanır.
- Bir şeyin nereye gideceği tahmin edilebilir olmalı; "bunu nereye koyayım?" sorusu yaşanmamalı.
- Dosya isimlendirmede tek bir şema seç ve tutarlı kal.
- Relative import spagettisinden (`../../../..`) kaçın; path alias kullan.
- Barrel/index dosyalarını yalnızca modül sınırında, public API'yi dışa açmak için kullan; her klasöre koyma (döngüsel bağımlılık riski).

## 4. Mimari ve Bağımlılık Yönü

- Net katmanlar tanımla (örn. giriş/transport → iş mantığı → veri erişimi) ve bağımlılığın tek yöne aktığından emin ol.
- Alt katman üst katmanı bilmez; veri erişimi iş mantığını, iş mantığı transport katmanını import etmez.
- Ortak yardımcılar hiçbir özelliğe bağımlı olmaz (en altta durur).
- Bağımlılıkları dışarıdan enjekte et (DI); sınıf içinde somut bağımlılığı doğrudan oluşturma.
- Somut implementasyona değil, davranış sözleşmesine (arayüz/soyutlama) bağımlı ol (Dependency Inversion).
- Mümkünse katman sınırlarını otomatik araçla (lint kuralları) zorla.

## 5. OOP ve Modelleme

- State veya polimorfizm taşıyan birimleri sınıf olarak modelle; saf, durumsuz yardımcılar fonksiyon kalır.
- Her şeyi sınıf yapma; gereksiz soyutlama da bir anti-pattern'dir.
- Değiştirilebilir parçaları arayüz/soyutlama ile tanımla, somut implementasyonu ayır.
- Karmaşık iş kuralı olan domain'lerde davranışı veriyle birlikte modele koy (anemic model'den kaçın); basit CRUD için zorlama.
- Anlamlı kavramları primitive yerine değer nesnesi (value object) olarak tiple ve doğrulamayı içine al.

## 6. Dış Entegrasyon ve Genişletilebilirlik

- Her dış servis/sağlayıcı entegrasyonunu, iş mantığını sağlayıcının somut API'sinden yalıtan bir **adapter** olarak yaz. Çekirdek mantık sağlayıcıya değil, bir davranış sözleşmesine (interface) bağımlı olsun.
- Aynı kategoride (örn. sipariş sağlayıcısı, ödeme sağlayıcısı, kargo sağlayıcısı) birden fazla entegrasyon gelebileceğini varsay; tek sağlayıcıya özgü detayları (auth, webhook formatı, durum eşlemesi) adapter'ın içine hapset, dışarı sızdırma.
- Yeni bir sağlayıcı eklemek, çekirdek iş mantığına dokunmadan yeni bir adapter yazmak kadar kolay olmalı (Open/Closed prensibi).
- Sözleşmeyi minimal ve gerçek ihtiyaca dayalı tut. **Erken soyutlamadan kaçın:** tek somut örnek varken kapsamlı abstract hiyerarşi / plugin sistemi / registry kurma; soyutlamayı ikinci gerçek örnek ortaya çıkınca olgunlaştır. Yanlış soyutlama, kod tekrarından daha pahalıdır.
- Davranış sözleşmesi için `interface` kullan; `abstract class`'ı yalnızca sağlayıcılar arasında gerçekten paylaşılan ortak kod (örn. retry, imza doğrulama) olduğunda tercih et.

## 7. Explicit Mapping (Katmanlar Arası Veri)

- Veritabanı/iç veri modelini asla dış arayüzde (API) doğrudan dönme; her zaman açık bir dönüşümle dışa açılan tipe çevir.
- İç model (kalıcılık), dış sözleşme (API I/O) ve gerekirse domain modelini ayrı tut.
- Dönüşümü gevşek kopyalama (spread) ile değil, alan alan açık yaz; böylece yeni bir iç alan otomatik olarak dışarı sızmaz.
- Gelen girdiyi doğrudan iç modele atama (mass assignment koruması); yalnızca izinli alanları seç (whitelist).

## 8. Tipler ve Validation

- Çalışma zamanı doğrulaması ile statik tipi tek kaynaktan üret; tip ile kontrol senkron kalsın.
- Her dış girdi (ve mümkünse çıktı) bir şema ile doğrulanır.
- Tipleri kullanıldıkları yere yakın tut; her şeyi tek bir dev tip dosyasına yığma.
- Client'tan/dışarıdan gelen veriye asla güvenme; whitelist yaklaşımı uygula.

## 9. Async ve Hata Yönetimi

- Asenkron işlerde tutarlı, modern bir yaklaşım kullan; callback yuvalanmasından kaçın.
- Bağımsız işleri paralel çalıştır; gereksiz yere sırayla bekleme.
- Yalnızca hata nesnesi (veya türevi) fırlat; ham değer/string fırlatma.
- Operasyonel hata ile programcı hatasını ayır. Özel hata tipleri tek bir yerde toplanır.
- Tek bir merkezi hata yöneticisi ile yanıt üret; her giriş noktası kendi formatını uydurmasın.
- Yakalanmamış hatalar / reddedilen promise'ler global olarak dinlenir.

## 10. API / Arayüz Tasarımı

- Tutarlı yanıt yapısı (envelope) kullan; başarı ve hata aynı şekle uysun.
- Doğru durum kodları / hata semantiği kullan.
- Kaynak odaklı, tutarlı ve öngörülebilir isimlendirme.
- Arayüzü sürümle; geriye dönük uyumluluğu koru, kırıcı değişiklikleri yönet.
- Liste uçlarında standart sayfalama, filtreleme, sıralama.
- Sözleşmeyi (API dokümantasyonu) güncel tut; değişiklikte birlikte güncellenir.

## 11. Veri Saklama (Veritabanı)

### Şema
- Doğru veri tiplerini kullan (örn. para için ondalık/decimal, asla kayan nokta; tarih için zaman dilimli zaman damgası).
- Bütünlük kısıtlarını (zorunluluk, benzersizlik, ilişki, kontrol) veri katmanında tanımla; yalnızca uygulamaya güvenme.
- Tutarlı isimlendirme ve id stratejisi.

### Migration / Şema Değişikliği
- Tüm şema değişiklikleri versiyonlu migration ile; elle veriye/şemaya dokunma.
- Uygulanmış migration'ı düzenleme; yeni migration ekle.
- Kırıcı değişiklikleri kesintisiz (zero-downtime) için aşamalandır: ekle → dağıt → doldur → zorunlu kıl → eskiyi kaldır.

### Performans
- Sık sorgulanan ve ilişki kolonlarını indeksle; aşırı indekslemeden de kaçın.
- İlişkili veriyi toplu çek; **N+1 sorgudan kaçın**.
- Yalnızca gereken alanları seç.
- Büyük veri setlerinde offset yerine cursor/keyset sayfalama.
- Performans kritik noktalarda sorgu planını incele.
- ORM kullanılıyorsa ürettiği sorguyu görmezden gelme; geliştirmede sorguları görünür kıl.

### Şişme (bloat) ve Büyüme
- Sürekli büyüyen tablolara (log, audit, event, session) retention/arşivleme politikası uygula.
- Çok büyük tabloları gerektiğinde bölümle (partition).
- Soft delete'i dikkatli kullan; sorgu karmaşası ve şişme maliyetini göz önünde tut.

### Bağlantı ve Transaction
- Bağlantıları havuzla (connection pool) yönet; her istekte yeni bağlantı açma. Yüksek eşzamanlılıkta havuz tükenmesine karşı önlem al.
- Çoklu yazma işlemlerini transaction'a sar (atomiklik).
- Transaction'ları kısa tut; içinde dış çağrı veya ağır hesaplama yapma.
- Yarış durumuna (race condition) açık akışlarda uygun kilitleme veya optimistic locking kullan.

## 12. Yan Etki / Dış Kaynak Temizliği

- Bir kayıt dış bir kaynağa referans tutuyorsa (obje deposu / S3 dosyası, cache, arama indeksi, dış servisteki obje), o kayıt **silindiğinde dış kaynağı da sil**. Yetim (orphan) veri bırakma — yetim obje hem maliyet hem güvenlik/yönetim sorunudur.
- Aynı kural **güncellemede** de geçerli: bir dosya/kaynak referansı değişiyorsa, eskisini temizle.
- Bu temizliği her silme çağrısına elle eklemek yerine **tek bir yere** (repository/servis metodu veya entity lifecycle hook'u) hapset; silme tek kapıdan geçsin, kim nereden silerse silsin temizlik otomatik çalışsın.
- **Sıralama:** önce DB değişikliğini commit et, sonra dış kaynağı temizle. Dış silmeyi transaction içinde yapma. Dış silme başarısız olursa yetim kalmaması için retry/temizlik job'ına düşür.
- **S3'e özgü:** Silme idempotenttir (olmayan objeyi silmek hata değildir). Birden çok obje için döngüde tek tek değil toplu silme (`DeleteObjects`) kullan. Bucket'ta **versioning açıksa** normal silme yalnızca delete marker koyar; veri ve maliyeti sürer — eski versiyonları da sil veya bir lifecycle politikasıyla süpür.
- Bir entity'ye silme/güncelleme eklerken bağlı dış kaynağın da ele alındığını doğrulayan bir test yaz (kaydı sil → dış kaynağın gerçekten gittiğini assert et).

## 13. Güvenlik

- Sırlar koda gömülmez, repoya girmez; ortam değişkeninden okunur. Örnek bir env şablonu güncel tutulur.
- Bilinen güvenlik katmanlarını uygula (güvenlik header'ları, rate limiting).
- Şifreleri güçlü bir algoritma ile hash'le; kimlik token'larında güçlü sırlar kullan.
- Enjeksiyon saldırılarına karşı parametreli sorgu / güvenli katman kullan.
- Hassas veri (şifre, token, kart) loglara asla yazılmaz.
- Bağımlılıkları güncel ve bilinen açıklardan arınmış tut.

## 14. Configuration

- Hardcoded değer yok; tüm ayarlar ortamdan gelir.
- Ortam değişkenleri tek bir yerde okunur ve uygulama açılışında doğrulanır; geçersizse uygulama başlamaz.
- Ayarlara dağınık şekilde her dosyadan erişme.

## 15. Logging ve Gözlemlenebilirlik

- Gelişigüzel çıktı (örn. doğrudan konsol) yerine yapılandırılmış (structured) logger.
- Log seviyeleri doğru kullanılır.
- İstek/iz takibi için correlation id.
- Metrikler ve gerekirse dağıtık izleme (tracing); hata izleme entegre edilir.
- Hassas veri loglanmaz.

## 16. Dayanıklılık (Resilience)

- Dış servis çağrılarında timeout + retry (exponential backoff).
- Sağlık/hazırlık (health/readiness) ucu; kritik bağımlılıklar kontrol edilir.
- Graceful shutdown: kapanış sinyalleri yakalanır, açık işler düzgün tamamlanır.
- Kritik işlemlerde (ödeme, sipariş) idempotency.
- Cache eklenirse net invalidation stratejisi ve TTL (cache-aside deseni).

## 17. Test

- Birim ve entegrasyon testlerini ayır; iş mantığı için birim, uçtan uca için entegrasyon.
- Yeni davranış için test yazılır.
- Test dosyaları ilgili kodun yanında, tutarlı isimlendirmeyle.
- Testler bağımsız ve tekrarlanabilir olmalı; gerçek dış servise bağlanma, mock/stub kullan.

## 18. Ortak Fonksiyonlar (utils)

- Ortak yardımcı alanı yalnızca generic, domain bilgisi içermeyen, **yan etkisiz** saf fonksiyonlar içindir.
- İş kuralı içeren hiçbir şeyi buraya koyma; o bir servise/domaine aittir.
- Tek devasa yardımcı dosyası yerine konu bazlı küçük dosyalar.
- Yardımcı fonksiyonlar veriye dokunmaz, log atmaz, dış çağrı yapmaz.

## 19. classes.md & helpers.md (ZORUNLU Kayıt)

- Yeni bir **class** tanımladığında → `classes.md`'ye ekle.
- Yeni bir **helper** tanımladığında → `helpers.md`'ye ekle.
- Mevcut bir class/helper'ı sildiğinde veya yolunu/imzasını değiştirdiğinde **aynı commit içinde** ilgili md dosyasını güncelle.
- Her kayıt için: **ad**, **dosya yolu** (relative link), **kısa kullanım amacı** (1 satır), **public API özeti** (constructor + temel metodlar / fonksiyon imzası).
- Format için `classes.md` ve `helpers.md`'nin kendisindeki örneklere bak.
- **Kapsam:** Yalnızca modüller arası paylaşılan / public API niteliğindeki class ve helper'ları kaydet. Modül-içi private olanları kaydetme.
- **Drift kontrolü:** CI/pre-commit, yeni bir public class/fonksiyon ekleyen ama ilgili md'yi güncellemeyen commit'lerde uyarı versin. Bayat kayıt, hiç kayıt olmamasından daha zararlıdır.
- Mümkün olduğunda bu kaydı bir dokümantasyon aracıyla otomatik üret; manuel kayıt yalnızca otomasyon kurulana kadarki geçici çözümdür.

## 20. Alt Dizin CLAUDE.md Standardı

Bu kurallar projedeki **tüm alt dizin CLAUDE.md dosyaları** için geçerlidir.

- Alt dizin CLAUDE.md'leri yalnızca o dizine **özgü** kuralları içerir; bu kök dosyadaki genel kuralları tekrar etme, onlarla çelişme.
- Kısa tut (hedef: birkaç ekranı geçmesin); uzun anlatım yerine net, emir kipinde direktifler.
- Şu iskeleti kullan:
  1. **Kapsam** — bu kurallar hangi dizin/modül için geçerli.
  2. **Bağlam** — bu modülün ne yaptığı, dikkat edilecek özel durumlar.
  3. **Kurallar** — yalnızca bu modüle özgü maddeler.
  4. **Yapma** (gerekiyorsa) — bu modüle özgü yasaklar.
- Genel bir kuralın bu modülde istisnası varsa, istisnayı ve gerekçesini açıkça yaz.
- Yeni bir alt CLAUDE.md oluştururken bu standarda uy; mevcut birini düzenlerken de standarda çek.

## 21. Tarih/Saat ve i18n

- Her şey UTC saklanır; yalnızca sınırda (kullanıcıya gösterirken) lokalize edilir.
- Kullanıcıya dönen metinler koda gömülü değil, mesaj kataloğunda.

## 22. Standards & Cost Review (ZORUNLU)

Anlamlı bir kod düzenlemesinden (yeni uç/akış/servis veya mevcut mantığın değişmesi) sonra, commit'ten önce **`standards-reviewer` subagent'ını çalıştır** (`.claude/agents/standards-reviewer.md`). Read-only, adversarial bir pass'tir; çıktı **file:line + somut fix + maliyet büyüklük tahmini** içerir. Tek bir vendor'a göre değil, mimarinin liyakatine göre yargılar.

Agent mevcut değilse veya çalıştırılamıyorsa, aynı denetimi aşağıdaki iki eksende elle yap:

1. **Sektör standardı / mimari:** API/arayüz sözleşmesi, idempotency, hata & dayanıklılık, güvenlik, eşzamanlılık (concurrency/locking), sorumluluk ayrımı (katman sınırları), geri-uyumluluk.
2. **Maliyet & performans:** gereksiz sorgu / **N+1**, eksik index / tam tarama, hot spot & kilit çekişmesi (lock contention), taranan/işlenen veri miktarı, gereksiz büyük payload, bağlantı havuzu tükenmesi, önbellek (cache) fırsatı, soğuk başlangıç maliyeti.

Önceliklendirme:
- 🔴 **Critical** (standart ihlali / güvenlik açığı / ciddi maliyet) → commit'ten **önce** çöz.
- 🟡 **Important** → görev olarak takip et, biriktirme.

## 23. Git Kuralları

- Her kod değişikliğinden sonra commit yap
- **`git add -A` KULLANMA** — sadece değiştirdiğin dosyaları `git add <dosya1> <dosya2>` ile ekle
- Commit öncesi `git diff --stat` ile hangi dosyaların değiştiğini kontrol et, görevle ilgisiz dosya varsa ekleme
- Commit mesajı: ne değiştiğini kısaca açıkla (Türkçe)
- Birden fazla dosya değiştiysen tek commit yeterli

## 24. Dependency ve CI/CD

- Lock dosyası commit edilir, elle düzenlenmez.
- Yeni paket eklemeden önce gerekçe; mevcut bir paket işi görüyorsa yenisini ekleme.
- Pre-commit hook ile bozuk kod commit edilmez.
- Merge öncesi lint + test + build geçmek zorunda.

## 25. DO NOT (yapma)

- Kaçış tipi (örn. `any`) kullanma.
- İç/veri modelini doğrudan dış arayüzde dönme.
- Gelişigüzel konsol çıktısı bırakma; yapılandırılmış logger kullan.
- Bağımlılık klasörünü veya lock dosyasını elle düzenleme.
- Uygulanmış migration'ı geriye dönük değiştirme.
- Sırrı koda gömme veya commit etme.
- Hassas veriyi loglama.
- Transaction içinde dış servis çağırma.
- Döngü içinde tek tek sorgu atma (N+1).
- Relative import spagettisi (`../../../..`).
- Gelen girdiyi doğrudan iç modele yazma (mass assignment).
- Dış kaynağa (S3 vb.) referanslı bir kaydı, dış kaynağı temizlemeden silme (yetim obje bırakma).

## UI: içerik genişliği (kalıcı kural)

- Tüm sayfa ana kapsayıcıları **header ile aynı genişlikte** olmalı:
  `mx-auto w-full max-w-7xl px-4`. Yeni sayfalarda varsayılan budur; daha dar
  (`max-w-2xl/3xl/6xl`) kullanma.
- **Hero** alanları **tam genişlik** (edge-to-edge); hero üzerindeki başlık/metin overlay'i
  içeride `mx-auto max-w-7xl px-4` ile hizalanır.
- Tek istisna: `components/site/page-shell.tsx` (`PageShell`, max-w-3xl) yalnızca uzun-metin
  **yasal/bilgi** sayfaları (gizlilik, kvkk, sss vb.) için okunabilirlik amacıyla dardır.
  Blog/mağaza/panel gibi sayfalarda PageShell kullanma; header genişliğini koru.