Рубрика AI-готовности документации API: 28 критериев
AgentFit оценивает каждый проверяемый сайт по 28 критериям, сгруппированным в шесть категорий, дающих в сумме 100 баллов. У каждого критерия есть явная спецификация: что проверяет аудит, как уровни оценки переводятся в баллы и однострочная подсказка, как устранить недочёт. Спецификация детерминирована и полностью воспроизведена в коде на Go. Прочитайте статью о методологии, чтобы понять подход.
Помимо 28 оцениваемых критериев, AgentFit также выявляет новые сигналы, такие как поддержка WebMCP и обнаружение MCP-сервера. WebMCP · MCP.
На этой странице
Что такое AI-готовность документации
Агент читает документацию по HTTP, а не в браузере, где за ним сидит человек. Он не выполняет ваш JavaScript, не скроллит, не наводит курсор на вкладку, чтобы раскрыть список эндпоинтов, и не спрашивает у коллеги, какой тут лимит запросов. Он делает запрос, разбирает ответ и либо находит пригодный контракт, либо сдаётся и додумывает. AI-готовность — это доля того пути, которую машина проходит без посторонней помощи.
Её можно измерить, потому что каждый шаг этого пути — наблюдаемый факт в HTTP-ответе. Есть ли /llms.txt и разбирается ли он. Указан ли на странице абсолютный canonical. Валидна ли OpenAPI-спецификация и описаны ли в ней схемы ответов. Присутствуют ли метод, путь и рабочий пример в том HTML, который приходит до запуска скриптов. Ничего из этого не требует оценивать качество текста. AgentFit проверяет 28 таких фактов и по каждому показывает, что именно он увидел: URL, который запрашивал, и фрагмент-доказательство.
Как считается балл
У каждого из 28 критериев есть лестница целочисленных ступеней и вес. Критерий возвращает статус — присутствует, частично, отсутствует, неприменимо или ошибка — и балл от нуля до своего веса. Оценки 28 критериев складываются в шесть категорий, которые в сумме дают ровно 100. «Неприменимо» и «ошибка» дают ноль, но помечаются по-разному намеренно: «мы не смогли измерить» — не то же утверждение, что «этого нет», и если их слить, заблокированный запрос будет выдавать себя за находку.
Веса — не вкусовщина. Каждый выведен по правилу, записанному до того, как были посчитаны числа: критерий получает вес, если он разводит сайты, одинаковые по остальной рубрике, и теряет вес, если его балл в основном определяется тем, на какой платформе собрана документация. Очко за выбор хостинга — это очко про хостинг, а не про документацию. Правило, метрика и итоговый вектор весов были закоммичены в репозиторий до калибровочного прогона; порядок коммитов и есть аудиторский след. Эта же процедура однажды уже отклонила гипотезу собственного автора.
Аудит детерминирован: один и тот же сайт, проверенный дважды, даёт побайтово одинаковый JSON. Во время оценки не работает ни одна языковая модель — два маленьких классификатора (реалистичность примеров и полнота описания эндпоинта) вкомпилированы в бинарник и версионируются вместе с ним, так что чей-то переобученный чекпойнт не сдвинет ваш балл незаметно. Когда меняется сама линейка, версия рубрики поднимается и проставляется на прогоне, а сравнение двух прогонов, посчитанных по разным версиям, отклоняется — вместо того чтобы выдать смену линейки за регресс на вашей стороне.
Веса категорий. В третьей колонке — вопрос, на который категория отвечает за вас.
| Категория | Вес | На какой вопрос отвечает |
|---|---|---|
| A — Обнаруживаемость | 14 | Может ли агент найти вашу документацию по предсказуемым URL? |
| B — Элементы страницы | 21 | Может ли парсер напрямую считать содержимое каждой страницы? |
| C — API-контракт | 17 | Опубликован ли контракт API в виде машиночитаемой спецификации? |
| D — Контент | 23 | Достаточно ли контекста на странице каждого эндпоинта, чтобы им пользоваться? |
| E — Рендеринг и гигиена | 21 | Стабилен ли сайт и работает ли он без JavaScript? |
| F — Агентские возможности | 4 | Предоставляет ли сайт интерфейсы для агентов (llms.txt, WebMCP, MCP, доступность)? |
A — Обнаруживаемость · 14/100
Может ли агент найти вашу документацию по предсказуемым URL?
Обнаруживаемость — это всё, что агент находит до того, как откроет первую страницу документации: индекс /llms.txt в корне хоста, полнотекстовый /llms-full.txt, robots.txt с внятной позицией по ИИ-краулерам, sitemap с реальными страницами, а не с архивами тегов, и теги на главной, ведущие к markdown-двойнику. Самая дешёвая категория из всех — каждый артефакт здесь — это статический файл, который генерируется на сборке, — и при этом чаще всего пустая.
A1 · llms.txt в корне хоста соответствует спецификации llmstxt.org
агентам (да и людям, впервые попавшим на сайт) нужен единый предсказуемый указатель того, где лежит документация. /llms.txt — это соглашение, предложенное Anthropic и сообществом llmstxt.org: один файл в формате Markdown в корне хоста с картой документации.
Оценка. 2 = H1 + ≥1 H2 + ≥3 ссылок, и все они открываются · 1 = любой файл с H1 (понижен с 2, если ссылки не открываются) · 0 = файл отсутствует или это HTML-обёртка.
Исправление. Опубликуйте /llms.txt в корне хоста с заголовком `# H1`, заголовками разделов `## H2` и как минимум тремя Markdown-ссылками, ведущими на конкретные страницы документации. Спецификация — на https://llmstxt.org.
A2 · Существует llms-full.txt или посекционные агрегаты для LLM
/llms-full.txt — это полнотекстовый дамп вашей документации в одном месте; агенты на больших языковых моделях предпочитают его обходу 200 HTML-страниц. Посекционные варианты (/llms-api.txt и т. п.) тоже подходят.
Оценка. 3 = /llms-full.txt в корне хоста, >1 КБ · 2 = посекционный агрегат, найденный через llms.txt · 0 = ни того ни другого, либо SPA-обёртка по адресу /llms-full.txt.
Исправление. Генерируйте /llms-full.txt на этапе сборки (для mkdocs/docusaurus есть плагины) и отдавайте его как text/plain. Держите размер в пределах 100 МБ, чтобы агенты могли скачать файл без потоковой передачи.
A3 · robots.txt объявляет политику для AI-ботов и абсолютный Sitemap
каждый AI-краулер (GPTBot, ClaudeBot, Google-Extended, PerplexityBot, CCBot) читает /robots.txt перед обходом. Явные Allow/Disallow для каждого UA плюс абсолютная директива `Sitemap:` снимают неоднозначность как насчёт индексирования, так и насчёт того, что именно индексировать.
Оценка. 3 = явная директива для UA AI-бота И строка с абсолютным Sitemap: · 2 = только директива для AI-бота · 1 = только абсолютный Sitemap · 0 = ни того ни другого, либо 404.
Исправление. Добавьте `User-agent: GPTBot\nAllow: /` (или Disallow, если того требует политика) для каждого крупного LLM-бота, а также строку `Sitemap: https://example.com/sitemap.xml`. Директива `Content-Signal:` от Cloudflare тоже засчитывается.
A4 · sitemap.xml: корректный формат, абсолютные URL, мало таксономического шума
карты сайта сообщают краулерам, что индексировать и как часто это меняется. Корректный `<urlset>` с абсолютными URL в `<loc>` по множеству разных страниц сигнализирует о реальном покрытии; заглушка с одним URL (или картой, где 70%+ — шум вроде /tag/ и /category/) не даёт никакого сигнала.
Оценка. 3 = корректный формат + ≥3 различных путей + <30% таксономического мусора · 2 = слишком скудный (<3 путей) или 30–70% мусора · 1 = только корректный формат · 0 = 404 или ошибка разбора.
Исправление. Генерируйте /sitemap.xml на этапе сборки, включайте каждую страницу документации с абсолютным URL в `<loc>` и исключайте варианты /tag/, /category/, /author/, /page=. Ссылайтесь на него из robots.txt абсолютной строкой `Sitemap:`.
A5 · Теги обнаружения на главной: альтернатива в Markdown + OpenGraph
теги обнаружения позволяют агентам найти Markdown-версию страницы без отдельного запроса, а OpenGraph превращает опубликованные ссылки на документацию в расширенные превью в Slack/Discord/Twitter. И то и другое говорит об осведомлённости о машинных потребителях.
Оценка. 2 = `<link rel=alternate type=text/markdown>` + ≥3 различных свойств `og:` · 1 = только альтернатива в Markdown ИЛИ только OpenGraph · 0 = ни того ни другого.
Исправление. Добавьте `<link rel="alternate" type="text/markdown" href="/page.md">` рядом с вашей canonical-ссылкой и убедитесь, что на главной заданы `og:title`, `og:description`, `og:image` (минимум 3 свойства).
B — Элементы страницы · 21/100
Может ли парсер напрямую считать содержимое каждой страницы?
Элементы страницы решают, можно ли разобрать отдельную страницу без догадок: чистый markdown-двойник по адресу .md или через Accept: text/markdown, разбираемый JSON-LD с объявленным типом, абсолютный canonical, машиночитаемая дата изменения и элемент main или article, отмечающий, где кончается контент и начинается навигация. По canonical агенты схлопывают дубликаты, по дате решают, что перечитать; без этих сигналов ваша страница для них — однородная стена из div-ов.
B1 · .md-двойник страниц документации возвращает чистый Markdown
просмотр 200 HTML-страниц для чтения документации нормален для людей; для агентов это затраты на токенизацию на порядок выше. Markdown-двойник на каждую страницу позволяет агентам вытаскивать только текст.
Оценка. 7 = у 3 из 3 выбранных страниц есть работающий .md-двойник · 4 = у 2 из 3 · 2 = у 1 из 3 · 0 = у 0 из 3.
Исправление. Отдавайте `{page}.md` (или `{page}/index.md`) рядом с каждой HTML-страницей ЛИБО поддерживайте согласование содержимого по `Accept: text/markdown`, возвращающее `Content-Type: text/markdown`. У mkdocs-material и docusaurus для этого есть плагины.
B2 · JSON-LD с корректным @type на главной и на странице документации
JSON-LD — это совместимый со schema.org способ объявить «эта страница — статья» / «этот продукт — SoftwareApplication». На него ориентируются и поисковики, и агенты, и экстракторы структурированных данных.
Оценка. 4 = разбираемый JSON-LD с `@type` И на главной, И на выбранной странице документации · 3 = на одной из двух · 0 = ни на одной.
Исправление. Встройте `<script type="application/ld+json">{"@context":"https://schema.org","@type":"TechArticle",...}</script>` на каждую страницу документации. Для главной хорошо подходит тип `WebApplication`.
B3 · Абсолютный <link rel=canonical> на главной и на выбранной странице
canonical-ссылки детерминированно решают вопрос «это http- или https-версия, со слешем в конце или без, с query-параметрами или без?». Без них агенты могут проиндексировать один и тот же контент под несколькими URL.
Оценка. 3 = абсолютный canonical И на главной, И на выбранной странице · 2 = только на главной · 1 = присутствует, но относительный · 0 = отсутствует.
Исправление. Добавьте `<link rel="canonical" href="https://example.com/page">` в `<head>` каждой страницы. URL должен включать схему и хост (относительные canonical-ссылки — валидный HTML, но для межхостовых агентов теряют смысл).
B4 · Свежесть: dateModified (JSON-LD) или заголовок Last-Modified
агенты (и поисковики) меньше доверяют документации, которая не сообщает, когда её обновляли в последний раз. Страница документации 2019 года без сигнала свежести неотличима от обновлённой вчера.
Оценка. 2 = присутствует `dateModified` в JSON-LD ИЛИ HTTP-заголовок `Last-Modified` · 0 = ни того ни другого.
Исправление. Либо добавьте `"dateModified": "2026-05-28"` в блок JSON-LD, либо настройте CDN/сервер на выдачу HTTP-заголовка `Last-Modified`. В большинстве генераторов статических сайтов шаблонизация на этапе сборки делает это бесплатно.
B5 · Машиночитаемые таксономии (keywords, теги, категории)
размеченная тегами документация помогает агентам фильтровать («покажи мне страницы по аутентификации») без разбора всего текста. Засчитываются `<meta name="keywords">`, `keywords` в JSON-LD или URL вида `/tags/`.
Оценка. 2 = присутствует хотя бы один таксономический сигнал (meta keywords, keywords в JSON-LD или ссылки вида /tags|/categories|/topics/) · 0 = ни одного.
Исправление. Добавьте `<meta name="keywords" content="api,auth,oauth">` на каждую страницу, ЛИБО включите массив `keywords` в JSON-LD, ЛИБО организуйте контент под URL-префиксами `/topics/` или `/tags/`.
B6 · <main> или <article> оборачивает основной текст контента
семантические обёртки HTML5 позволяют агентам (и программам чтения с экрана) отбросить навигацию, подвал и боковые панели и читать только текст документации. Страница, где тело — сплошные `<div>`, заставляет действовать наугад.
Оценка. 2 = текст в `<main>` >200 символов И текст в `<article>` >100 символов · 1 = только `<main>` ИЛИ только `<article>` · 0 = ни того ни другого.
Исправление. Оборачивайте основной текст страницы в `<main>` (или в `<article>` для отдельных страниц документации). Не используйте их для боковых панелей и навигации — они предназначены для самого контента.
C — API-контракт · 17/100
Опубликован ли контракт API в виде машиночитаемой спецификации?
Категория API-контракта задаёт один вопрос: есть ли спецификация, которую агент найдёт и которой сможет доверять. C1 — самый тяжёлый критерий рубрики, 8 баллов, разбитых на «документ найден по находимому URL» и «это валидная OpenAPI 3.x с info, путями и схемами ответов». Разбиение сделано намеренно: файл, который существует, но не описывает, что вернётся, — это половина контракта. Валидная спека стоит дороже любой страницы прозы, потому что из неё генерируются клиент, тесты и описания инструментов — без чтения документации вообще.
C1 · OpenAPI / Swagger / AsyncAPI-спека — найдена и валидна
OpenAPI-спека — главный машиночитаемый контракт REST API: агент, нашедший ВАЛИДНУЮ спеку, генерирует клиентов, тесты и точную документацию, не читая HTML. v3 объединяет обнаружение и валидность в один критерий.
Оценка. 8 = валидная OpenAPI 3.x (info, ≥1 path, схемы ответов у ≥30% операций) · 3 = спека найдена по доступному URL, но не валидна 3.x (включая Swagger 2.0) · 0 = ничего · error если не удалось скачать домашнюю страницу.
Исправление. Опубликуйте спеку по `/openapi.json` или `/openapi.yaml` в корне хоста (или объявите через RFC 9727 api-catalog `service-doc`). Сделайте её OpenAPI 3.x и добавьте `responses`-схему к каждой операции — это даёт полные 8.
C2 · Коллекция Postman или SDK с обнаруживаемой загрузкой/форком
спецификация OpenAPI позволяет агентам сгенерировать клиента; готовая коллекция Postman или собранный SDK позволяет ЛЮДЯМ попробовать API за 30 секунд. И то и другое говорит о вложениях в опыт разработчика.
Оценка. 4 = ссылка на коллекцию Postman И ≥1 ссылка на реестр SDK · 3 = Postman ИЛИ ≥2 ссылки на SDK · 2 = 1 ссылка на SDK · 0 = ничего.
Исправление. Опубликуйте кнопку «Run in Postman», ведущую на god.gw.postman.com/run-collection, и сошлитесь хотя бы на один официальный SDK из npm/PyPI/RubyGems и т. п. прямо с главной страницы документации.
C3 · Страницы эндпоинтов показывают метод, URL, типы, обязательность, примеры
страница документации, которая просто говорит «вызовите /users», бесполезна без метода, типов параметров, обязательных полей и примера запроса/ответа. Агентам (и людям) нужны все пять элементов, чтобы сделать рабочий вызов.
Оценка. 5 = большинство выбранных страниц классифицированы ML-моделью как `complete` · 3 = большинство `partial` (или 2 complete + 1 absent) · 1 = большинство `absent` · 0 = страниц-кандидатов не найдено.
Исправление. На каждой странице эндпоинта приводите: HTTP-метод и путь, таблицу параметров с типами и флагами обязательности, пример с curl и пример JSON-ответа с кодом статуса. Таблицы параметров в стиле Markdown и блоки `<pre>` с JSON классифицируются уверенно.
D — Контент · 23/100
Достаточно ли контекста на странице каждого эндпоинта, чтобы им пользоваться?
Контент — самая крупная категория и единственная, которую нельзя починить правкой конфига. Здесь проверяется, есть ли на страницах эндпоинтов работающие примеры больше чем на одном языке, похожи ли значения в них на настоящие данные, а не на foo и example.com, описаны ли ошибки с кодами и причинами, задокументированы ли аутентификация и лимиты, и называется ли одна и та же сущность одинаково по всему сайту. Агент опирается именно на ваши примеры: сниппет, набитый заглушками, переезжает в сгенерированный код дословно.
D1 · Примеры кода включают curl И хотя бы один SDK на языке
примеры с curl можно проверить где угодно; примеры на SDK показывают идиоматичное использование. Вместе они закрывают и потребность «можно быстро попробовать?», и «как мне это интегрировать?».
Оценка. 4 = curl И блок SDK на каком-либо языке хотя бы на 1 странице · 2 = только curl · 1 = только SDK · 0 = ни того ни другого.
Исправление. Добавьте к каждому эндпоинту блок кода с вкладками, как минимум с curl + вашим самым используемым языком SDK (Python или JavaScript). Используйте `<code class="language-python">` или `language-bash`, чтобы и подсветка синтаксиса, и наш классификатор это распознали.
D2 · Реалистичные примеры (не foo/bar/example.com)
`/users/{id}` с `id = 1` и `email = [email protected]` заставляет читателя домысливать, как выглядят реальные данные. Реалистичные заглушки (`[email protected]`, `org_2N5x...`) упрощают работу и предотвращают случайную вставку из документации.
Оценка. 4 = ML-модель говорит, что <20% блоков кода перегружены заглушками · 3 = 20–40% · 2 = 40–60% · 1 = 60–80% · 0 = >80% либо блоков кода нет.
Исправление. Замените `foo`/`bar`/`example.com`/`your_api_key`/`<string>` на реалистично выглядящие значения (`pk_test_51N5...` у Stripe, `+14155552671` у Twilio). Не используйте реальные данные клиентов — но имитируйте их форму.
D3 · Каталог ошибок с HTTP-кодами и причинами
когда интеграция ломается в 3 часа ночи, разработчику нужно понять, что на самом деле означает `403 - resource_not_owned`, не заводя тикет. Отдельная справочная страница по ошибкам — это разница между пятиминутным исправлением и получасовой отладкой.
Оценка. 3 = отдельная страница ошибок (≥3 кодов с пояснениями) · 1 = коды ошибок описаны по тексту на разных страницах · 0 = нет ничего.
Исправление. Опубликуйте `/errors` (или `/reference/errors`) со списком каждого возвращаемого HTTP-статуса + кодов ошибок уровня приложения + одной фразой о причине каждой. Хорошо подходят таблицы; подойдут и списки определений `<dl>`.
D4 · Документированы аутентификация И ограничения частоты запросов
аутентификация — это база; ограничения частоты запросов — то, по чему разработчик понимает, переживёт ли его интеграция нагрузку прода. И то и другое должно быть на странице верхнего уровня, обнаруживаемой с главной.
Оценка. 3 = документированы и аутентификация, и ограничения частоты · 2 = только аутентификация · 1 = только ограничения частоты · 0 = ни того ни другого.
Исправление. Добавьте страницы `/authentication` (потоки bearer / API-ключ / OAuth) и `/rate-limits` (запросов в минуту, заголовки вроде `X-RateLimit-Remaining`, семантика повтора при 429). На каждой нужно хотя бы 200 символов контекста — а не просто сниппет кода.
D5 · Глоссарий ИЛИ согласованная терминология на всех страницах
это «workspace», «team» или «organisation»? Выбрать один термин и держаться его во всей документации — значит предотвратить целый класс тикетов «что здесь значит X?». Лучше всего отдельный глоссарий; согласованное употребление приемлемо.
Оценка. 3 = отдельный /glossary с ≥3 структурированными парами термин/определение · 2 = глоссария нет, но терминология остаётся согласованной между страницами (≥80% преобладающего варианта) · 1 = ссылка на глоссарий есть, но содержимое скудное · 0 = ни того ни другого.
Исправление. Опубликуйте `/glossary` в виде `<dl>` с парами `<dt>термин</dt><dd>определение</dd>` (или таблицу из 2 столбцов с определениями ≥50 символов). Используйте одинаковый регистр и написание каждого термина на всех страницах.
D6 · Устаревшие / бета-эндпоинты помечены простым текстом
разработчик, вставляющий ваш пример кода 2022 года в проект 2026 года, не должен узнавать об устаревании эндпоинта во время выполнения. Явные пометки `deprecated` / `beta` / `sunset` в документации избавляют от головной боли при миграции.
Оценка. 2 = `deprecated` в спецификации OpenAPI ИЛИ на ≥2 выбранных страницах рядом с заголовками эндпоинтов · 1 = найдены ключевые слова beta/experimental, но нет признаков устаревания · 0 = нет ничего.
Исправление. Помечайте каждый устаревший эндпоинт через `deprecated: true` в OpenAPI И видимым бейджем или предупреждением в HTML-документации (`<Warning>` у Mintlify, синтаксис admonition у Docusaurus и т. п.). То же для бета-эндпоинтов — видимо в тексте, а не только в спецификации.
E — Рендеринг и гигиена · 21/100
Стабилен ли сайт и работает ли он без JavaScript?
Рендеринг и гигиена — про то, переживёт ли всё вышеперечисленное встречу с обычным HTTP-клиентом. E1 здесь гейт: если контента нет в HTML, который приходит до выполнения JavaScript, агент видит пустую оболочку приложения, какой бы хорошей ни была документация. Остальное в категории — стабильные URL при переездах, явная версия API, внутренние ссылки, которые действительно открываются, заявленные условия использования и элементы управления с доступными именами, за которые агент может взяться, когда он не читает страницу, а работает с ней.
E1 · Контент виден в чистом HTML без JavaScript (отсекающий критерий)
это ОТСЕКАЮЩИЙ критерий. Если ваша документация отрисовывается только после выполнения JavaScript (обёртка single-page-app), агенты, скачивающие сырой HTML, не видят ничего. Веб-краулеры, скраперы, curl и большинство AI-загрузчиков не выполняют JS.
Оценка. 6 = текст тела >500 символов хотя бы на одной из главной или 2 подстраниц во всех режимах UA · 3 = главная проходит, но подстраницы — SPA · 0 = SPA-обёртка везде, либо ловушка одинаковой оболочки (3+ URL возвращают идентичное тело).
Исправление. Отдавайте предварительно отрисованный HTML по статическим URL. Если вы используете Next.js/Nuxt/SvelteKit, включите SSG или SSR для раздела документации. Обёртки single-page-app (React SPA, Vue SPA без SSR) не проходят этот критерий и каскадно обнуляют многие другие.
E2 · Стабильные URL: редиректы 301 сохраняют старые пути
когда вы реорганизуете документацию, старые ссылки не должны отдавать 404 — они должны делать 301 на новый URL. Стабильные URL — это то, благодаря чему ссылки из блогов, Stack Overflow и закладок переживают вашу перестройку.
Оценка. 2 = стабильный редирект 301/308 хотя бы на 1 из 2 выбранных вариантов URL · 1 = шаблон canonical-алиаса (200 с `<link rel=canonical>`) · 0 = 302 (временный), 404 или редиректа нет.
Исправление. Меняя URL документа, добавляйте редирект 301 со старого пути на новый. Генераторы статических сайтов делают это через конфиги `_redirects` (Netlify) или `redirects:` в `vercel.json` (Vercel).
E3 · Явная версия API в пути URL, заголовке или спецификации OpenAPI
`/v1/users` против `/v2/users` — это дешёвый способ версионировать API И сделать это очевидным для агентов. Метаданные версии, находящиеся только в HTTP-заголовке (а не в пути URL или заголовке страницы документации), для краулеров невидимы.
Оценка. 2 = версия в собственной структуре URL документации (URL карты сайта или спецификации OpenAPI: `/v1/`, `/2024-01-15/`) · 1 = версия в URL документируемого эндпоинта (примеры curl/кода), в `info.version` OpenAPI или в заголовке `<h1>`/`<h2>`/футере · 0 = нет нигде.
Исправление. Добавьте к путям API префикс `/v1/`, `/v2/` и показывайте их в примерах curl/кода; ЛИБО задайте непустой `info.version` в спецификации OpenAPI. API с версионированием по дате (`/2024-01-15/users`) тоже засчитываются.
E4 · Выборочная проверка 5 внутренних ссылок → все возвращают 200
битые внутренние ссылки — самый частый сбой документации после лет изменений. Выборочная проверка 5 ссылок ловит худшие случаи (4xx/5xx по ссылкам прямо на главной), не пытаясь обойти каждую ссылку.
Оценка. 2 = 5 из 5 выбранных ссылок на тот же хост возвращают 200 · 1 = 4 из 5 · 0 = ≤3 из 5 ЛИБО на главной найдено меньше 5 различных ссылок на тот же хост.
Исправление. Запускайте проверку ссылок в составе CI (lychee, htmltest, linkinator). Для самых посещаемых ссылок на главной исправляйте любые 404 перед выпуском. Пять рабочих ссылок с посадочной страницы — это абсолютный минимум.
E5 · Условия использования: TOS / лицензия / AI-политика явно заданы
без явного TOS или политики AI-использования каждый LLM-скрапер вынужден угадывать вашу позицию. Содержательная страница `/terms` или `/license` — особенно с ключевыми словами про AI/ML — делает политику машиночитаемой.
Оценка. 2 = страница TOS найдена И содержит ключевые слова AI/ML-политики в основном контенте · 1 = TOS найдена (содержательная, но без AI-ключевых слов, либо ссылка есть, но страница 404/скудная) · 0 = ссылки на TOS нет.
Исправление. Опубликуйте `/terms` (или `/legal`, `/license`) минимум с 1000 символами текста политики. Включите явные формулировки про AI-скрапинг, обучение моделей и автоматический доступ — даже если вы всё разрешаете, прямо сказать об этом и есть сигнал.
E6 · Агентская доступность: статические имена + валидность ARIA
AI-агент управляет страницей через дерево доступности: каждой кнопке, ссылке, полю и картинке нужно имя, за которое можно зацепиться. v3 переносит критерий из категории F в E рядом с E1, потому что он оценивает отрендеренную страницу, а не поверхность обнаружения.
Оценка. 4 = 0 нарушений (и ≥1 элемент для проверки) · 2 = 1–2 · 1 = 3–5 · 0 = ≥6 · not_applicable если именовать нечего · error если страницу не удалось просканировать. Статическая эвристика (без axe-core/headless).
Исправление. Дайте каждой `<button>`/`<a>`/иконке доступное имя; свяжите `<label>` с полями; добавьте `alt` картинкам и `<title>` инлайновым SVG; уберите положительный `tabindex`; исправьте опечатки в `aria-*` и ролях.
F — Агентские возможности · 4/100
Предоставляет ли сайт интерфейсы для агентов (llms.txt, WebMCP, MCP, доступность)?
Агентские возможности фиксируют явные интерфейсы для агентов: набор инструментов WebMCP на странице — декларативный или заданный из JavaScript и объявленный MCP-сервер, OAuth-метаданные которого соответствуют RFC 9728 и RFC 8414. Категория намеренно маленькая — 4 балла из ста. Обе спецификации молодые и ещё меняются, за пределами нескольких docs-платформ внедрение измеряется единицами процентов, и штрафовать каждый сайт за неучастие в эксперименте — значит описывать наш энтузиазм, а не чужую документацию. Вес вырастет, когда вырастет внедрение.
F2 · Интерфейс инструментов WebMCP для агентов в браузере
WebMCP позволяет странице выставить вызываемые инструменты ИИ-агенту, работающему во вкладке браузера, — через декларативную разметку `<form toolname tooldescription>`, императивный API `navigator.modelContext` или полифил. F2 засчитывает любой обнаруженный интерфейс; проверка схемы декларативных форм идёт в диагностику и на балл не влияет.
Оценка. 1 = WebMCP обнаружен, 0 ошибок схемы + 0 предупреждений · 1 = обнаружен с проблемами схемы (ошибки или предупреждения) · 0 = не обнаружен · error, если главную не удалось просканировать.
Исправление. Добавьте интерфейс инструментов WebMCP. Декларативная форма — единственная, которую внешний аудитор проверяет по статическому HTML: добавьте у `<form>` атрибуты `toolname` + `tooldescription`, а у каждого поля — `name` + `toolparamdescription`. Сначала чините ошибки «нет toolname» и «обязательный параметр без name»: это жёсткие отказы.
F3 · Анонсирован MCP-сервер (OAuth по RFC 9728 / 8414)
MCP-сервер позволяет агентам вызывать ваш API как управляемые инструменты. F3 вознаграждает анонс обнаруживаемого, защищённого OAuth MCP-эндпоинта через стандартные метаданные `.well-known`, чтобы агент мог аутентифицироваться и подключиться без индивидуальной настройки.
Оценка. 3 = полный oauth-mcp (protected-resource по RFC 9728 + метаданные сервера авторизации по RFC 8414 + PKCE S256) · 2 = частично · 1 = только эндпоинт · 0 = ничего · error, если сайт недоступен.
Исправление. Отдавайте `/.well-known/oauth-protected-resource`, указывающий на ваш MCP-эндпоинт, и документ метаданных сервера авторизации по RFC 8414 на том же хосте, анонсирующий PKCE `S256`.
С чего начать
На 5827 сайтах публичного корпуса AgentFit медиана — 22 балла из 100, четверть сайтов не набирает и 11, и только 19 % переваливают за 40. Баллы теряются в одних и тех же четырёх местах; ниже они отсортированы по тому, сколько очков приносит час работы:
- Нет /llms.txt в корне хоста — ноль по A1 у 75,0 % сайтов, это 3 балла. Один генерируемый файл, один шаг сборки. У 57 % корпуса нет ни llms.txt, ни llms-full.txt, ни ИИ-политики в robots.txt — то есть у агента вообще нет точки входа, объявленной для него.
- robots.txt не упоминает ни одного ИИ-краулера и не содержит абсолютной строки Sitemap — ноль по A3 у 65,8 % сайтов, это 3 балла. Пять строк текста в файле, который любой краулер читает первым.
- Нет markdown-двойника у страниц документации — ноль по B1 у 77,9 % сайтов, на которых проверку вообще удалось выполнить, это 5 баллов. У большинства генераторов статики исходный markdown уже лежит рядом: работа тут в роутинге, а не в тексте.
- Нет находимой валидной спецификации — ноль по C1 у 96,4 % сайтов, это 8 баллов. Самая крупная потеря на доске и единственная из четырёх, где нужна разработка, а не конфиг.
Порядок важнее самого списка. Девять критериев — llms.txt, llms-full.txt, robots, sitemap, discovery-теги на главной, JSON-LD, canonical, дата изменения, таксономии — весят 27 баллов и не требуют переписывать ни одной строчки документации; средний сайт забирает из них 8,5, то есть восемнадцать баллов лежат на столе. C1 и каталог ошибок в D — это недели, их надо планировать, а не втискивать. Одна оговорка про причинность: у сайтов с llms.txt медиана 41 против 18 у остальных, но это не значит, что файл приносит 23 балла. Скорее наоборот: llms.txt кладут те, кто и так следит за документацией. Разметка — дешёвый способ добрать баллы, а не способ сделать документацию хорошей.
Все цифры в этом разделе — замороженный срез: 5827 хостов с валидным прогоном по рубрике v3, снято 27 июля 2026 года, по одному прогону на хост, без доменов, принадлежащих AgentFit. Графики выше на этой странице строятся по живому корпусу и ДЕЙСТВУЮЩЕЙ рубрике, веса которой после того среза пересматривались, — совпадать эти два набора чисел не обязаны, и там, где они расходятся, актуален график. Это URL, которые люди присылали сами, а не курируемый список документаций API, так что медиана описывает присланное, а не рынок.
Частые вопросы
Что такое llms.txt и нужен ли он мне?
Это markdown-файл в корне хоста, который индексирует вашу документацию: заголовок H1, разделы H2 и ссылки на действительно важные страницы; формат предложен на llmstxt.org. Читать его никто не обязан, и AgentFit не выдаёт его за стандарт. Он оценивается по другой причине: стоит один шаг сборки и это единственное место, где границу вашей документации проводите вы, а не эвристики чужого краулера. Соседний файл /llms-full.txt — та же идея, доведённая до полного текста.
Нужен ли MCP-сервер, чтобы получить высокий балл?
Нет. Вся категория агентских возможностей — 4 балла из 100, и сайт без MCP-сервера и без WebMCP спокойно набирает за девяносто. Категория существует, чтобы фиксировать, кто уже строит интерфейсы для агентов, а не чтобы наказывать тех, кто не строит. Если MCP-сервер у вас есть, F3 проверяет, объявляет ли он себя так, как ожидает спецификация: метаданные защищённого ресурса по RFC 9728, документ сервера авторизации по RFC 8414 и PKCE с S256.
Чем это отличается от Lighthouse и SEO-аудита?
Другим читателем. Lighthouse измеряет опыт человека в браузере: скорость отрисовки, сдвиги вёрстки, доступность отрендеренной страницы. SEO-аудит измеряет соответствие поисковому индексу и его факторам. AgentFit измеряет, сможет ли программа, которая не исполняет ваш JavaScript и не скроллит, получить контракт вашего API. Пересечения реальны — рендеринг без JS, canonical, микроразметка встречаются во всех трёх, — но ломается всё по-разному, и идеальный Lighthouse прекрасно уживается с документацией, которой агент воспользоваться не может.
Почему в оценке нет нейросети?
Потому что балл, который нельзя воспроизвести, — это не измерение. Каждая проверка — это HTTP-запрос плюс парсер или правило, поэтому один и тот же сайт дважды получает один и тот же результат, а за каждым очком стоит URL и фрагмент, которые вы можете перепроверить сами. Два маленьких классификатора помогают двум критериям; они вкомпилированы в бинарник и версионируются вместе с ним, так что чужое переобучение не сдвинет ваш балл за ночь. Практические следствия: полный аудит занимает около тридцати секунд, ничего не стоит, и его может перепроверить скептик.
Как часто пересчитывать аудит?
После любого изменения в том, как документация собирается и отдаётся, в остальное время — раз в месяц. Балл двигается только когда двигается факт, так что ежедневные прогоны в основном измеряют шум вашего CDN. Сравнивать прогоны удобно в режиме diff; если между ними сменилась версия рубрики, сравнение будет отклонено, а не показано как ваш регресс.
У меня низкий балл — что это значит?
Обычно не то, что документация плоха для людей. Типичная картина низкого балла — хорошо написанный сайт, отданный как JavaScript-приложение и без машинных поверхностей: агент получает пустую оболочку, markdown-двойника нет, спецификации нет, и дальше сыплется всё остальное. Читайте отчёт со списка исправлений: он отсортирован по отношению очков к трудозатратам, и в каждом пункте указан URL, который запрашивался, — находку можно воспроизвести до того, как планировать работу.
Высокий балл гарантирует, что ChatGPT будет ссылаться на мою документацию?
Такое не может пообещать никто, и этот инструмент не обещает. Высокий балл означает более узкую и проверяемую вещь: агент, который до вас добрался, сможет получить, разобрать и процитировать вашу документацию без браузера. Сошлётся ли на вас поисковый ответ, зависит ещё от политики его краулера, от того, как часто про ваш продукт вообще спрашивают, и от ранжирования, которое вендоры не публикуют. AgentFit измеряет ту часть, которая в вашей власти.
Можно ли прогнать рубрику самому?
Да — руками. Полная спецификация на этой странице, критерий за критерием; тот же текст отдаётся как markdown по этому же адресу с заголовком Accept: text/markdown, а схема отчёта лежит в публичном OpenAPI-документе. Чего сделать нельзя — так это запустить нашу реализацию: исходники закрыты, готовых сборок мы не публикуем. Зато можно поймать нас на слове: на /reproducibility выложены три сырых отчёта и точные команды, чтобы сравнить их по полям с живым прогоном того же сайта. Все уже проверенные сайты доступны для просмотра, так что сравниться с соседом по рынку можно ещё до начала работы.
Проверить свою документацию · Посмотреть проверенные сайты · Проверить MCP-сервер