Причины миграции
Команда столкнулась с нестабильной работой портала документации на GitBook. Проблема усугубилась глобальной миграцией пользователей с MS SQL на PostgreSQL, что сделало использование зарубежного облачного сервиса рискованным. В условиях, когда документация является частью контура поддержки CRM-платформы, любая недоступность справки напрямую увеличивает нагрузку на специалистов поддержки.
В качестве альтернативы был выбран Diplodoc — инструмент с поддержкой подхода «документация как код». Он позволяет хранить Markdown-файлы в Git, использовать Pull Requests для ревью и расширенную разметку Yandex Flavored Markdown (YFM). Это позволило интегрировать процесс написания документации в привычный рабочий цикл разработчиков.
Использование ИИ и протокола MCP
Для переноса данных не использовались самописные конвертеры или регулярные выражения. Вместо этого к MCP-серверу GitBook был подключен агент Claude. Благодаря открытому стандарту Model Context Protocol (MCP), модель получила прямой доступ к содержимому страниц через интерфейс, не требуя предварительной выгрузки файлов или нарезки данных на части.
Агент самостоятельно обошел структуру документации, вычитал содержимое и сконвертировал разметку в формат YFM, выстроив дерево страниц под новую систему. Процесс проходил в режиме взаимодействия человека и ИИ: агент вносил правки, а человек проверял визуальный результат, так как ошибки в отрисовке (отступы, видеоплееры, адаптивность) невозможно заметить при чтении диффов в Git.
Границы возможностей ИИ
Несмотря на высокую эффективность, агент не обладает правом на самостоятельный коммит в репозиторий — финальное решение о слиянии изменений всегда остается за человеком. Основная задача ИИ — работа со структурой и логикой разметки, в то время как визуальный контроль (проверка корректности отображения блоков, таблиц и элементов на разных устройствах) остается за специалистом.