Почему ИИ-агенты не вывозят большую кодовую базу (и что мы пытаемся с этим сделать)

Я последнее время много экспериментирую с ИИ-агентами для разработчиков на реальных проектах. На небольших репозиториях — в целом, сказка. Автодополнение кода, быстрый рефакторинг, написание тестов, полная реализация небольшой фичи, если она никак не связана с другими модулями — всё работает отлично. Но как только дело доходит до большой кодовой базы (легаси) — начинается боль. И эта проблема намного интереснее, чем кажется на первый взгляд.

Самое частое, с чем сталкиваешься: LLM быстро начинает плодить абстракции. Ей проще переписать часть кода «красиво и правильно», чем разобраться во всех связях. А код, который модель посчитала неважным для задачи — просто выбрасывает. Даже не подозревая, что на нём завязаны ряд других модулей. Или, что ещё хуже, идёт менять те модули, чтобы они соответствовали новому интерфейсу (хорошо, если ещё и тесты подправит, но тут зависит от требований к системе и поддержке критических зон системы).

Но это не «забывание». LLM не забывает — она этого никогда не знала. Контекстное окно, хоть и большое (у некоторых моделей до 1 млн токенов), но ограничено, и модель «искренне уверена», что её решение оптимально. Для многих моделей качество заметно падает где-то после половины контекстного окна — это подтверждается независимыми бенчмарками.

Для решения этой проблемы многие команды начали описывать спецификацию проекта (DS — Detailed spec). Предельно детально расписывают архитектуру, потоки данных, все зависимости. Чтобы LLM было от чего отталкиваться и стараться придерживаться плана, а не гадать.

И тут всплывает следующая проблема.

Спеку пишет человек. Не LLM. В описании спеки нейросеть отвратительна по ряду причин, основная — отсутствие «понимания» и возможность «видеть» всю систему целиком. Модели выдают усреднённое решение с банальным шаблоном. А бизнес — это не шаблон, в реальном мире всё куда сложнее, многограннее и динамичнее. Где нужно понимать множество компромиссов в принятии того или иного решения. Описание приложения на уровне кода — да, LLM справится, просто по факту распишет, что где лежит по папочкам, укажет примерную область применения и зону ответственности (если ваше наименование соотносится с общими шаблонами проектирования). Но эта информация даст модели ответ на вопрос: «Где и Что», а не «Как и Почему».

Что я имею в виду? LLM отлично вычленяет факты — что где лежит, какие методы вызывает. Но архитектурное решение (а.к.а System Design) — это не факт, это компромисс. Почему выбрали PostgreSQL, а не MySQL или MongoDB? Почему этот модуль выделили в микросервис? Почему именно так сделали шардирование данных? Почему именно этот вид балансировки? Этого нет в коде. Этого нет в спеке, которую напишет LLM. Это есть в головах людей, которые принимали решения когда-то.

В общем, человек (даже самый дотошный) как бы ни старался, не может предусмотреть всё. Особенно когда кодовой базе пять лет, архитектура росла органически, и абсолютной истины про неё нет ни в одной голове. В результате — либо слишком абстрактные формулировки (на усмотрение LLM), либо «белые пятна» (LLM начнёт додумывать сама).

И то, и другое даёт модели простор на творчество. Которое, с вероятностью 90%, приведёт к тем же граблям. Это оттягивание неизбежного — не решение.

На практике это выглядит ещё страшнее. Недавно на Reddit разработчик рассказал, как ИИ-агент на базе Gemini 3.5 Flash «починил» восемь уязвимостей, затронув примерно 70 строк кода. В реальности агент «влез» в 340 файлов и удалил более 28 тысяч строк, не связанных с задачей. Сайт на полчаса выдавал ошибку 404. При этом в инструкциях для агента было прямо запрещено менять конфигурационный файл, но модель проигнорировала это правило. А когда разработчик вручную откатил изменения, Gemini написала, что якобы сама успешно завершила сборку и восстановила работу сайта.

Это не единичный случай. Cursor в обычном режиме покрывает всего 0,04% средней кодовой базы и 0,00004% крупного монорепозитория. Поиск по коду на основе эмбеддингов возвращает топ-100 файлов, но если изменение затрагивает файлы, которые не попали в этот топ — всё ломается.

Кодинг агенты часто сталкиваются с параличом «чистого листа» в кодовой базе из 710+ файлов — они просто не могут определить, с чего начать.

Я к чему это всё.

ИИ-агенты, LLM-модели — это офигенные ассистенты. Они ускоряют рутину, пишут тесты, рефакторят изоляцию. Но как только дело доходит до системной логики, где одно изменение тянет за собой цепочку — человек обязан проверять. Лично. Каждый diff.

Инструмент не заменяет понимания контекста. Особенно когда контекст — это legacy-код на 200К строк, где документация устарела, а «так исторически сложилось» — это «архитектурный паттерн».

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

Сейчас в индустрии активно ищут решения. Вот несколько направлений, которые кажутся перспективными:

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

• Кодовая база как главный фактор. Сама кодовая база — куда сильнее любых промптов или конфигурационных файлов — влияет на результат работы ИИ. Если она спроектирована плохо, ИИ не может достаточно быстро получать обратную связь, не может найти то, что ему нужно, и не может понять, как протестировать свои изменения.
• Правила для агентов. Появляются рекомендации по написанию кода «под поиск агентов»: отличительные имена вместо generic, точные типы, комментарии в тех местах, где агент будет искать, и модули, названные по концепциям предметной области.
• Контекстная осведомлённость. Некоторые подходы фокусируются на том, чтобы дать агенту структурированное понимание кодовой базы: граф зависимостей, тестовую инфраструктуру, архитектурные соглашения и историю изменений.

Но все эти решения — лишь костыли. Полностью доверять ИИ-агентам работу с большой кодовой базой мы начнём нескоро. А пока — код-ревью, тесты и человеческий глаз остаются главными инструментами.