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.
.envyi 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.examplei 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.

5.5 KiB Raw Permalink Blame History Unescape Escape