Как я строил агента для код-ревью на LangGraph и где сломалась красивая теория

Пару месяцев назад я смотрел демку: AI-агент получал пулл-реквест, пробегал по diff-у, находил потенциальный race condition и писал развёрнутый комментарий с предложением фикса. Всё это занимало около 40 секунд.

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

Я прикинул план: LangGraph для оркестрации, GPT-4 в качестве модели, GitHub API для интеграции. Неделя на прототип, ещё неделя на полировку. Дальше можно катить в продакшен.

Забегая вперёд, скажу, что я ошибся в оценке примерно в четыре раза. А результат оказался совсем не тем, что я ожидал. Ниже расскажу, что именно пошло не так и какие выводы я сделал.

Постановка задачи

Изначально требования выглядели понятно. Есть PR, в нём diff — набор изменённых файлов. Агент должен:

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

• найти типовые ошибки: необработанные исключения, потенциальные утечки ресурсов, забытые await;

• оценить очевидные проблемы с производительностью;

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

Архитектура на старте получилась линейной. Webhook от GitHub запускает пайплайн, агент забирает diff и контекст файлов, разбивает изменения на чанки по файлам, для каждого чанка вызывает LLM, собирает все замечания в один список, дедуплицирует и публикует комментарии в PR.

[GitHub Webhook]
       │
       ▼
[Получить diff и контекст файлов]
       │
       ▼
[Разбить на чанки по файлам]
       │
       ▼
[Для каждого файла: анализ → замечания]
       │
       ▼
[Собрать замечания, дедупликация]
       │
       ▼
[Отправить комментарии в PR]

Чисто, линейно, понятно. И, как выяснилось позже, наивно.

Прототип на LangGraph

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

Ниже — упрощённый скелет графа. Я опускаю обработку ошибок, ретраи и работу с GitHub API, чтобы сосредоточиться на структуре.

from langgraph.graph import StateGraph, END
from typing import TypedDict
 
 
class ReviewState(TypedDict):
    pr_url: str
    diff_chunks: list[dict]
    reviews: list[dict]
    final_comments: list[dict]
 
 
def fetch_diff(state: ReviewState) -> ReviewState:
    """Загружаем diff пулл-реквеста и разбиваем по файлам."""
    chunks = github_client.get_pr_diff(state["pr_url"])
    return {"diff_chunks": chunks}
 
 
def analyze_chunk(state: ReviewState) -> ReviewState:
    """Прогоняем каждый чанк через LLM и просим вернуть JSON с замечаниями."""
    reviews = []
    for chunk in state["diff_chunks"]:
        prompt = f"""Ты — опытный код-ревьюер.
Проанализируй diff и найди проблемы.
Стайлгайд: {STYLE_GUIDE}
 
Diff:
{chunk['content']}
 
Ответь в JSON: [{{"file": "...", "line": N, "comment": "...", "severity": "..."}}]
"""
        result = llm.invoke(prompt)
        reviews.extend(parse_json(result))
    return {"reviews": reviews}
 
 
def filter_and_post(state: ReviewState) -> ReviewState:
    """Дедуплицируем и постим комментарии в PR."""
    comments = deduplicate(state["reviews"])
    github_client.post_review_comments(state["pr_url"], comments)
    return {"final_comments": comments}
 
 
graph = StateGraph(ReviewState)
graph.add_node("fetch", fetch_diff)
graph.add_node("analyze", analyze_chunk)
graph.add_node("post", filter_and_post)
graph.add_edge("fetch", "analyze")
graph.add_edge("analyze", "post")
graph.add_edge("post", END)
 
app = graph.compile()

На тестовом PR агент показал себя хорошо. Нашёл незакрытый файловый дескриптор, указал на пустой except Exception, предложил вынести магическую константу в отдельный параметр. Команда оценила результат, я получил добро на запуск в продакшене.

Что произошло в продакшене

Первые три дня агент работал в режиме «пишет комментарии, но не блокирует мердж». Я собрал статистику и посмотрел на неё внимательно. Радужная картина с демо в реальности оказалась куда менее красивой.

Галлюцинации в контексте кода

Это первая и самая болезненная проблема. Агент работает с diff-ом, а diff — это не весь файл. Модель видит изменённые строки и небольшой контекст вокруг.

Типичный сценарий: агент видит вызов self.cache.get(key), не видит определение self.cache — оно где-то выше, за пределами diff-а — и уверенно пишет, что метод не обрабатывает случай неинициализированного кеша, нужно добавить проверку на None.

Звучит разумно. Но self.cache инициализируется в __init__ и никогда не бывает None. Агент этого не знает, потому что __init__ не попал в diff.

По моим замерам, около 30% всех замечаний были такими «умными» догадками на пустом месте. Каждое третье — мимо.

Контекстное окно и реальные PR

На демо был аккуратный PR из трёх файлов и 80 строк diff-а. В жизни у нас регулярно встречаются PR на 40 файлов и 2000 с лишним строк. Это плохая практика, но реальность именно такая.

Когда вход в модель раздувается, происходит несколько неприятных вещей. Модель путает, к какому файлу относится замечание. Иногда обрезает вывод посередине. Один раз агент вернул JSON с незакрытой скобкой, парсер упал, комментарии не были опубликованы, и никто не заметил этого до конца дня.

Стоимость

Грубая арифметика выглядела так. Один ревью среднего PR — это 500–700 строк diff-а, что соответствует примерно 15–20 тысячам входных токенов и 2–3 тысячам выходных. На GPT-4 цена одного ревью получалась в районе 0.50–0.70 доллара.

Дальше простое умножение. 12 PR в день, 22 рабочих дня — выходит 130–185 долларов в месяц. Не катастрофа, но и не копейки. А когда я попытался добавить полный контекст файлов, чтобы бороться с галлюцинациями, стоимость выросла в три-четыре раза.

Недетерминизм

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

Параметр temperature=0 помогает, но не решает проблему до конца. На длинных промптах модель всё равно «плавает».

Для команды это неприятный момент. Живой ревьюер тоже ошибается, но он стабилен в своих предпочтениях. Известно, что один коллега всегда придирается к именованию, другой — к обработке ошибок. С агентом нет никакого способа предсказать, чего ожидать в следующем ревью.

Эффект «мальчика, который кричал волк»

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

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

Что я изменил

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

Расширенный контекст вместо голого diff-а

Первое изменение касалось входных данных. Агент теперь получает не просто diff, а diff с расширенным контекстом. Для каждого изменённого файла я подтягиваю окружение — класс или функцию, в которую вносятся изменения, плюс сигнатуры импортов.

Подход дороже по токенам, но число галлюцинаций про несуществующие проблемы упало примерно вдвое.

def fetch_diff_with_context(state: ReviewState) -> ReviewState:
    """Расширяем каждый чанк диффа окружающим контекстом."""
    chunks = github_client.get_pr_diff(state["pr_url"])
    enriched = []
    for chunk in chunks:
        full_file = github_client.get_file_content(
            chunk["repo"], chunk["file_path"], chunk["base_ref"]
        )
        # Берём не весь файл целиком, а релевантную область
        context = extract_surrounding_context(
            full_file,
            chunk["changed_lines"],
            context_window=50,  # 50 строк вокруг каждого изменения
        )
        chunk["full_context"] = context
        enriched.append(chunk)
    return {"diff_chunks": enriched}

Few-shot из реальных ревью команды

Вторая правка — стиль и тон. Вместо абстрактного «ты опытный ревьюер» в системный промпт пошли 15–20 примеров реальных ревью-комментариев из наших PR. С конкретным стилем, уровнем детализации, обращениями.

Эффект заметный. Агент перестал писать в стиле учебника. Меньше формулировок вроде «рассмотрите возможность», больше конкретики типа «здесь будет NPE если user None, добавь guard clause».

Confidence score и порог отсечения

Третья правка — фильтрация по уверенности. Я добавил в промпт требование оценивать каждое замечание по шкале от 1 до 10. Всё, что ниже 7, не публикуется, а складывается в лог для моего разбора.

Приём грубый, но рабочий. Доля мусорных комментариев упала примерно с 60% до 25%.

def analyze_with_confidence(state: ReviewState) -> ReviewState:
    """Агент оценивает уверенность в каждом замечании; ниже порога — фильтруем."""
    reviews = []
    for chunk in state["diff_chunks"]:
        prompt = f"""...
Для каждого замечания укажи confidence от 1 до 10.
10 = ты уверен, что это баг или нарушение стайлгайда.
5 = возможная проблема, но нужен больший контекст.
1 = стилистическое предложение.
 
Ответь JSON: [{{"file": "...", "line": N, "comment": "...",
                "severity": "...", "confidence": N}}]
"""
        result = llm.invoke(prompt)
        parsed = parse_json(result)
        # Публикуем только уверенные замечания
        reviews.extend([r for r in parsed if r["confidence"] >= 7])
    return {"reviews": reviews}

Гибрид: LLM плюс детерминированные правила

Главный сдвиг — отказ от идеи делать всё через языковую модель. Часть проверок отлично закрывается обычными инструментами: неиспользуемые импорты, нарушение naming convention, отсутствие type hints. Это работа для линтера или AST-анализа, а не для LLM.

После рефакторинга агент работает только там, где нужно понимание: логические ошибки, архитектурные нюансы, неочевидные баги. Рутину делает детерминированный код, который не галлюцинирует.

[GitHub Webhook]
       │
       ▼
[Получить diff + расширенный контекст]
       │
       ├──────────────────┐
       ▼                  ▼
[Rule-based проверки]  [LLM-анализ (только сложные кейсы)]
       │                  │
       ▼                  ▼
[Объединение результатов]
       │
       ▼
[Фильтр по confidence + дедупликация]
       │
       ▼
[Пост в PR]

Цифры

После доработок я три недели собирал метрики. Сравнение с первой версией ниже.

Первая версия (только LLM):

Финальная версия (гибрид):

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

Экономия времени ревьюеров на первичном проходе — около 15–20 минут на PR. При двенадцати PR в день это 3–4 часа суммарно. Из этого нужно вычесть моё время на поддержку: правки промптов, разбор edge cases, обновление few-shot примеров. Получается порядка 3–5 часов в неделю.

Выводы

Демо показывает работу системы в идеальных условиях. Чистый PR, простой код, знакомый язык, аккуратные участники. Продакшен — это legacy-монолит с многолетней историей, гигантские пулл-реквесты и кодовая база, которую не понимают целиком даже её авторы. Между демо и продакшеном — пропасть, которую промпт-инженерия в одиночку не закроет.

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

Метрика «количество комментариев» — ловушка. Первая версия писала много и казалась активной. На самом деле полезность определяется тем, читают ли её люди. Один точный комментарий ценнее десяти размытых.

Агент — это не инструмент в режиме «поставил и забыл». Промпты деградируют со временем, кодовая база меняется, в команду приходят новые люди со своими привычками. Если нет возможности уделять системе несколько часов в неделю, лучше за неё не браться.

Если бы я начинал заново, то не стал бы делать «универсального ревьюера». Я бы взял одну конкретную проверку — например, поиск необработанных исключений — и довёл её до 95% точности. Потом добавил бы вторую. Инкрементально, без героизма.

Если у вас был похожий опыт внедрения AI-агентов, поделитесь в комментариях. Интересно сравнить, какие проблемы у вас совпали, а какие нет. А если вы ещё только смотрите демки и прикидываете сроки — закладывайте в оценку запас. Большой.