Agentic code review: как научить LLM исследовать репозиторий перед ревью

Введение

Инструменты для AI-ревью кода за последние пару лет стали обычной частью CI/CD-процессов. Модель анализирует изменения в Pull Request, формирует комментарии и помогает разработчикам быстрее находить потенциальные проблемы в коде. Такой подход удобен: достаточно передать в LLM diff изменений и получить автоматическое ревью.

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

Чтобы решить эту проблему, в инструменте ai-review был добавлен agentic режим. В этом режиме модель может не только анализировать diff, но и исследовать репозиторий: просматривать структуру проекта, искать символы и читать файлы, чтобы собрать необходимый контекст перед формированием итогового ревью.

В этой статье разберём, что такое agentic code review и как такой режим был реализован в инструменте ai-review.

Ограничения обычного AI code review

Большинство инструментов для AI-ревью кода работают по довольно простой схеме:

diff Pull Request → LLM → комментарии

Модели передаётся diff изменений, после чего она анализирует код и формирует рекомендации или замечания. Такой подход достаточно удобен и легко интегрируется в CI/CD: достаточно передать модели изменения в Pull Request и опубликовать её ответы в виде комментариев.

Однако у этой схемы есть важное ограничение — модель видит только локальные изменения, но не имеет доступа к контексту всего репозитория.

1. Дублирование кода

Например, разработчик добавляет новую функцию:

def calculate_fee(amount):
    ...

Для модели это просто новый фрагмент кода в diff. Она не знает, что похожая функция уже может существовать в другом модуле проекта — например, в payments/utils.py или billing/helpers.py. В результате LLM не может подсказать, что логика уже реализована и её стоит переиспользовать.

2. Отсутствие архитектурного контекста

Ещё одна проблема — отсутствие понимания внутренней архитектуры проекта.

Модель не знает:

какие утилиты уже существуют в проекте
какие архитектурные паттерны используются
какие внутренние API или сервисы уже реализованы

Поэтому рекомендации часто остаются на уровне локального анализа кода и не учитывают реальную структуру системы.

3. Поверхностное ревью

В итоге AI-ревью становится довольно поверхностным. Модель может заметить:

синтаксические проблемы
потенциальные ошибки
проблемы читаемости кода

Но она почти не способна анализировать изменения в контексте всей кодовой базы. А именно это и делает ревью кода по-настоящему полезным для команды.

Поэтому для более качественного анализа модели нужен контекст всего проекта, а не только diff Pull Request. Именно эту проблему и решает агентский подход к ревью кода.

Что такое agentic code review

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

В классическом сценарии взаимодействие с LLM выглядит так:

prompt → answer

Модель получает входные данные, формирует ответ — и на этом процесс заканчивается.

В агентском подходе вместо одного запроса используется итерационный цикл рассуждения и действий. Модель может анализировать промежуточные результаты, решать, какой контекст ей нужен, и выполнять дополнительные действия для его получения.

В контексте ревью кода это может выглядеть примерно так:

модель анализирует diff Pull Request
понимает, что ей не хватает контекста
выполняет поиск по репозиторию
читает нужные файлы
продолжает анализ с учётом найденной информации
формирует итоговое ревью

Схематично этот процесс можно представить так:

Pull Request
     ↓
   Diff
     ↓
    LLM
     ↓
Agent Loop
 ├─ search
 ├─ read file
 ├─ grep
 └─ git
     ↓
Final review

В результате модель получает возможность самостоятельно собирать контекст, который ей необходим для анализа изменений. Это делает ревью гораздо ближе к тому, как его выполняет человек: разработчик тоже редко ограничивается только diff — он открывает соседние файлы, ищет похожие функции и проверяет, как устроена существующая логика.

Такой агентский подход уже используется в современных AI-инструментах для разработки — например, в Cursor или Copilot Agents. Вместо статического анализа кода модель может активно исследовать проект и принимать решения о том, какую информацию ей нужно получить.

Именно эта идея легла в основу agentic режима, который был реализован в ai-review.

Agentic режим в ai-review

После понимания общей идеи agentic систем возникает логичный вопрос: как реализовать такой подход в инструменте для ревью кода.

В ai-review для этого был добавлен отдельный agent loop — итерационный цикл, в котором модель может выполнять несколько шагов перед тем, как сформировать финальное ревью. На каждом шаге LLM анализирует текущий контекст и принимает решение: достаточно ли информации для ответа или нужно получить дополнительные данные из репозитория.

Если модели требуется больше контекста, она может выполнить одну из доступных read-only команд. Например, посмотреть структуру проекта, найти нужный файл или прочитать его содержимое. После этого результат команды добавляется в контекст, и модель продолжает анализ.

В упрощённом виде такой цикл выглядит так:

модель анализирует diff Pull Request
решает, нужен ли дополнительный контекст
при необходимости выполняет команду (например ls или grep)
получает результат и продолжает анализ
после нескольких шагов формирует итоговое ревью

Включается агентский режим через конфигурацию:

agent:
  enabled: true
  max_iterations: 25

По умолчанию этот режим выключен, поэтому существующие установки ai-review продолжают работать в классическом режиме — один запрос к LLM на основе diff. Это обеспечивает полную обратную совместимость и позволяет включать agentic режим только там, где он действительно нужен.

Для работы агента доступен небольшой набор read-only команд, которые позволяют безопасно исследовать репозиторий. Например:

ls — посмотреть структуру каталогов
cat — прочитать файл
grep / rg — найти символы или строки в коде
git — получить информацию о состоянии репозитория

Такой минимальный набор инструментов уже позволяет модели находить связанные файлы, проверять существующие реализации и собирать дополнительный контекст перед тем, как сформировать итоговое ревью.

Как выглядит агентское ревью на практике

Чтобы лучше понять, как работает agentic режим, посмотрим на реальный пример выполнения ревью в CI.

После запуска ai-review начинается agent loop — итерационный цикл, в котором модель может выполнять несколько действий перед тем, как сформировать финальный ответ.

На каждом шаге модель принимает решение: достаточно ли текущего контекста или нужно получить дополнительную информацию из репозитория.

Шаг 1 — агент исследует структуру проекта

Сначала модель пытается понять, где именно находится изменённый код и какие файлы могут быть с ним связаны.

Для этого она выполняет команду:

Agent action: ls demo/agentic_review/payments/

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

Шаг 2 — агент читает нужный файл

После просмотра структуры проекта модель решает открыть файл с основной логикой сервиса:

Agent action: cat demo/agentic_review/payments/service.py

Содержимое файла возвращается модели и добавляется в контекст. Теперь она может анализировать изменения не только в diff Pull Request, но и в существующем коде модуля.

Это позволяет, например:

понять, как реализована текущая логика
проверить, не дублирует ли новый код уже существующие функции
увидеть, какие зависимости используются внутри сервиса

Шаг 3 — формирование итогового ревью

После нескольких таких шагов модель решает, что у неё достаточно контекста, и завершает агентский цикл.

Финальный ответ выглядит примерно так:

FINAL:

Summary of changes:
- Introduced a demo agentic review project with multiple modules
- Added payment formatting and calculation logic
- Implemented review API with permission checks
- Added shared helpers and basic test coverage

После этого ai-review публикует комментарии в Pull Request так же, как и в обычном режиме.

Ключевая особенность такого подхода заключается в том, что модель сама решает, какой контекст ей нужен для анализа изменений.

Вместо статического анализа diff происходит небольшое «исследование» репозитория: модель может просматривать структуру проекта, искать нужные файлы и читать код перед тем, как формировать итоговое ревью.

Это делает анализ значительно глубже и ближе к тому, как код проверяет человек во время обычного code review.

Ограничения и безопасность agentic режима

Несмотря на преимущества агентского подхода, на практике у него есть несколько важных нюансов, которые стоит учитывать.

1. Не все модели хорошо работают в агентском режиме

Agentic workflow требует от модели умения последовательно выполнять несколько шагов: корректно использовать tool-calling, анализировать результаты команд и принимать решение о следующем действии. На практике это получается не у всех моделей.

Некоторые модели могут:

плохо следовать протоколу вызова инструментов
пропускать шаги в reasoning-цикле
генерировать некорректные команды
преждевременно завершать цикл или, наоборот, зацикливаться

По опыту тестирования agentic режима в ai-review, лучше всего себя показывают более мощные модели, например:

GPT-4.1 и новее
Claude Opus
Gemini Pro

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

Поэтому при использовании agentic режима обычно приходится немного экспериментировать с настройками — подбирать модель, корректировать системный prompt и ограничивать количество итераций, чтобы найти баланс между качеством ревью, скоростью работы и стоимостью вызовов модели.

2. Безопасность выполнения команд

Ещё один важный аспект — безопасность. Давать LLM полный доступ к shell в CI-среде было бы крайне рискованно. Поэтому в ai-review используется строгая allowlist-модель доступа к командам.

Агент может выполнять только те команды, которые явно разрешены в конфигурации:

allow_commands:
  - "^ls"
  - "^cat"
  - "^rg"
  - "^grep"
  - "^git"

Все остальные команды автоматически блокируются. Такой подход позволяет ограничить возможности агента только безопасными read-only операциями: просмотром структуры проекта, чтением файлов и поиском по коду.

Дополнительно используются несколько механизмов защиты:

command timeout — ограничение времени выполнения команды
iteration limits — защита от бесконечных агентских циклов
context budget — ограничение объёма данных, которые могут быть добавлены в контекст модели

Эти ограничения помогают предотвратить проблемы вроде утечки чувствительных данных, выполнения неожиданных команд или бесконтрольного роста контекста.

В результате агент получает достаточно возможностей для исследования репозитория, но при этом остаётся в безопасных рамках.

Заключение

Agentic режим позволяет превратить AI-ревью из простого анализа diff в более глубокий анализ кода с учётом контекста всего репозитория. Вместо одного запроса к модели используется небольшой цикл рассуждения, в котором LLM может исследовать структуру проекта, искать нужные файлы и читать код перед тем, как сформировать итоговое ревью.

Такой подход делает автоматическое ревью более полезным: модель лучше понимает архитектуру проекта, реже предлагает дублирующий код и в целом ближе к тому, как код анализирует человек во время обычного code review.

Если вам интересно подробнее узнать про ai-review, в предыдущих статьях я разбирал установку, настройку и интеграцию инструмента в CI/CD:

Исходный код проекта доступен на GitHub: https://github.com/Nikita-Filonov/ai-review. Если инструмент оказался полезным — буду рад ⭐ на репозитории.