Modern Web Guidance 1.0 Nedir? Kurulum, legacy-scan ve Test Mühendisi Gözüyle İnceleme

Modern Web Guidance, Google Chrome, Microsoft Edge, Mozilla Firefox ve MDN ekiplerinin birlikte yürüttüğü, AI kodlama ajanlarını eski kod alışkanlıklarından uzaklaştırıp tarayıcının yerleşik özelliklerine yönlendiren açık kaynaklı bir rehber paketidir. 10 Kasım 2026'da 1.0 sürümüne ulaşan paket; Claude Code, Codex, Copilot ve benzeri ajanlara 250 web platformu özelliği için hedefli rehberler sunuyor. Bu yazıda paketin ne yaptığını, resmi kaynağa göre doğru kurulumunu, telemetrinin nasıl kapatılacağını ve bir test mühendisi olarak ajanın ürettiği "modern" kodu nasıl doğrulamanız gerektiğini anlatıyorum.

Modern Web Guidance hangi sorunu çözüyor?

Dil modelleri büyük ölçüde geçmiş yılların kodlarıyla eğitildiği için, bir ajandan modal pencere, akordeon ya da içeriğe göre büyüyen bir form alanı istediğinizde çoğu zaman onlarca satır JavaScript alırsınız. Oysa bu işlerin önemli bir kısmını tarayıcı bugün yerleşik olarak yapıyor. Paketin resmi açıklaması da sorunu böyle tarif ediyor: model bir API'nin varlığını bilse bile, onu üretimde doğru kullanmaya yetecek kadar güncel örnek görmemiş olabilir.¹

Modern Web Guidance bu açığı, ajanın bağlam penceresine yalnızca o görevle ilgili, uzmanlarca hazırlanmış rehberi ekleyerek kapatıyor. Rehberler üç konuya odaklanıyor:

• Modern tarayıcı API'leri: Modellerin sık yanlış kurguladığı API'lerin doğru kullanımı.
• Performans ve erişilebilirlik: Tarayıcının optimize edebildiği ve erişilebilirlik desteği hazır gelen platform özelliklerini tercih etmek.
• Bilinçli fallback'ler: Ağır polyfill'ler ve eski kütüphaneler yerine, duruma özel ve hafif yedek çözümler.

Somut bir örnek: onay penceresi

Bir ajana "kaydı silmeden önce onay soran bir pencere ekle" dediğinizde sık karşılaşılan çıktı aşağıdakine benzer. Görünürlük, Escape tuşu, odak ve kaydırma kilidi tek tek elle yönetilir:

// Tipik "eski usul" onay penceresi
const overlay = document.querySelector('.overlay');
const modal = document.querySelector('.modal');

function openModal() {
  overlay.classList.add('is-open');
  modal.classList.add('is-open');
  document.body.style.overflow = 'hidden';
  modal.querySelector('button').focus();
  document.addEventListener('keydown', closeOnEscape);
}

function closeOnEscape(event) {
  if (event.key === 'Escape') closeModal();
}
// ...ayrıca closeModal, odak tuzağı, aria-modal ve z-index yönetimi

Aynı iş yerleşik <dialog> öğesiyle çok daha kısa yazılır. Escape ile kapanma, arka plan katmanı (::backdrop), sayfanın geri kalanının etkileşime kapanması ve odak yönetimi tarayıcıdan gelir:⁴

<button type="button" id="delete-btn">Kaydı sil</button>

<dialog id="confirm" aria-labelledby="confirm-title">
  <form method="dialog">
    <h2 id="confirm-title">Kayıt silinsin mi?</h2>
    <button value="cancel">Vazgeç</button>
    <button value="delete">Sil</button>
  </form>
</dialog>

<script>
  const confirmDialog = document.getElementById('confirm');
  document.getElementById('delete-btn')
    .addEventListener('click', () => confirmDialog.showModal());
  confirmDialog.addEventListener('close', () => {
    if (confirmDialog.returnValue === 'delete') deleteRecord();
  });
</script>

Nasıl çalışıyor?

README'de anlatılan akış üç adımdan oluşuyor:¹

1. Etkinleşme: Ajan web platformuyla ilgili bir görev aldığında modern-web-guidance skill'ini devreye alır.
2. Yerel arama: Ajan modern-web-guidance search "<sorgu>" komutunu çalıştırır ve görevle en ilgili rehberi bulur.
3. Rehberin alınması: modern-web-guidance retrieve <rehber-id> ile rehberdeki kod kalıpları, bilinen tuzaklar ve fallback önerileri ajanın bağlamına eklenir.

Rehberler toplam 250 özelliği kapsıyor: CSS ve yerleşim (140), HTML ve DOM (36), JavaScript ve API'ler (74). Bunlara ek olarak Manifest V3, service worker ve Chrome Web Store konularını kapsayan ayrı bir chrome-extensions paketi de bulunuyor.

Deneysel özellikler varsayılan olarak kilitli

Yalnızca tek bir tarayıcı motorunda yakın zamanda çıkmış ("volatile") özellikler ve Origin Trial aşamasındaki API'ler aramada görünür, ancak rehberleri varsayılan olarak verilmez. Böylece ajan, kararlı olmayan bir API'yi sizin açık onayınız olmadan kullanmaz. Bunlara izin vermek isterseniz proje kökündeki .mwgrc dosyasına iki anahtar ekleyebilirsiniz:¹

{
  "allowOriginTrials": true,
  "allowVolatileFeatures": true
}

Aynı ayarlar set-allow-origin-trials ve set-allow-volatile-features komutlarıyla da yapılabiliyor. Resmi belgelerde .mwgrc için bu iki anahtar dışında bir ayar tanımlı değil; farklı anahtarlar öneren kaynaklara ihtiyatla yaklaşın.

Kurulum: doğru komut ve telemetriyi kapatma

Önce telemetriyi kapatın. Google, aracı geliştirmek için varsayılan olarak anonim kullanım verisi topluyor: kurulum sayısı, ajanın adı, alınan rehberlerin kimlikleri ve ajanın ürettiği arama sorguları. README'ye göre ham kullanıcı istemleri toplanmıyor.¹ Kapatmak için şu satırı kabuk profilinize (.zshrc ya da .bashrc) ekleyin ve terminali yeniden açın:

export DISABLE_TELEMETRY=1

Ardından etkileşimli kurulum sihirbazını proje kökünde çalıştırın:

npx modern-web-guidance@latest install

Hangi rehber paketlerinin kurulacağını kendiniz seçmek için komuta --choose ekleyebilirsiniz. Rehberleri güncellemek için npx modern-web-guidance@latest update yeterli.

Claude Code ve diğer ajanlar için kurulum yolları

Sihirbaz dışında, ajanların kendi eklenti ve skill sistemleri üzerinden de kurulum yapılabiliyor:¹

legacy-scan ile mevcut kodu taramak

Paketin üçüncü komutu, var olan kod tabanınızı modernleştirilebilecek eski kalıplar için tarıyor:¹

npx modern-web-guidance@latest legacy-scan .

Ne bulacağı tamamen projenize bağlı. Rehberlerin kapsamına bakınca tipik adaylar elle yazılmış modal ve odak tuzakları, scrollHeight ile büyütülen metin kutuları ve konumu JavaScript ile hesaplanan açılır menüler gibi kalıplar olacaktır.

Test mühendisi olarak önerim, taramayı ilk aşamada yalnızca bir rapor olarak kullanmak ve bulguları doğrudan "hemen düzelt" listesine çevirmemek. Her modernleştirme bileşenin davranışını değiştirir: odak sırası, klavye kullanımı ve ekran okuyucu çıktısı farklılaşabilir. Bu yüzden her değişikliğin bir regresyon testiyle birlikte gelmesi gerekir.

Test mühendisi gözüyle: etkisi nasıl ölçülüyor?

Paketi benim için asıl ilginç kılan kısım, etkisini nasıl ölçtükleri. Ekip gerçek web uygulamaları üzerinde geliştirici görevleri tanımlamış ve her görevin sonucunu Playwright tabanlı değerlendiricilerle (grader) doğruluyor. Görev metinleri bilerek API adı içermiyor ("görselleri daha hızlı yükle" gibi); böylece ajanın doğru rehberi kendisinin bulup bulmadığı ölçülüyor.¹

Kalibrasyon adımı ise test mühendislerinin çok iyi bildiği bir soruyu yanıtlıyor: testin kendisi doğru mu? Her değerlendirici, referans çözüm üzerinde %100 geçmek ve hiç değiştirilmemiş temel uygulama üzerinde %100 kalmak zorunda. Böylece hem hiçbir şeyi yakalamayan hem de her şeyi hata sayan testler baştan eleniyor.

README'deki 8 Kasım 2026 tarihli sonuçlar, rehberin ajanların başarısını belirgin şekilde artırdığını gösteriyor:¹

Bu rakamlar her değerlendirme turunda güncelleniyor; ajan ve rehber bazında en güncel döküm için resmi Eval Dashboard'a bakabilirsiniz.³

Kendi test süreciniz için çıkarılacak dersler

• Testinizi de test edin: Bir doğrulama, bilinen iyi sürümde geçmeli ve bilinen kötü sürümde kalmalı. İkisini de otomatik olarak kontrol etmek, yanlış güven veren testleri erkenden yakalar.
• Katkıyı A/B ile ölçün: "Rehberli ve rehbersiz" karşılaştırması, bir AI aracının ekibinize gerçekten ne kattığını ölçmenin en net yolu. Aynı yaklaşımı kendi istem şablonlarınız ve kurallarınız için de kullanabilirsiniz.
• Doğrulamaları katmanlayın: Değerlendiriciler kaynak kod kalıbını, hesaplanan stilleri, çalışma anındaki DOM davranışını ve erişilebilirlik durumunu ayrı ayrı kontrol ediyor. Tek bir ekran görüntüsü karşılaştırması bu kadar sinyal vermez.

Ajanın yazdığı modern kodu Playwright ile test etmek

Rehber ajanı yerleşik özelliklere yönlendirse de bu özelliklerin hepsi her tarayıcıda aynı olgunlukta değil. Bu yüzden ajanın ürettiği kodu en az Chromium, Firefox ve WebKit üzerinde koşturmak gerekiyor:⁵

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
});

Yukarıdaki onay penceresi için görünürlüğü, Escape ile kapanmayı ve odağın tetikleyen butona geri dönmesini doğrulayan bir test:

import { test, expect } from '@playwright/test';

test('onay penceresi açılır, Escape ile kapanır ve odak geri döner', async ({ page }) => {
  await page.goto('/kayitlar');

  const deleteButton = page.getByRole('button', { name: 'Kaydı sil' });
  await deleteButton.click();

  const dialog = page.getByRole('dialog', { name: 'Kayıt silinsin mi?' });
  await expect(dialog).toBeVisible();

  await page.keyboard.press('Escape');
  await expect(dialog).toBeHidden();
  await expect(deleteButton).toBeFocused();
});

Son satırdaki odak kontrolü, erişilebilirlik testlerinde en sık atlanan noktadır. Bu kontrol bir tarayıcıda kalırsa, bulduğunuz şey klavye kullanıcılarını doğrudan etkileyen gerçek bir hatadır.

Desteği sınırlı özelliklerde fallback'i test edin

Örneğin bir metin kutusunun içeriğe göre büyümesini sağlayan field-sizing: content her tarayıcıda desteklenmeyebilir. Ajandan @supports ile korunan bir sürüm isteyin; desteklemeyen tarayıcılarda kullanıcı en azından kutuyu elle büyütebilsin:

.comment-box {
  min-block-size: 3lh;
  resize: vertical; /* fallback: kullanıcı elle büyütebilir */
}

@supports (field-sizing: content) {
  .comment-box {
    field-sizing: content;
    max-block-size: 12lh;
    resize: none;
  }
}

Çoklu tarayıcı projeleri sayesinde aynı test hem modern yolu hem de fallback yolunu kapsar. Fallback'i olmayan bir özellik, desteklemeyen tarayıcıda kırık bir arayüz demektir.