ŞARTNAME VE UYGULAMA REHBERİ

llms.txt Nedir? Yapay Zeka İçin Makine Okunabilir İçerik Haritası Nasıl Kurulur?

llms.txt, AI araçları ve ajanları için önemli kaynakları işaretlemeyi amaçlayan gelişen bir proposal'dır. Doğru kullanımı öğrenin; sitemap, robots.txt ve taranabilir HTML'in yerine koymayın.

12 dk okuma · v2 describedby RFC şartnamesi ile güncellendi

Özet ve Temel Çıkarım

llms.txt, modern web sitelerinin karmaşık HTML, CSS ve JavaScript yükünü eleyerek yapay zeka sistemlerine (ChatGPT Search, Claude, Perplexity, Cursor) sade, token tasarruflu ve yapılandırılmış Markdown içeriği sunmasını sağlayan açık bir web standardıdır. robots.txt veya sitemap'in alternatifi değil; yapay zekaya özel tamamlayıcı bir anlamsal köprüdür.

1. llms.txt Nedir ve Neden Ortaya Çıktı?

Geleneksel web sayfaları insan gözü için tasarlanmıştır: stil şablonları (CSS), karmaşık DOM düğümleri, dinamik JavaScript bileşenleri, reklam ağları, açılır pencereler ve navigasyon çubukları. İnsan için zengin olan bu görsel katman, yapay zeka modelleri ve RAG (Retrieval-Augmented Generation) boru hatları için ciddi bir gürültü (noise) ve maliyet (token overhead) kaynağıdır.

Bir yapay zeka ajanı veya arama botu tipik bir HTML sayfasını ayrıştırmaya çalıştığında:

Bağlam Penceresi İsrafı: Sayfadaki gerçek metin 500 token iken, çevreleyen HTML şablonları 8.000 token tüketebilir.
Ayrıştırma Halüsinasyonu: Navigasyon linkleri, çerez uyarıları ve alt bilgi (footer) metinleri asıl içerikle karışarak modelin yanlış bilgi üretmesine yol açar.
İşlem ve Gecikme Yükü: İstemci taraflı (CSR / SPA) çalışan sayfaları render etmek için headless tarayıcı (Chromium) çalıştırma zorunluluğu, botların yanıt sürelerini ve kaynak tüketimini katbekat artırır.

llms.txt, bu sorunu kökten çözmek için ortaya atılmıştır: Web sitesinin kök dizininde (/llms.txt) barındırılan, standart sözdizimine sahip tek bir dosya ile yapay zekaya doğrudan projenin amacını, temel kaynaklarını ve sadeleştirilmiş Markdown belgelerini işaret eder.

2. llms.txt Dosya Mimarisi ve v2 Sözdizim Grameri

Standart bir /llms.txt dosyası, standart Markdown (CommonMark) formatında yazılır ancak ayrıştırıcıların (parser) deterministik çalışabilmesi için kesin kurallara uymak zorundadır.

Zorunlu Hiyerarşi Kuralları

Tek H1 Başlığı: Dosya mutlaka projenin, kurumun veya ürünün resmi adını içeren tek bir H1 (# Başlık) ile başlamalıdır. Birden fazla H1 kullanılamaz.
Özet Blok Alıntısı (Blockquote): H1 başlığının hemen altında, projenin ne yaptığını ve kime hizmet ettiğini tek veya iki cümlede anlatan bir blok alıntı (> ...) yer almalıdır. Ayrıştırıcılar bu bölümü sistem istemlerine (system prompt) doğrudan bağlam olarak enjekte eder.
Bölüm Başlıkları (H2): Kaynaklar anlamsal kategorilere ayrılmalıdır (örn. ## Dokümantasyon, ## API Referansı, ## Ürünler).
Biçimlendirilmiş Bağlantı Listesi: Her kaynak, - [Başlık](URL): Kısa açıklama formatında bir liste öğesi olmalıdır. URL'ler mutlak (absolute HTTPS) olmalı ve doğrudan temiz Markdown veya sade HTML içeriğe yönlendirmelidir.

Eksiksiz Örnek: Üretim Seviyesinde llms.txt

# HTML&HTML

> HTML&HTML, web sitelerinin yapay zeka arama motorları ve otonom ajanlar tarafından erişilebilirliğini, anlaşılabilirliğini ve taranabilirliğini denetleyen deterministik teşhis platformudur.

## Temel Dokümantasyon
- [Mimari Genel Bakış](https://htmlandhtml.com/docs/architecture.md): 18 bağımsız teşhis motorunun deterministik çalışma prensipleri.
- [AI Görünürlük Kriterleri](https://htmlandhtml.com/docs/ai-readiness.md): robots.txt, canonical, HTTP başlıkları ve LLMO kriterleri.
- [llms.txt Spesifikasyonu](https://htmlandhtml.com/tr/rehberler/llms-txt/): v2 şartnamesi, describedby protokolü ve sözdizimi doğrulaması.

## Araçlar ve Doğrulayıcılar
- [llms.txt Validator](https://htmlandhtml.com/tr/llms-txt-validator/): Gerçek zamanlı sözdizimi, HTTP başlığı ve bağlantı sağlığı denetleyicisi.
- [AI Crawler Checker](https://htmlandhtml.com/tr/ai-crawler-checker/): RFC 9309 uyumlu AI bot erişim denetimi.

## İsteğe Bağlı Kaynaklar
- [Changelog](https://htmlandhtml.com/changelog.md): Sürüm notları ve API değişiklik geçmişi.

3. llms.txt ile llms-full.txt Arasındaki Fark

Şartname iki ayrı dosyayı tanımlar ve her ikisinin de kullanım senaryosu farklıdır:

Özellik	/llms.txt (Dizin Dosyası)	/llms-full.txt (Tam Metin Dosyası)
Amacı	Yapay zekaya içeriğin haritasını sunmak; modelin ihtiyaç duyduğu kaynağı seçerek tek tek indirmesini sağlamak.	Tüm kritik belgeleri tek bir dosyada birleştirerek modelin tek HTTP GET isteğiyle tüm bağlamı belleğe almasını sağlamak.
Dosya Boyutu	Küçük (Genellikle 1 KB - 10 KB).	Orta / Büyük (50 KB - 500 KB+).
Kullanıcı Ajanı	Web arama ajanları, CLI araçları, hızlı bağlam tarayıcıları.	Cursor, Windsurf, Claude Projects, NotebookLM gibi derin kod/doküman asistanları.
İçerik Yapısı	Markdown linkleri ve özet açıklamalar.	Belgelerin tam metni (başlıklar, kod örnekleri, açıklamaların tamamı).

En İyi Uygulama: Eğer teknik bir ürün, SaaS platformu veya API sunuyorsanız, hem /llms.txt hem de birleştirilmiş /llms-full.txt dosyasını eşzamanlı olarak yayınlamalısınız.

4. Keşfedilebilirlik: rel="describedby" Standart Protokolü

Bir dosyanın sunucuda bulunması, botların onu otomatik keşfedeceği anlamına gelmez. Yapay zeka tarayıcılarının /llms.txt dosyanızı doğrudan bulabilmesi için IETF RFC 9264 uyumlu rel="describedby" mekanizması kullanılmalıdır.

A. HTML <head> Etiketi ile Keşif

Sitenizin her sayfasında (özellikle ana sayfada) <head> alanına aşağıdaki satırı ekleyin:

<link rel="describedby" href="https://example.com/llms.txt" type="text/markdown">

B. HTTP Yanıt Başlığı (Response Header) ile Keşif

Özellikle API uç noktalarında veya statik dosyalarda HTML DOM'u bulunmadığından, HTTP yanıt başlığı eklemek en kurumsal yöntemdir:

Link: <https://example.com/llms.txt>; rel="describedby"; type="text/markdown"

Nginx, Cloudflare Workers, Netlify veya Apache üzerinden bu başlığı tanımlayarak botların sayfayı indirmeden önce makine dokümantasyonundan haberdar olmasını sağlayabilirsiniz.

5. Yapay Zeka Arama Motorları llms.txt'yi Nasıl İşler?

Yapay zeka arama dünyasındaki botların davranışları geleneksel Googlebot'tan farklıdır:

ChatGPT Search (OAI-SearchBot): Kullanıcı bir soru sorduğunda canlı web araması yapar. İlgili sitenin /llms.txt dosyası varsa, sayfalar dolusu HTML taramak yerine ilgili Markdown dosyasını doğrudan çekerek yanıt sentezinde kullanır.
Perplexity (PerplexityBot): Kaynak atıfları (citations) üretirken en yüksek bilgi yoğunluğuna sahip temiz metinleri önceler. llms.txt üzerinden sağlanan doğrudan referanslar atıf alma ihtimalini artırır.
Claude (Claude-SearchBot / Anthropic): Uzun bağlam pencerelerinde (200k+ token) birleştirilmiş llms-full.txt dosyalarını doğrudan RAG bağlamı olarak tüketebilir.
Google Search ve Googlebot: Google, web sayfalarını klasik PageRank ve HTML dizinleme motoruyla tarar. Google doğrudan llms.txt'yi organik sıralama faktörü olarak kullanmaz; ancak Google Gemini tabanlı yapay zeka arama modülleri temiz Markdown içeriğini keşif aşamasında değerlendirebilir.

6. En Yaygın 6 Uygulama Hatası ve Çözümleri

HTML&HTML doğrulama motorumuzun yüz binlerce web sitesinde tespit ettiği en kritik llms.txt hataları şunlardır:

H1 Altındaki Alıntı Bloğunu Unutmak: Sadece # Başlık yazıp altına liste koymak v2 şartnamesine aykırıdır. Blok alıntı (> Açıklama) olmadan dosya standart uyumlu kabul edilmez.
HTML Sayfalarına Link Vermek: llms.txt içindeki bağlantıların arkasında karmaşık CSS/JS dolu HTML bulunuyorsa sistemin amacı zedelenir. Bağlantılar doğrudan .md dosyalarına veya minimum HTML içeren sayfalara gitmelidir.
Kırık Linkler (404 / 301 Döngüleri): Ajanlar liste içerisindeki bir bağlantıya tıkladığında 404 hatası alırsa o domain'e ait güven skorunu düşürür ve taramayı keser.
Yanlış Content-Type Başlığı: Dosya sunulurken HTTP başlığında Content-Type: text/plain; charset=utf-8 veya text/markdown; charset=utf-8 dönülmelidir. application/octet-stream dönülmesi botların dosyayı indirmesini engelleyebilir.
robots.txt ile Kendi Dosyasını Engellemek: Webmaster'ların sıkça yaptığı hata: Disallow: /*.txt veya Disallow: /llms.txt yazarak AI botlarının dosyaya ulaşmasını engellemektir. robots.txt içinde açıkça Allow: /llms.txt izni verilmelidir.
İçeriği Güncellememek: Değişen dokümantasyon, silinen API uç noktaları veya güncellenmeyen sürümler yapay zekanın eski bilgiyle halüsinasyon görmesine neden olur.

7. Kontrol Listesi: Sitenizin llms.txt Kurulumunu Doğrulayın

Yayına almadan önce aşağıdaki teknik adımları teyit edin:

Dosya kök dizinde mi? (https://siteniz.com/llms.txt)
HTTP yanıt kodu temiz 200 OK mü? (Yönlendirme veya 301/302 zinciri yok)
İlk satırda tek bir H1 ve altında blok alıntı (>) var mı?
Tüm linkler çalışan mutlak HTTPS URL'leri mi?
HTML <head> içinde rel="describedby" etiketi tanımlandı mı?
robots.txt dosyasında AI botları için /llms.txt erişimi açık mı?

Sitenizi hemen denetleyin

Bu rehberde açıklanan kuralları ücretsiz olarak web siteniz üzerinde test edin.

llms.txt Doğrulayıcı →

OTOMATİK KOD PAKETİ

Tespit edilen teknik engelleri mühendislik ekibiniz için kök neden, kabul testleri ve geri alma planlarıyla çözmek için $99 Tam Site Düzeltme Talimatı ürününü inceleyin.

← Tüm Rehberler Metodolojiyi İncele →