Как ИИ генерирует учебные примеры: кейс Bitrix24, где онбординг разработчиков ускорился в 3 раза

Проблема, которая съедает месяцы: разработчик пришел, а разбираться не в чем

Новый разработчик приходит в проект. Ему показывают репозиторий на миллион строк кода, кидают ссылку на документацию (если она есть). Дальше — как повезет. Он тратит недели, чтобы понять, как работает какой-нибудь критичный, но плохо задокументированный модуль вроде Service Locator. Старшие разработчики отрываются от своих задач, чтобы объяснить одно и то же десятому новичку. Продуктивность всей команды проседает.

В Bitrix24 с этой проблемой столкнулись в лоб. Их кодовая база — огромная экосистема. Онбординг нового разработчика мог затягиваться на месяцы. Классическая документация часто описывала что делает метод, но почти никогда — как и зачем его использовать в реальной жизни, с какими edge-кейсами столкнешься.

Решение: не писать примеры вручную, а заставить ИИ их извлекать из кода

Команда поставила задачу: создать библиотеку учебных примеров (tutorials) для ключевых архитектурных паттернов и модулей. Писать вручную — годы. Решили автоматизировать с помощью ИИ.

Идея проста до гениальности: скормить ИИ исходный код модуля и существующую (пусть и скудную) документацию. А затем попросить его не просто пересказать, а сгенерировать понятные, практические примеры использования, которые показывают паттерн в действии.

Основной инструмент: GPT-4o (актуальная версия на начало 2026 года). Почему не специализированные код-модели вроде Qwen Coder? Потому что задача — не написать код, а объяснить его. Нужна модель с сильными способностями к естественному языку, которая умеет структурировать информацию и создавать нарратив. Про разницу в подходах мы писали в статье «ИИ как младший коллега».

1 Подготовка сырья для ИИ: что нужно собрать

ИИ — не волшебник. Мусор на входе — мусор на выходе. Первый шаг — собрать контекст.

• Исходный код модуля (например, класса ServiceLocator). Весь, со всеми публичными и защищенными методами.
• Существующая документация (PHPDoc, README, внутренние wiki). Даже если она формальная.
• Примеры использования в реальных проектах. Это ключевое. Нужно найти 3-5 реальных мест в кодовой базе, где этот модуль уже используется. ИИ проанализирует их и поймет контекст.
• Список частых ошибок, которые делают разработчики при работе с этим модулем. Можно взять из истории code review или тикетов в Jira.

2 Конструирование промпта: от простого к сложному

Вот как выглядел эволюционировавший промпт для генерации примера использования Service Locator в Bitrix24:

Плохой промпт (получите общие фразы):

Напиши пример использования Service Locator в Bitrix24.

Хороший промпт (получите рабочий код):

Ты — senior разработчик Bitrix24. Обучаешь нового сотрудника.

Контекст:
1. Исходный код класса \Bitrix\Main\ServiceLocator (приложен).
2. В кодовой базе он используется для получения сервисов: EventManager, Cache, Database.Connection.
3. Частая ошибка новичков: пытаются создать экземпляр сервиса через `new`, а не получать его через локатор.

Задача: Созжи учебный пример (tutorial) для онбординга.
Структура:
- Краткая суть паттерна "Service Locator" в контексте Bitrix24 (1 абзац).
- Пример №1: Получение сервиса EventManager и подписка на событие.
- Пример №2: Работа с кешем (Cache) — сохранение и получение данных.
- Пример №3: Что будет, если запросить несуществующий сервис (обработка ошибки).
- Раздел "Частые ошибки": с примерами неправильного кода и исправлениями.

Код должен быть готов к запуску в среде Bitrix24. Используй актуальное API на 2026 год.

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

3 Валидация и доработка: ИИ пишет, человек правит

Сгенерированный пример — не истина в последней инстанции. Его нужно проверить.

1. Запустить код. Да, просто скопировать и выполнить в тестовом окружении. Многие упускают этот шаг, а потом получают примеры с устаревшими методами. Автоматизировать эту проверку можно через инструменты вроде BigCodeArena.
2. Проверить на соответствие best practices проекта. ИИ может сгенерировать рабочий, но неидиоматичный для вашей кодовой базы код.
3. Добавить нюансы, которые ИИ мог упустить. Например, особенности конфигурации в продакшене vs разработке.

В Bitrix24 на этом этапе подключался senior-разработчик. Он тратил не 2 часа на написание примера с нуля, а 15 минут на проверку и правку результата ИИ. Выигрыш в времени — 85-90%.

Конкретный результат: как выглядел учебный пример по Service Locator

Вот фрагмент того, что в итоге получили разработчики Bitrix24 (упрощенно):

// Учебный пример: Работа с кешем через Service Locator
// ====================================================

// 1. Правильно: получаем сервис кеша через локатор
$cacheService = \Bitrix\Main\ServiceLocator::getInstance()->get('cache');

// Ключ для кеширования
$cacheKey = 'user_profile_' . $userId;
$cacheTtl = 3600; // 1 час
$cachePath = '/user/profiles/';

// Пытаемся получить данные из кеша
if ($cacheService->initCache($cacheTtl, $cacheKey, $cachePath)) {
    $profileData = $cacheService->getVars();
    echo "Данные загружены из кеша\n";
} elseif ($cacheService->startDataCache()) {
    // Данных в кеше нет, запрашиваем из базы
    $profileData = fetchUserProfileFromDatabase($userId);
    
    // Сохраняем в кеш
    $cacheService->endDataCache($profileData);
    echo "Данные загружены из БД и сохранены в кеш\n";
}

// 2. Частая ошибка: НЕ делайте так (прямое создание объекта)
// $cacheService = new \Bitrix\Main\Data\Cache(); // ОШИБКА!
// Почему: это обход общего контекста и конфигурации, может привести к проблемам с зависимостями.

Пример сразу показывает как делать, объясняет почему именно так и предупреждает о типовой ошибке. Это именно то, что нужно новичку.

Главные нюансы и подводные камни (чтобы не наступить)

Итог: цифры и эффект для Bitrix24

За полгода команда сгенерировала и внедрила более 120 таких учебных примеров для ключевых модулей.

• Время онбординга нового middle-разработчика сократилось с ~3 месяцев до ~1 месяца.
• Количество вопросов от новичков к старшим коллегам по базовым темам упало на ~70%.
• Затраты senior-разработчиков на создание обучающих материалов снизились в 3-4 раза.

Самое интересное — побочный эффект. Пока ИИ «объяснял» код разработчикам, он находил внутренние противоречия в самой кодовой базе и устаревшие подходы. Несколько таких примеров стали триггером для рефакторинга.

Этот подход убивает двух зайцев: ускоряет онбординг и запускает процесс улучшения документации. Как показывает кейс Tailwind CSS, если вы не сделаете вашу документацию полезной и удобной, разработчики уйдут к ИИ-ассистентам, которые дадут им ответ, возможно, не самый лучший. Лучше самим контролировать этот нарратив.

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