Pagespeed plan

PageSpeed Insights Denetim + Plan

Bir URL'yi Google PageSpeed Insights API'siyle (Lighthouse motoru) test eder ve PSI sayfasinda gorunen her seyi (firsatlar + tanilar + yeni "Insights" denetimleri + teknolojiye ozel oneriler) onceliklendirilmis bir eylem planina cevirir. SEO / teknik / erisilebilirlik derinligi yerlesiktir (references/ dosyalari); claude-seo kurulu OLMASA da plan tam yazilir. claude-seo kuruluysa opsiyonel ekstra derinlik icin devredilir.

Ne zaman kullanilir

Kullanici bir sitenin/URL'nin hizini, Core Web Vitals'ini, SEO/erisilebilirlik/best-practices durumunu olcmek ve ne yapilmasi gerektigine dair plan istediginde.

Gereksinimler

• Python 3 (yalnizca standart kutuphane; pip install gerekmez).
• Internet erisimi (googleapis.com'a).
• claude-seo GEREKMEZ. SEO/teknik/erisilebilirlik derinligi references/ altinda yerlesiktir. claude-seo kuruluysa opsiyonel devir yapilir; degilse plan yine tam yazilir.
• Opsiyonel PSI_API_KEY ortam degiskeni. Anahtarsiz da calisir ama Google dusuk hiz limiti uygular; medyan-of-3 birden fazla istek attigi icin anahtar onerilir. Ucretsiz anahtar: Google Cloud Console > "PageSpeed Insights API"'yi etkinlestir > Credentials > API key.

Adimlar

1. Kullanicidan URL'yi al. Strateji belirtmediyse --strategy both (mobil + masaustu); mobil skor genelde onceliklidir.
2. Bu SKILL.md ile ayni dizindeki betigi calistir (varsayilan 3 kosu, medyan alinir):

   python3 scripts/psi_audit.py <URL> --strategy both --runs 3 --locale tr --out psi_veri.json
   

   Anahtar varsa: PSI_API_KEY=... python3 scripts/psi_audit.py <URL> ... Hiz limiti/kota (429) olursa: --runs 1, PSI_API_KEY ekle, ya da PSI'siz teshise gec (bkz. "Derin teshis" #5). both+--runs 3 = 6 istek; anahtarsiz gunluk limit dusuktur.
3. Betik STDOUT'a (ve --out ile dosyaya) tam kapsamli bir ozet JSON basar:
   • results.<strateji>.categories: kategori skorlari (0-100) + runs (kosu basina ham skor).
   • labMetrics: FCP, LCP, TBT, CLS, SpeedIndex, TTI (medyan).
   • fieldData + fieldOverall: gercek kullanici (CrUX) verisi (varsa).
   • labVsFieldGaps: lab ile saha celiskileri.
   • counts: kategori basina toplam / duzeltilecek / gecti sayilari.
   • auditsByCategory: her kategoride PSI'de gorunen TUM denetimler — firsatlar, tanilar (cache politikasi, byte agirligi, DOM vb.) ve yeni insights (or. resim teslimi). Her denetimde: passed, score, group/groupTitle, display, savingsMs, savingsBytes, weight, description (duzeltme rehberi/ONERI) ve passed=false ise details: PSI sayfasindaki SOMUT KANIT — hangi element (selector/snippet), hangi deger (kontrast orani, tap-target boyutu, alt'sizgorsel vb.) ve hedef. Kontrast/buton boyutu/alt gibi bulgulari somutlastirir. Cok kalemliyse details.truncated kalan sayisini verir.
   • opportunities: kazanci (savingsMs) olan denetimler, kazanca gore sirali (oncelik icin).
   • thirdParties: en cok engelleyen ucuncu taraf servisler.
   • resourceSummary: kaynak turune gore istek + boyut.
   • largestResources: en agir tekil kaynaklar (transferSize'a gore). Tur-toplaminin gizledigi sisman tek dosyayi (cogu zaman logo/header ikonu) yuzeye cikarir — bunu daima gozden gecir.
   • stackPacks: teknolojiye ozel oneriler (WordPress, WooCommerce, React vb.).
   • screenshots (yalniz --screenshots ile): kaydedilen ekran goruntusu/filmstrip dosya yollari.
   • geo (yalniz --geo ile): robots.txt AI-crawler kurallari + llms.txt var/yok.
   • Cok-URL modu (birden cok URL veya --sitemap): tum cikti {"pages": {url: <ustteki bicim>}} sarilir.
   • warnings / errors: kismi/tam basarisizlik nedeni.
4. SEO / teknik / erisilebilirlik derinligi icin references/ dosyalarini kullan (asagidaki bolum). claude-seo kuruluysa opsiyonel olarak ek derinlik icin cagir.
5. Iki kaynagi birlestirip asagidaki formatta tek bir plan yaz. .md dosyasina kaydet (or. <alanadi>-pagespeed-plani.md) ve sohbette kisa ozet goster.

TAMLIK KURALI (onemli)

Plan, PSI'de gorunen hicbir bulguyu atlamamali:

• auditsByCategory'deki passed=false olan HER denetim plana girsin — grup grup (or. "Firsatlar", "Tanilar", "Insights") baslikla; counts.duzeltilecek ile sayisi tutmali.
• Her maddede denetimin adi + display degeri + varsa savingsMs + description'dan cikan somut ONERI (ne yapilacak) yer alsin. Oneri olmadan bulgu yazma — bulgu + duzeltme birlikte.
• details varsa SOMUT KANITI yaz: hangi element + mevcut deger → hedef. Ornek: kontrast ".btn-x 2.1:1 → 4.5:1"; dokunma hedefi "a.nav 24×24 → 48×48"; alt "img.logo alt eksik". Genel oneri + o sayfaya ozel kanit birlikte olmali (korlemesine "kontrasti duzelt" yetmez).
• stackPacks'teki teknolojiye ozel onerileri ilgili denetimin altina entegre et (or. cache icin "WordPress'te su onbellek eklentisi").
• Gecmis (passed=true) denetimler istege bagli "Gecen denetimler" altinda kisaca ozetlenebilir.
• Kullanici "ozet" isterse ilk 5-10 onceligi one cikar ama tam listeyi de plana ekle.

SEO / Teknik / Erisilebilirlik derinligi (yerlesik)

Bu derinlik references/ altinda yerlesiktir; claude-seo olmadan da tam plan yazilir:

1. PSI'deki auditsByCategory.seo + accessibility + best-practices bulgularini (her birinin description onerisi ve details kaniti ile) topla.
2. Su yerlesik referanslarla derinlestir:
   • references/teknik-seo-derin.md — SEO/teknik denetimler (crawlability, indexability, guvenlik, URL, mobil/dokunma hedefi, JS render) + PSI audit id eslemesi.
   • references/core-web-vitals-derin.md — LCP alt-parcalari, INP/CLS kirilimi, esikler, saha-lab.
   • references/seo-performans-ajan.md — performans teshis yontemi + darbogaz katalogu.
   • references/schema-ve-erisilebilirlik.md — JSON-LD sablonlari + WCAG/a11y denetim eslemesi (kontrast/tap-target/alt icin somut yazim tablosu).
3. Ciktiyi planin "SEO / Projeye Ozel Aksiyonlar" ve "Erisilebilirlik & En Iyi Uygulamalar" bolumlerine entegre et (cakisanlari tekille).
4. Opsiyonel: claude-seo KURULUYSA, URL + bu bulgulari baglam vererek calistir ve ciktisini ustteki derinlige EK olarak entegre et. Kurulu degilse bu adim atlanir (uyari/eksik notu YOK — yerlesik referanslar zaten yeterli).

Ek modlar (CI, coklu sayfa, diff, HTML rapor, GEO)

Ayni psi_audit.py + iki kucuk yardimci betik; hepsi stdlib (pip yok), PSI JSON'una karsi calisir.

• Coklu sayfa / sitemap: psi_audit.py <url1> <url2> ... ya da --sitemap <sitemap.xml> --max-pages N (varsayilan 10). Cikti pages altinda toplanir; kota icin coklu modda --runs varsayilani 1.
• robots.txt -> sitemap otomatik kesif: --from-robots <site-url> → sitenin /robots.txt'indeki Sitemap: satirlarini bulur, yoksa /sitemap.xml'e duser; bulunan sayfalari --max-pages ile tarar.
• Ekran goruntusu / filmstrip: --screenshots <klasor> → Lighthouse'un final + filmstrip gorsellerini yazar (ekstra istek YOK). Plana/HTML rapora gorsel kanit ekler.
• GEO / llms.txt: --geo → robots.txt'te AI-crawler (GPTBot/ClaudeBot/Google-Extended...) durumu + llms.txt varligi. Derinlik: references/teknik-seo-derin.md (AI-crawler tablosu).
• CI butce kapisi: --budget "perf=90,lcp=2500,cls=0.1,seo=90,a11y=90" → esik ihlalinde exit 1 + BUTCE ozeti (yapiyi kirmizi yapmak icin). Kategori: skor>=esik; metrik: deger<=esik (ms/CLS).
• Oncesi/sonrasi diff: python3 scripts/psi_diff.py eski.json yeni.json [--fail-on-regression] → kategori/CWV/denetim deltalari; regresyonda exit 1.
• Trend gecmisi: --history <dosya.jsonl> → her kosuyu kompakt bir JSONL kaydina ekler (skor + CWV). python3 scripts/psi_diff.py --trend <dosya.jsonl> → zaman-sirali skor/CWV trend tablosu (Markdown).
• Deterministik plan (LLM'siz): python3 scripts/psi_plan.py psi_veri.json --out plan.md → JSON'dan bu SKILL'in plan iskeletini (ozet/CWV/oncelik/bulgu+kanit) kod ile uretir. Claude'un yazdigi zengin plana bir baseline/alternatiftir; ag yok.
• Paylasilabilir HTML rapor: python3 scripts/psi_report.py psi_veri.json --out rapor.html → kendine-yeter (harici istek yok) tek dosya; skor kartlari, CWV, bulgular + details kaniti, filmstrip.
• Kod-tarafi kontrast: python3 scripts/contrast.py "#onrenk" "#arkaplan" [--large] [--behind <zemin>] → WCAG orani + AA/AAA; AA gecmezse exit 1 (chrome gerekmez).

Plan formati (Markdown)

1. Ozet – URL (gerekirse finalUrl/redirect notu), test tarihi, strateji(ler), kosu sayisi, kategori skor tablosu (mobil vs masaustu) ve counts ("PSI'de N bulgu, M duzeltilecek").
2. Core Web Vitals – LCP / INP (veya TBT) / CLS icin lab + varsa saha + etiket; labVsFieldGaps varsa vurgula.
3. Oncelikli aksiyonlar – Etki x Efor matrisine gore sirali tablo (ilk 5-10): | # | Aksiyon | Etki | Efor | Tahmini kazanc | Ilgili denetim |
4. Tum performans bulgulari – auditsByCategory.performance'in tamami, grup grup (Firsatlar / Tanilar / Insights). thirdParties, resourceSummary ve largestResources (en agir tekil dosyalar — gizli logo/ikon darbogazini yakalar) ile destekle.
5. SEO / Projeye Ozel Aksiyonlar – yerlesik references/ derinliginden (+ claude-seo kuruluysa). Her madde: PSI SEO denetimi + description onerisi + varsa details kaniti.
6. Erisilebilirlik & En Iyi Uygulamalar – ilgili auditsByCategory denetimlerinin tamami; her bulguda details kaniti (hangi element + deger → hedef) somut yazilir. Bkz. references/schema-ve-erisilebilirlik.md (kontrast/tap-target/alt yazim tablosu).
7. Teknolojiye ozel notlar – stackPacks ozeti.
8. Sonraki adimlar / tekrar test – degisiklik CANLIYA ciktiktan SONRA (bkz. "Derin teshis" #4 — deploy/cache dogrulamasi) ayni URL'yi yeniden calistir.

Plani teknik ekibin dogrudan uygulayabilecegi somutlukta yaz: her maddede ne, nerede, neden.

Onceliklendirme kurallari

• Etki: savingsMs (firsatlar/insights); ucuncu tarafta blockingMs; digerlerinde denetim weighti + skor dusuklugu. labVsFieldGaps'te saha kotuyse o metrigi yukari tasi.
• Efor (tahmini): resim sikistirma/format, alt metin, meta aciklama, kontrast, cache baslik ayari = dusuk; kullanilmayan JS/CSS, lazy-load, 3P script erteleme = orta; sunucu yaniti/TTFB, kritik CSS, mimari/render, font stratejisi = yuksek.
• Ilk 3-5 aksiyon "yuksek etki + dusuk/orta efor".
• Spekulatif kovalamama: dusuk-kazancli bulgularda (unused-javascript/unused-css) once mevcut durumu dogrula (build'de code-splitting zaten var mi, ana bundle vs ayri chunk) — korlemesine kovalama.

Core Web Vitals esikleri (referans)

• LCP: <=2.5 sn iyi, <=4.0 sn gelistirilmeli, >4.0 sn zayif
• INP: <=200 ms iyi, <=500 ms gelistirilmeli, >500 ms zayif
• CLS: <=0.1 iyi, <=0.25 gelistirilmeli, >0.25 zayif
• FCP (lab): <=1.8 sn iyi; TBT (lab): <=200 ms iyi
• Kategori skoru: 90-100 iyi, 50-89 gelistirilmeli, 0-49 zayif

Derin teshis ve yaygin tuzaklar (saha dersleri)

Ozet metrikler kok nedeni GIZLEYEBILIR. Skor iyilesmiyorsa veya bir metrik inatciysa:

1. "Gorsel agir ama LCP gorseli optimize" celiskisi → tekil buyuk kaynaklara bak. resourceSummary sadece TUR TOPLAMI verir (or. "image: 371 KB") ve tek bir sisman dosyayi gizler — cogu zaman logo / header ikonu. Once largestResources'a bak; supheliyse dosyayi curl -s -o /dev/null -w '%{size_download}' <url> ile OLC. Header'da eager yuklenen global gorseller (logo) LCP gorseliyle bant genisligi yarisir → LCP'yi tikar. Cok siklikla bir gorsel, optimizasyon pipeline'i (CDN f_auto/q_auto, <img> wrapper) DISINDA kalmistir. CDN transform byte-testi: ayni gorseli varyantlarda olcup karsilastir — curl -s -o /dev/null -w '%{size_download} %{content_type}\n' ile w_800/q_auto/f_auto (Cloudinary/imgix/Unsplash) "hangi boyut/format ne kadar" tablosu cikar. Canlida GERCEKTE inen kaynagi dogrula: gorsel CMS/DB'den geliyorsa koddaki fallback URL'yi duzeltmek etkisiz kalabilir.

2. SPA'da gec-LCP. LCP gorseli JS render + API cagrisi sonrasi indirilmeye baslarsa (React/Vue/SPA) fetchpriority=high bile gec devreye girer. Cozum: HTML'e sunucu-taraflı <link rel=preload as=image> enjekte et ya da URL'yi HTML'e inline ver. Preload URL'si <img>'in gercekte indirdigiyle BIREBIR eslesmeli (CDN transform + srcset/sizes dahil), yoksa cift indirme olur ve preload bosa gider.

3. a11y/color-contrast: "hangi element" bilgisi ZATEN PSI details'inde — chrome GEREKMEZ. extract_details, color-contrast/image-alt/link-name/target-size icin node (selector/snippet) + degerini (oran/boyut) verir. Oncelik sirasi:

   1. PSI details (birincil) — hangi element/renk buradan cikar.
   2. curl ile canli kaynak/renk dogrulama.
   3. Kaynaga erisim varsa scripts/contrast.py "#onrenk" "#arkaplan" ile WCAG orani + AA/AAA; yari-saydam/rgba icin --behind <zemin> (red-600/40 gibi renkler zemine harmanlanir). Korlemesine tema degistirme.
   4. Opsiyonel CLI (kuruluysa, duzeltme sonrasi 0-ihlal teyidi): npx lighthouse --only-categories=accessibility, @axe-core/cli veya pa11y (Chrome ister, MCP degil). chrome-devtools yalnizca kuruluysa opsiyonel bir alternatiftir; hicbir adim ona bagli degil.

4. Retest'ten ONCE degisikligin CANLIDA oldugunu DOGRULA. autoDeploy kapali olabilir, manuel deploy gerekebilir, CDN/HTML cache bayat olabilir → yoksa eski surumu olcup "degismedi" sanirsin. Once curl -s <url> | grep '<beklenen-asset-veya-markup>' ile yeni surumu teyit et, sonra PSI'yi tekrar calistir.

5. PSI kota (429) yonetimi ve PSI'siz teshis. Anahtarsiz gunluk limit dusuktur; ayni gun birkac tam testte dolar. Doldugunda: PSI_API_KEY kullan (yarin sifirlanir), --runs 1'e dus, ya da PSI'yi atla — curl byte olcumu (curl -s -o /dev/null -w '%{size_download} %{content_type}') kaynak agirligini/formatini, opsiyonel npx lighthouse (kuruluysa) lab tarafini PSI'siz verir. Once/sonra dogrulamasi icin PSI sart degil: ayni curl byte olcumunu iki surumde karsilastir. (chrome-devtools kuruluysa network paneli + lighthouse de kullanilabilir — opsiyonel.)

6. "Deploy sonrasi hicbir sey degismedi" = kok neden YANLIS (iterasyon refleksi). Degisiklik CANLIDA (bkz. #4) ama metrik OYNAMADIYSA, hipotezin yanlisti → duzeltmeyi geri sorgula ve baska darbogaz ara (bizde bu, gizli logo darbogazini yakalatti). Bir bulguyu "duzelttim" sanip gecme; olc, tutmadiysa kok nedeni degistir.

Notlar

• Betik yalnizca okuma yapar; siteyi degistirmez.
• auditsByCategory PSI'nin metrik disindaki tum gorunur denetimlerini icerir; gizli (grupsuz) ve "uygulanamaz/manuel" denetimler PSI'de de gosterilmedigi icin haric tutulur.
• Lab verisi her zaman doner; saha (CrUX) verisi yalnizca yeterli trafigi olan sayfalarda bulunur.
• Medyan-of-3 lab varyansini azaltir; kucuk oynamalar normaldir.
• Iki --out dosyasini elle karsilastirarak "onceki/sonraki" (baseline/diff) bakisi elde edebilirsin.