Рассказываем на опыте команды Битрикс24, как создать AI-конвейер для документации, как оценивать его эффективность и чему теперь учить технических писателей.Как устроен конвейерНаш отдел документации сильно эволюционировал: от типичной работы руками и долгих ожиданий ответов от разработчиков мы перешли к работе с AI, а производительность выросла в среднем в 5,5 раза. Мы начали с простой задачи: уменьшить зависимость от отдела разработки, а на выходе получили цикл AI-производства контента с несколькими уровнями проверки и оценки текстов.По сути это конвейер из нескольких самостоятельных скиллов. У нас несколько документационных продуктов, и у каждого свой набор скиллов под конкретную специфику. Самый развернутый конвейер работает на REST-документации.AI генерирует статью по исходному коду и сразу проверяет ее на тестовом портале: делает настоящий запрос к API. Из полученных тестовых данных удаляется все чувствительное: домен подменяется на тестовый, вычищается ID пользователя, код вебхука, потенциальные секреты.Отдельный скилл сверяет с кодом все указанные в новом тексте методы, параметры, типы, обязательность, поля ответа, коды ошибок. Скилл сверки выдаёт отчёт, расхождения исправляются, и сверка запускается заново.Дальше AI-агент использует скиллы, которые проверяют текст по смыслу и формальным правилам, и финально убирают технические огрехи. Всю цепочку запускает оркестрирующая команда: при необходимости она повторяет сверку с кодом и доработку текста, но ограниченное число раз — если ошибки остались, решение принимает человек. На выходе технический писатель получает готовый текст и его оценку по трем параметрам: соответствие коду, качество текста, техническое качество. В зависимости от оценки AI-агент присваивает статье статус: готова к публикации, нужна доработка или не прошла проверку.Как настроить процесс AI-генерации контентаПереходить на работу с AI-агентами лучше постепенно. Сделать резкий переход за несколько дней от ручного написания к автоматической генерации вряд ли получится: на разработку новых инструментов и перестройку процессов понадобится время, недели или даже месяцы.Мы проходили этот путь поэтапно. Сначала снизили зависимость от разработчиков, научив технических писателей самостоятельно вызывать новые методы API в тестовой среде и смотреть, что они возвращают на самом деле, затем постепенно стали передавать эту задачу AI и параллельно учились писать скиллы, а затем объединять их в последовательную цепочку действий.Учим технических писателей работать без помощи разработчиковВо многих командах процесс создания документации выглядит так:выходит новый метод,у техписателя появляется список вопросов по нему,он отдает их разработчику этого метода,разработчик отвечает,писатель оформляет ответ по стандартам и публикует на сайте документации.Так было и у нас — внутри команды это буквально называлось «оформить доку»: писатель не проверял метод сам, а причесывал чужой ответ.Первое, что стоит сделать, чтобы сократить зависимость от разработчиков, — научить технических писателей самих проверять новые элементы кода, которые требуют описания в документации. Для этого мы рекомендуем включить в команду специалиста из технической поддержки. Он сможет показать, как самостоятельно провести проверку в тестовой среде, как понять, что запрос и ответ работают корректно, и как из результатов проверки собрать описание и опубликовать его.После того, как мы подключили к команде технического специалиста, наши техписатели стали приходить к разработчикам только по двум поводам: если ловили баг или если нужен был точечный ответ на конкретный технический вопрос.Это сильно упрощает жизнь команде, и разобравшись как следует в новом процессе, вы начнете постепенно делегировать эти задачи AI-агентам.Последовательно подключаем AI-агентовНачать можно с отдельных промптов и запускать их вручную. Это поможет понять, как работает AI, скорректировать задачи. Затем постепенно создавайте тематические блоки инструкций с конкретными триггерами «если задача такая-то, сначала открой инструкцию для такого-то шага». Это станет основой для формирования скиллов AI-агента.Мы шли по такому же пути — сначала учились писать большие промпты, затем разбирались со скиллами, и, наконец, смогли переписать каждую инструкцию в самостоятельный скилл, который агент подключает сам, по смыслу задачи, а не по прямой команде человека.Следующий шаг — научить скиллы объединяться в конвейер. Тогда весь процесс сверки с кодом, работы с текстом и финальной чистки будет выполняться уже не вручную: вам не придется запускать агента для каждой задачи. У нас за работу конвейера отвечает оркестрирующая команда, которая прогоняет нужные скиллы друг за другом сама, в том числе с ограниченным числом повторных попыток.Для разных типов контента можно собирать собственные конвейеры, со своими специализированными шагами, но логика подключения агентов будет одинакова: сначала технический писатель учится все делать вручную, затем готовит общую письменную инструкцию, потом пишет отдельные скиллы, и затем создает автоматическую оркестровку.Как правильно работать со скиллами для AI-конвейера документацииХранениеХранить скиллы удобнее в общем внутреннем git-репозитории, едином для всей команды. Если вы создаете документацию для нескольких продуктов, заведите для каждого свою папку: в ней лежат скиллы — каждый в отдельной папке со своим инструктивным файлом — и общие правила продукта.Дальше важно, как эти скиллы попадают к человеку. Скорее всего сотрудники работают не одновременно со всеми продуктами, для которых пишется документация, а каждый со своим. Поэтому каждый в своем файле настроек указывает пути только к тем проектам, с которыми реально работает. После обновления репозитория сотрудник запускает скрипт синхронизации: он читает эти настройки и раскладывает актуальные скиллы по указанным проектам, а проекты без пути просто пропускает. Скиллы копируются в служебную папку, исключенную из git, — поэтому в открытые репозитории документации попадает только готовый текст, а не логика генерации и проверки.НаписаниеСкилл — это не просто текстовая инструкция, а файл с коротким именем и точным описанием: когда именно агент должен его подключить, а когда — нет. Например, «используй для таких-то запросов», «не используй, если речь только о примере кода — для этого отдельный скилл». Дальше в файле следует пошаговая инструкция, что агент должен делать на этом шаге. У части скиллов в папке лежат вспомогательные файлы, на которые ссылается основная инструкция, например, отдельный файл с правилами перевода или чек-лист критериев для конкретного типа страницы.Новый скилл добавляется в общее хранилище стандартным способом. Папка с инструкцией помещается в раздел репозитория того продукта, для которого предназначен скилл. Затем изменения сохраняются и отправляются в общий репозиторий. При следующем обновлении и синхронизации скилл появляется у всех, кто подключил этот продукт, без ручной рассылки файлов. Достаточно один раз добавить скилл в общее хранилище, и он сам разойдется по рабочим местам.ИспользованиеДля каждого проекта создайте локальную инструкцию, которую агент будет читать перед началом работы. Так вам не придется каждый раз вручную указывать агенту, какой скилл запустить: он сам сопоставит задачу с описаниями скиллов и откроет подходящий. Если вы создаете страницы разных типов, зафиксируйте в инструкции четко, какой скилл обязателен для конкретного типа. Отдельные скиллы можно также объединять в конвейер: одна оркестрирующая команда прогоняет нужные шаги друг за другом сама, а не человек вручную запускает их по одному.Мы сознательно держим скиллы разных продуктов в одном репозитории и переиспользуем наработки между ними, а не пишем параллельно похожие скиллы для каждого продукта по отдельности.Как оценивать эффективность перехода на AI-генерациюМы рекомендуем считать производительность по единицам контента на человека. За единицу контента логичнее всего взять страницу, которую подготовил и опубликовал технический писатель. Это может быть описание метода, обзорная страница, туториал, урок курса.Для нас количественный показатель принципиально важен, так мы видим, насколько быстрее и больше мы стали выдавать контента. Показательнее всего сравнение год к году. Например, в августе 2025 г. мы создавали в среднем 20,7 единицы контента на человека, в августе 2026-го — 113,6. За год производительность выросла в 5,5 раза.Но у количества есть обратная сторона — с помощью AI можно быстро нагенерировать очень много плохого контента. Поэтому как только вы увидите, что скорость выросла, подумайте над тем, как измерять не только объем, но и качество. Самый рабочий вариант — разработать критерии качества для каждой страницы и оценивать их, например, от 1 до 10. В оценку могут войти такие критерии, как обнаруживаемость методов, полнота описания параметров и структуры ответа, примеры кода, коды ошибок и др. Для разных типов материалов они могут отличаться.У нас есть собственная метрика AI Friendly Index (AFI). Это оценка по 100-балльной шкале, которая формируется из 10 критериев. Она показывает, хватает ли странице информации, чтобы по ней можно было написать рабочий код, не заглядывая в исходники. AI-агент сам оценивает подготовленный текст по этой метрике и если баллов не хватает, он не просто ставит низкую оценку, а показывает список конкретных проблем и что именно нужно поправить.Количественную метрику мы советуем вводить не саму по себе, а сразу вместе с метрикой качества вроде AFI, иначе рост цифр будет не показательным, ведь страницы можно нагенерировать быстро, но плохо.Кроме того, мы рекомендуем все также вычитывать готовые тексты, с AI-генерацией проверка готового черновика будет занимать у вас меньше времени. А в спорных ситуациях вы по-прежнему можете прийти с точечным вопросом к разработчику — таких обращений станет меньше, но они не исчезнут совсем.Как поменялась профессия технического писателя и к чему теперь их готовитьС появлением в отделе AI-инструментов задачи технического писателя полностью поменялись. Теперь он не пишет и не редактирует ответы разработчика. Он выстраивает процесс работы AI-агентов: создает скиллы и проверяет результат.Мы полностью перешли на AI-генерацию. Раньше каждый сотрудник в отделе назывался технический писатель, сейчас это AI-контент-инженеры. Да и сама наша команда документации неофициально переименовалась в команду AI-контента.Если раньше заметная часть дня техписателя уходила на ожидание ответов от разработчика по новой теме, то сейчас у нашей команды стало больше сосредоточенной проверки: контент-инженер читает уже подготовленный и сверенный с кодом текст, ищет, где агент ошибся или додумал лишнее. Эта работа требует новых навыков, которых раньше в профессии не было.Первый навык — вычитка и фактчекинг чужого, сгенерированного текста. Это совсем не то же самое, что вычитка своего: AI-черновик читаешь более подозрительно, специально ищешь, где агент мог додумать за автора. У этого навыка свой предел выносливости, теперь сотрудники устают по-другому и быстрее, чем от самостоятельного написания текста. Когда вы начнете писать документацию с помощью AI, вам придется выработать новый рефлекс — перестать читать текст как читатель и начать читать его как проверяющий. На формирование новой привычки уйдет несколько недель.Второй навык — формулирование и донастройка инструкций для агента. По сути, техписатель теперь не только пишет документацию, но и описывает правила, по которым агент будет писать и проверять ее в следующий раз.РекомендацииСовет сотрудникам. Осваивайте в первую очередь не инструменты как набор кнопок, а два новых навыка — критичное чтение сгенерированного текста и способность превратить разовое замечание в правило, которое затем можно зашить в инструкцию агенту, а не повторять вручную каждый раз.Совет руководителям. Не делайте переход одномоментным, начните со снижения зависимости от разработчиков, если у вас она есть, затем обучите команду самостоятельно проверять работу методов, и только потом передавайте генерацию агенту.Совет тем, кто пишет скиллы. Двигайтесь поэтапно: проще взять один небольшой скилл и довести его до отличной, стабильной работы, а потом постепенно добавлять к нему следующие, чем сразу тратить недели на настройку сложной системы из множества скиллов и в итоге не получить нигде идеального результата.