При работе с крупными проектами через кодинг-агентов (Claude Code, Cursor, Codex) разработчики неизбежно упираются в ограничения контекстного окна. Пока проект состоит из пары файлов, агент справляется уверенно. Но как только кодовая база разрастается до десятков модулей и пакетов, агент начинает теряться: читает файлы подряд через поиск, забивает контекст лишним кодом, упускает неявные зависимости и ломает соседние сервисы при рефакторинге.
Обычно для поиска по проекту используют полнотекстовый grep или векторный поиск по документации. Однако для реального кода этого недостаточно: текстовые совпадения не показывают точную структуру — какая функция вызывает другую, откуда передаются параметры конфигурации и как устроена схема таблиц в базе. Репозиторий Graphify-Labs/graphify строит локальный граф зависимостей для всей кодовой базы без сторонних векторных баз и лишних расходов.
Зачем агентам граф зависимостей
Вместо того чтобы заставлять агента искать файлы вслепую, Graphify заранее формирует структурированный граф связей репозитория:
- Точные зависимости: инструмент определяет связи между файлами и функциями, цепочки импортов и иерархию классов на более чем 40 языках программирования.
- Ключевые компоненты (узлы системы): автоматически выявляет центральные модули, через которые проходит основной поток данных — например, базовые клиенты баз данных, шины событий или модули авторизации.
- Разделение на подсистемы: группирует кодовую базу по функциональным модулям, формируя логические блоки архитектуры.
- Интеграция с документацией: связывает код с файлами Markdown, схемами SQL-миграций, конфигами и поясняющими комментариями разработчиков (
# WHY:,# NOTE:, ADR).
Локальный анализ без внешних затрат
Большинство систем анализа кода требуют отправлять проект во внешние облачные сервисы или разворачивать тяжелые векторные базы данных. Это создает риски утечки приватного кода и приводит к ощутимым расходам на токены при каждой индексации.
Graphify работает иначе:
| Параметр | Graphify | Традиционные RAG-системы и облачные базы |
|---|---|---|
| Где выполняется анализ | Локально на компьютере | Во внешних облачных сервисах |
| Расход токенов на построение | 0 токенов (бесплатно) | Оплата за каждый токен при индексации |
| Характер связей | Строгие связи по синтаксическому дереву кода | Приблизительный текстовый поиск по совпадениям |
| Безопасность кода | Исходный код не покидает локальную среду | Данные передаются сторонним провайдерам |
Интерактивная схема в браузере
После сканирования проекта Graphify формирует HTML-страницу с интерактивным графом. Разработчик может открыть её в браузере, масштабировать схему, кликать по компонентам и отслеживать цепочки вызовов. Это помогает быстро войти в курс дела на незнакомом проекте и проверить архитектурные связи перед внесением правок.
Установка и базовые команды
В каталоге PyPI пакет опубликован под именем graphifyy (с двумя буквами «y» на конце), а исполняемая консольная команда называется graphify. Рекомендуется установка через изолированный менеджер uv:
# Установка CLI
uv tool install graphifyy
# Построение графа для текущего проекта
graphify .
# Подключение скила к установленным AI-ассистентам
graphify installПосле выполнения анализа в каталоге graphify-out/ появляются рабочие файлы:
GRAPH_REPORT.md— текстовый отчет об архитектуре и узловых компонентах;- Интерактивный граф в формате HTML;
- Файл
graph.jsonс полной структурой связей для скриптов и агентов.
Прямые запросы к графу через терминал
К построенному графу можно обращаться напрямую из командной строки для быстрой навигации:
# Трассировка маршрута между двумя сервисами
graphify path "AuthService" "DatabasePool"
# Детальная справка по компоненту и его окружению
graphify explain "PaymentGateway"
# Точечный вопрос по архитектуре
graphify query "как поток аутентификации связан с брокером сообщений?"Интеграция с кодинг-агентами: Claude Code, Cursor и Codex
Команда graphify install регистрирует правила для сред разработки и терминальных агентов:
- Защита контекста от переполнения: для Claude Code и Gemini CLI настраивается перехватчик (pre-tool hook), который срабатывает перед чтением файлов пачками. Агент перенаправляется к вызову
graphify queryилиgraphify path, обращаясь только к релевантным файлам. Это снижает расход контекста до 80%. - Файлы инструкций: в проект добавляются конфигурационные правила (
AGENTS.md, правила для Cursor), ориентирующие агентов использовать граф в первую очередь. - Автоматическое обновление: команда
graphify hook installнастраивает Git-хук, который обновляет граф при каждом коммите, поддерживая схему связей в актуальном состоянии.
Итог
Graphify организует работу кодинг-агентов на основе строгой инженерной структуры проекта, а не слепого поиска по текстам файлов. Локальный граф зависимостей помогает агентам быстрее ориентироваться в незнакомой кодовой базе, бережет контекстное окно и делает доработку сложных проектов более надежной.
