Практические уроки от создания кодовой базы на 350 тысяч строк в одиночку с помощью AI-агентов

Инженерная среда как контекст

52-дневный проект разработчика (600 коммитов, ~965 тысяч строк кода в обработке, 356 тысяч строк продакшен-кода) показал, что качество вывода агентов критически зависит от инженерной среды, а не только от модели. Сама кодовая база служит контекстной системой для агента, устраняя необходимость в отдельных RAG или файлах памяти.

Чёткие архитектурные границы оказались необходимыми. Кодовая база следует строгой DDD-слоистости: доменный слой для структур данных, сервисный слой для бизнес-логики, слой обработчиков для конвертации HTTP-форматов, с 22 доменными модулями, имеющими чёткие границы. Это указывает агентам, где вносить изменения.

Структура директорий функционирует как документация с согласованием имён между стеками. Для функции, такой как «Loop»: backend/internal/domain/loop/ для структур данных, backend/internal/service/loop/ для логики, web/src/components/loops/ для фронтенда. Это прямое отображение от концепции продукта к пути в коде устраняет необходимость агентам исследовать всю кодовую базу.

Усиление технического долга

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

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

Строгая типизация как шлюз качества

Использование Go + TypeScript + Proto обеспечивает отлов ошибок на этапе компиляции, что смещает ошибки агентов со времени выполнения на время разработки. Сгенерированные агентом функции с несовпадающими сигнатурами вызывают сбои сборки. TypeScript немедленно отлавливает несоответствия форматов API. Сгенерированный Proto код не скомпилируется, если форматы сообщений изменятся без синхронизации с бэкендом. Эти ошибки просочились бы в рантайм в слабо типизированных языках.

Четырёхуровневая система обратной связи

Агентам нужны четыре уровня обратной связи для эффективной итерации:

• Компиляция — горячая перезагрузка, перезапуск Go в течение 1 секунды, ошибки типов TypeScript отмечаются в реальном времени. Устраняет синтаксические ошибки и ошибки типов.
• Модульные тесты — 700+ тестов, покрывающих доменный и сервисный слои. Агенты узнают в течение 5 минут, внесли ли они регрессии, особенно для граничных условий, таких как мультитенантная изоляция.
• E2E тесты — сквозная валидация реальных функциональных путей. Отлавливает проблемы интеграции, недоступные модульным тестам.
• CI пайплайн — каждый PR запускает полный набор тестов, линтинг, проверку типов, сборку на нескольких платформах. Последняя страховочная сеть перед слиянием.

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