Как не утонуть в кодовой базе и превратить проект в граф знаний

Представьте типичную ситуацию: вы входите в новый проект на 50 тысяч строк кода или возвращаетесь к своему старому пет-проекту спустя полгода. Вы помните, что где-то была логика авторизации, но она размазана между контроллерами, мидлварами и каким-нибудь AuthService.ts. Чтобы восстановить связи в голове, приходится либо долго грепать по файлам, либо надеяться, что AI-ассистент в чате не "галлюцинирует".

Обычно мы скармливаем нейронкам контекст кусками. Но код — это не просто текст, это структура связей. Недавно я наткнулся на проект Graphify, который пытается решить проблему контекста радикально: он сканирует весь ваш проект и строит граф знаний. Это не просто визуализация для красоты, а инструмент, который учит ваш AI-ассистент понимать архитектуру кодовой базы на глубоком уровне.

Зачем это нужно, если есть IDE и Grep

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

Graphify делает три вещи, которые меняют правила игры. Во-первых, он извлекает зависимости не только из кода через AST (абстрактные синтаксические деревья), но и из документации, SQL-схем и даже видео-туториалов. Во-вторых, он интегрируется напрямую в ваши AI-инструменты вроде Claude Code, Cursor или Aider. В-третьих, он создает интерактивную карту, которую можно открыть в браузере.

Вместо того чтобы спрашивать чат-бота "Где у нас обрабатываются платежи?", вы вводите команду /graphify ., и ассистент получает готовую карту связей. Теперь он знает, что PaymentController вызывает StripeProvider, который в свою очередь пишет в таблицу subscriptions.

Что умеет Graphify

Проект поддерживает около 36 языков программирования. Для извлечения структуры кода он использует tree-sitter, поэтому процесс проходит локально и быстро. В графе оказываются не только функции и классы, но и их связи: кто кого вызывает, кто что наследует и какие интерфейсы реализует.

Вот список того, что можно скормить инструменту:

• Исходники на Python, TS, Go, Rust, Java, C++ и даже экзотику вроде COBOL или Apex.
• Манифесты пакетов: package.json, pyproject.toml, go.mod. Граф сразу видит внешние зависимости.
• Документацию в Markdown, PDF и даже офисные документы (нужны дополнительные расширения).
• Базы данных: можно натравить инструмент на живой PostgreSQL, и он вытащит схему таблиц.
• Мультимедиа: если установить расширение для видео, Graphify транскрибирует ролики и привяжет термины из видео к коду.

После сканирования в папке graphify-out/ появляется три файла: graph.html для визуального осмотра, graph.json для программного доступа и GRAPH_REPORT.md. Последний файл особенно интересен: там нейронка выписывает "God nodes" — самые перегруженные части кода, через которые проходит всё управление, и "Surprising connections" — связи между модулями, которые выглядят странно или неочевидно.

Как начать пользоваться

Установка максимально простая, особенно если у вас есть uv (рекомендую именно этот способ для изоляции зависимостей):

uv tool install graphifyy
graphify install

Обратите внимание на вторую букву y в названии пакета на PyPI — graphifyy. Разработчики предупреждают, что другие пакеты с похожими именами к ним отношения не имеют.

После установки в любом поддерживаемом AI-чате (например, Claude Code) появляется команда /graphify .. После её запуска ассистент сам проиндексирует проект. Если вы хотите, чтобы граф обновлялся автоматически, можно поставить git-хук:

graphify hook install

Это добавит post-commit хук, который будет пересобирать граф (локальную часть с AST) при каждом коммите. Это бесплатно и не требует обращения к API нейронок.

Под капотом: как это устроено

Проект написан на Python. Основная магия происходит в момент сборки графа. Graphify разделяет извлечение данных на два этапа:

1. Локальный: tree-sitter разбирает код на узлы и ребра без участия сторонних API. Это гарантирует приватность вашего кода.
2. Семантический: для обработки текстов, PDF и связей между "смыслами" используются LLM (Claude, OpenAI, Gemini или локальный Ollama).

Интересная деталь: проект поддерживает алгоритм Leiden для обнаружения сообществ. Он группирует части графа в логические кластеры и дает им названия. Если ваш проект — "каша" из файлов, Graphify попробует выделить в нем осмысленные домены, например "Auth Module" или "Data Ingestion Pipeline", даже если они не разнесены по разным папкам.

Практическая ценность

Я вижу несколько сценариев, где это экономит часы жизни.

Первый — подготовка к рефакторингу. Команда graphify path "ClassNameA" "ClassNameB" покажет кратчайший путь зависимостей между двумя сущностями. Вы сразу увидите, сколько всего сломается, если вы решите удалить этот "ненужный" метод.

Второй — онбординг. Вместо того чтобы объяснять новичку архитектуру на салфетке, можно просто дать ему graph.html. Там можно кликать по узлам, фильтровать связи и видеть, как данные текут по системе.

Третий — работа с PR. Команда graphify prs --triage использует AI для оценки влияния ваших изменений на всю систему через призму графа. Она может подсказать, что ваш фикс в модуле логирования неожиданно затрагивает биллинг.

Стоит ли пробовать

Graphify — это не волшебная кнопка, которая напишет код за вас. Это "очки дополненной реальности" для разработчика. Если вы работаете над микросервисом из трех файлов, он вам скорее помешает. Но для монолитов, легаси-проектов или систем с кучей документации это отличный способ перестать гадать и начать видеть.

Проект активно развивается, у него огромное комьюнити (больше 70k звезд на GitHub) и поддержка со стороны Y Combinator. Из минусов — иногда визуализация падает при попытке отрисовать граф на 5000+ узлов, но в таких случаях лучше переходить на текстовые запросы через CLI.

Если вы чувствуете, что ваш AI-ассистент "глупеет" на больших файлах — попробуйте скормить ему граф. Скорее всего, результат вас удивит.