Bu içeriği projenin CLAUDE.md / AGENTS.md / .cursorrules dosyasına yapıştır. AI araçları bu kuralları proje konteksti olarak otomatik okur.

---

TypeScript Çalışma Kuralları

tsconfig baseline

tsconfig.json içinde şu ayarlar açık olur:

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noFallthroughCasesInSwitch": true,
    "noPropertyAccessFromIndexSignature": true,
    "exactOptionalPropertyTypes": true,
    "useUnknownInCatchVariables": true,
    "isolatedModules": true,
    "skipLibCheck": true
  }
}

Gevşetme (örn. noUncheckedIndexedAccess: false) sadece açıklanan bir migration dönemi için — inline // TODO(typescript-strict): ... notu ile.

Tip disiplini

• any yasaktır. Emin değilsen unknown kullan ve narrow et. any gördüğün bir dosya = refactor fırsatı.

• as cast sadece:

  • Şema doğrulama (zod, valibot) sonrası
  • External boundary'de (JSON response, DOM event, env var)
  • as const ve as unknown as X (son çare double cast, yorum gerekir)

  İç kodda cast görürsen refactor et.

• Discriminated union > optional + if kontrol. "Bu alan şimdi var mı acaba" sorusunu kod okumakla değil tiple çöz:

  // ❌
  type Result = { ok: boolean; value?: User; error?: string };
  
  // ✅
  type Result =
    | { ok: true; value: User }
    | { ok: false; error: string };
  

• Public API'lerde dönüş tipi explicit. Exported fonksiyonlar, route handler'lar, component prop'lar. Inline helper'larda inference kabul.

• Generic constraint'leri gerçekten kısıtlayacak şekilde yaz — <T> yerine <T extends { id: string }> ihtiyaç olduğunda.

Null / undefined tutarlılığı

• Projede biri seçilir — genellikle undefined. | null | undefined birlikte nadiren. "Yok"u iki farklı şekilde ifade etme.
• API response parse'ında nullability normalize edilir (zod .nullable().transform(x => x ?? undefined)).
• Non-null assertion ! yasaktır. Sebep varsa yorum ve tercih sırasıyla: type guard → early return → ?? throw.
• == ve != yasaktır, ===/!== kullan. Tek istisna: x == null (null + undefined check için) — projede karar verilip tutarlı kullanılır.

Yapı & dosya organizasyonu

• export default yasak — Next.js'in dayattığı yerler hariç (page.tsx, layout.tsx, route.ts, middleware.ts).
  • Sebep: named export refactor / rename'de güvenli, barrel export anlamlı.
• Hot file: 300 satırı geçerse parçala. Tek bir dosyada 5+ component yok.
• Barrel export (index.ts) sadece public API için. İç modül ağacı barrel'lanmaz (bundle size + import döngüsü riski).
• Klasör yapısı pragmatik: feature-based > type-based. components/UserCard/ > components/ + hooks/ + types/.
• Path alias @/ proje köküne. Göreli path ../../ üç seviyeyi geçiyorsa alias'a geç.

Naming

• Types / interfaces: PascalCase — User, OrderItem
• Types vs interfaces: default type. interface yalnızca declaration merging ya da extend pattern'i gerektiğinde.
• Props: FooProps ekstansiyonu — UserCardProps
• Variables / functions: camelCase
• Constants: SCREAMING_SNAKE_CASE yalnızca gerçekten compile-time constant için — hepsi değil.
• Boolean'lar: is, has, can, should prefix'li — isLoading, hasAccess.
• Event handler'lar: handleX veya onX — projede biri seçilir.

React / JSX kuralları (React kullanıyorsanız)

• React.FC / FunctionComponent kullanma. function MyComponent(props: Props) { ... } yaz.
• Props spreading: <Comp {...props} /> sadece known-safe prop'lar için. Arbitrary spread = tip kaybı.
• key={index} yasak (stable ID yoksa slugify(title) veya uuidv5).
• dangerouslySetInnerHTML yorumlu, XSS kontrol edilmiş şekilde.

Paket ekleme kriterleri

Yeni paket eklemeden önce:

1. Stdlib / framework built-in aynı işi yapıyor mu?
2. Mevcut paket aynı işi yapıyor mu? (e.g. date-fns varken moment ekleme)
3. Son 18 ayda maintain edilmiş mi?
4. Bundle size < 20KB gzip mi? Değilse gerekçe yaz.
5. Security advisory var mı?

Package.json'a eklenen her bağımlılık PR description'da gerekçelendirilir.

Testler

• Tip testi ≠ runtime testi. expectTypeOf (vitest) / tsd ile tip testi ayrıdır.
• Mock'lar yalan söyler. Boundary'de (HTTP, DB) mock kabul; iç kütüphanelerde mocklama, gerçeğini kullan.
• Snapshot testi sadece complex stable output için — UI snapshot'ı genelde gürültü.
• Test isimleri cümle formatında: "süresi geçmiş token reject edilir".
• Her bug fix bir regression test ile gelir.

Performans pragmatiği

• Array.prototype.reduce okunaklı olmadıkça for-of kullan. Reduce her durumda doğru araç değil.
• Derin kopya (JSON.parse(JSON.stringify(...))) sadece küçük POJO için. Büyük yapılar için structuredClone, Immer veya structural sharing.
• Memoization gerçekten gerekliyse. useMemo / useCallback her yerde ≠ performans, gürültü.
• Bundle impact gözet: lodash yerine lodash-es/... veya native.

Error handling

• Throw edilen her şey Error instance'ı olsun. throw "message" yasak.
• Custom error class'ları belirli kategoriler için: ValidationError, NotFoundError, AuthError.
• try/catch ile yutma yasak — ya handle et ya yukarı fırlat. console.error(e) + return null anti-pattern.
• Async'te Promise.all başarısızlığı için Promise.allSettled düşünülür.

Logging

• console.log prod kodunda yasak. Logger (pino/winston) veya console.log yerine debug kütüphanesi.
• Log seviyesi: debug, info, warn, error. Seviye bilinçli seçilir.
• Structured log: serbest string değil { event, ...context }.

API ve veri sınırları

• Client'tan gelen JSON her zaman zod/valibot ile parse edilir. as Response yasak.
• Dış API response'u da schema ile parse — dış servis kontratı değişirse anlarız.
• Environment variable'lar start-up'ta zod ile validate: eksik env → fast fail.

Commit & PR

• Conventional Commits + "neden". "what"ı diff söylüyor, mesaj "why" söyler.
• 72 karakter max başlık. Imperative mood. Nokta yok.
• Her PR kendi başına test edilebilir. Scope = 1 niyet.

Yasak listesi (özet)

• any tipi
• as X içeride (boundary dışı)
• Non-null assertion !
• == / !=
• export default (Next.js exception dışı)
• throw "string" — Error olmalı
• console.log prod'da
• Math.random() / Date.now() test içinde (deterministik olmalı)
• ts-ignore / ts-expect-error yorumsuz
• 300+ satır dosya
• Barrel dışından geniş re-export