Монорепо как зеркало: когда Python и JS живут в одном доме

Монорепо как зеркало: Python + Next.js в одном проекте

Завязка

Представьте ситуацию: вы разработчик и в ваших руках проект voice-agent — голосовой помощник на основе Claude, построенный как монорепо. С одной стороны Python-backend (FastAPI, aiogram для Telegram), с другой — Next.js фронтенд (React 19, TypeScript 5.7) для Telegram Mini App. Звучит здорово, но вот в чём подвох: когда в одном репозитории живут две экосистемы с разными правилами игры, управлять ими становится искусством.

Развитие

Первой проблемой, которая выпрыгнула из неоткуда, была забывчивость переменных окружения. В Python проект использует pydantic-settings для конфигурации, но выяснилось, что эта библиотека не экспортирует значения автоматически в os.environ. Результат? Модульный код, читавший переменные прямо из окружения, падал с загадочными ошибками. Пришлось документировать эту ловушку в ERROR_JOURNAL.md — живом архиве подводных камней проекта, где уже скопилось десять таких «моментов истины».

Далее встал вопрос архитектуры. Backend требовал координатора — центрального паттерна, который бы оркестрировал взаимодействие между агентами и фронтенд-запросами. На бумаге это выглядело идеально, но в коде его не было. Это создавало технический долг, который блокировал Phase 2 разработки. Пришлось вводить phase-gate валидацию — автоматическую проверку, которая гарантирует, что прежде чем переходить к следующей фазе, все артефакты предыдущей действительно на месте.

В процессе появилась и проблема с миграциями базы данных. SQLite с WAL-режимом требовал аккуратности: после того как junior-агент создавал файл миграции, она не всегда применялась к самой БД. Пришлось вводить обязательный чек: запуск migrate.py, проверка таблиц через прямой SQL-запрос, документирование статуса. Без этого можно часами отлавливать фантомные ошибки импорта.

Познавательный блок

Интересный факт: монорепо — это не просто удобство, это культурный артефакт команды разработки. Google использует одно гигантское хранилище для всего кода (более миллиарда строк!), потому что это упрощает синхронизацию и рефакторинг. Но цена высока: нужны инструменты (Bazel), дисциплина и чёткие протоколы. Для нашего voice-agent это значит: не просто писать код, а писать его так, чтобы Python-part и Next.js-part доверяли друг другу.

Итог

В итоге сложилась простая истина: монорепо работает только если есть система проверок. ERROR_JOURNAL.md превратился не просто в логирование ошибок, а в живой артефакт культуры команды. Phase-gate валидация стала гарантией, что при параллельной работе нескольких агентов архитектура не съезжает в стороны. А обязательная проверка миграций — это не занудство, а спасение от трёх часов ночного отлавливания, почему таблица не там, где ей быть.

Главный урок: в монорепо важна не столько архитектура, сколько честность системы. Чем раньше вы перейдёте от надежды на память к автоматическим проверкам, тем спокойнее спать будете.

Почему Python и Java не могут дружить? У них разные dependency trees 😄