Библиотека сайта rus-linux.net
Как AI-агенты работают с большой кодовой базой: возможности и ограничения
Агент уже давно может писать функции, и это уже не новость. Интереснее другое: что он делает, когда функция живёт не в одиночку, а среди сотен модулей, и правка в одном месте тихо ломает соседний. Интерфейс перестает совпадать с вызовом, ошибка проявляется только при редком сочетании условий, и искать ее потом непросто.
Поэтому в большом проекте важны три вопроса, и ни один из них не про то, умеет ли агент писать код. Вопросы о важном:
- Понимает ли он, куда ложится его правка?
- Считается ли с архитектурой, которая уже есть?
- И можно ли проверить результат, а не поверить ему?
Их и разберем в данной статье.
Что агент делает с проектом
Чат видит то, что вы в него вставили. Агент видит проект: открывает файлы, читает исходники, правит их и, если дать ему терминал и разрешения, запускает команды и тесты.
Порядок обычно такой. Агент находит участок, относящийся к задаче: смотрит структуру репозитория, ищет нужные функции, классы и конфигурации. Затем выясняет, кто этот код вызывает и на что он опирается, то есть читает импорты, интерфейсы и тесты. Составляет план и список файлов к правке. Правит, стараясь не выбиваться из соглашений проекта. И проверяет тесты, сборку и всё, что доступно. Но по прямой это идет редко. Упавший тест возвращает к плану, план к правкам, и так по кругу.
Почему не нужно читать весь репозиторий?
В тысячи файлов не вчитаешься, да и модель всё это не вместит. Агент поступает как человек в чужой кодовой базе: ищет. По тексту, по именам символов, по индексу, по документации, а нужное собирает по кускам. Результат зависит от инструментов поиска и навигации, а ещё от того, заметит ли модель связь между двумя фрагментами из разных каталогов.
Контекстное окно (сколько информации модель удерживает за один заход) тоже много значит, но большое окно не означает понимания проекта. Можно пройти мимо важной зависимости, неверно прочитать комментарий, не знать про поведение компонента, о котором в доступных материалах ни слова. Задача не в том, чтобы показать агенту больше файлов, а в том, чтобы привести его к тем, от которых зависит правильность ответа.
Где агент помогает, а где подводит
Лучше всего агент справляется, когда задачу можно ограничить, а результат проверить. Три типичных случая.
- Чужой модуль. Агент находит точку входа, идёт по цепочке вызовов, объясняет, что делают функции, и показывает связанные тесты. Разобраться действительно быстрее. Но рассказ об архитектуре может оказаться неполным или ошибочным, поэтому его стоит сверить с исходниками.
- Новая функция - например, параметр в существующем API. Агент найдёт обработчик, посмотрит похожие реализации, определит затронутые файлы и предложит правки. А вот про совместимость со старыми клиентами он может забыть, второй путь обработки данных пропустить, а соглашения проекта нарушить.
- Ошибка или рефакторинг. По тексту ошибки агент находит подозрительный участок, предлагает правку и дописывает тест. Может упростить повторяющуюся логику или перекроить отдельный модуль. Риск тут в том, что исправление закрывает симптом, а не причину, и что рефакторинг меняет поведение так тихо, что этого никто не замечает.
Общий знаменатель простой: агент знает только то, что ему показали. Неявные требования системы остаются за кадром.
Почему зелёные тесты ничего не гарантируют?
Агент переписал обработчик авторизации. Проект собирается, тесты проходят. Но у токена есть второй путь обновления, и тесты про него не слышали. Часть пользователей получает ошибку, хотя проверка формально прошла успешно.
Обычно причина одна из этих:
- модули связаны, а агент связь не заметил;
- документация устарела или спорит с кодом;
- он вызвал метод, которого нет, или неверно понял API;
- важный сценарий никто не покрыл тестами;
- правка сломала соседнюю часть системы.
Про права отдельно. Терминал и файловая система в руках агента означают, что надо четко знать, на что он способен. Рядом с секретами, чувствительными данными и продакшеном доступ лучше урезать, а опасные операции подтверждать вручную.
Как организовать работу
От модели зависит не всё: многое решает постановка задачи. Вот что обычно помогает.
- Не начинайте с правок. «Исправь все проблемы проекта» или сразу большой рефакторинг. Это плохое первое задание. Сначала пусть найдёт связанные файлы, объяснит, как всё устроено сейчас, и предложит план. Заодно станет ясно, правильно ли он понял задачу, пока ничего не сломано.
- Сузьте задачу. Вместо «исправь авторизацию» расскажите, что именно нарушено, при каких условиях это воспроизводится и что трогать без нужды нельзя. Вот как это может выглядеть:
Найди обработчик обновления токена авторизации и изучи связанные тесты. Определи причину ошибки при истечении срока действия токена. Сначала предложи план исправления и перечисли затрагиваемые файлы. После согласования внеси минимальные изменения, добавь тест для проблемного сценария и запусти релевантные проверки. Не изменяй публичный API без отдельного обоснования.
Такой запрос задаёт направление, но проверку за инженера не делает.
- Смотрите на diff. Перед началом зафиксируйте исходное состояние и работайте в отдельной ветке. Когда агент закончит, откройте diff, то есть разницу между старой и новой версиями файлов, и ответьте себе на три вопроса: соответствует ли код задаче, не затронуто ли лишнее, нет ли нежелательных правок. Потом тесты, сборка и остальные проверки проекта. Git отследит изменения и позволит их откатить, но правильность кода не подтвердит. Тесты проверяют только предусмотренные сценарии, поэтому ревью не заменяют.
- Ведите записи. Инструкции по сборке, запуску тестов, архитектуре и соглашениям помогают агенту ориентироваться в репозитории. Если задача долгая, записывайте решения, проверенное и оставшиеся проблемы, а не надейтесь на историю диалога. В проектах с множеством модулей и сложными зависимостями это особенно заметно.
Как выбрать инструмент
Только качества кода при выборе AI-IDE или агента мало. Проверяйте, насколько точно он находит нужные файлы, видит связи между компонентами, работает с несколькими файлами и дает ли контролировать, что именно изменилось.
Для этого достаточно небольшого теста на реальном проекте: пусть найдет реализацию конкретной функции, объяснит цепочку её вызовов, предложит ограниченное изменение, а вы проверите. Смотреть стоит не на то, насколько убедительно звучит объяснение, а на то, совпадает ли оно с исходниками, соблюдены ли требования и насколько чисты правки.
Чек-лист
Прежде чем отдавать агенту задачу в большой кодовой базе, пройдитесь по списку.
- Нужный код найден, файлы названы верно.
- Он указал основные места вызова и зависимости, которые заденет изменение.
- Объяснение совпадает с исходниками. Никаких догадок и несуществующих методов.
- Перед правками агент назвал файлы, которые собирается менять, и объяснил почему.
- Публичные интерфейсы и поведение других компонентов без необходимости не тронуты.
- В diff нет случайных правок, пропавшего нужного кода и несвязанных изменений.
- Релевантные тесты запущены, ошибки названы честно, а об успехе без подтверждения никто не заявлял.
- Граничные случаи нового или исправленного поведения проверены.
- Результат можно воспроизвести локально: тестами, сборкой или другими командами проекта.
- Агент не запускает опасных команд и не получил лишнего доступа к секретам, данным и продакшену.
Отметьте каждый пункт: «выполнен», «не выполнен» или «не проверен». Если ваш ИИ-помощник не нашёл нужный код, выдумал зависимости, нагородил лишних правок или выдал проведенную проверку за успешную, значит не стоит на него ставить задачи без дополнительного контроля.
Прогоните список на задачах разного типа: разбор незнакомого модуля, исправление ошибки, небольшая новая функция. Одна удача ни о чём не говорит. Стабильность видна на серии. Для более детального разбора темы можно, например, изучить особенности работы AI-агентов с кодовой базой - статья подробно описывает процессы обработки данных на примере AI IDE Kodik.
Можно ли доверить агенту большой проект?
Агент ускоряет разбор чужого кода, подготовку локальных правок, написание тестов и рутину. Но архитектуру целиком он не понимает и последствия правок за пределами изученного участка видит не всегда.
Важно: делать выводы о качестве агента нужно только по тому, решают ли проверенные изменения поставленную задачу. Объём кода и скорость генерации ничего не говорят.
Поэтому, чем сложнее проект, тем уже должна быть задача и тем внимательнее проверка: и догадок агента, и итогового кода. Начните с мелких изменений, посмотрите на результат и расширяйте круг задач постепенно.