Допустим, я прошу агента зайти на сайт ресторана и узнать, сколько стоит маленькая картошка фри. Если я открываю сайт сам, то сразу ищу глазами «Меню», а в нём — картошку. Агенту тоже надо как-то добраться до цены. Только вместо того, чтобы пробежать страницу глазами, он получает от инструмента HTML, очищенный текст или скриншот — смотря чем его оснастили. И если инструмент отдаёт меню целиком, в контекст вместе с картошкой попадают бургеры, напитки и всё остальное, что было на странице.

Я подумал: а что, если дать агенту оглавление сайта, по которому он сможет сразу открыть нужный кусок меню? В Deckard мы сделали для этого открытый генератор agent-sitemap. Он раскладывает страницы на Markdown-записки и связывает их ссылками. Потом мы дали Claude Code два вопроса к собственному сайту. По карте он выкачал меньше текста, зато в статистике оказалось больше входных токенов. Ниже покажу, где взялась эта разница.

У сайта появился ещё один способ чтения

С SEO мы привыкли думать о том, как человек найдёт страницу через поисковик. Дальше он открывает её и сам разбирается, куда смотреть. С агентом появляется ещё один вопрос: что он получит, когда страница уже найдена? Например, в статье на десять экранов нужное условие может занимать один абзац в середине. Если инструмент вернёт статью целиком, агент будет искать этот абзац среди всего остального текста.

Я здесь разбираю именно этот этап, когда адрес сайта уже известен. Попадёт ли сайт в выдачу поисковика или в список источников ассистента — отдельный вопрос. Картой я хочу сократить путь от известного адреса до конкретного ответа.

Что дают sitemap.xml и llms.txt

В sitemap.xml можно посмотреть, какие страницы есть на сайте. По нему я найду URL меню, но где внутри меню картошка, из этого файла не видно. В llms.txt можно описать, что лежит по каждой ссылке, и дать Markdown-версии страниц. Для небольшого сайта этого может хватить. Но если меню длинное, после перехода по ссылке агент всё равно получает длинное меню, просто уже без HTML.

В генераторе мы сделали отдельный Markdown-файл для каждого раздела. Индекс ведёт на карточку страницы, из карточки можно перейти к нужному разделу, а оттуда — к соседним материалам. Ссылку на индекс можно положить в llms.txt.

Как устроена карта

Файл

Что в нём

Зачем его открывать

index.md

Страницы, короткие описания и оценки размера

Выбрать страницу

Карточка страницы

Вводный текст, разделы и ссылки на связанные страницы

Выбрать раздел

Заметка раздела

Текст раздела и ссылки на соседние материалы

Получить ответ или понять, куда идти дальше

Возьмём то же меню. Для примера я бы записал его карточку так:

# Меню

## Разделы

- [Бургеры](https://example.com/ai/menu/burgers.md)
  Состав, размеры и цены бургеров.
- [Картофель и закуски](https://example.com/ai/menu/sides.md)
  Порции и цены гарниров.
- [Напитки](https://example.com/ai/menu/drinks.md)
  Объём и цены напитков.

Агент открывает индекс, идёт в меню и по описанию выбирает «Картофель и закуски». Бургеры и напитки в этом проходе читать незачем. В заметке остаётся адрес исходной страницы, чтобы на неё можно было сослаться и проверить цену. Те же связи генератор записывает в graph.json, если карту нужно читать из своего кода.

Откуда берутся текст и связи

На входе у генератора либо локальные HTML и Markdown, либо сайт со своим sitemap.xml. Текст делится по заголовкам второго уровня (##). Часть связей уже есть в документе: страница содержит разделы, за одним разделом идёт другой, а в тексте автор мог сам сослаться на другую страницу сайта.

Чтобы найти связи, которых в исходнике нет, мы сравниваем слова из разделов на разных страницах. Для этого в базовой сборке хватает TF-IDF и косинусной близости. Тут легко получить ложное совпадение: слово «доставка» может часто встречаться и в тарифах, и в правилах возврата. Поэтому можно включить дополнительный проход с LLM. Он пишет короткие пояснения к заметкам и переходам и может отсеять часть связей, найденных по словам. Авторские ссылки при этом остаются в карте.

Где здесь векторный поиск

Если на сайте тысячи страниц или посетители спрашивают совсем другими словами, чем написано в документации, я бы проверил и векторный поиск. Для карты мне достаточно выложить статические файлы рядом с сайтом и дать агенту инструмент, который умеет открывать URL. Дальше он сам ходит по ссылкам, поэтому может выбрать не тот раздел или открыть пять соседних, хотя хватило бы одного. Если индекс вырастет до размера большой статьи, его тоже придётся целиком читать или делить на части.

Эти подходы можно использовать вместе. Поиск находит раздел с правилом, а ссылка из раздела ведёт к исключениям. На сайте из нескольких страниц я бы начал с оглавления и посмотрел, где агенту действительно понадобился поиск.

Первый замер: текста меньше, входных токенов больше

В README проекта есть пробный замер на двух вопросах к нашему сайту. Ответы спрятаны внутри длинных статей. В одном варианте Claude Code начинал с главной страницы, в другом — с индекса карты. В обоих случаях он мог пользоваться curl и получал подсказку, что сайт отдаёт Markdown. Ответы сверяла модель по заранее заданным эталонам. Привожу цифры из README, отдельного прогона для этой статьи не делал.

Вопрос

Откуда начали

HTTP-запросы

Получено символов

Входные токены

developer

Главная

5

37 728

31 828

developer

Карта

3

12 890

33 029

ship

Главная

4

20 711

30 983

ship

Карта

3

11 737

31 958

Модель засчитала все четыре ответа. С картой агент сделал шесть запросов вместо девяти и выкачал примерно на 58% меньше текста. Я бы по этим двум колонкам ожидал, что и токенов будет меньше, но в последней колонке прирост на 3,5%.

Посмотрим, что складывает счётчик в стенде. В число символов попадает содержимое HTTP-ответов. В число входных токенов входит и остальной контекст, который модель получает на разных шагах. Плюс стенд складывает обычные входные токены, запись в кеш и чтение из кеша, хотя у них разные цены. По этой таблице видно, сколько текста отдал сайт. Чтобы понять, сколько стоил ответ и что именно добавило токены, нужно посмотреть на проходы агента и отчёт по категориям отдельно.

Пока это по одному запуску на два вопроса в Claude Code. Ассистент с обычным веб-поиском и браузером может пройти этот маршрут по-другому.

Что означает подпись «примерно N токенов»

Рядом со ссылкой в карте есть оценка размера. Я смотрю на неё примерно как на длину статьи перед открытием: станет ли ссылка одним абзацем или ещё одной страницей на десять экранов? В коде генератора оценка считается по символам, с разными коэффициентами для преимущественно кириллического текста и остальных случаев. Токенизатор конкретной модели здесь не используется.

Есть нюанс: в оценку попадает основной текст, а в файле ещё есть заголовки, метаданные и ссылки. Для короткой заметки эти добавки могут быть длиннее самого раздела. У карточки страницы вообще может стоять оценка для исходной страницы целиком, хотя сама карточка состоит из введения и оглавления. Здесь я бы показал два числа: размер файла, который агент сейчас откроет, и размер исходного текста.

Как проверить подход на своём сайте

npx agent-sitemap https://example.com

Генератор соберёт каталог ai. Его нужно выложить рядом с сайтом, проверить, что открывается /ai/index.md, и дать этот адрес агенту. Ссылку можно добавить и в llms.txt, но при замере я бы передал адрес явно: иначе легко перепутать результат навигации по карте с тем, нашёл ли агент карту вообще.

Для следующего замера я бы взял 10–30 реальных вопросов и повторил каждый по несколько раз в одинаковых условиях. Часть ответов пусть лежит в одном разделе, часть требует нескольких страниц, а части на сайте вообще нет. Смотрел бы, правильно ли агент ответил и сослался на источник, сколько сделал запросов, сколько текста выкачал, сколько времени и денег ушло. Если модель ещё проверяет ответы, время этой проверки стоит писать отдельно от времени, которое агент потратил на ответ.

В нынешнем замере мне не хватает двух вариантов. Первый — дать агенту llms.txt с целыми Markdown-страницами, чтобы понять, что даёт уже одна очистка HTML. Второй — сразу дать правильную страницу. Если на ней два абзаца, идти через индекс и карточку, скорее всего, дольше, чем прочитать её целиком.

Где карта требует осторожности

Я бы смотрел, что получается на границах разделов. Если правило попало в одну заметку, а исключение — в другую, агент может ответить правильно только для половины случаев. Заголовок «Дополнительная информация» тоже мало что говорит о том, есть ли под ним ответ. На этом месте может ошибиться как агент, так и LLM, которая при сборке писала пояснение.

Для меню есть ещё простой вопрос: когда обновилась цена? Если сайт поменял её сегодня, а копию Markdown обновляли неделю назад, полезнее сходить на сайт или в актуальный API. И содержимое заметок приходит извне, как любая веб-страница: инструкции, найденные внутри текста, нельзя принимать за команды от пользователя.

Мне теперь интересно, где агенту хватает обычного оглавления, а где ему действительно помогают переходы между разделами. Генератор и стенд можно посмотреть в репозитории agent-sitemap, код открыт под MIT. Если попробуете на своей документации или каталоге, интересно сравнить, по каким вопросам он пошёл по ссылкам, а по каким сразу нашёл ответ.

Комментарии (4)


  1. TVD2100
    19.11.2026 16:54

    Интересно, по подходу напоминает Open Knowledge Format (OKF), но для сайта. Если все будут дополнять сайт md версией, то агентам жить станет проще, да и сайтам тоже :)


    1. aleko855 Автор
      19.11.2026 16:54

      Да, при написании ориентировались как раз на OKF. Он и правда наиболее близок


  1. NeoCode2
    19.11.2026 16:54

    Забавно получается. html за десятилетия существования веба превратился в жуткое УГ, когда простейшая страница весит десятки если не сотни мегабайт, в коде километры вложенных div-ов, да еще и тьюринг-полные скрипты, которые делают что хотят... а markdown неожиданно (благодаря нейронкам) превращается в то, чем должен был стать html по изначальному замыслу его создателя Тима Бернерса-Ли. Что дальше? Публикация md-копий каждой страницы рядом с html? А как же баннеры? Как же шпионские скрипты чтобы идентифицировать пользователя даже без явного логина? Как же уникальный десигн? Как же все ухищрения с защитой от скачивания?


    1. aleko855 Автор
      19.11.2026 16:54

      Все так