133 lines
5.5 KiB
Markdown
133 lines
5.5 KiB
Markdown
# 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. |