Агент для код-ревью на Claude Agent SDK
Код-ревью — идеальная задача для AI-агента: нужно читать контекст, искать связанные файлы, применять разные критерии к разным участкам кода. Разбираем, как построить агента, который делает ревью как опытный инженер — с приоритизацией замечаний, поиском контекста и структурированным отчётом прямо в GitHub.
ПродвинутыйAI-агенты35 минClaude Agent SDK, Python, GitHub API
1
Агент — не замена тимлиду, а первый фильтр
Зачем вообще AI на ревью? Не чтобы заменить человека — чтобы разгрузить его. Агент за 30 секунд прочитает каждую строку diff, поймает null-pointer и забытый await, проверит импорты. Человек потратит это время на архитектурные решения и бизнес-логику — то, что AI делает плохо.
Практический вывод: проектируйте агента как помощника с чётким scope. Безопасность, баги, тесты — да. Архитектурные предложения и стиль кода — нет.
🤖 Отдайте агенту
- Проверка 100% строк diff
- Типичные паттерны багов
- Безопасность и секреты
- Покрытие тестами
👤 Оставьте человеку
- Архитектурные решения
- Бизнес-контекст и цели
- Менторство и обучение
- Компромиссы и trade-offs
Агент, который за 30 секунд находит 80% проблем, меняет ритм работы всей команды. Не гонитесь за 100% — это ловушка.
2
Пять инструментов — и ни одним больше
Хороший ревьюер не смотрит только на diff. Он открывает соседние файлы, проверяет использование функции в других местах, ищет тесты. Агент делает то же самое — но только если вы дали ему правильные инструменты.
Каждый инструмент — ответ на один вопрос: "что изменилось?", "как это используется?", "есть ли тесты?". Агент сам решает, какой вопрос задать — это и делает его агентом, а не скриптом. И все инструменты строго read-only — агент анализирует, но не трогает код.
Читаем diff
что нужно понять?
Ищем контекст
контекст собран
Анализируем
замечания готовы
Формируем отчёт
5 инструментов агента (только чтение!):
что_изменилось → читает diff PR
контекст → открывает файл вокруг изменений
использования → где ещё вызывается эта функция
тесты → есть ли тесты на изменённую логику
история → кто и зачем менял этот файл раньшеИнструмент `get_file_history` спасает от ложных тревог. Агент видит, что "подозрительный код" был намеренно написан три месяца назад — и не кричит.
3
System prompt — это личность ревьюера
Claude Agent SDK берёт на себя цикл рассуждений: вызов модели, выполнение инструментов, возврат результатов. Вам не нужно писать этот цикл — SDK крутит его, пока агент не решит, что задача выполнена.
Но SDK — это мотор. А руль — system prompt. Именно в нём вы определяете, каким ревьюером будет ваш агент. Педантичный формалист и прагматичный senior дадут разный результат на одном и том же коде. Запишите в промпт конкретные правила: какие категории проверять, какой тон замечаний, что игнорировать. Чем конкретнее — тем предсказуемее.
Параметр `max_turns` — страховка от зацикливания. Для ревью хватает 10-15 итераций: прочитать diff, запросить контекст, сформировать отчёт. Если агент крутится дольше — промпт слишком расплывчатый.
агент = модель + инструменты + system prompt
system prompt = личность ревьюера:
какие категории проверять (баги, безопасность, тесты)
какой тон (строгий / дружелюбный)
что игнорировать (стиль, форматирование)
max_turns = 10-15 (страховка от зацикливания)
запуск: "Review PR: {url}" → агент сам решает
какие файлы открыть и в каком порядкеНачните с haiku для тестов — убедитесь, что агент вызывает правильные инструменты. На opus переходите когда логика работает. Разница в стоимости — в 10 раз.
4
Если всё одинаково важно — ничего не важно
Самая частая проблема AI-ревью: 20 замечаний без приоритетов. Разработчик не знает, что исправить до мержа, а что можно проигнорировать. Решение — четыре уровня, зашитые в system prompt: Critical (блокирует мерж), Important (желательно), Minor (по возможности), Nitpick (можно пропустить).
Только Critical и Important появляются как строчные комментарии в PR. Minor и Nitpick — только в summary. Это не просто удобство: разработчики быстро устают от агента, который засыпает PR мелочами, и начинают игнорировать всё.
Critical — блокирует мерж
Баги, уязвимости, потеря данных
Important — желательно исправить
Производительность, тесты, дублирование
Minor — по возможности
Читаемость, именование, комментарии
Nitpick — можно пропустить
Стиль, форматирование, вкусовщина
Добавьте в промпт лимит: не больше 3 Critical за одно ревью. Если агент находит 10 — проблема не в коде, а в ваших критериях.
5
Комментарии прямо к строкам — или агент бесполезен
Агент, который пишет ревью в консоль — игрушка. Настоящая ценность появляется, когда замечания привязаны к строкам кода прямо в PR. Разработчик видит их в контексте, не переключаясь между инструментами.
Нюанс GitHub API: привязать комментарий можно только к строке, которая есть в diff текущего PR. Если строка за пределами diff — публикуйте как общий комментарий. Паттерн, который работает: сначала summary с общим счётом ("2 Critical, 3 Important"), потом строчные комментарии только для Critical и Important.
Формат каждого комментария: severity в заголовке, одно предложение про проблему, одно — про исправление. Без простыней текста. Разработчик должен понять замечание за 5 секунд.
публикация в PR:
1. summary-комментарий: "2 Critical, 3 Important"
2. для каждого замечания с severity ≥ important:
→ комментарий К СТРОКЕ в diff
→ формат: [SEVERITY] проблема + исправление
3. minor и nitpick → только в summary, не в строках
нюанс: строчный комментарий можно привязать
только к строке, которая есть в diff текущего PRЗапретите агенту комментировать стиль кода. Стилевые замечания — самые субъективные и самые раздражающие. Пусть линтер делает своё, а агент — своё.
Результат
Агент на Claude Agent SDK, который читает diff PR, ищет контекст в репозитории, классифицирует замечания по четырём уровням и публикует структурированный ревью прямо в GitHub — summary + строчные комментарии для Critical и Important.