# Strona czytelna dla *agentów AI*.

> Jak sprawić, żeby agenci AI (ChatGPT, Claude, Perplexity) dostawali pełną treść strony: llms.txt, wersja Markdown pod tym samym adresem i testy, które to sprawdzają.

Maciej Wiatr, Kraków, 2026-10-25. https://maciejwiatr.com/pl/strona-czytelna-dla-ai

## Co dostaje agent, który otwiera stronę

Gdy ChatGPT, Claude albo Perplexity pobiera stronę, dostaje to samo co przeglądarka: menu, baner cookies, znacznik skryptu dla każdego pakietu JavaScript, czcionki, analitykę i stopkę z dziesiątkami linków. Płaci tokenami za każdy z tych bajtów, a potem musi sam znaleźć w nich właściwą treść.

Vercel zmierzył jedną ze swoich stron: około 500 KB HTML wobec 3 KB Markdownu, czyli o 99,37% mniej. Moje strony są lżejsze, ale różnica też jest wyraźna: artykuł, w którym to opisuję, waży 29 KB jako HTML i 9,1 KB jako Markdown.

Wersja Markdown ma tę samą treść, bez całej reszty: nagłówki, akapity, listy, linki i kod.

## Kiedy to ma znaczenie

- Gdy ludzie pytają ChatGPT, Claude'a albo Perplexity o produkt, a odpowiedź ma się opierać na treści ze strony.
- Gdy dokumentację, blog albo bazę wiedzy czytają agenci programistyczni.
- Gdy ma to działać stale, w kodzie i w testach, a nie dzięki jednorazowej wtyczce.

Agentów rzadko wpisuje się dziś w wymagania strony, więc w większości zespołów nikt za to nie odpowiada.

## Z czego to się składa

- **Markdown pod tym samym adresem.** Strona odpowiada Markdownem na żądanie z nagłówkiem `Accept: text/markdown`, a HTML-em na każde inne. Obie wersje powstają z tego samego źródła w tym samym wdrożeniu, więc zmiana treści trafia do obu naraz.
- **`Vary: Accept` na obu wersjach.** Bez tego CDN może zapamiętać jedną wersję i podawać ją wszystkim: przeglądarki dostaną Markdown, a agenci HTML.
- **Link alternate w nagłówku każdej strony.** Klient, który nie prosi o Markdown, znajdzie w HTML-u adres wersji Markdown.
- **Plik llms.txt.** Krótki opis serwisu i lista najważniejszych stron z linkami do ich wersji Markdown.
- **Mapa strony w Markdownie.** Tytuły, daty i jednozdaniowe streszczenia, żeby agent mógł wybrać, co przeczytać.
- **Testy.** Sprawdzają, że każdy adres odpowiada właściwym formatem, że Markdown zawiera treść ze źródła i że nagłówki dla cache są na miejscu.

## Jak to robię

1. **Najpierw pomiar.** Pobieram stronę dwa razy, jako przeglądarka i jako agent, i porównuję, co wróciło: format, rozmiar i nagłówki.
2. **Jedno źródło.** HTML i Markdown powstają z tej samej treści w tym samym buildzie. Przy CMS-ie zamiana treści z edytora na Markdown odbywa się w tym samym wdrożeniu co HTML.
3. **Reguła przed plikiem.** Vercel podaje plik pasujący do adresu, zanim zadziała jakakolwiek reguła przepisywania adresów (rewrite). Dlatego HTML leży pod wewnętrzną ścieżką, a reguła na nagłówek `Accept` wybiera wersję. W Next.js to samo załatwia reguła beforeFiles.
4. **Sprawdzenie na produkcji.** Po wdrożeniu pobieram obie wersje z produkcji i sprawdzam, czy CDN je rozróżnia.

## Ta strona działa tak samo

Ta strona też ma wersję Markdown pod tym samym adresem. Sprawdź to w terminalu:

```sh
curl -sL -H "accept: text/markdown" https://maciejwiatr.com/pl/strona-czytelna-dla-ai
```

Albo wciśnij Start poniżej. Tester pobiera stronę dwa razy, jako przeglądarka i jako agent, i porównuje odpowiedzi. Jego interfejs jest po angielsku.

[Sprawdź tę stronę testerem czytelności dla agentów AI](https://maciejwiatr.com/agent-readable-check?url=https://maciejwiatr.com/pl/strona-czytelna-dla-ai)

Cały mechanizm opisałem w artykule [Making Next.js agent-readable](https://maciejwiatr.com/blog/making-nextjs-agent-readable) (po angielsku): konfigurację dla Vercela, wersję dla Next.js sprawdzoną w Next.js 16.4 i listę rzeczy, które sprawdzam w code review. Wcześniej, w Mimirze, zbudowałem katalog przetargów nastawiony na SEO, z około 200 000 zaindeksowanych stron.

## Pytania

### Czy zmieni się to, co widzą ludzie i Google?

Nie. Przeglądarka i każdy klient, który nie prosi o `text/markdown`, dostaje ten sam HTML co wcześniej. Markdown dostają tylko ci, którzy o niego poproszą albo wejdą pod jego adres z llms.txt lub linku alternate.

### Czy trzeba przepisać stronę albo zmienić CMS?

Nie. Na stronie statycznej to głównie konfiguracja routingu i jeden krok w buildzie. Przy CMS-ie dochodzi zamiana treści z edytora na Markdown, w tym samym wdrożeniu co HTML, żeby obie wersje zawsze się zgadzały.

### Co, jeśli strona stoi za Cloudflare?

Trzeba ustawić cache. Cloudflare domyślnie rozróżnia odpowiedzi po adresie i kilku stałych nagłówkach. Od lipca 2026 może je rozróżniać także po `Accept`, ale tylko gdy ten nagłówek doda się w regule cache (Cache Rule). Po wdrożeniu warto pobrać obie wersje i sprawdzić, co zapamiętał cache.

### Czy wszyscy agenci proszą o Markdown?

Nie. curl, fetch w Node.js i requests w Pythonie domyślnie wysyłają `Accept: */*`, a urllib w Pythonie nie wysyła tego nagłówka wcale. Wszystkie dostają HTML. Dla nich jest link alternate w HTML-u i lista adresów w llms.txt.

Masz pytanie albo uwagę? Napisz: [maciej.wiatr00@gmail.com](mailto:maciej.wiatr00@gmail.com)

## Zobacz też

- [Agenci AI i automatyzacja przeglądarki](https://maciejwiatr.com/pl/agenci-ai-krakow): Agenci AI, którzy wykonują pracę w przeglądarce i w firmowych narzędziach: wypełniają formularze, zbierają dane i przechodzą przez panele bez ręcznego klikania.
- [Maciej Wiatr, strona główna](https://maciejwiatr.com/pl/)