first commit

SKILL.MD

@@ -0,0 +1,133 @@
+# AI Project Skills (MUST APPLY)
+
+Bu doküman, projeyi geliştirirken AI agent’ın (Claude) UYGULAMAK ZORUNDA olduğu kuralları tanımlar.
+Buradaki her madde “MUST” seviyesindedir. İstisna yoktur.
+Bir değişiklik bu kuralları etkiliyorsa aynı değişiklikte dokümanlar da güncellenmelidir.
+
+---
+
+## 1) Docker & Compose Standartları (MUST)
+
+- Projede Docker altyapısı kullanılacak.
+- İki compose dosyası olacak:
+  - `docker-compose.dev.yml` (dev)
+  - `docker-compose.yml` (prod)
+- Dev ortamında yapılan değişiklikler canlı yansıyacak (hot reload / watch).
+- Proje DEV ortamında **tek komut** ile ayağa kalkmalıdır:
+  - `docker compose -f docker-compose.dev.yml up --build`
+- Bu komut dışında:
+  - manuel migrate/seed/kurulum komutu çalıştırmak
+  - ekstra adım istemek
+  - “önce şunu yap sonra bunu yap” tarzı süreçler
+  **KABUL EDİLMEZ.**
+- Servisler için healthcheck tanımlanacak (db/redis/app) ve bağımlılıklar healthcheck üzerinden yönetilecek.
+- Docker image’ları mümkünse multi-stage build ile üretilecek; prod image minimal olacak; container non-root user ile çalışacak.
+
+---
+
+## 2) Ortam Değişkenleri (MUST)
+
+- Ortam değişkenleri `.env` üzerinden tanımlanacak.
+- Repo içinde `.env` bulunmayacak (gitignore).
+- `.env.example` dosyası oluşturulacak.
+- `.env`yi etkileyen her güncellemede `.env.example` da aynı PR/commit içinde güncellenecek.
+- Compose dosyalarında:
+  - `.env` dosyası okunacak ve değişkenler servislere aktarılacak.
+  - `.env` içinde olmayan bir değişken kullanılıyorsa compose içinde DEFAULT değer verilecek (örn. `${VAR:-default}`).
+- Uygulama ayağa kalkarken env doğrulaması yapılacak:
+  - Eksik değişken varsa fail-fast (startup’ta hata).
+  - Tip doğrulaması yapılacak (string/number/boolean).
+  - Öneri: `zod` / `envalid` benzeri bir yaklaşım.
+
+---
+
+## 3) Backend Teknoloji Yığını (Koşullu MUST)
+
+Backend kullanılacaksa aşağıdakiler ZORUNLUDUR:
+- Node.js
+- Socket.IO
+- Redis
+- PostgreSQL
+
+Backend için ek zorunluluklar:
+- `/health` ve `/ready` endpointleri olacak.
+- Structured logging (JSON) kullanılacak, log seviyeleri (debug/info/warn/error) standardize edilecek.
+- Hata yanıt formatı tutarlı olacak (error code + message + details).
+
+---
+
+## 4) PostgreSQL Şema Yönetimi (MUST) — Tek Komut Kuralı ile Uyumlu
+
+- PostgreSQL kullanılıyorsa şema yönetimi **deterministic** olmalıdır:
+  - Temiz kurulumda ve güncellemelerde aynı sonuca güvenilir şekilde ulaşmalıdır.
+- Migration yaklaşımı kullanılacaksa:
+  - Migration’lar **backend container startup adımının parçası** olarak otomatik çalıştırılacaktır.
+  - Kullanıcıdan manuel olarak `migrate/seed` komutu çalıştırması istenmeyecektir.
+  - Backend, DB hazır olana kadar bekleyecek (healthcheck + retry/backoff) ve ardından:
+    1) migration’ı çalıştıracak
+    2) uygulamayı başlatacaktır
+- DB migration aracı seçilebilir (Prisma/Knex/TypeORM/Flyway vb.) ancak seçilen araç:
+  - README’de ve `/doc/ops.md` içinde açıkça belirtilecek
+  - dev/prod için aynı “tek komut” felsefesini bozmayacak şekilde entegre edilecektir.
+- Opsiyonel seed gerekiyorsa (ör. admin user vb.):
+  - seed işlemi de otomatik olacak
+  - yine manuel komut gerektirmeyecek.
+
+---
+
+## 5) Frontend Teknoloji Yığını (Koşullu MUST)
+
+Frontend kullanılacaksa aşağıdakiler ZORUNLUDUR:
+- React
+- React Router
+- Font Awesome
+
+Frontend için ek zorunluluklar:
+- Socket ile gelen canlı veriler ve state yönetimi README’de ve `/doc/socket-events.md` içinde açıklanacak.
+- Uygulama konfigürasyonu (API base url, socket url vb.) `.env` üzerinden yönetilecek.
+
+---
+
+## 6) Dokümantasyon Zorunlulukları (MUST)
+
+- Projedeki tüm dökümanlar `/doc` dizini altında olacak.
+- Proje için mutlaka bir “özet dokümanı” hazırlanacak:
+  - `/doc/overview.md`
+  - İçerik: Projenin ne yaptığı, neden oluşturulduğu, nasıl ilerlediği, önemli kararlar, güncellemeler.
+  - Projeye yapılan her güncellemede bu dosya gerektiği kadar güncellenecek.
+- API ve Socket sözleşmeleri dokümante edilecek:
+  - REST varsa: `/doc/api.md` (OpenAPI/Swagger referansı dahil)
+  - Socket varsa: `/doc/socket-events.md` (event adı, yön, payload şeması, örnek)
+- Operasyon / çalıştırma notları: `/doc/ops.md` (build, run, dev/prod, troubleshooting).
+- Mimari kararlar için `/doc/decisions/ADR-XXXX.md` formatı kullanılacak (kısa ve net).
+
+---
+
+## 7) README Standartları (MUST)
+
+- README her zaman güncel kalacak.
+- Projeye ait frontend ve backend bilgileri detaylı anlatılacak:
+  - Kurulum
+  - Dev/Prod çalıştırma
+  - Env değişkenleri
+  - Endpointlerin ne iş yaptığı
+  - Socket ile iletilen canlı veriler (event listesi)
+  - Migration/seed yaklaşımı (varsa) ve “tek komut” akışının açıklaması
+- README içinde anlatım Font Awesome ikonları ile zenginleştirilecek.
+- README, `/doc` içindeki ana dokümanlara link verecek.
+
+---
+
+## 8) Değişiklik Kuralı (MUST)
+
+- Bir değişiklik:
+  - `.env` / `.env.example`i etkiliyorsa ikisi birlikte güncellenecek.
+  - API/Socket sözleşmesini etkiliyorsa `/doc/api.md` veya `/doc/socket-events.md` güncellenecek.
+  - Çalıştırma şeklini (docker/komut/akış) etkiliyorsa README ve `/doc/ops.md` güncellenecek.
+  - DB şemasını etkiliyorsa migration/init/ops dokümanları aynı değişiklikte güncellenecek.
+- Bu güncellemeler yapılmadan değişiklik “tamamlandı” sayılmaz.
+
+---
+
+## 9) İletişim Kuralı (MUST)
+- Proje oluşturulurken ve geliştirilirken tüm iletişim Türkçe yapılacak.