kolaytercih/AGENTS.md

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.

Görsel dilin tek kaynağı: docs/tasarim/DESIGN.md

UI'a dokunan her iş (yeni ekran, bileşen, kart, modal, buton, form; mevcut arayüz değişikliği) önce docs/tasarim/DESIGN.md okunarak yapılır; renk, yazı tipi, köşe, gölge, boşluk ve tek kaynak bileşenlerin sınıf dizileri oradan birebir alınır, "yaklaşık aynısı" yazılmaz. Aşağıdaki rozet/çarpı/CTA kuralları o belgenin özetidir. Genel tasarım katalogları (ui-ux-pro-max gibi "50 stil, 97 palet" kütüphaneleri) bu projede kullanılmaz; yön zaten belli. İş bitmeden pnpm tasarim:denetim sıfır hata vermeli (pnpm lint bunu da koşar); betik scripts/tasarim-denetim.ts, kural eklerken DESIGN.md'deki bölüm numarasına atıf yap.

Karanlık mod: token'la çalışır, dark: yazılmaz

Sitede açık / koyu / sistem teması var (DESIGN.md §2.3). Karanlık mod src/app/globals.css içindeki .dark bloğunda palet token'ları çevrilerek çalışır (slate ölçeği ters döner, renkli açık zeminler koyu tona iner); bileşenlere dark: sınıfı yazılmaz. Yeni UI yazarken: yüzey zemini bg-card'dır (bg-white koyu temada da beyaz kalır — yalnız logo karosu gibi gerçekten beyaz kalması gereken yerde); koyu hap (bg-slate-900) yazısını text-slate-50 ile alır; SVG/satır içi stilde sabit renk yerine var(--card), var(--color-slate-200) gibi değişken kullanılır; koyu vurgu yüzeyi (bg-slate-950) kt-koyu-yuzey sınıfını taşır. pnpm tasarim:denetim bunları yuzey-beyaz, koyu-hap-beyaz-yazi ve dark-sinif kurallarıyla yakalar.

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 SectionEyebrowdur (piksel imzalı PixelMark ikonu + inline-flex items-center gap-2 rounded-full border border-slate-200 bg-card px-3.5 py-1.5 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.

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:

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:

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.