Привлекаем трафик из нейросетей — попробуйте GEO-продвижение

Заказать звонок
Телефон отдела продаж:
8 (800) 775-16-41
Наш e-mail:
mail@texterra.ru
Читайте
Заказать услугу
Документация для AI: что предусмотреть, если ее читает агент, а не человек Редакция «Текстерры»
Редакция «Текстерры»

Документацию все чаще читает не разработчик, а его AI-ассистент. Мы видим это по нашему MCP-серверу REST-документации: через него агенты обращаются к документации десятки тысяч раз в месяц. Поэтому у вендоров ПО появляется новая задача: делать документацию удобной для AI.

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

  • Нехватка информации. Человек, наткнувшись на пробел в документации, обычно это замечает: спотыкается, идет спрашивать коллегу или гуглить. Агент просто достраивает недостающий фрагмент статистически похожим продолжением — оно выглядит так же убедительно, как правильный ответ.

  • Самодостаточность фрагментов. Человек читает страницу целиком и помнит, что было выше. Агент часто получает не всю документацию и даже не всю страницу, а один фрагмент — например, через поиск. Поэтому каждый фрагмент должен быть понятен сам по себе: в нем названы объект, условие и результат, а не стоят отсылки вроде «см. выше» или «аналогично». При этом не нужно повторять один и тот же факт в нескольких блоках — повторы агенту мешают.

  • Канонические примеры и вариации. Человеку обычно достаточно одного хорошего примера, поскольку он умеет транслировать общий принцип на похожие случаи. Агент же воспроизводит синтаксис примера буквально, поэтому для него ценнее не один базовый пример, а покрытие разных вариантов и нестандартных ситуаций отдельными примерами.

  • Различия в формулировках. Человек нормально воспримет, если один и тот же факт на разных страницах сформулирован немного по-разному. Агент, который вытаскивает конкретный факт и сталкивается с двумя слегка различающимися формулировками одного и того же, не может понять, какая из них приоритетна. Он либо случайным образом берет одну из них, либо смешивает в ответе. То есть агенту важно не просто единообразие стиля, а буквальное совпадение формулировки одного факта везде, где он встречается.

  • Явные запреты. Людям не обязательно явно указывать в документации то, что нельзя сделать с конкретным методом. Человек попробует, получит ошибку, поймет границу. Агент, который пишет код за один проход, такой обратной связи не получает, поэтому отсутствие информации про ограничение он читает как «наверное, можно, просто не описано». Явные запреты типа «этот метод не поддерживает X» — для агента работают, а для человека часто кажутся лишними.

Когда мы адаптируем документацию для AI, мы подразумеваем, что читать ее могут агенты с разными навыками и разными задачами. Понятная агентам документация должна поддерживать несколько сценариев чтения. Например, есть агент, который получает через поиск один блок страницы, — ему нужна самодостаточность фрагмента. Есть агент с большим контекстным окном, который читает весь раздел документации целиком, — ему самодостаточность фрагментов и раздельные примеры уже не так критичны, он сам видит связи между страницами. А есть агент с доступом к инструментам, который может вызвать метод и посмотреть, что вернется, а не гадать по описанию. В конце статьи вы найдете чек-лист, который поможет проверить, насколько ваша документация понятна AI-агенту.

Как это выглядит у нас на практике. Общие блоки — предупреждение об устаревшем методе, пометка «работает только в контексте приложения», сноска об обязательных параметрах, таблица системных ошибок — хранятся в одном месте и вставляются на все страницы одним и тем же текстом. Автор их не переписывает, поэтому формулировка одного факта совпадает буквально на сотнях страниц.

Подключим вашу документацию к AI-помощнику и настроим поиск по источникам с учетом прав доступа. Проверим, как он отвечает на реальных задачах.
Разработка AI-помощников

Изучая то, как AI-агенты взаимодействуют с документацией, мы обнаружили несколько проблем, когда AI просто не может получить доступ к информации:

  • Контент физически недоступен. Если страница в браузере состоит из заголовка и пустого контейнера, а остальной текст подгружается через JavaScript, человек этого не замечает — он в любом случае увидит на экране нужную информацию. А агент, который запрашивает страницу как текст, без полноценного браузера, получает пустышку: либо ничего не находит, либо работает по старой закэшированной версии. Поэтому мы рекомендуем отдавать контент сразу в ответе сервера, без JS-дозагрузки. Первый же ответ должен содержать весь текст страницы, а не только каркас.

  • Нет карты документации. Человеку достаточно поиска и меню. Агент, у которого нет явной навигации, либо обходит все постранично, либо не находит нужный раздел вообще. Нужно дать агенту отдельные навигационные форматы — путеводитель по всей документации и оглавление раздела, которое обновляется автоматически при сборке и не расходится с текстом статей.

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

Задача технического писателя не только в том, чтобы один раз написать хороший текст. Нужно отдельно думать о том, как агент физически получает к нему доступ — и на уровне выдачи одной страницы, и на уровне навигации по всей документации.

Эту задачу мы рекомендуем рассматривать на двух уровнях — технической доступности информации и ее полноты.

Основная проблема, которую нужно решить, — доступность контента. Для этого нужно как минимум проконтролировать способ отдачи контента: передавать весь текст HTML-страницы в ответ на запрос, как уже говорилось выше. И не закрывать документацию от AI-краулеров: у нас robots.txt разрешает обход всем ботам, а карта сайта указана прямо в нем.

Но эффективнее всего агент работает с MCP-сервером. Это протокол (и сервер на его основе), через который AI делает структурированный запрос на поиск и получение метода, статьи или события и получает ответ напрямую, без необходимости разбирать HTML-страницы. Он помогает агенту получать сведения из документации и снижает риск ошибок из-за недостающего контекста. Мы подняли отдельный MCP-сервер для REST-документации. Он ничего не делает в Битрикс24 и не вызывает методы — только ищет и отдает документацию: описание метода, параметры, ошибки, примеры кода. Для агента это прямой канал чтения документации.

Но не всякий агент видит, что у нас есть MCP, и предлагает его подключить. Также есть пользователи, которые просто дают агенту ссылку на конкретную страницу документации — агент может просто не дойти до MCP. Для таких случаев мы сформировали конкретный набор форматов, которые добавили специально для агентов:

  • llms.txt — по сути, свод-путеводитель по документации в открытом текстовом формате, который сейчас становится общеотраслевым соглашением. У нас в нем перечислены базовый URL и авторизация, скоупы, модули со ссылками на разделы, ссылки на OpenAPI-спецификацию и MCP-сервер. Агент может прочитать один файл и понять карту всей документации, не обходя ее постранично. Так выглядит начало нашего файла:

# Bitrix24 REST API — документация (русский язык)

Официальная документация REST API Битрикс24 на русском языке. Содержит руководства и справочник по более чем 2000 методам...

Базовый URL вызова методов: https://{portal}.bitrix24.ru/rest/{method_name}

Аутентификация: OAuth 2.0 (параметр auth) или входящий вебхук (токен в URL).

Все методы сгруппированы по скоупам (crm, task, disk, im, sale, catalog и др.).

Машиночитаемая OpenAPI-спецификация: https://apidocs.bitrix24.ru/openapi.json

MCP-сервер для AI-ассистентов: https://mcp-dev.bitrix24.tech/mcp

Полный список статей: https://apidocs.bitrix24.ru/pages-index.json

Дальше идут готовые команды подключения MCP-сервера для популярных AI-ассистентов и карта разделов — по строке на раздел, например:

## CRM

Лиды: crm.lead.* — CRUD для лидов

Сделки: crm.deal.* — CRUD для сделок

  • Автоматически генерируемая OpenAPI-спецификация — собирается из репозитория и обновляется сама при каждом дополнении документации, а не ведется отдельно вручную, то есть не может разойтись с текстом статей.

  • Отдельное оглавление для агентов — также автоматически обновляется при сборке документации. Вместе с llms.txt оно дает агенту структуру документации без необходимости читать все подряд в поисках нужного метода.

Агенту нужно явно знать, какая версия API перед ним и что устарело. У нас каждая страница метода новой версии API помечена одинаковой плашкой со ссылкой на обзор версии, а у устаревших методов стоит одинаковое предупреждение: «Развитие метода остановлено. Используйте...» — и ссылка на замену. Так агент не соберет вызов по методу, который больше не развивается, и не перепутает адреса вызова старой и новой версии.

Документацию для AI мы также рекомендуем писать с помощью AI. У себя в отделе мы настроили конвейер для AI-генерации контента: набор скиллов под конкретный продукт документации, где каждый скилл отвечает за свой шаг, и оркестрирующая команда, которая прогоняет их друг за другом сама. Для того чтобы AI-агенты могли работать, мы также описали подробные правила для каждого проекта документации — требования к оформлению статей, к полноте и структуре, и локальные инструкции, которые агент читает перед началом работы. Именно из них он понимает, что делать и на что опираться.

Когда статья уже есть, задача скилла — сверить ее с тремя источниками: исходным кодом, правилами проекта и соседними статьями раздела, чтобы взять из них образец структуры, формата и глубины детализации. На основе сверки он находит расхождения: где текст устарел, где разошелся с кодом, где выбивается из общего формата раздела. Технический писатель проверяет итог и решает спорные случаи, которые агент вынес в отчет.

Чтобы результат был понятен AI, предусмотрите следующие моменты:

  • убедитесь, что соседние статьи в разделе оформлены единообразно — именно на них агент будет ориентироваться. У нас на каждой странице метода один и тот же порядок блоков: область доступа и кто может вызывать метод, описание в одно предложение, таблица параметров с типами и обязательностью, примеры кода на нескольких языках, пример ответа, таблица возвращаемых данных, ошибки метода с кодами и ссылки на связанные методы;

  • проверьте, что правила проекта описаны явно, а не подразумеваются: агент не догадается, что «у нас так принято»;

  • после генерации просмотрите расхождения, которые нашел скилл: безопасные он исправляет сам, а правки, которые меняют смысл или факт, оставляет на решение человека.

Когда статью нужно написать с нуля, скилл использует те же три источника, просто без шага сверки — сверять не с чем. Он смотрит на код, на то, как оформлены соседние методы в разделе, и пишет по этому образцу.

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

Покажу на одной странице — методе event.offline.list, который читает очередь оффлайн-событий. Ее мы недавно сверили с исходным кодом и доработали под агентов. Репозиторий документации публичный, поэтому изменения можно посмотреть целиком.

Фильтр. Было:

Поддерживается фильтрация по полям: ID, TIMESTAMP_X, EVENT_NAME, MESSAGE_ID. PROCESS_ID, ERROR со стандартными операциями типа =, >, <, <= и так далее

Для человека это нормально. Для агента «и так далее» — это приглашение достроить: он подставит отрицание, потому что в других методах оно работает. Стало:

Перед именем поля ставится операция: =, >, <, >=, <=, @ — значение входит в массив, % — подстрока. Без операции работает точное совпадение. Пример: {«>ID»: 100, «=EVENT_NAME»: «ONCRMLEADADD»}. Отрицание ! не поддерживается: метод вернет ошибку ERROR_ARGUMENT.

Теперь список операций закрытый, есть пример и прямой запрет с кодом ошибки.

Ограничение по тарифу. Было:

Параметр доступен на тарифе Профессиональный и выше.

По одному названию тарифа агент не может определить доступность параметра в конкретном портале.

Стало:

Параметр доступен не на всех тарифах: проверьте его методом feature.get с кодом rest_auth_connector, иначе метод вернет ошибку WRONG_LICENSE.

У агента появился вызов, которым это можно проверить, и код ошибки, если он не проверил.

Ошибки. В таблице ошибок была одна строка:

Метод запустил не администратор.

Стало девять: на каждое ограничение из описания своя. Например:

Статус

Код

Когда возникает

403

ACCESS_DENIED

Метод вызвал не администратор

403

WRONG_AUTH_TYPE

Метод вызван не в контексте приложения, например через вебхук

400

ERROR_ARGUMENT

В фильтре передана неподдерживаемая операция, например !

Человек без этих строк попробует вызвать метод через вебхук, получит ошибку и поймет. Агент без них напишет код через вебхук и отдаст его.

Ответ. Ответ метода описывался одной строкой:

Корневой элемент ответа.

Теперь расписано каждое поле записи, и заодно выяснилось, что result — это массив, а не объект, как было указано раньше. Агент, который поверил бы старому описанию, написал бы разбор ответа под объект.

Раньше можно было отвлечь от работы нескольких разработчиков и попросить их проверить документацию. Сейчас, когда мы переориентировались на AI, оценивать качество тоже должен AI. Для этого мы используем собственную метрику — AI-Friendly Index (AFI). Это оценка по 100-балльной шкале, которая складывается из 10 критериев. Она показывает, хватает ли странице информации, чтобы по ней можно было написать рабочий код, не заглядывая в исходники.

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

AI-агент сам оценивает текст по этой метрике. Если баллов не хватает, он не просто ставит низкую оценку, а показывает список конкретных проблем и что именно нужно поправить. На основе этого отчета мы дорабатываем документацию.

У нас в отделе аудит AI-Friendly Index реализован отдельно для каждого продукта документации. Он устроен как самостоятельный скилл, который можно запустить и отдельно на одну конкретную страницу или заданный список страниц, и автоматически в конвейере генерации, как итоговая проверка черновика, который подготовил агент.

Техническим писателям важно освоить новый навык: ориентироваться не на воображаемого человека-читателя, который может найти недостающие фрагменты, а на AI-читателя, который недосказанность не заметит и просто достроит. Сменив фокус, вы научитесь автоматически включать в документацию самодостаточные фрагменты, явные «нельзя», буквальное совпадение формулировок одного факта на разных страницах.

Для тренировки навыка рекомендую конкретную практику. Дочитав текст, задавайте себе вопрос «агент, у которого нет ничего, кроме этого текста, вытащит из него правильный и полный ответ?». По сути именно это и делает агент, когда оценивает AI-Friendly Index — только вместо интуиции сотрудника у него есть чек-лист из десяти критериев под каждый тип страницы. Поэтому регулярная работа с отчетами аудита — это не только контроль качества, но и способ самому натренировать этот взгляд на собственный текст.

  • Самодостаточность. Каждый блок понятен без соседних: в нем названы объект, условие и результат. Нет «см. выше» и «аналогично».

  • Вариации примеров. Не один базовый пример, а отдельные примеры под разные варианты вызова и нестандартные случаи. Во всех примерах одного метода — одинаковый набор параметров и значений.

  • Единые формулировки. Один факт — одна формулировка во всей документации. Повторяющиеся блоки берутся из одного источника, а не переписываются на каждой странице.

  • Явные запреты. Что метод не поддерживает, кто не может его вызвать, в каком контексте он не работает — написано прямо и продублировано в таблице ошибок с кодом.

  • Полнота параметров и ответа. У каждого параметра — тип, обязательность, допустимые значения; вложенные объекты раскрыты на странице, а не спрятаны за ссылкой.

  • Доступность. Текст страницы приходит в первом ответе сервера, без JS-дозагрузки.

Читайте также:

Техническая доступность сайта: как проверить, видит ли его поиск и AItexterra.ru

Как бренду работать над контентом, чтобы он попал в AI-ответы [запись вебинара + расшифровка]

Что мешает AI-агенту выбрать товар: эксперимент TexTerra в трех интернет-магазинах

Поделиться статьей:

Новое на сайте

13 ноя 2026
755
Нейросеть упоминает бренд, но ссылается на чужой сайт: что делать?

Нейросеть назвала вашу компанию, но среди источников — чужие статьи, рейтинги или каталог? Причины могут быть разными: где-то поиск вообще не включился, где-то робот не может использовать страницу сайта, а где-то сторонний материал точнее отвечает на вопрос пользователя. Рассказываем пошагово, как определить, какой случай — ваш, и что проверить.

12 ноя 2026
60 808
Как понять, что контент работает: метрики, атрибуция и связь с продажами

20 000 просмотров — это успех? Зависит от того, зачем писали статью. Если ради заявок, просмотры ни о чем не говорят: важнее, сколько читателей оставили обращение и сколько из них оказались целевыми. Разобрали, какие метрики ставить под каждую цель, где искать их в системах аналитики и как довести данные до сделки в CRM.

11 ноя 2026
1 022
Кого цитируют AI, когда малый бизнес спрашивает о продвижении: исследование TexTerra

Блоги агентств дают всего 22% ссылок в ответах нейросетей о продвижении малого бизнеса, а блоги сервисов и площадок — уже 34%. Причем у агентств своя точка входа: больше половины цитат приходятся на статьи о продвижении в конкретных нишах. Исследовали ответы нейросетей и выяснили, какие материалы агентств попадают в источники и что из этого следует для вашего блога.

Смотреть все статьи

У вас есть деловой запрос? Давайте обсудим!

Оставьте свои контакты, мы свяжемся с вами в ближайшее время.