Как мы собрали среду для AI-ассистированной разработки приложений Битрикс24

Привет, меня зовут Владимир Верхотуров, я занимаюсь DevRel в Битрикс24, а именно обеспечиваю связь внешних разработчиков (партнёры/клиенты) и внутренних команд, чтобы интеграции и решения на базе REST и других инструментов запускались быстро, стабильно и предсказуемо. И в этой статье я хочу рассказать о стартер-ките AI-ассистированной разработки, который мы создали, чтобы ускорить и немного упростить вывод новых продуктов на Маркетплейс приложений Битрикс24.

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

Эти задачи особенно чувствительны в тиражируемых продуктах. Приложение должно выдерживать нагрузку от сотен или тысяч клиентов. Любая неточность в архитектуре превращается в проблему в момент масштабирования.

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

Архитектурный контур стартер-кита

Стартер-кит формирует полный рабочий стек, где каждый слой выстроен так, чтобы приложение развивалось в согласованной среде. Архитектура не ограничивается набором технологий — она задаёт форму взаимодействия между ними.

Frontend

В основе клиентского слоя — официальный UI Kit, построенный на Nuxt. Соответственно, в режиме разработки это сильно упрощает отладку. А для прода фронт собирается в статику, максимально снижая нагрузку на серверную инфраструктуру владельца приложения.

Проект уже содержит:

• layouts для слайдеров и размещений;

• middleware, управляющее инициализацией контекста портала;

• batch-механику для ускоренного получения данных.

Клиент опирается на JWT-токен, который выдаёт бекенд. Это формирует чёткий и безопасный механизм обмена данными, который прекрасно работает в контексте iframe, несмотря на все ограничения, накладываемые современным браузерами.

Из нашего опыта, вопрос «как передавать контекст из пользовательского интерфейса в бизнес-логику на бекенде» один из наиболее частых для разработчиков, впервые сталкивающихся с iframe. Мы заложили проверенный механизм в наш стартер, чтобы это не вызывало никаких сложностей.

Backend

Сервер реализован в трёх вариантах:

• PHP;

• Python;

• Node.js.

Все варианты следуют одному API-контракту: единый набор маршрутов, одинаковая схема аутентификации и единые принципы работы с SDK Битрикс24. Структура каталогов и организация кода также унифицированы. Благодаря этому приложения в любой из реализаций развиваются по одному и тому же сценарию. Остаётся только выбрать нужный вариант бека на старте проекта.

Инфраструктура

Инфраструктурный слой включает:

• PostgreSQL 17 — для установок и рабочих данных;

• Cloudpub — публичный туннель, необходимый для интеграции с Битрикс в режиме разработки на локальной машине;

• RabbitMQ — очередь для асинхронных операций;

• Docker Compose — стандартный инструмент, который поднимает весь стек единым набором контейнеров.

Сервисы запускаются в фиксированной последовательности, общий контур воспроизводим на любой машине. Это важное условие для стабильной разработки, когда среда работает одинаково у всей команды.

Отдельно отмечу, что запуская стартер разработчик сразу получает HTTPS адрес для локальной разработки приложения. Таким образом, мы решаем проблему требования HTTPS для локальных приложений — разработчик сразу получает публичный URL с SSL-сертификатом.

Инструкции и слой знаний

Отдельный элемент архитектуры — каталог инструкций, сформированный как навигационная система для разработчиков и AI-агентов.

Внутри него описаны:

• особенности каждого языка;

• правила работы с очередями;

• структура фронтенда;

• паттерны SDK;

• требования к качеству кода.

Центром служит файл instructions/knowledge.md, который задаёт карту проекта и сокращает путь к нужным разделам. Благодаря этому стартер-кит работает как самоописанная система: код и инструкции поддерживают друг друга и обеспечивают единый контекст для всех участников разработки.

Почему это важно?

При генерации кода AI часто опирается на общедоступные практики, которые могут противоречить внутренней логике конкретного проекта. Загружая knowledge.md в контекст агента, разработчик гарантирует, что сгенерированный контроллер или сервис будет соответствовать принятым стандартам (например, использовать конкретный DTO или Middleware), что существенно снижает количество ошибок на этапе Code Review.

UI Kit

Одним из ключевых элементов стартер-пака является постоянно дорабатывающийся UI Kit, который играет важную роль в создании интерфейсов в рамках экосистемы Битрикс24. Этот инструмент позволяет разработчикам обеспечивать единообразный стиль и пользовательский опыт в приложениях, что способствует плавному переходу между различными частями портала.

В результате приложения, построенные с использованием UI Kit, интегрируются в общий интерфейс Битрикс24, обеспечивая пользователей удобством и предсказуемостью взаимодействия.

Функциональные возможности

Стартер-пак задаёт прикладные механизмы, которые позволяют сосредоточиться на логике продукта, а не на предварительной технической настройке.

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

Единый набор API-маршрутов

В проекте уже определён минимальный набор эндпоинтов:

• /api/health;

• /api/install;

• /api/getToken;

• /api/list;

• /api/enum.

Они реализованы одинаково в трёх стеках. Это исключает расхождения и служит точкой опоры для всей прикладной логики.

Авторизация Битрикс24

Поддержана полная цепочка:

• получение и фиксация установочных данных (AUTH_ID, REFRESH_ID, member_id, DOMAIN);

• генерация сервером собственного JWT;

• работа фронтенда в контексте токена;

• обновление истекающих данных через SDK.

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

Интеграция клиентской части

Фронтенд изначально адаптирован к среде Битрикс24:

• работа в клиентском режиме (*.client.vue);

• поддержка размещений и слайдеров;

• корректное поведение в iframe;

• batch-вызовы и единая модель состояния на Pinia.

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

Версионность проекта

Зачастую, публикация приложения - это выпуск MVP, проверка продуктовой гипотезы. И когда оказывается, что предложенный функционал интересен пользователям, перед разработчиком встает вопрос, а как развивать свой код дальше? И может оказаться, что изменения достаточно большие, чтобы потребовался выпуск мажорной версии. При этом существующие пользователи обновляются нелинейно, а значит, какое-то время нужно, чтобы работал и старый, и новый код. Появляются версии одного и того же приложения.

Стартер-пак поддерживает такие параллельные версии приложения:

• создание через scripts/create-version.sh;

• управление через make create-version;

• выбор версии в процессе dev-init.

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

Фоновые процессы

Вторая частая боль разработчиков решений — масштабирование. Особенно это касается сценариев, связанных с обработкой REST-событий, действий бизнес-процессов и роботов CRM. Эта нагрузка непредсказуема, но самое важное - нельзя терять такие вызовы, потому что Битрикс24 не делает ретраев в этих сценариях. Поэтому очень важно сразу закладывать в архитектуру правильные подходы, и входящая очередь, в данном случае, ключевой элемент.

В стартере очередь реализуется с помощью готового менеджера - RabbitMQ, который подключается по профилю queue.

Платформа предоставляет:

• брокер сообщений;

• панель управления;

• логи и изолированные воркеры.

Каждая серверная реализация имеет собственные инструкции по созданию обработчиков. Такая архитектура поддерживает масштабирование и перенос длительных операций в асинхронный контур.

Инструменты инженерного цикла

Стартер-пак содержит унифицированный набор команд:

• make dev-init, make dev-php, make dev-python, make dev-node;

• make prod-*;

• make queue-up, make queue-down;

• make security-scan.

Чтобы не заставлять AI агентов и разработчиков использовать длинные команды docker compose, мы завернули всё в Make. Одной командой make dev-init поднимается база, очередь, туннель и бэкенд на выбранном языке программирования. AI-агенту достаточно сказать "запусти проект", и он знает, какую команду вызвать.

Docker-стек и организация сервисов

docker-compose.yml описывает взаимодействие всех компонентов проекта. Конфигурация сформирована так, чтобы среда поднималась воспроизводимо и в нужной последовательности.

Сервисы стека

PostgreSQL 17 (database)
Контейнер поднимается с init.sql, включает healthcheck и отдельный каталог логов. Это обеспечивает стабильное состояние базы при каждом запуске.

RabbitMQ (rabbitmq)
Активируется профилем queue. Предоставляет инструменты для работы с задачами и панель управления.

Frontend (frontend)
Nuxt 3 с Битрикс24 UI Kit. Контейнер работает через volume-маунты в dev-режиме и через сборку в prod-режиме. Внутренний порт обеспечивает связь с серверными сервисами.

Cloudpub (cloudpub)
Создаёт публичный домен для режима разработки на локальной машине. Используется dev-init, который автоматически подключает туннель для корректной работы приложения в Битрикс24.

API-контейнеры (api-php, api-python, api-node)
Выбор стека осуществляется профилями. Подключают код через volume и стартуют после успешного healthcheck базы.

Особенности конфигурации

• единая внутренняя сеть internal-net;

• профили для выбора нужного набора сервисов;

• зависимость API от готовности базы через healthcheck.

Конструкция делает окружение предсказуемым: проект поднимается одинаково на любом рабочем месте.

Кому и для чего предназначен стартер-кит

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

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

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