Ajanın o sayfayı gerçekten okudu mu? Agent Reading Test ile sına

“Okudum” demek, okumak değil

Kodlama ajanına “şu belgeye bak, ona göre yaz” dediğinde ajan sayfayı tarayıcı gibi açmıyor. Arada bir getirme hattı (fetch pipeline) var: Sayfayı indiriyor, HTML’i metne çeviriyor, çoğu zaman belli bir uzunlukta kesiyor. Bazı araçlar metni ajana vermeden önce daha küçük bir modelle süzüyor ya da özetliyor. Ajan sana sadece bu süzgeçten geçen kısmı anlatıyor. Ama “sayfayı okudum” diyor.

Ajanların web’i nasıl okuduğunu araştıran Dachary Carey, Nisan 2026’da bu farkı görünür kılmak için Agent Reading Test’i tanıttı. Test, Carey’nin de üzerinde çalıştığı ve ajanlara uygun belge yazımını tarif eden bir kontrol listesine, Agent-Friendly Documentation Spec’e dayanıyor.

Nasıl çalışıyor?

Site, hayalî bir ürünün on belge sayfasından oluşuyor. Her sayfanın içine CANARY- ile başlayan benzersiz işaretler (kanarya token’ları) gizlenmiş. Ajana sadece “şu adrese git, talimatları uygula” diyorsun. Ajan önce gerçekçi on görev yapıyor: Webhook yeniden deneme kuralını bul, v1’den v2’ye geçiş adımlarını çıkar gibi. Sonra en sonda, yolda hangi işaretleri gördüğü soruluyor.

Bu sıra bilinçli. Ajan baştan işaret aradığını bilse, süzgeç de onları “önemli” sayıp tutabilirdi. Görev önce geldiği için hat, gerçek kullanımdaki gibi davranıyor. Ajanın listesini sitedeki puanlama formuna yapıştırıyorsun, 20 üzerinden bir puan ve test test döküm alıyorsun. Doğru cevaplar insanlar için olan formda, ajan onları görmüyor.

Hangi tuzaklar var?

Her sayfa tek bir sorunu sınıyor:

• Kesilme: 150 bin karakterlik bir sayfada 10, 40, 75, 100 ve 130 bininci karakterlerde işaret var. Hattın nerede kestiğini gösteriyor.
• CSS altında gömülü içerik: Asıl metin yaklaşık 80 bin karakterlik satır içi CSS’in arkasında. Kısa okuyan bir hat sayfayı boş sanıyor.
• SPA kabuğu: İçerik ancak JavaScript çalışınca beliriyor. Sadece HTML’i okuyan ajan bir yükleniyor simgesi görüyor.
• Sekmeli içerik: Sekiz programlama dili için kurulum, sekmeler hâlinde. Ajan genelde ilk birkaçını okuyor.
• Sahte 404: Sayfa “bulunamadı” diyor ama HTTP durumu 200. Ajan bunu gerçek belge sanabiliyor.
• Kapanmamış kod bloğu: Markdown’da kapanmayan bir kod bloğu sayfanın geri kalanını yutuyor.
• İçerik pazarlığı: Sunucu, Accept: text/markdown isteyene sayfanın Markdown hâlini veriyor. Bunu isteyen ajan daha temiz metin alıyor.
• Başka alan adına yönlendirme, aynı başlığı taşıyan bölümler ve uzun menülerin arkasında başlayan içerik de sınanıyor.

Puan şişmesi

Testin en öğretici bulgusu bu. Carey’nin yazısına göre Claude Code, testin 18 puanlık ilk sürümünde 17 aldığını söyledi ama gerçekte 15’te kaldı. Hattının takip etmediği bir yönlendirmeyi görüp adresi elle ikinci kez çekmiş ve bunu “buldum” diye saymıştı. GitHub Copilot ise 25 işaret bulduğunu söyledi. Testte toplam 23 işaret var, kendi listesinde 16 tane çıktı.

Ajanın elle bulduğu çözüm kötü değil. Ama asıl okuma aracının bozuk olduğunu gizliyor. Normal bir işte o ikinci adımı her zaman atmayacak. Videoda denenen Kimi 2.5 ise 20 üzerinden 13 aldı ve en çok sekmeli içerikle Markdown sayfasında takıldı.

Belge yazıyorsan

Testin dayandığı belge önerileri basit: Sayfaları kısa tut, sekmeli içeriği ayrı sayfalara da koy, içeriği JavaScript’e bağlama, Markdown sürümü sun ve bir llms.txt dosyasıyla nerede ne olduğunu göster. llms.txt dosyalarının kötüye kullanılabileceğini de şu yazıda anlattık. Ekibin afdocs adlı aracı, bir belge sitesini bu önerilere göre otomatik kontrol ediyor.

Düşün

• En çok kullandığın kütüphanenin belge sitesi bu tuzakların kaçına düşüyor?
• Ajanın bir sayfayı okuduğunu söylediğinde, gerçekten okuduğunu nasıl doğrularsın?

Kendi cümlelerimizle yazılmış bir özettir, çeviri değildir. Tüm kaynaklar yukarıda.