kolaytercih/AGENTS.md

<!-- BEGIN:nextjs-agent-rules -->
# This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.

# Tarayıcı açma

**Varsayılan: açma.** UI değişikliklerini tarayıcıda/preview'da doğrulamaya çalışma; kullanıcı kendisi kontrol ediyor. Dev sunucusu veya browser paneli açma — sadece kod değişikliğini yap ve ne değiştiğini raporla. Bu kural `yazilimci`, `qa-muhendisi` dışındaki roller ve genel kod işleri için geçerlidir.

**İstisna: `tasarimci` ve UX işi.** Tasarımcı, gerekli gördüğünde önizlemeyi/dev sunucusunu **açabilir**. Bazı tasarım sorunları koddan teşhis edilemez — taşma, üst üste binme, kırılma noktaları, gerçek metin uzunluğuyla oluşan yerleşim, karanlık mod, odak halkası, dokunma hedefi. Bunlarda "koddan çıkarım" yetmez; bakmak gerekir.

Açtığında geçerli olanlar:
- **Gerekçesini yaz:** neyi koddan göremediğin için açtın.
- **Ne gördüğünü yaz**, hangi genişlikte (375 / 768 / 1024 / 1280 px) ne olduğunu tek tek. Ekran görüntüsü alabilirsin.
- İşin bitince **sunucuyu kapat** (`preview_stop`). Disk ve bellek dar olabilir; açık bırakma.
- Tarayıcıda hesap açma, şifre/kart/kimlik girme, ödeme, mesaj gönderme, yayın/post, CAPTCHA çözme, dosya indirme **yine yasak** (PROTOKOL md.5). Çerez bandı çıkarsa reddet. Kullanıcının açık oturumlarına girme.
- Canlı siteye (`kolaytercih.com`) bakmak serbesttir ve çoğu zaman dev sunucusu açmaktan ucuzdur — önce onu dene.

# Push öncesi build zorunlu

Push emri geldiğinde önce lokalde `pnpm build` başarıyla geçmeli; geçmeden asla push etme. Kritik detay: çalışma ağacı kirliyken build, commit'lenmemiş dosyaları da gördüğü için CI'da kırılacak bir commit'i yakalayamayabilir. Bu yüzden build'i **push edilecek commit'in kendisi** üzerinde doğrula (ör. geçici `git worktree add <dir> HEAD` + `node_modules` symlink'i ile). Ayrıca kısmi commit atarken değişikliğin bağımlılık kapanışını kontrol et — bir dosyanın kullandığı prop/export başka bir commit'lenmemiş dosyadan geliyorsa onları da aynı commit'e dahil et.

# Badge/eyebrow rozetleri: tek kaynak SectionEyebrow

Site genelindeki tüm badge/rozet/eyebrow elemanları ana sayfadaki section başlıklarının üstünde duran rozetle birebir aynı olmalı. Kanonik bileşen `src/components/pixel-decor.tsx` içindeki `SectionEyebrow`dur (piksel imzalı `PixelMark` ikonu + `rounded-full border border-slate-200 bg-white px-3.5 py-1.5 font-bricolage text-xs font-semibold text-primary`; metin büyük-küçük harfli yazılır — uppercase yok). Yeni bir badge/eyebrow gerektiğinde `SectionEyebrow` kullan (`className` prop'u kenar boşluğu için var); `@/components/ui/badge`'deki `Badge` ile ya da elle yazılmış pill span'lerle yeni badge tasarlama. İnteraktif chip/buton pill'leri (filtre çipleri, nav butonları) bu kuralın dışındadır.

# UI tutarlılığı: ortak elemanlar tek kaynaktan

Modallar arası ortak elemanlar (kapatma çarpısı, başlık düzeni vb.) görsel olarak birebir aynı olmalı. Kapatma çarpısının kanonik stili `src/components/ui/dialog.tsx` içindeki `DialogContent` varsayılan butonudur (yuvarlak, `size-9`, `border border-slate-200`, `size-4` X ikonu, hover'da `bg-slate-100`, `active:scale-[0.96]`). Yeni bir modal eklerken bu varsayılanı kullan; özel yerleşim gerekiyorsa (ör. katalog-arama'da input satırının içindeki buton) `showCloseButton={false}` ver ama **aynı class setini** kopyala — farklı boyut/renk/varyantta yeni bir çarpı tasarlama. Aynı prensip diğer tekrarlanan UI parçaları için de geçerli: bir eleman iki yerde görünüyorsa stilini tek kaynaktan al veya birebir eşleştir.

# CTA butonlarında ikon: yıldız yok, sağ ok metnin sonunda

Funnel CTA butonlarında ("Listemi oluştur", "Tercihlerimi belirle", giriş/ödeme CTA'ları vb.) `Sparkles` (yıldız) ikonu kullanılmaz. Kanonik desen: buton metni önce gelir, sonunda `<ArrowRight className="size-4" aria-hidden />` durur. Yeni bir CTA butonu eklerken bu deseni uygula; metnin başına ikon koyma. Dekoratif `Sparkles` kullanımları (boş durum başlık ikonları, bilgi satırları) bu kuralın dışındadır — kural yalnızca aksiyon butonları/CTA linkleri içindir.

# Meraklısına'daki mermaid şeması mimariyle senkron kalmalı

`/meraklisina` sayfasındaki sihirbaz akış şeması (`src/features/pazarlama/components/huni-semasi.tsx` içindeki `SEMA` sabiti) ürünün gerçek davranışının belgesidir, dekor değildir. Sihirbaz/listeleme mimarisinde davranış değiştiren her değişiklikte bu şema da aynı PR/commit içinde güncellenmeli: sihirbaz adımlarının sayısı-sırası-içeriği (alan → il → devlet/vakıf), aday havuzu kuralları, 24'lük liste iskeleti (hayal/dengeli/güvenli dağılımı — üçüncü dilimin kullanıcıya görünen adı "Güvenli"dir; iç anahtar, tip, DB değeri, mermaid `classDef` ve analitik değeri `garanti` olarak kalır, görünen etiketin tek kaynağı `src/lib/risk.ts` içindeki `DILIM_ETIKET`), havuz 24'ün altına düşünce filtre gevşetme sırası ve yapay zekânın havuz-dışına-çıkamama kuralı. Şemayı güncellerken çevresindeki unsurları da eşitle: bölümdeki anlatım metni (`src/features/pazarlama/components/meraklisina-icerik.tsx`, 4. bölüm), kabın `aria-label`'ı ve figcaption. Şema öğrenci diliyle kalmalı (SQL/prompt/teknik detay yok) ve ürünün risk renk dilini korumalı — kırmızı/sarı/yeşil her zaman metin etiketiyle birlikte, renk tek başına anlam taşımaz.
<!-- END:nextjs-agent-rules -->

# Yayın sonrası arama motoru bildirimi (zorunlu)

Yeni ya da güncellenmiş bir rehber yazısı **canlıya çıktıktan sonra** şu iki adım yapılır, atlanmaz:

1. **Search Console'da URL denetimi.** Her yeni yazının tam adresi (`https://kolaytercih.com/rehber/<slug>`) Search Console'un URL denetleme kutusuna girilir; "URL Google'da yok" diyorsa **"Dizine eklenmeyi iste"** tıklanır. Google mülk başına günde sınırlı sayıda (~10-13) istek kabul eder — kota dolduğunda ısrar edilmez, kalanlar ertesi güne bırakılır ve nereye kalındığı not edilir.
2. **`sitemap.xml` yeniden gönderilir.** Search Console → Site Haritaları → `https://kolaytercih.com/sitemap.xml` tekrar gönderilir; "Başarılı" durumu ve keşfedilen URL sayısı not edilir. Aynı sitemap Bing Webmaster Tools'a da gönderilir.

**Sıra kuralı — ihlal edilmez:** URL denetimi yalnızca **canlıda 200 dönen** adres için yapılır. Commit'lenmemiş, push edilmemiş ya da deploy olmamış bir yazının adresi Search Console'a verilmez — 404 gönderilmiş olur ve günlük kota boşa yanar. Yazı yazıldığında sıra şudur: yaz → Bilal commit'ler ve yayınlar → canlıda 200 doğrulanır (`curl -s -o /dev/null -w "%{http_code}"`) → **sitemap'te görünür doğrulanır (aşağı)** → ancak o zaman Search Console.

**Sitemap ön kontrolü — bildirimden önce, her adres için tek komut.** 22 Eylül 2026'da `kyk-burs-mu-kredi-mi` bildirildiğinde Search Console "Yönlendiren site haritası algılanmadı" dedi. Bu yüzden bildirimden önce adresin **bizim sitemap'imizde gerçekten olduğu** doğrulanır:

```sh
curl -s https://kolaytercih.com/sitemap.xml | grep -c "/rehber/<slug><"
```

Desendeki kapanış `<` şart: onsuz bir slug, kendisiyle başlayan daha uzun bir slug'ı da sayar ve sayım yanlış 1 döner. Sonuç **1 değilse o adres bildirilmez** — sorun deploy tarafındadır (yazı dosyası canlı derlemeye girmemiş; `src/app/sitemap.ts` slug listesini `content/rehber`'den üretir), önce o çözülür. 0 iken yapılan bildirim kotadan bir istek yakar. Toplu yayında hepsi tek seferde sayılır:

```sh
for s in <slug1> <slug2> …; do printf "%s -> " "$s"; curl -s https://kolaytercih.com/sitemap.xml | grep -c "/rehber/$s<"; done
```

**Sırayı bozma:** sitemap **önce** yeniden gönderilir, URL denetimleri **sonra** yapılır. Sayım 1 çıktığı hâlde Search Console yine "yönlendiren site haritası algılanmadı" diyorsa bu bizim değil Google'ın okuma gecikmesidir — **istek tekrarlanmaz, kota yakılmaz**; bir hafta sonra bakılır.

**Kota sayacı — her bildirim gününde tutulur.** Günlük kota mülk başına ~10-13 istek. `docs/ekip/YAYIN-KUYRUGU.md` içindeki **"Kota kullanımı"** tablosuna o günün satırı yazılır (`22 Eyl: 6/13` biçiminde) ve her istekten sonra güncellenir; **13'e varınca o gün durulur**, kalan adresler ertesi güne yazılır. Başarısız/boşa giden istek de sayaca yazılır — kotadan düşen odur, sonuç değil.

**Mülk ve hesap — işe başlamadan önce.** Mülk **`sc-domain:kolaytercih.com`** ve Bilal'in **ikinci** Google hesabında (Search Console adresinde `/u/1/`); birinci hesap (`bilalgursen777@gmail.com`) mülkü görmüyor, "Maalesef bu mülke erişiminiz yok" diyor. Bu yüzden: (a) işe başlarken doğru hesapta olunduğu **görülür** — adres çubuğunda `/u/1/` ve üstte mülk adı; (b) Search Console'un arama kutusu **dar pencerede kendini kapatıyor**: pencere genişletilir → büyüteç düğmesine basılır → kutunun açıldığı **görülür** → ancak o zaman yazılır. Açılmamış kutuya yazmak ve kutuya doğrudan değer basmak (`form_input`) yasak; 22 Eylül'de kaybedilen 2 istek böyle gitti (biri tekrar istek, biri iki adresin birbirine yapışmasıyla oluşan bozuk adres). Kalıcı çözüm Bilal'de: birinci hesabı mülke **tam yetkili kullanıcı** olarak eklemek — hesap değiştirme penceresiyle uğraşmak bitince bu hata sınıfı da biter.

**Yetki:** Bu adımlar Bilal'in Google oturumunu kullanır. Ajan bu işi ancak Bilal açıkça söylediğinde ve kendi tarayıcısı üzerinden yapar; hesap açma, şifre girme, başka Google hizmetine geçme yasaktır. "Tarayıcı açma" kuralı (UI'ı önizlemede doğrulama yasağı) bu işi kapsamaz — o kural dev sunucusu ve arayüz doğrulaması içindir.

**Kuyruk:** Henüz yayımlanmamış ama yazılmış yazıların adresleri `docs/ekip/YAYIN-KUYRUGU.md` dosyasında tutulur; yayın sonrası bu listeden tek tek düşülür.

# Yıkıcı git komutları yasak (22 Eyl 2026 gece vardiyasında öğrenildi)

Ajanlar şu komutları **hiçbir koşulda** çalıştırmaz: `git reset --hard`, `git checkout -- <dosya>`, `git restore <dosya>`, `git clean`, `git stash`.

Sebebi: bu komutların hepsi **çalışma ağacındaki commit'lenmemiş değişiklikleri** siler ve bu değişiklikler çoğu zaman ajanın kendisine ait değildir — Bilal'in ya da paralel çalışan başka bir oturumun işidir. 22 Eylül gecesi bir kod ajanı kendi dalında commit'ini düzeltmek için `reset` koştu ve üç dosyada başkasının işini yok etti: `docs/ekip/KARARLAR.md` (iki karar kaydı), `docs/ekip/BACKLOG.md`, `content/rehber/veliler-icin-tercih-rehberi.md`. Commit'lenmemiş içerik git nesne veritabanına hiç girmediği için `git fsck` ile kurtarılamaz; o gece kurtarma yalnızca metin başka bir ajanın raporunda saklandığı için mümkün oldu.

Yerine ne yapılır:
- Son commit'i düzeltmek: `git commit --amend` (reset gerekmez).
- Bir commit'i geri almak: `git revert <sha>` (yeni commit üretir, çalışma ağacına dokunmaz).
- Kendi yazdığın bir dosyayı geri almak: dosyayı elle düzenle, `checkout --` kullanma.

Kural ihlal edilmişse: ne kaybedildiğini `git reflog` + `git diff <reset öncesi sha>` ile tespit et, **derhal raporla**, kendi başına yeniden oluşturmaya çalışmadan önce kaybın kapsamını yaz.