Agentic Engine Optimization (AEO): Dokümantasyonu Kodlama Ajanları İçin Tasarlamak

Geliştirici portallarını yıllarca “tıklayan, gezen, öğreticiyi bitiren” insan davranışına göre ölçtük: oturum süresi, kaydırma derinliği, dönüşüm hunisi. Oysa artık belgelerin önemli bir kısmını otomatik istemciler tüketiyor: IDE içi ajanlar, CLI yardımcıları, MCP sunucuları ve bağlam penceresi sınırlı büyük dil modelleri. Bu trafik, klasik analitikte neredeyse görünmez kalır; oysa ürününüzün “ajan tarafından anlaşılıp anlaşılmadığı”, doğrudan entegrasyon başarısına bağlanır.

Bu yazıda, bu boşluğu doldurmaya aday bir çerçeveyi ele alıyorum: Agentic Engine Optimization (AEO) — teknik içeriği, otonom olarak getirip işleyen yapay zeka tüketicileri göz önünde bulundurarak yapılandırma ve sunma pratiği.

AEO nedir?

Kısaca: AEO, dokümantasyonun ve API ile ilgili materyalin, kod yazan yapay zeka ajanları tarafından gerçekten kullanılabilir olmasını hedefleyen bir uygulama alanıdır. Arama motoru optimizasyonunda (SEO) olduğu gibi, burada da “kaliteli içerik yeter” demek yetmez; içeriğin kim tarafından, nasıl çekildiği ve bağlamda nasıl tüketildiği belirleyici hale gelir.

İnsan okuyucu başlıkları sırayla gezebilir; ajan ise çoğu zaman tek veya birkaç HTTP isteğiyle sayfayı alır, metne çevirir, token sayısına göre keser veya tamamen vazgeçer. Bu yüzden AEO, görsel hiyerarşiden çok metin yapısı, erişilebilirlik (robots), keşif (indeks dosyaları) ve token bütçesi üzerinden düşünür.

İnsan yolculuğu ile ajan yolculuğu neden farklı?

İnsan geliştirici genelde menüden ilerler, birkaç iç bağlantıya tıklar, örnek kodu denemek için araçları kullanır; analitik bu davranışı yakalar.

Kodlama ajanı ise çoğu zaman sayfa hiyerarşisini adım adım taklit etmez. Belgeyi bir kerede indirip işlemeye çalışır; istemci tarafı etkileşimler, reklam pikselleri ve “sayfada kalma süresi” gibi sinyaller onun için anlamsızdır. Sonuç: dokümanınız okunmuş olsa bile panonuzda “sıfır etkileşim” görebilirsiniz; bu, içeriğin kullanılmadığı anlamına gelmez — ölçümün modele uymadığı anlamına gelir.

Token ekonomisi: görünmezlik riski

Ajanların bağlam penceresi sınırsız değildir. Pratikte yüz binlerce token’lık tek bir “rehber”, tüm görev bağlamını doldurabilir veya sessizce kesilmeye mahkûm olur. Aşırı uzun sayfalarda tipik sonuçlar şunlardır:

• Metnin sonuna doğru kritik uyarıların düşmesi (kesme),
• Ajanın daha kısa bir kaynağa yönelmesi,
• Parçalama denemelerinde gecikme ve hata riski,
• Modelin eğitimden gelen genel cevaplara kayması (halüsinasyon).

Bu yüzden sayfa başına kabaca token tahmini artık yalnızca editoryal bir lüks değil; ajanların “bunu şimdi okuyayım mı?” kararı için bir sinyal. Karakter sayısını dörtte birine bölmek gibi kaba ama işe yarar bir tahmin yöntemi, birçok senaryoda yeterlidir.

Pratik üst sınırlar (rehber niteliğinde):

Katman katman bir AEO yığını

AEO tek bir ayar değil; birbirini tamamlayan katmanlardan oluşur.

1. Erişim: robots.txt ve izinler

Ajanlar çoğu zaman çekmeden önce robots.txt ile sınırları kontrol eder. Yanlışlıkla geniş bir Disallow kuralı, dokümantasyonun otomatik istemciler için görünmez kalmasına yol açabilir; tarayıcıda “sayfa açılıyor” gibi görünürken ajan hiç veri almayabilir.

İhtiyaç halinde, otomasyon için ayrıntılı kurallar sunan agent-permissions.json gibi yaklaşımlar da gündeme geliyor; ama çoğu ekip için ilk adım tutarlı bir robots denetimidir.

2. Keşif: llms.txt

llms.txt, kök dizinde barındırılan, genelde Markdown biçimli bir “ajan dostu indeks” dosyasıdır. İnsanlar için site haritasına, ajanlar için ise “hangi belge ne işe yarar?” sorusuna kısa cevaplar sunar. İyi bir indeks:

• Görev ve kullanım senaryosuna göre gruplanır (salt ürün ağacı yansıması olmak zorunda değildir),
• Her maddeyi bir cümleyle ne öğrenileceğini söyleyen açıklamalarla doldurur,
• Mümkünse kritik sayfalar için yaklaşık token notu düşer,
• Kendisi de birkaç bin token’ı aşmayacak şekilde sade tutulur.

3. Yetenek sinyali: skill / capability dosyaları

İndeks “nerede” sorusuna cevap verir; yetenek bildirimi ise “bu API bu niyeti karşılar mı?” sorusuna yaklaşır. Örneğin bir skill.md benzeri dosyada özetlenebilecekler:

• Neler yapılabilir (yetenek listesi),
• Hangi girdiler zorunlu (anahtarlar, ortamlar, redirect URI),
• Sınırlar (hız limiti, süre, zorunlu güvenlik önlemleri),
• Derinlemesine okuma için bağlantılar.

Böylece ajan, on bin token’lık rehberi baştan sona çekmeden önce uyumluluk hakkında daha iyi bir iç karar verebilir.

4. Biçim: ajanların parse etmesi kolay içerik

• Mümkünse ham Markdown veya düşük gürültülü metin yolu sunun; saf HTML’den türetilmiş metin, etiket ve navigasyon kalıntılarıyla token israf eder.
• Başlık hiyerarşisini atlamayın; her bölümde önce sonuç / ne yapılır, sonra gerekçe.
• Örnek kod, iddianın hemen altında dursun.
• Parametreleri uzun cümleler yerine tablolarla sıkıştırmak genelde hem insana hem modele daha iyidir.

5. Token’ı görünür kılma

Belge başına veya HTTP üzerinden yaklaşık token veya karakter sayısı yayınlamak, ajanın veya onu yöneten sistemin önceliklendirmesine yardım eder. Bu bilgi llms.txt ile sayfa içi meta veride tutarlı olursa daha faydalıdır.

6. “AI için kopyala” ve depo kökünde AGENTS.md

Geliştirici, tarayıcıdan kopyaladığında menü ve footer gürültüsü de gelir. Temiz Markdown kopyalayan bir düğme küçük bir UX iyileştirmesi gibi görünse de bağlam kalitesini ciddi artırır.

Öte yandan, AGENTS.md gibi kök düzeyindeki dosyalar, kod deposunu açan ajanlara proje yapısı, komutlar, kısıtlar ve harici belge bağlantıları hakkında tek giriş noktası sunarak dokümantasyonla köprü kurar.

Trafik ve ölçüm

Ajan trafiğini yalnızca yönlendirme (referrer) raporlarına bırakmak yetersiz kalabilir; bazı istemciler doğrudan veya özgün kullanıcı aracı dizeleriyle gelir. Sunucu günlüklerinde istemci imzalarını, chat arayüzlerinden gelen yönlendirmeleri ve bilinen yapay zeka asistanı domain’lerini ayrı bir segmentte toplamak, AEO yatırımının etkisini görmek için erken uyarı göstergesi sağlar.

Özet kontrol listesi

• [ ] robots.txt yapay zeka ve dokümantasyon yollarında istenmeyen engel oluşturmuyor.
• [ ] Kökte veya keşfedilebilir bir yerde llms.txt (veya eşdeğeri sade indeks) var.
• [ ] Uzun referanslar mantıklı parçalara bölünmüş; mümkünse token/karakter tahmini üretiliyor.
• [ ] Yetenek ve kısıtlar düz metinle özetlenebiliyor; yalnızca “nasıl çağrılır” değil, “ne vaat edilir” de yazıyor.
• [ ] Markdown veya düşük gürültülü kaynak erişimi mümkün.
• [ ] İnsan odaklı ölçümler tek başına “ajan başarısı” yerine geçmiyor; günlük veya özel segmentlerle tamamlanıyor.

AEO, SEO’nun yanına ikinci bir eksen koyuyor: içeriği, otonom tüketicinin gerçek kısıtlarına göre tasarlamak. İyi haber şu ki net başlıklar, sade örnekler, erişilebilir ham metin ve dürüst token bilgisi — insan okuyucuya da fayda sağlar. Kötü haber ise ölçümün sessiz kalması: ajanlar çoğu zaman huninizde görünmez. Bu yüzden hem biçimi iyileştirmek hem de günlüklerde ve indekslerde ajan dostu sinyaller üretmek, aynı paketin parçası.