Технічна документація має другого читача: ШІ-агенти

Ключові тези

1. Стандартна браузерна аналітика не показує значну частину машинного трафіку, оскільки більшість ШІ-клієнтів не виконує JavaScript.
2. Частка агентного трафіку швидко зростає, але кількість запитів сама по собі не показує якість документації.
3. llms.txt майже не впливає на цитування в ШІ-відповідях, проте може допомагати рантайм-агентам швидше знаходити потрібні сторінки.
4. Семантична розмітка, ARIA, доступний із сирого HTML-контенту і зрозуміла навігація залишаються базовими вимогами до технічної документації для ШІ-агентів.
5. Ефективність документації для агентів варто оцінювати за 404-помилками, нерелевантними переходами та здатністю агента знайти правильну інформацію, а не лише за обсягом трафіку.

Технічна документація дедалі частіше має дві аудиторії: людей і машинних клієнтів. Через це виникає практичне питання: якою має бути технічна документація для ШІ-агентів, чи потрібен llms.txt, чи варто віддавати Markdown і наскільки серйозно вже зараз вкладатися в нові стандарти.

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

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

Чому веб-аналітика не враховує трафік від ШІ-агентів

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

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

Цим даним уже майже два роки, тому виникає логічне питання щодо їхньої актуальності. На початку квітня 2026 року інженер Cisco DevNet Олексій Борисенко опублікував препринт зі знятими HTTP-відбитками девʼяти кодинг-агентів і шести ШІ-асистентів на реальному порталі документації. Робота ще не пройшла рецензування, але загальна картина залишилася схожою.

Більшість кодинг-агентів використовує легкі HTTP-клієнти на кшталт curl, axios або Go net/http і не рендерить сторінки. Серед винятків — Aider та OpenCode, які працюють через Headless Chromium і можуть виконувати JavaScript. Окрему категорію становлять браузерні агенти, що працюють у повноцінному браузері.

Отже, краулери та значна частина агентів не бачать контент, який залежить від JavaScript. Замість орієнтації на середні показники це можна перевірити безпосередньо для конкретного сайту:

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

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

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

Яка частка трафіку на документацію припадає на ШІ-агентів?

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

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

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

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

Водночас важливо враховувати конфлікт інтересів. Mintlify і GitBook продають платформи документації з ШІ-функціями, тому зростання агентного трафіку підтримує їхню продуктову тезу. Це не робить дані неправильними, але означає, що їх варто розглядати окремо від незалежних вимірювань.

Cloudflare у цьому контексті ближчий до нейтрального джерела. Його оцінку коректніше описувати як «близько 57 %», оскільки в різних публікаціях фігурують трохи різні значення. Важливе уточнення: йдеться про HTML-запити, а не всю активність в інтернеті. Якщо врахувати застосунки, відео та соціальні мережі, люди все ще генерують близько двох третин активності.

Не менш важливо визначити, кого саме називають «агентами». Під цим терміном можуть матися на увазі тренувальні краулери, яким потрібен великий обсяг даних; пошукові боти, орієнтовані на актуальність; або рантайм-агенти, що шукають конкретну відповідь у момент виконання завдання.

Розбивка GitBook показує ще одну важливу деталь. За обсягом агентського трафіку домінує ChatGPT — близько 54 %, приблизно 12 % припадає на Meta AI, а всі кодинг-агенти разом становлять менш як 7 %.

Тому типовий «другий читач» документації — це не обовʼязково кодинг-агент. Значна частина машинних клієнтів — асистенти, і саме тут важливо розуміти, як ШІ-агенти читають документацію та використовують її для формування відповідей. Cursor, Claude Code та інші кодинг-агенти становлять меншу, але дуже цільову аудиторію для девелоперської документації.

Місячні рейтинги агентів при цьому залишаються волатильними. Лідери можуть швидко змінюватися, тому один часовий зріз не варто сприймати як сталий розподіл ринку.

Чому трафік від ШІ-агентів — це неправильний показник

Навіть правильно порахований агентний трафік не обовʼязково відповідає на головне питання — наскільки добре документація працює для машинних клієнтів.

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

Інше викривлення працює у протилежний бік. За даними препринту Cisco, агенти можуть стискати те, що для людини було б багатосторінковою сесією, до одного-двох запитів. Через це традиційні метрики на кшталт session depth, time-on-page та bounce rate втрачають звичний зміст.

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

Чи справді файл llms.txt працює для ШІ-агентів?

llms.txt — це файл у корені сайту зі структурованим переліком сторінок, задуманий як карта для мовних моделей. За останні два роки навколо нього сформувалося чимало рекомендацій, які повʼязують наявність файлу з видимістю в ШІ-відповідях. Відкриті дані такої залежності не підтверджують.

Ahrefs у червні 2026 року перевірив 137 210 доменів. Приблизно 28 % мали llms.txt, хоча самі автори називають це верхньою межею через технічну специфіку своєї вибірки. Найпоказовіший результат: 97 % валідних файлів протягом травня не отримали жодного запиту.

Серед тих файлів, до яких запити все ж надходили, значну частину трафіку створювали SEO-інструменти, що просто перевіряли їхню наявність. Серед ШІ-клієнтів помітними читачами були GPTBot і Claude Code.

SE Ranking у листопаді 2025 року проаналізував 300 тисяч доменів. Рівень adoption становив близько 10 %, а кореляції між наявністю llms.txt та цитуваннями в ШІ-відповідях дослідження не виявило. Модель прогнозування цитувань навіть ставала точнішою після виключення змінної llms.txt.

Різниця між 28 % у Ahrefs і 10 % у SE Ranking не обовʼязково є суперечністю. Вона добре демонструє вплив вибірки: перший показник описує технічнішу аудиторію конкретного продукту, тоді як другий охоплює ширший сегмент вебу.

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

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

Бенчмарк Mintlify включав 2 400 прогонів на 20 сайтах документації з Claude Code і Codex. Без карти агенти систематично зверталися до неіснуючих URL та читали нерелевантні сторінки. Додавання посилання на llms.txt знижувало частоту помилок майже на 90 % і скорочувало витрати запитів та токенів.

Водночас цей результат потребує обережної інтерпретації: дослідження провів вендор на сайтах власних клієнтів.

Ще один практичний аспект — способи віддачі Markdown. За даними того самого звіту, частка прямих запитів до .md-адрес зросла з 25,1 % у лютому до 54,4 % у липні. Водночас запити із заголовком Accept: text/markdown скоротилися з 25,2 % до 8,3 %.

Це не означає, що один із механізмів потрібно вимкнути. Прямі .md-маршрути вже формують значну частину машинного трафіку, тоді як підтримка content negotiation може вимагати лише одного додаткового правила на сервері.

Перевірити обидва механізми можна командами:

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

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

Якщо звести висновок до одного речення, llms.txt має практичне застосування для документації для ШІ-агентів та API-довідників, куди агент приходить із конкретним питанням. Водночас відкриті дані не дають підстав розглядати його як інструмент для збільшення кількості цитувань у ШІ-відповідях.

Google, llms.txt та Lighthouse: перегляд сторінок з позиції агента

У травні 2026 року Google опублікував гайд з оптимізації під генеративні функції пошуку. Один із ключових пунктів розділу про міфи стосується машиночитаних файлів: вони не потрібні для появи в Google Search, оскільки сам пошук їх не використовує.

Майже одночасно Lighthouse — інструмент аудиту в складі Chrome — отримав категорію Agentic Browsing, яка серед іншого перевіряє наявність llms.txt.

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

І пошуковий гайд, і документація Chrome пояснюють, як ШІ-агенти читають документацію, зокрема через дерево доступності. Розбіжність стосується переважно llms.txt. Це показує різницю в рівнях універсальності: файл може бути корисним для вузького класу клієнтів, тоді як семантична розмітка працює значно ширше.

Категорію Agentic Browsing коректно вважати доступною, але ще не стабільною. Набір перевірок може змінюватися без гарантій сумісності. Це особливо важливо для команд, які планують інтегрувати аудит у CI.

Як перевірити, чи можуть ШІ-агенти читати вашу документацію

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

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

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

npm i -g lighthouse

lighthouse https://docs.whitechain.io/ \

--only-categories=agentic-browsing \

--preset=desktop \

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

Про те, як агенти реально працюють із документацією, також свідчить відтворюваний експеримент GitBook. Для тесту використовувався вигаданий API, якого не було в тренувальних даних, і три кодинг-агенти з однаковим завданням.

Codex перед написанням коду читав повний API-довідник і завершив три з трьох прогонів без помилок. Claude Code і Cursor читали лише quick-start, отримували помилку 422, а потім виправляли рішення на основі тексту помилки.

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

Як ми оптимізуємо нашу документацію для ШІ-агентів

Семантика й ARIA — перший пріоритет. Гайд Google і документація Lighthouse описують дерево доступності як один із ключових каналів взаємодії агентів зі сторінкою. Тому як оптимізувати документацію для ШІ-агентів — це насамперед питання структурованого, семантично зрозумілого контенту.

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

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

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

Прогін agentic-аудиту — у передрелізні перевірки документації. Такий аудит дозволяє отримувати конкретний перелік проблемних елементів замість припущень щодо того, як сторінку бачить машинний клієнт.

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

WebMCP — відкладено, з тригером. Інвестиції в експериментальний API для документації до стабілізації екосистеми несуть додатковий ризик. До рішення можна повернутися після стабілізації відповідних аудитів або появи реального використання таких інструментів агентами в продакшені.

Ціна трафіку від ШІ-сканерів

Обговорення агентного трафіку часто виходить із припущення, що його зростання автоматично є позитивним сигналом. Досвід інфраструктурних платформ показує інший бік проблеми.

У липні 2024 року команда Read the Docs повідомила, що один краулер за місяць завантажив 73 терабайти заархівованого HTML. Після блокування ШІ-краулерів добовий трафік скоротився приблизно з 800 до 200 гігабайтів.

Ці дані вже не описують поточний стан ринку, проте добре демонструють масштаб потенційного крайнього випадку.

Змінився і рівень, на якому вирішується проблема. У липні 2025 року Cloudflare почав блокувати ШІ-краулерів за замовчуванням для нових доменів і запустив Pay Per Crawl. У липні 2026 року модель еволюціонувала в Pay Per Use: оплата привʼязується не просто до обходу сторінки, а до використання контенту у відповіді.

З 15 вересня 2026 року «змішані» краулери також мають блокуватися за замовчуванням на сторінках із рекламою для нових клієнтів, нових сайтів і безкоштовного тарифу.

Cloudflare обґрунтовує цей напрямок, зокрема, співвідношенням кількості обходів до рефералів. Показники змінюються залежно від періоду, але різниця в порядках залишається значною: від приблизно чотирнадцяти обходів на один реферал у Google до десятків тисяч у деяких ШІ-краулерів.

Ще один показовий факт 2026 року: понад половина ШІ-краулінгу в мережі Cloudflare припадає на повторне завантаження сторінок, які не змінилися.

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

Що буде, якщо не оптимізувати документацію для ШІ?

Аргументи проти активної оптимізації у 2026 році теж мають достатню доказову базу. Google прямо зазначає, що llms.txt не впливає на видимість у пошуку. Кілька досліджень не виявляють звʼязку між файлом і цитуваннями, а 97 % досліджених валідних llms.txt узагалі не отримували запитів протягом місяця.

Read the Docs показує, що агентний трафік може створювати суттєві витрати. WebMCP залишається експериментальним. Cloudflare поступово переходить до жорсткішого контролю краулерів. Значна частина статистики про частку агентів водночас походить від вендорів, зацікавлених у розвитку цього сегмента.

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

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

Перелік вимог до документації, оптимізованої для ШІ

Історія Stack Overflow може здатися очевидною паралеллю, але вона не повністю описує ситуацію з офіційною документацією.

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

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

За такою логікою офіційна документація також мала б швидко втрачати людський трафік. Проте співзасновник Read the Docs на початку 2025 року зазначав, що суттєвого падіння трафіку платформа не побачила.

Можливе пояснення полягає в різниці сценаріїв використання. Офіційна документація залишається першоджерелом специфікацій, API, поведінки продукту та актуальних технічних деталей. В опитуванні Stack Overflow 2025 року технічна документація також залишалася ресурсом номер один для навчання розробників — її назвали 68 % респондентів.

Отже, документація не втратила читача. Натомість у неї зʼявився ще один тип читача — з іншими вимогами до формату, іншою вартістю помилки та обмеженою видимістю у стандартній веб-аналітиці.

Висновок

1. Перевірити, чи враховує аналітика клієнтів без JavaScript. Якщо вимірювання повністю залежить від браузерного скрипту, частина машинного трафіку залишатиметься поза дашбордами.
2. Запустити agentic-аудит на кількох типах сторінок документації. Це дає конкретний перелік технічних проблем замість припущень.
3. Не оцінювати машиночитані формати лише через пошукову видимість. Для агентів показовішими є 404-помилки, нерелевантні переходи та кількість зайвих запитів до отримання правильної відповіді.
4. Перед використанням статистики перевіряти методологію та першоджерело. Різні показники adoption або частки агентів можуть описувати різні вибірки й різні типи трафіку.
5. Якщо визначати один базовий напрямок роботи, ним залишається семантична розмітка та коректний ARIA.

Останній пункт не має універсально виміряного розміру ефекту саме для ШІ-агентів. Його пріоритетність випливає з технічного механізму та низького ризику: семантика одночасно підтримує машинне читання, доступність і стабільну структуру контенту.

У технічної документації вже зʼявився другий читач, але за словом «агент» приховуються різні типи клієнтів із різною поведінкою. Наступний етап — клієнти, які не лише читають документацію, а й виконують дії на її основі. Підготовка до цього сценарію починається не з експериментальних стандартів, а з документації, яку машина може стабільно отримати, правильно прочитати та однозначно інтерпретувати.