У документації тепер два читачі

💡 Усі статті, обговорення, новини про Front-end — в одному місці. Приєднуйтесь до Front-end спільноти!

Мене звати Ярослав Дворовенко, я Head of Ecosystem у Whitechain — Layer 2 мережі від WhiteBIT, криптобіржі з власною технологічною екосистемою та інфраструктурними продуктами для цифрових активів. Ця стаття для тих, хто відповідає за технічну документацію, DevRel або продуктовий сайт і хоче зрозуміти, хто насправді все це читає.

Дві незручні умови

Цього літа нам довелося вирішувати, що робити з документацією для AI-агентів: чи потрібен llms.txt, чи віддавати Markdown, чи вкладатися в нові стандарти. Пошук рішення ускладнювали дві умови. Перша — власної аналітики агентного трафіку в нас немає. Я не знаю, яка частка читачів наших документів не люди, і не буду вдавати, що знаю.

Друга незручна умова стосується вже вас, якщо ви відповідаєте за сайт чи документацію: якщо ваша аналітика тримається на браузерному JavaScript, ви своєї частки теж не бачите. Стандартні лічильники спрацьовують у браузері й просто не фіксують клієнтів, які скриптів не виконують, а більшість машинних клієнтів їх і не виконують. Детальніше про механізм — у наступному розділі.

Чому у вас (і в нас) немає цих цифр

Стандартна веб-аналітика рахує людей через JavaScript: скрипт вантажиться на сторінці, виконується в браузері, надсилає подію. Клієнт, який скриптів не виконує, у такому дашборді не «недорахований» — він відсутній за визначенням.

А більшість машинних клієнтів скриптів якраз не виконують. Спільне дослідження Vercel і MERJ наприкінці 2024 року проаналізувало понад 500 мільйонів запитів GPTBot і не знайшло жодного випадку виконання JavaScript.

На початку квітня 2026 інженер Cisco DevNet Олексій Борисенко опублікував препринт зі знятими HTTP-відбитками дев’яти кодинг-агентів і шести AI-асистентів на живому порталі документації (arXiv:2604.02544, ще не рецензовано). Картина та сама, але з корисними уточненнями. Більшість кодинг-агентів — легкі HTTP-клієнти на кшталт curl, axios чи Go net/http, які нічого не рендерять. Є й винятки: Aider та OpenCode працюють через Headless Chromium і виконують JavaScript. Окремий клас — браузерні агенти, які працюють у справжньому браузері і рендерять сторінку.

Формула виходить така: краулери й більшість агентів вашого JavaScript не бачать, окремі бачать, і замість сперечатися про середні цифри простіше перевірити власний сайт:

# Чи є текст сторінки в сирій відповіді сервера

curl -s your-docs.example/quickstart | grep -c «фраза, яку видно в браузері»

Нуль у відповіді при видимій фразі в браузері означає: контент домальовує JavaScript, і для більшості машинних клієнтів цієї сторінки не існує.

Що кажуть ті, хто рахує, і чому їхні числа не складаються

Заголовки останнього півроку повні відсотків: агенти вже більшість, боти обігнали людей. Перше, що варто зробити з цими числами, розкласти їх за тим, що саме вони вимірюють, бо вимірюють вони різне.

Чотири різні знаменники і один напрямок. Скласти ці числа в один показник не можна: перший, хто спробує, сам породить заголовок-кашу, з якої ми почали. Зате з розбіжності видно головне: як не міряй, машинна частина трафіку або вже більшість, або дуже близька до неї.

Аргумент, сильніший за будь-яке окреме число, — траєкторії. У Mintlify частка агентів зросла з 15,2% на початку 2026 року до 66% у липні. У GitBook — з менш ніж 10% у січні 2025 до приблизно 41% у грудні, тобто вчетверо за рік, і до більшості «навмисних прочитань» у травні 2026. Mintlify і GitBook — два вендори, незалежні один від одного, з різними методологіями, і криві в них однакової форми. Один дашборд може помилятися; два, які не знають один про одного, навряд.

Варто чесно сказати і про зацікавленість джерел. І Mintlify, і GitBook продають платформи документації з AI-функціями — їм вигідно, щоб агентів було багато. Це не робить дані фальшивими, але зобовʼязує тримати їх окремо від незалежних вимірів. Cloudflare тут ближчий до нейтрального арбітра, і його цифру я свідомо пишу як «близько 57%»: у переказах вона існує в трьох варіантах — від 57,3% до 57,5%, а сам автор визнавав, що точну дату перетину визначити складно. Є й масштабна поправка: йдеться про HTML-запити, а не про користування інтернетом. Якщо додати застосунки, відео й соцмережі, люди досі становлять близько двох третин активності.

Ще одне уточнення стосується того, хто ці «агенти». Слово досі покриває три різні типи: тренувальний краулер, якому потрібен обсяг; пошуковий бот, якому потрібна свіжість; рантайм-агент, який прийшов по конкретну відповідь просто зараз. Розбивка GitBook додає несподіваний штрих: за обсягом агентського трафіку домінує ChatGPT — близько 54%, ще приблизно 12% дає Meta AI, а всі кодинг-агенти разом — менш як 7%. Тобто типовий «другий читач» — це асистент, що читає доки для людини в чаті, а Cursor і Claude Code — маленька, але найцільовіша меншість саме для девелоперської документації. Місячні рейтинги агентів волатильні, лідери міняються від місяця до місяця, тож один знімок не варто сприймати як сталий порядок.

Метрика, яка міряє не те

Навіть коректно порахований агентний трафік відповідає на неправильне питання. Річ у логіці підрахунку: точніший агент витрачає менше запитів, бо не блукає по сайту в пошуках відповіді. Кожен помилковий URL і кожна прочитана нерелевантна сторінка логуються окремо, тож зростання кількості агентних запитів до ваших доків може означати не зростання інтересу, а те, що агенту складніше знайти потрібне. Цей нюанс визнає сам звіт Mintlify, з якого всі беруть цифру 66%.

Другий фактор викривлення зазначає препринт Cisco: агенти стискають те, що для людини вилилося б у багатосторінкову сесію, в один-два запити. Session depth, time-on-page і bounce rate на такому клієнті втрачають сенс: один запит ховає всю «сесію».

У підсумку цифри спотворюються в обидва боки — ретраї їх роздувають, компресія ховає. Тому за орієнтир варто брати не обсяг трафіку, а частоту марної роботи агента: скільки 404-х він ловить і скільки нерелевантних сторінок читає, поки знайде відповідь.

llms.txt: вирок із двох незалежних досліджень

llms.txt — файл у корені сайту зі структурованим переліком сторінок, задуманий як карта для мовних моделей. За два роки навколо нього виріс цілий жанр порад «додайте це і вас цитуватимуть AI». Данні цю обіцянку не підтверджують.

Ahrefs у червні 2026 перевірив 137 210 доменів. У 28% з них є файл llms.txt, і самі автори дослідження вважають це верхньою межею, бо їхня клієнтська вибірка технічніша за середній веб. Головний результат: 97% валідних файлів за травень не отримали жодного запиту. А серед тих, хто запити все ж отримали, головним читачем виявилися SEO-інструменти, які перевіряють саму наявність файлу; з AI-клієнтів у топі GPTBot і Claude Code.

SE Ranking ще в листопаді 2025 перевірив 300 000 доменів: рівень впровадження близько 10%, кореляція з цитуваннями в AI-відповідях нульова. Ба більше, їхня модель передбачення цитувань у дослідників навіть ставала точнішою, якщо змінну llms.txt з неї прибрати. Розбіжність між 28% в Ahrefs і 10% у SE Ranking пояснюється вибіркою: перша цифра описує технічну аудиторію одного продукту, друга — ширший веб. Запамʼятайте цей приклад для фінального чекліста.

Отже, файл мертвий? Ні, він просто працює для іншої аудиторії, ніж та, для якої його рекламують. Для тренувальних краулерів і пошукових ботів llms.txt практично не існує. А для рантайм-агента, який уже прийшов на ваш сайт із конкретним питанням, це карта, що економить невдалі спроби вгадати URL. Бенчмарк Mintlify (2 400 прогонів на 20 сайтах документації з Claude Code і Codex) показав: без карти агенти системно вгадують мертві URL і читають нерелевантні сторінки, а додавання посилання на llms.txt знижує частоту помилок майже на 90% і економить агенту запити й токени. Застереження обов’язкове: це бенчмарк вендора на сайтах його власних клієнтів.

Суміжна практична деталь — маршрути віддачі. За тим самим звітом, частка прямих запитів до .md-адрес зросла з 25,1% у лютому 2026 року до 54,4% у липні 2026 року, а запити з заголовком Accept: text/markdown впали з 25,2% до 8,3%. Висновок не «вимкніть те, що падає», а «тримайте обидва»: прямі .md вже дають більшість машинного трафіку, а content negotiation коштує одного правила на сервері. Перевірити свій сайт:

curl -sI -H «Accept: text/markdown» your-docs.example/quickstart | grep -i «^content-type»

curl -sI your-docs.example/quickstart.md | head —1

Підсумок: llms.txt варто впроваджувати для документації та API-довідників, до яких агент приходить із конкретним питанням, і не варто розглядати як інструмент для потрапляння в AI-відповіді.

Google суперечить сам собі, але не там, де здається

У травні 2026 Google опублікував гайд з оптимізації під генеративні функції пошуку. Перший пункт розділу про поширені міфи стосується прямо нашої теми: машиночитані файли не потрібні для появи в Google Search, оскільки сам пошук їх не використовує. Майже одночасно Lighthouse (інструмент аудиту в складі Chrome) отримав категорію Agentic Browsing, яка серед іншого перевіряє наявність llms.txt.

На перший погляд це суперечність всередині однієї компанії: один продукт каже, що файл не має значення, інший — включає його в перевірку. Але суперечність зникає, якщо дочитати обидва документи до кінця. І пошуковий гайд, і документація Chrome стверджують одне й те саме: агент читає сторінку через дерево доступності. Розходяться вони лише щодо ролі llms.txt, і саме це розходження показує різницю рівнів надійності: файл працює для вузького класу клієнтів, семантична розмітка — для всіх. Статус самої категорії Agentic Browsing найточніше описати як «доступна, але не стабільна»: набір перевірок може змінюватися без гарантій сумісності. І це варто врахувати перед тим, як вбудовувати аудит у CI-пайплайн.

Як самостійно перевірити свій сайт за хвилину

Усе вище — чужі дані. А ось що можна перевірити на своєму сайті без жодної аналітики: категорію Agentic Browsing в Lighthouse. Вона не оцінює на око, а дає конкретний результат, який кожен відтворить сам:

npm i -g lighthouse

lighthouse docs.whitechain.io \

—only-categories=agentic-browsing \

—preset=desktop \

—output=json —output-path=./agentic.json

Тут є нюанс: режим Navigation оцінює одну сторінку, а не весь сайт. Тому чесний прогін — це кілька сторінок різних жанрів одного домену: корінь, навчальний розділ, сторінка API-довідника, туторіал. Розкид результатів всередині власного сайту цікавіший за порівняння з чужими.

Аудит показує, чи здатен агент прочитати сторінку. А от чи прочитає він її взагалі — окреме питання, і відповідь на нього дає інший, вже не інструментальний, а поведінковий тест. Свіжий відтворюваний експеримент GitBook перевірив саме це: вигаданий API, якого немає в тренувальних даних моделей, і три кодинг-агенти з однаковою задачею. Codex перед написанням коду прочитав повний API-довідник і виконав задачу правильно в усіх трьох прогонах. Claude Code і Cursor обмежилися quick-start, наштовхнулися на помилку 422 і виправляли код уже за текстом цієї помилки. Висновок тут важливіший за рейтинг агентів: значення має не кількість прочитаних сторінок, а й те, чи веде вхідна сторінка до правильної.

Що ми вирішили у своїх доках і чому

Семантика й ARIA — перший пріоритет. Підстава проста: і гайд пошуку Google, і документація Lighthouse описують дерево доступності як основний канал читання для агентів. Чесне уточнення: виміряного розміру ефекту не існує ні в кого — це рекомендація з відомим механізмом і невідомою величиною. Ставимо її першою не через силу доказів, а через співвідношення ціни й ризику: ця робота окупається для скрінрідерів незалежно від агентів і залишається корисною, навіть якщо машиночитані конвенції завтра зміняться.

llms.txt і прямі .md-маршрути — лишаємо. Ціна утримання близька до нуля, користь для кодинг-агентів показана бенчмарком Mintlify.

Quick-start має вести на повний довідник. Це пряме рішення з експерименту GitBook: частина агентів далі за вхідну сторінку не піде, тож критичні розділи мають бути доступні з неї за один перехід.

Прогін agentic-аудиту — у передрелізні перевірки документації. Хвилина на прогін і конкретні зламані елементи замість припущень.

MCP-сервер документації — ще ні. Він у розробці, і поки його немає, чесніше сказати це прямо, ніж вдавати, що ми попереду.

WebMCP — відкладено, з тригером. Вкладати роботу в експериментальний API для документації передчасно. Переглянемо рішення в двох випадках: якщо аудити перестануть вимагати origin trial, або якщо агент, яким реально користуються наші розробники, почне читати ці інструменти в проді.

Ціна другого читача

Розмова про агентний трафік часто виходить із припущення, що він корисний для сайту. Команда Read the Docs у липні 2024 показала зворотний бік з позиції тих, кому це коштувало грошей: один краулер за місяць викачав у них 73 терабайти заархівованого HTML, а після блокування AI-краулерів добовий трафік впав приблизно з 800 до 200 гігабайтів. Даним два роки, і як опис поточного стану їх читати не варто, а як масштаб раннього крайнього випадку цілком.

Що точно змінилося, так це рівень, на якому проблему вирішують. У липні 2025 Cloudflare почав блокувати AI-краулерів за замовчуванням для нових доменів і запустив Pay Per Crawl. У липні 2026 модель еволюціонувала в Pay Per Use: платити пропонують вже не за обхід, а за випадок, коли контент реально використано у відповіді. А з 15 вересня 2026 року «змішані» краулери блокуватимуться за замовчуванням на сторінках із рекламою для нових клієнтів, нових сайтів і всього безкоштовного тарифу. Один з аргументів — співвідношення кількості обходів і рефералів, яке Cloudflare публікує з 2025 року. Показники змінюються від знімка до знімка, але порядок промовистий: від чотирнадцяти обходів на один реферал у Google до десятків тисяч в окремих AI-краулерів. І ще одна цифра 2026 року: понад половина всього AI-краулінгу в мережі Cloudflare — це повторне завантаження сторінок, які не змінилися.

Важливе уточнення: ми не маємо даних ні про обсяг власного трафіку в байтах, ні про вартість обслуговування доків. Головний аргумент цього розділу ми підтверджуємо чужими цифрами, тому саме ці дві метрики варто виміряти до того, як ухвалювати будь-які рішення про блокування.

Очевидне заперечення: а якщо не робити нічого

Протилежна позиція базується на тих самих джерелах і виглядає сильно. Google прямо каже, що llms.txt не впливає на видимість у пошуку. Незалежні дослідження не знаходять зв’язку між наявністю файлу та цитуваннями, а 97% таких файлів узагалі ніхто не читає. Read the Docs показує, що агентний трафік — це витрата. WebMCP залишається експериментальним, а Cloudflare рухається до блокування такого трафіку за замовчуванням. До того ж оцінки часток агентів походять від вендорів, зацікавлених у тому, щоб ці частки виглядали великими.

Звідси складається цілком розумна позиція: більшості команд у 2026 році вкладатися в підготовку доків під агентів передчасно; дешевше зачекати рік і подивитися, які конвенції виживуть. Ця позиція справедлива у двох випадках із трьох. Чекати з WebMCP — розумно. Чекати з llms.txt — можна: на сучасній платформі файл, найімовірніше, уже віддається без вашої участі, а якщо ні, то і ціна впровадження, і ціна очікування низькі. А от чекати з семантикою й доступністю сенсу немає: ця робота потрібна незалежно від агентів і окупалася ще до їх появи.

Що з цього виходить

Найочевидніша історична паралель не працює, і це варто сказати прямо. Кількість питань на Stack Overflow сягнула пік,(близько 200 тисяч на місяць, у 2014 році. У грудні 2025 року їх було вже менш на чотири тисячі — майже на 80% менше, ніж роком раніше.

Рецензоване дослідження у Scientific Reports порівняло Stack Overflow з девелоперськими спільнотами Reddit і зафіксувало суттєве падіння на першому, тоді як у спільнотах Reddit такого падіння не було. Соціальна тканина виявилася буфером, а чистий обмін інформацією модель відтворює найлегше.

За цією логікою офіційна документація мала б упасти першою — вона і є чистим обміном інформацією без соціальної тканини. Але співзасновник Read the Docs на початку 2025 року писав, що побоювався того самого для Read the Docs, однак суттєвого падіння трафіку не побачив. Його пояснення: офіційна документація стійкіша за Q&A, бо працює в іншому сценарії використання.

А в опитуванні Stack Overflow 2025 року технічна документація залишилася ресурсом номер один для навчання розробників — 68% відповідей. Доки не втратили читача. Вони отримали ще одного — з іншими вимогами до формату, іншою ціною помилки й повною невидимістю для стандартної аналітики.

Практичні висновки:

1. Перевірте, чи бачить ваша аналітика клієнтів без JavaScript. Якщо вона тримається на браузерному скрипті — не бачить, і ваші графіки описують меншу частину трафіку, ніж ви думаєте.
2. Проженіть agentic-аудит на своїх доках. Хвилина роботи і конкретний список зламаних елементів замість припущень.
3. Не міряйте машиночитані формати метриками пошукової видимості. Міряйте частоту марної роботи агента: 404 та переходи на нерелевантні сторінки.
4. Перш ніж цитувати чиюсь цифру, відкрийте першоджерело. У цьому тексті завдяки цьому знайшлися три варіанти одного відсотка, применшений результат у власному звіті вендора та розрив між 28% та 10% у рівні впровадження, який пояснюється вибіркою, а не реальною різницею.
5. Якщо робите щось одне з переліку, робіть семантичну розмітку і коректно налаштовуйте ARIA.

П’ятий пункт має найменше кількісних доказів: ми знаємо, як ці механізми допомагають агентам працювати зі сторінкою, але не знаємо, наскільки великим буде ефект у конкретному випадку. Водночас це відносно недорога зміна з низьким ризиком, тому її варто зробити першою. Решту рішень краще ухвалювати після вимірювання власного агентного трафіку та поведінки агентів на сайті.

Загальний висновок простий: агенти вже читають документацію, але звична вебаналітика показує їхню поведінку лише частково. Тому спочатку варто переконатися, що ви бачите цей трафік, потім знайти місця, де агенти помиляються або витрачають зайві запити, і лише після цього оптимізувати документацію під їхню роботу.