20 августа 2026 года
Как создать сайт, удобный для агентов
Такие агенты, как Claude Code, Cursor и Codex, уже ищут документацию, вызывают API и непосредственно пишут код. Люди больше не являются единственными читателями документации инструментов для разработчиков.
Однако сайт, обеспечивающий отличное взаимодействие для людей, всё ещё может быть неудобен для агентов:
- Люди могут перемещаться по навигации, тогда как агенты могут не знать, с чего начать;
- Люди видят полностью отрендеренную страницу, тогда как агенты могут получить лишь пустую оболочку, ожидающую выполнения JavaScript;
- Люди могут не обращать внимания на навигацию, кнопки и рекламу, тогда как агентам необходимо извлекать основное содержимое из большого объёма HTML;
- Даже если сайт предоставляет Markdown, агенты могут не знать о его существовании.
Rspress — генератор статических сайтов на основе Rsbuild. Его цель — сделать каждый документ удобнее для обнаружения, чтения и понимания агентами. В этой статье представлены лучшие практики Rspress по созданию сайтов, удобных для агентов.
llms.txt: Карта сайта для эпохи агентов
Спецификация llms.txt определяет Markdown-индекс, размещаемый в корне сайта или в его подкаталоге. Он содержит введение в сайт и ссылки на подробный контент.
sitemap.xml помогает поисковым системам индексировать страницы, а llms.txt помогает агентам обнаруживать содержимое с помощью поэтапного раскрытия информации: сначала он предоставляет краткий индекс документации, а затем позволяет агентам по запросу читать релевантные страницы.
Например, файл llms.txt сайта Rspress доступен по адресу https://rspress.rs/llms.txt:
Текущий результат doc_build в Rspress делится на три категории: HTML для людей, Markdown для каждой страницы для агентов и индексные файлы для обнаружения содержимого.
SSG-MD: Версия SSG в формате Markdown
Rspress предоставляет генерацию статических сайтов в Markdown (SSG-MD). Подобно генерации статических сайтов (SSG), SSG-MD преобразует страницы в файлы Markdown вместо HTML-файлов, а также создаёт llms.txt и llms-full.txt, благодаря чему техническую документацию становится проще понимать и использовать большим языковым моделям.
Rspress — это не только фреймворк для SSG: благодаря SSG-MD он также рассматривает генерацию Markdown как полноценную возможность: HTML для людей, Markdown для ИИ.
В следующей таблице сравниваются SSG и SSG-MD:
Почему SSG-MD?
Во фронтенд-фреймворках на основе React извлечение статической информации из динамически отрендеренного содержимого зачастую затруднено. MDX сталкивается с той же проблемой: файлы .mdx содержат Markdown, но также могут включать React-компоненты, делая документацию более интерактивной. Rspress позволяет пользователям расширять документацию с помощью фрагментов MDX, React-компонентов, хуков и маршрутов TSX, однако этот динамический контент создаёт проблемы при преобразовании в Markdown:
-
Передача исходного MDX в ИИ добавляет шум в виде синтаксиса кода и приводит к потере содержимого отрендеренных React-компонентов.
-
Преобразование HTML в Markdown часто даёт неудовлетворительные результаты, из-за чего сложно гарантировать качество информации.
Генерация статических сайтов (SSG) создаёт статический HTML для поисковых роботов и улучшает SEO. SSG-MD решает аналогичную проблему для инструментов ИИ: он улучшает GEO и качество статической информации для больших языковых моделей. В отличие от преобразования HTML в Markdown, рендеринг из виртуального DOM React предоставляет SSG-MD более богатый источник информации.

Как работает SSG-MD?
- Внутри Rspress реализован метод
renderToMarkdownString, аналогичныйrenderToStringизreact-dom, который преобразует React-компоненты в строки Markdown:
В принципе, этот API работает с любым сайтом, созданным с использованием React; если вам это интересно, см. react-render-to-markdown.
- Rspress использует собственный плагин remark
remarkSplitMdxдля предварительной обработки MDX-файлов перед рендерингом. Этот плагин разделяет AST MDX, отделяя обычное содержимое Markdown от JSX-компонентов: текст Markdown сериализуется в строковые литералы, а JSX-компоненты и MDX-выражения (например,{variable}) сохраняются как React-элементы. Это позволяет передавать содержимое Markdown как есть, не обрабатывая его через React-рендеринг, в то время как динамические компоненты рендерятся с помощьюrenderToMarkdownString.
Например, следующий MDX:
преобразуется в компонент следующего вида:
- Rspress предоставляет переменную окружения
import.meta.env.SSG_MD, благодаря которой React-компоненты могут отличать рендеринг SSG-MD от рендеринга в браузере и соответствующим образом настраивать свой вывод:
- Внутренняя библиотека компонентов Rspress адаптирована для SSG-MD, поэтому на этапе SSG-MD компоненты генерируют содержательный Markdown. Например:
Он преобразуется в:
Accept: text/markdown: Возвращение Markdown на основе заголовка запроса
В ноябре 2025 года Boris Cherny, руководитель Claude Code, написал в X:
В следующей версии Claude Code инструмент WebFetch будет автоматически добавлять к запросам
Accept: "text/markdown, *", что поможет сайтам с документацией предоставлять документацию, требующую меньше токенов.
Cloudflare также отмечает, что такие агенты для работы с кодом, как Claude Code и OpenCode, отправляют заголовок запроса Accept, содержащий text/markdown.
Клиенты для агентов, такие как Claude Code, и сайты с документацией, такие как Bun, одними из первых начали использовать соглашение Accept: text/markdown. По сравнению с HTML Markdown не содержит элементы оформления страницы, такие как навигация, стили и скрипты, требует меньше контекста и избавляет от необходимости извлекать основное содержимое из HTML. Поэтому агенты могут быстрее получать пригодный для использования контент. Если сайт уже генерирует Markdown, поддержка этого заголовка делает эти преимущества надёжными, вместо того чтобы полагаться на самостоятельный разбор HTML каждым клиентом.
Rspress — полностью статический фреймворк и не имеет сервера развёртывания, который выбирал бы HTML или Markdown в зависимости от заголовка запроса. Тем не менее поддержать этот заголовок достаточно просто: нужно настроить соответствующее правило у провайдера хостинга. На сайте Rspress используется перенаправление Cloudflare. Запросы, содержащие Accept: text/markdown, внутренне перенаправляются на соответствующий .md-файл по тому же пути, тогда как обычные браузеры по тому же URL по-прежнему получают HTML.
Ответ представлен в формате Markdown:
AFDocs: Проверки и оценка
AFDocs — сопутствующий инструмент с открытым исходным кодом для спецификации документации, удобной для ИИ-агентов. В справочнике проверок перечислены 23 проверки в 7 категориях, а также критерии прохождения, предупреждения и ошибки для каждой проверки.
Несколько описанных в этой статье оптимизаций Rspress для агентов можно проверить с помощью AFDocs:
Rspress также использует другие проверки AFDocs для дальнейшего улучшения, включая такие метрики, как размер HTML.
Выполните следующую команду, чтобы проверить общедоступный сайт с документацией:
Отчёт содержит результат каждой проверки, рекомендуемые изменения и итоговую оценку, что делает его полезным для сравнения сайта до и после обновления с учётом требований агентов.
Agent Score от Mintlify также основан на этой спецификации. Помимо 23 базовых проверок, он добавляет проверки обнаруживаемости полного содержимого, Agent Skills и MCP-серверов.
Важно отметить, что AFDocs не оценивает качество написания документации или правильность ответов агентов. Он лишь проверяет набор верифицируемых правил.
injectLlmsHint: Предоставление URL llms.txt
Проверки обнаруживаемости содержимого AFDocs включают два релевантных правила:
llms-txt-directive-html: Если агент напрямую открывает HTML-страницу, может ли он узнать, что на сайте естьllms.txtи Markdown-версия текущей страницы?llms-txt-directive-md: Если агент получает Markdown-страницу, может ли он узнать, где находится вся документация сайта?
Даже если сайт предоставляет Markdown, агент, попавший на глубоко вложенную страницу, может не знать, что для текущей страницы существует Markdown-версия или что существует /llms.txt. Поэтому каждая страница должна явно предоставлять эти точки входа.
Rspress включает injectLlmsHint по умолчанию. Когда включён SSG-MD, Rspress вставляет визуально скрытый обычный текст в начало основного содержимого сгенерированного HTML:
Здесь не используются display: none, hidden или aria-hidden. URL также отображаются непосредственно в виде обычного текста, а не заключены в элементы ссылок. Подсказка остаётся невидимой для читателей, но сохраняется в DOM, благодаря чему агенты, которые разбирают HTML или преобразуют HTML в Markdown, могут сохранить и прочитать эту директиву.
Правило llms-txt-directive-html в AFDocs предъявляет то же требование: директиву можно визуально скрыть с помощью таких методов, как clip-rect или sr-only, но она должна оставаться в DOM и сохраняться при преобразовании HTML в Markdown.
Сгенерированный Markdown-вывод также включает следующее содержимое:
Этим двум выводам соответствуют проверки llms-txt-directive-html и llms-txt-directive-md.

