code-review-graph: делает AI-проверку кода более точной и экономит токены

code-review-graph — это инструмент с открытым исходным кодом для AI-помощников по кодированию. Он сначала создает структурированный «граф знаний» для кодовой базы локально, а затем передает AI только релевантный контекст, избегая полного сканирования всего репозитория при каждой задаче. Он использует Tree-sitter для парсинга AST, организует функции, классы, импорты, вызовы и тестовые зависимости в графовую структуру, а затем предоставляет их через MCP таким инструментам, как Claude Code, Codex, Cursor и др.

Какую проблему решает

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

Идея code-review-graph заключается в предварительном моделировании «зависимостей кода», чтобы AI при ревью читал только те файлы, которые действительно затронуты изменением, а не выполнял полное сканирование наугад. В официальной документации эта возможность называется blast-radius analysis, то есть «анализ радиуса взрыва»: когда файл изменяется, инструмент прослеживает цепочки вызовов, наследования, зависимостей и тестов, выявляя весь код, который может быть затронут.

Как это работает

Инструмент сначала использует Tree-sitter для парсинга репозитория в AST, извлекает структурную информацию (функции, классы, импорты, точки вызова, отношения наследования и покрытие тестами) и сохраняет её в локальную графовую базу данных SQLite. На этапе ревью AI не читает весь проект напрямую, а сначала запрашивает граф, получает минимальный набор контекста и читает только те файлы и узлы, которые непосредственно связаны с текущей проблемой.
Он также поддерживает инкрементальные обновления. Согласно официальной документации, последующие обновления будут перепарсить только измененные файлы и обновлять связанные узлы с помощью хэширования и отслеживания зависимостей; в проекте с примерно 2 900 файлами переиндексация может быть выполнена менее чем за 2 секунды. Для больших репозиториев, таких как monorepo, этот подход особенно ценен, так как позволяет сократить количество файлов с десятков тысяч до десятка действительно необходимых к прочтению.

Поддерживаемые платформы и инструменты

code-review-graph интегрируется через MCP во множество AI-платформ для кодирования. В официальном quick start и документации по платформам перечислены поддерживаемые объекты: Claude Code, Codex, Cursor, Windsurf, Zed, Continue, Kiro, OpenCode, Antigravity, Qwen и Qoder. Это означает, что он не ограничивается одним AI-редактором, а стремится предоставить возможности графового контекста различным coding agent'ам и AI IDE.

Если вы хотите установить только для одной платформы, вы также можете явно указать имя платформы, например, code-review-graph install --platform codex, code-review-graph install --platform cursor, code-review-graph install --platform claude-code или code-review-graph install --platform kiro.

Как использовать

Самый простой процесс использования: сначала установить, затем добавить MCP-конфигурацию для AI-инструмента, и наконец в конкретном проекте построить граф.

pip install code-review-graph
code-review-graph install
cd /path/to/your/project
code-review-graph build

Здесь есть очень важный и легко неправильно понятый момент: code-review-graph install не является «командой инициализации проекта», выполняемой в корне проекта; по сути, это глобальная команда конфигурации. Официальная документация четко объясняет: эта команда автоматически обнаруживает установленные на вашем компьютере AI-инструменты для кодирования, записывает соответствующую MCP-конфигурацию и внедряет инструкции, связанные с графом, в конфигурации правил этих платформ; после выполнения необходимо перезапустить соответствующий редактор или инструмент.

Соответственно, code-review-graph build — это команда, которую следует выполнять в корне проекта. Официальные пояснения говорят: «Then open your project», затем дайте AI assistant построить code review graph для «this project»; при этом файл игнорирования инструмента .code-review-graphignore должен находиться в корне репозитория, а локальные данные графа хранятся в каталоге проекта .code-review-graph/. Другими словами, install отвечает за подключение возможностей к вашему AI-инструменту, а build отвечает за построение графа для текущего репозитория.

Чтобы избежать путаницы у читателей, можно четко сопоставить обязанности этих двух команд:

Если редактор не поддерживает хуки, или вы хотите, чтобы граф постоянно оставался актуальным в фоновом режиме, можно использовать режим daemon. Официальная документация предоставляет команды crg-daemon add, crg-daemon start, crg-daemon status и другие команды для регистрации нескольких репозиториев и автоматического отслеживания изменений файлов.

Часто используемые команды

Помимо установки и построения графа, официальная документация предоставляет довольно полные возможности CLI.

В инструментах, поддерживающих Slash Commands, можно также напрямую использовать /code-review-graph:build-graph, /code-review-graph:review-delta и /code-review-graph:review-pr для вызова соответствующих рабочих процессов.

Насколько это эффективно

Официальные бенчмарки, основанные на 6 реальных репозиториях с открытым исходным кодом и 13 коммитах, показывают, что режим графа по сравнению с наивным полным чтением в среднем снижает потребление токенов примерно до одной восьмой, общее сокращение в 8,2 раза. Согласно публичным данным, выгода не одинакова для разных репозиториев, но для большинства средних и крупных проектов наблюдается значительное снижение.

Другим ключевым показателем является точность анализа влияния. Официально полученные результаты: полнота (recall) 100%, средний F1 = 0,54, средняя точность (precision) = 0,38. Это указывает на консервативную стратегию: лучше указать больше файлов, которые «могут быть затронуты», чем пропустить действительно затрагиваемые зависимые файлы.

Однако этот подход не оптимален для всех сценариев. В документации четко указано, что в небольших проектах с очень локальными изменениями накладные расходы на метаданные графа могут превышать стоимость прямого чтения файлов; например, в тесте с изменением одного файла в express reduction составило всего 0,7x. Поэтому наиболее подходящие сценарии — это средние и крупные проекты, многотяжелые изменения, сложные зависимости и высокочастотные рабочие процессы AI ревью.

Каким командам подходит

Если команда уже включила Claude Code, Codex, Cursor или подобные инструменты в повседневный процесс разработки, и проект достаточно большой, с сложными модульными отношениями и частыми ревью PR, то ценность code-review-graph будет очевидна. По сути, он не заменяет ревью кода, а сначала помогает AI правильно определить «что читать», чтобы последующие ревью, отладка, анализ архитектуры и онбординг строились на более точном контексте.

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