Привет! Меня зовут Игорь Росляков, я технический писатель. По приглашению руководителя направления «Маркет и интеграции» Сергея Вострикова готовлю цикл статей на тему ИИ-ассистированной разработки решений для Битрикс24.
Сегодня — 6-я статья. Почти все проекты мы делаем на основе одного репозитория b24-ai-starter, который служит базой для разработки приложений. В нём уже есть все инструкции для ИИ, которые облегчают работу агентов. Рассказываем, почему это удобно и полезно и вообще достойно того, чтобы стать стандартом разработки.
Сегодняшняя статья больше про теорию, но в других статьях много практических материалов, которые можно взять за основу и использовать в своём портале — например, их можно показать своим разработчикам или использовать самому. Что было в предыдущих туториалах:
Пишем первое приложение с AI-стартером, чтобы видеть прибыли и убытки
Добавляем в бизнес-портал Битрикс24 роботов для автоматизации
Что даёт воспроизводимая среда разработки и как развернуть контейнеры на VPS.
Анализ и модернизация коннектора баз данных с помощью AI-агентов
Что будет в этой статье:
Что такое Starter Kit
Starter Kit или стартер-кит — это стартовый комплект, в котором собраны типовые элементы для быстрого запуска: шаблоны, конфигурации, примеры, документация, зависимости или физические компоненты. Такие комплекты бывают в разработке, тестировании, обучении, работе с микроконтроллерами и вообще в любой области. Их задача — сократить путь от «я хочу попробовать» до «у меня уже что-то работает».
Это не новая идея, стартер-киты придумывают, собирают и пишут уже довольно давно. Например, в виде книг с дополнительными цифровыми пособиями:
Есть стартер-киты, которые можно потрогать и использовать руками. Например, набор для обучения микроконтроллерам на Raspberry Pi. По смыслу это не просто коробка деталей, а учебная лаборатория: плата Pico 2 W, макетная плата, провода, резисторы, кнопки, светодиоды, дисплеи, датчики, моторчики, пульт, RFID-модуль, ультразвуковой датчик, джойстик и другие компоненты:
В разработке стартер-кит — это подготовленный каркас проекта с уже выбранной структурой, зависимостями, настройками окружения и базовыми сценариями запуска. Он помогает не тратить время на настройку одних и тех же вещей и сразу работать в рамках нужных соглашений.
Хороший стартер-кит ускоряет старт и задаёт единый подход к разработке. Это особенно удобно, если вы создаёте проект для конкретной платформы. Пример: стартер-киты Vercel — облачной платформы для деплоя и хостинга веб-приложений, особенно фронтенд и фуллстек. Используя эти стартеры, человек быстрее создаёт проект, и само приложение изначально заточено под Vercel.
Ещё стартер-киты сильно упрощают ИИ-разработку, потому что нейросетям проще работать с уже подготовленной хорошей структурой: готовые компоненты, роутинг, стили, API-слои, auth, база. А если агенту дать только абстрактную задачу и неограниченный доступ к репозиторию, результат будет зависеть от того, как сама нейросеть интерпретирует структуру проекта.
Что даёт b24-ai-starter
Стартер-кит приложений Битрикс24 помогает пользователю быстрее создавать кастомизации для своих порталов. Вот что это может быть:
Структура проекта
Наш стартер задаёт базовую структуру проекта, workflow и окружение для разработки с помощью ИИ-агентов. У нейросети сразу есть не просто исходный код, а навигация по проекту, инструкции по стеку и готовые сценарии работы.
Разработчику — или любому другому пользователю — не нужно придумывать, где будет фронтенд, как отделить бэкенд, куда вынести инфраструктурные файлы и где хранить инструкции. Эти решения уже приняты до старта. Это значит не то, что проект нельзя менять, а только то, что у пользователя сразу есть исходная форма, от которой можно отталкиваться.
Дальше эта структура превращается в архитектурные правила: если проект растёт, важно не только добавлять новое, но и сохранить понятное разделение ответственности между частями приложения.
Окружение
Для приложения Битрикс24 особенно важно локальное окружение, потому что приложение должно работать не просто у разработчика на компьютере, а внутри контекста портала.
Чтобы приложение работало на платформе в вашем аккаунте, нужны публичный URL, корректные переменные окружения, токены, бэкенд, фронтенд и база данных. Стартер-кит собирает эти элементы в единый воспроизводимый контур, и разработчик в итоге запускает подготовленную среду, приближенную к реальному сценарию работы приложения. Какой именно сценарий — зависит от конкретного приложения, но стартовая ситуация всегда в том, чтобы просто портал Битрикс24 зарегистрировал ваше приложение и мог обмениваться с ним запросами.
Контекст для AI-агента
Можно сказать, что разработчик получает стартовую кодовую базу, а нейросеть получает ещё и карту этой базы.
В стартере есть отдельный слой инструкций: не только README для человека, но и навигация для агентов. ИИ лучше понимает, где искать информацию, какой стек выбран, какие команды запускать, как устроено приложение и какие решения уже приняты в проекте. Поэтому агент работает внутри заранее подготовленного контекста.
Архитектурные правила
В проекте заранее определены основные границы системы:
Что дают архитектурные границы разработчику
Стартер фиксирует архитектурные правила, но не запрещает развитие проекта, а задаёт понятное место для новых частей. Проект показывает, что приложение состоит из нескольких слоёв: фронтенд, бэкенд, инфраструктура и инструкции для разработки. Eсли разработочику нужен бэкенд на языке, которые не представлены в стартере, он должен будет добавить свою папку в backends/ и предложить агенту сформировать нужный бэкенд в рамках уже заложенных в стартер контрактов между фронтом и беком.
Что дают архитектурные границы ИИ-агенту
Архитектурные правила нужны не только человеку, но и агенту. Чем понятнее карта проекта, тем лучше работает нейросеть. Без карты ИИ начинает достраивать её сам: предполагает структуру, выбирает место для новых файлов, интерпретирует naming. Поэтому для ИИ-ассистированной разработки архитектурные правила важны не меньше промпта. Получается, что промпт описывает задачу, а стартер-кит задаёт пространство для реализации.
В нашем стартере архитектурная структура дополнена инструкциями, которые работают вместе со структурой. Структура показывает агентам дерево файлов, а инструкции объясняют, как с этим работать.
Например, создание виджета:
Такая инструкция помогает создавать приложения со встройкой в свой портал, например дашборды с дополнительной информацией:
Какие архитектурные правила можно стандартизировать в стартере
В стартер-ките можно стандартизировать многие вещи, которые обычно расползается в проектах при быстрой разработке.
Структура проекта: фронтенд, бэкенд, инфраструктура, инструкции и скрипты лежат в предсказуемых местах. Это упрощает навигацию и для человека, и для ИИ.
Docker и запуск окружения. Docker Compose использует профили: можно поднять фронтенд, нужный бэкенд, базу данных, CloudPub и RabbitMQ. Разработчик работает через Makefile, а не через набор случайных команд.
CloudPub — сервис, который даёт локальному приложению публичный HTTPS-адрес. Он нужен как туннель между Битрикс24 и локальной разработкой.
Naming и соглашения. Страницы frontend имеют суффикс .client.vue, компоненты Битрикс24 UI Kit используются с префиксом B24, эндпойнты бэкенда находятся под /api/*, переменные окружения описаны в .env.example.
API-контракт. Фронтенд не зависит от конкретного языка бэкенда. PHP, Python и Node.js могут реализовывать один и тот же набор endpoints.
Разделение frontend и backend. Фронтенд отвечает за интерфейс, Bitrix24 frame, placement, слайдеры и пользовательские действия. Бэкенд отвечает за установку приложения, хранение токенов, JWT, работу с базой и серверную интеграцию.
Работа с переменными окружения. .env.example задаёт единый список параметров: CloudPub, Bitrix24 OAuth, JWT, база данных, RabbitMQ, telemetry. Это снижает риск, что агент придумает новый способ конфигурации.
Безопасность
AI-агенты ускоряют не только разработку, но и появление ошибок. Если раньше небезопасное решение появлялось постепенно по мере ручной разработки, то теперь агент может за один запрос создать endpoint, Dockerfile, работу с токенами и конфигурацию окружения. Если в проекте нет заранее заданных правил безопасности, ошибка масштабируется так же быстро, как и полезный код.
Поэтому безопасность в ориентированный на разработку с нейросетями стартер-кит должна быть встроена в основу проекта: структуру, запуск, Docker-сборку, работу с секретами, API-контракт, проверки зависимостей и инструкции для агентов.
Как b24-ai-starter внедряет безопасные практики ещё до начала разработки
Стартер-кит полезен тем, что переносит часть security-решений, которые часто внедряют после проекта сразу на старте — то есть они уже есть до проекта. Так разработчик получает проект, где уже предусмотрены шаги и проверки, защищающие безопасность.
Что уже есть в проекте:
.env.example с ожидаемыми переменными окружения.
JWT-слой между фронтендом и бэкендом.
Разделение публичных и защищённых API endpoints.
Docker Compose profiles вместо ручного запуска сервисов.
multi-stage Dockerfile для фронтенда, Python и Node.js.
Отдельные security-команды в Makefile.
scripts/security-tests.sh как оркестратор проверок.
scripts/security-scan.sh для аудита зависимостей.
Инструкции для агентов, которые объясняют, как работать внутри заданной архитектуры.
Это не заменяет полноценный аудит конкретного приложения, но снижает вероятность того, что базовые вещи вообще забудут сделать. Можно сказать, что встроенная безопасность работает как инженерная страховка от случайности.
Как работают некоторые основные встроенные практики
Работа с секретами. Секреты не должны попадать в код, поэтому стартер использует .env.example как шаблон, а реальные значения хранятся в .env после инициализации. При таком подходе можно заранее стандартизировать переменные для JWT_SECRET, CLIENT_ID, CLIENT_SECRET, CloudPub, базы данных, RabbitMQ.
Multi-stage Docker builds. Контейнер — это часть attack surface. Чем больше лишних инструментов остаётся в runtime-образе, тем шире поверхность атаки. Multi-stage сборки позволяют отделять build-этап от production runtime и не тащить в финальный образ всё, что нужно только для сборки.
Валидация. Любой входящий payload должен проверяться. Это касается запросов от фронтенда, событий Битрикс24, вебхуков, данных установки приложения и параметров API. Стартер-кит может заранее задавать паттерн: минимальное количество публичных эндпойнтов, защищённые эндпойнты требуют JWT, а данные проходят через явную обработку. То есть нельзя брать входящий JSON и сразу использовать его.
Проверка зависимостей. Современный проект зависит от десятков пакетов — а часто и больше. Даже если собственный код надёжный, уязвимость может прийти через зависимость. Поэтому в стартер встроены команды для аудита зависимостей: Composer для PHP, pnpm для frontend/Node.js, дополнительные проверки через security scripts.
Автоматические проверки и CI-ready подход
CI могут воспринимать как «сервер, который запускает тесты после push». Но на практике это более широкая идея.
Continuous integration нужен, чтобы изменения в проекте регулярно проходили один и тот же набор проверок перед деплоем: код собирается, тесты запускаются, зависимости анализируются, секреты не попадают в репозиторий, Docker-образы не содержат известных уязвимостей.
Главная ценность этого процесса не в конкретной платформе, а в командах, которые проект умеет выполнять автоматически. Поэтому хороший starter-kit не должен навязывать определённую CI-систему. Лучше использовать более универсальный подход — подготовить проект так, чтобы проверки можно было запускать локально в Docker и затем без больших изменений перенести в любой CI pipeline.
Такой подход можно назвать CI-ready. Готового файла вроде .github/workflows/security.yml пока нет, но есть исполняемые команды, которые этот будущий pipeline сможет вызывать. Стартер превращает проект из набора файлов в воспроизводимую среду.
Готовый CI — следующий слой. Он может быть реализован в GitHub Actions, GitLab CI или Jenkins. Но когда в проекте уже есть Docker Compose, Makefile, .env.example и security scripts, CI не приходится заново изобретать правила запуска. Он просто использует те же команды, которые уже работают локально.
Стандартизированная разработка
Для реального проекта нужно, чтобы код можно было собрать, запустить и проверить в воспроизводимой стандартизированной среде. Иначе результат зависит от машины конкретного разработчика: версии Node.js, PHP или Python, локальных переменных окружения, установленных расширений, настроек базы данных и случайных файлов, которые есть только у него.
Проект должен быть подготовлен к воспроизводимой среде. Поэтому сначала нужно описать окружение как часть проекта: какие сервисы нужны, какие переменные обязательны, какие команды запускают фронтенд, бэкенд, базу данных, проверки и сборку.
На верхнем уровне в нашем стартере это работает так:
Docker описывает, какие сервисы нужны приложению.
Docker Compose собирает их в единую систему.
.env.example показывает, какие параметры окружения должны быть задан.
Makefile даёт стандартные команды.
Скрипты в
scripts/автоматизируют повторяемые операции.
В стартере в файле docker-compose.yml описаны основные сервисы: фронтенд, бэкенд на выбор — PHP, Python и Node.js, база данных на выбор — PostgreSQL или MySQL, CloudPub и RabbitMQ. Через профили можно поднимать только нужную часть системы: например, фронтенд с PHP-бэкендом и PostgreSQL или фронтенда с Python-бэкендом и очередью.
Makefile выступает как единая точка входа. Разработчику не нужно помнить длинные команды Docker Compose, он использует понятные сценарии:
make dev-php
make dev-python
make dev-node
make down
make security-testsЭто удобно для человека, но ещё важнее для автоматизации. CI-системе тоже проще вызвать одну стандартную команду, чем повторять сложную логику запуска внутри workflow-файла.
Кроме того, что это удобный и полезный шаблон проекта, стартер-кит помогает передать команде набор инженерных практик: как начать проект, как организовать код, как работать с окружением, как использовать AI-агентов в разработке.
Когда каждый проект начинается одинаково, команде проще масштабироваться. Новый разработчик быстрее понимает, где что лежит. Ревьюеру проще проверять изменения. Поддержке проще разбираться в чужом проекте. AI-агенту проще выполнять задачи, потому что структура и инструкции повторяются от проекта к проекту.
Observability
Observability — наблюдаемость системы. Это не то же самое, что простое логирование того, что произошло в системе. Observability пытается дать цельную картину: не только дать сигнал поломки, но и её детали, то есть где, у кого, после какого действия, насколько часто это повторяется.
Что это даёт и из чего получается
Если в системе реализована такая практика, специалист может получить ответы на важные для бизнеса и разработки вопросы:
Где пользователи застревают?
Какие действия выполняют чаще всего?
Какие порталы чаще сталкиваются с ошибками?
Сколько времени занимают API-вызовы?
Где растёт latency, задержка в ответах?
В какой момент обычная ошибка превращается в инцидент?
На практике observability обычно складывается из нескольких типов данных.
Логи помогают понять конкретные ошибки и события.
Метрики показывают численные показатели во времени: количество ошибок, скорость запросов, задержку ответов, нагрузку.
Трейсы помогают увидеть путь операции через разные части системы.
Продуктовые события показывают поведение пользователей: установка приложения, первое открытие, нажатие кнопки, прохождение онбординга, использование конкретной функции.
Observability в приложениях Битрикс24
В ориентированных на конкретные платформы приложениях наблюдаемость особенно полезна, потому что проблема может возникать не только в коде.
Ошибки и баги могут быть связаны с конкретным порталом, правами доступа, установкой приложения, Bitrix24 REST API, iframe-контекстом, сетевой инфраструктурой. Без наблюдаемости такие проблемы часто выглядят как несвязанные между собой: функция не работает, экран долго грузится, портал не регистрирует приложение. С observability эти сигналы можно связать в одну картину и найти источник проблем.
Что такое OpenTelemetry и зачем он нужен
OpenTelemetry — открытый стандарт для сбора логов, метрик и трейсов. Его главная идея в том, что приложение не должно быть жёстко привязано к конкретной системе мониторинга. Код отправляет данные в стандартном формате OTLP, а дальше их может принять отдельный сервис OpenTelemetry Collector и передать в хранилище или систему визуализации.
Мы планируем добавить к экосистеме стартер-кита отдельный проект на эту роль. Это будет соседняя инфраструктура наблюдаемости. Для неё уже предусмотрены переменные окружения в файле .env.example:
###> OpenTelemetry ###
# Единая точка включения/выключения телеметрии для backend и frontend.
# Используется PHP-бэкендом (TELEMETRY_ENABLED) и Nuxt-фронтом (NUXT_PUBLIC_TELEMETRY_ENABLED).
# OTel Collector должен быть запущен через b24-ai-starter-otel: cd ../b24-ai-starter-otel && make up
TELEMETRY_ENABLED=false
OTEL_EXPORTER_OTLP_ENDPOINT=http://host.docker.internal:4318
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <generate-your-token>
OTEL_SERVICE_NAME=b24-app
OTEL_SERVICE_VERSION=1.0.0
OTEL_ENVIRONMENT=development
# Профиль телеметрии: simple-ui | integration-sync | integration-with-migration | migrator-light | migrator-advanced | development
OTEL_TELEMETRY_PROFILE=simple-ui
###< OpenTelemetry ###Это будет работать так: приложение на базе стартера отправляет телеметрию наружу, а b24-ai-starter-otel принимает её, сохраняет и показывает в Grafana.
То есть приложение отправляет события и трейсы в OTel Collector. Collector принимает данные по OTLP, ClickHouse хранит их, а Grafana строит дашборды и алерты.
Что будем делать дальше
Мы остановились на теме observability — в следующий раз раскроем эту тему подробнее. Подробнее расскажем про проект нашего OpenTelemetry Collector и покажем, как его подключать к уже готовым приложениям на базе стартер-кита.
Содержание цикла статей про создание приложений с AI-агентами
Пишем первое приложение с AI-стартером, чтобы видеть прибыли и убытки
Добавляем в бизнес-портал Битрикс24 роботов для автоматизации
Что даёт воспроизводимая среда разработки и как развернуть контейнеры на VPS
Анализ и модернизация коннектора баз данных с помощью AI-агентов
Как стартер-кит может стать стандартом разработки