Монорепо, голос и журнал ошибок: как AI учится не ломать код

Когда AI-помощник встречается с монорепо: отладка голосового агента

Проект voice-agent — это амбициозная задача: связать Python-бэкенд с Next.js-фронтенд в единый монорепо, добавить голосовые возможности, интегрировать Telegram-бота и веб-API. Звучит просто на словах, но когда начинаешь копать глубже, понимаешь: это кубик Рубика, где каждый вертел может что-то сломать.

Проблема, с которой я столкнулся, была банальной, но коварной. Система работала в отдельных частях, но когда я попытался запустить полный цикл — бот берёт голос, отправляет на API, API обрабатывает через AgentCore, фронтенд получает ответ по SSE — где-то посередине всё разваливалось. Ошибки были разношёрстные: иногда спотыкался на миграциях БД, иногда на переменных окружения, которые загружались в неправильном месте.

Первым делом я понял: нужна система для документирования проблем. Создал ERROR_JOURNAL.md — простой журнал “что сломалось и как это чинилось”. Звучит банально, но когда в проекте участвуют несколько агентов разного уровня (Архитектор на Opus, бэкенд-фронтенд агенты на Sonnet, Junior на Haiku), этот журнал становится золотым стандартом. Вместо того чтобы каждый агент наново натыкался на баг с Tailwind v4 в монорепо, теперь первым делом смотрим журнал и применяем известное решение.

Архитектура обработки ошибок простая, но эффективная:

1. Ошибка возникла → читаю docs/ERROR_JOURNAL.md
2. Похожая проблема есть → применяю известное решение
3. Новая проблема → исправляю + добавляю запись в журнал

Основные боли оказались не в коде, а в конфигурации. С Tailwind v4 нужна магия в next.config.ts и postcss.config.mjs — добавить turbopack.root и base. SQLite требует WAL-режим и правильный путь к базе. FastAPI любит, когда переменные окружения загружаются только в точках входа (telegram_main.py, web_main.py), а не на уровне модулей.

Интересный момент: я переоценил сложность. Большинство проблем решались не рефакторингом, а правильной организацией архитектуры. AgentCore — это единое ядро бизнес-логики для бота и API, и если оно валидируется с одной строки (python -c "from src.core import AgentCore; print('OK')"), весь стек работает как часы.

Итог: система работает, но главный урок не в технических трюках — в том, что монорепо требует прозрачности. Когда каждая составляющая (Python venv, Next.js сборка, миграции БД, синхронизация переменных окружения) задокументирована и протестирована, даже сложный проект становится управляемым. Теперь каждый новый агент, который присоединяется к проекту, видит ясную картину и может сразу быть полезным, вместо того чтобы возиться с отладкой.

На следующем этапе плотнее интегрирую streaming через Vercel AI SDK Data Stream Protocol и расширяю систему управления чатами через новую таблицу managed_chats. Но это — уже другая история.

😄 Что общего у монорепо и парка развлечений? Оба требуют хорошей разметки, иначе люди заблудятся.