Создание графа знаний из кода с помощью Graphify

Разбираем инструмент Graphify, который превращает кодовую базу, схемы SQL и документацию в структурированный граф знаний для работы с AI-агентами.

Как Graphify работает с кодом

Анализ через AST вместо векторных баз

Когда мы говорим о работе ИИ-агентов с кодом, большинство разработчиков сразу думают о RAG (Retrieval-Augmented Generation) и векторных базах данных. Идея кажется логичной: нарезать код на куски, превратить их в эмбеддинги и искать похожие фрагменты по семантическому сходству. Но с кодом этот подход работает плохо. Векторный поиск хорош для поиска «по смыслу», но он совершенно не понимает структуру. Если вы попросите ИИ найти место, где вызывается конкретный метод, векторная база может выдать кучу похожих по смыслу функций, но пропустить ту самую, которая реально связана с вашим объектом.

Graphify решает эту проблему иначе. Вместо того чтобы полагаться на «магию» сходства векторов, инструмент использует AST (Abstract Syntax Tree — абстрактное синтаксическое дерево). Это фундаментальный способ представления структуры программы. Когда Graphify сканирует репозиторий, он не просто читает текст, он строит иерархию: файлы, модули, классы, методы и выражения.

С практической точки зрения это означает, что вместо разрозненных кусков текста мы получаем карту зависимостей. Если агент хочет понять, как работает конкретный сервис, он не просто ищет похожие куски кода, а идет по цепочке вызовов, которую Graphify уже выстроил в графе. Это критически важно для таких инструментов, как Claude Code, которым нужна высокая точность контекста, чтобы не плодить лишний код.

Детерминированный подход к связям

Главная проблема современных LLM при анализе больших кодовых баз — это галлюцинации и потеря контекста. Если агент пытается угадать связь между двумя компонентами, он может ошибиться. Graphify минимизирует этот риск за счёт детерминизма. Связи в графе не «вычисляются» нейросетью, они извлекаются напрямую из синтаксиса языка.

Если в коде написано import { UserService } from './services', Graphify создаст в графе ребро (edge) между текущим модулем и UserService. Это не вероятность, это факт. Такая предсказуемость позволяет строить сложные запросы к графу знаний. Например, можно спросить: «Покажи все функции, которые косвенно зависят от изменения схемы таблицы users в базе данных».

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

bash
# Анализ проекта и генерация графа в формате JSON
graphify analyze ./src --output graph.json --format json

Если вы работаете с SQL-схемами, инструмент также извлечет связи между таблицами, превращая реляционную структуру в часть общего графа знаний. Это превращает разрозненную документацию и код в единую, логически связанную среду.

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

В конечном счёте, использование AST-подхода превращает работу ИИ из «угадывания по сходству» в «навигацию по структуре». Это делает поведение агентов более предсказуемым, а их вклад в разработку — более качественным.

Интеграция с инструментами разработки

Использование в Claude Code и Cursor

Когда мы говорим об интеграции графа знаний в рабочий процесс, важно понимать: Graphify не заменяет IDE, он даёт ей «зрение». Если обычный поиск по коду работает на основе текстовых совпадений, то использование графа позволяет AI-агентам понимать семантические связи.

В случае с Claude Code, инструмент становится критически важным. Проблема стандартных агентов в том, что при работе с большой кодовой базой они быстро теряют контекст или начинают галлюцинировать, пытаясь угадать зависимости. Если вы уже настраивали CLAUDE.md для Claude Code, то понимаете, что структурирование инструкций — это только половина дела. Граф, сгенерированный Graphify, позволяет агенту не просто «читать» файлы, а перемещаться по дереву вызовов и связям между схемами БД.

Для Cursor интеграция выглядит иначе. Здесь Graphify выступает как поставщик внешнего контекста. Вы можете экспортировать полученный граф в формате, который Cursor сможет проиндексировать через @Codebase или через кастомные контекстные файлы.

С практической точки зрения, это решает проблему «раздутого контекста». Вместо того чтобы скармливать модели десятки файлов, вы передаёте ей компактное представление структуры. Это напрямую коррелирует с методами оптимизации, описанными в материале про Ponytail, где основной упор делается на минимизацию лишних токенов.

Поддержка CLI-интерфейсов

Для системного инженера или DevOps-специалиста GUI — это часто лишняя прослойка. Graphify предоставляет полноценный CLI, что позволяет встроить генерацию графа в CI/CD пайплайны или автоматизировать обновление знаний при каждом пуше в репозиторий.

Предсказуемость инфраструктуры требует, чтобы документация и понимание структуры кода не отставали от реальности. Вы можете настроить автоматический запуск Graphify сразу после прохождения тестов.

Для начала работы убедитесь, что у вас установлен Node.js, а затем установите инструмент глобально:

bash
npm install -g @graphify/cli

Чтобы построить граф для текущего проекта, используйте команду analyze. Я рекомендую всегда указывать выходную директорию, чтобы не засорять корень проекта:

bash
# Анализируем проект и сохраняем граф в папку ./docs/knowledge-graph
graphify analyze ./src --output ./docs/knowledge-graph --format json

Если ваш проект включает сложные SQL-схемы, Graphify может подтянуть их в общий граф, обеспечивая связность между кодом приложения и структурой данных. Это особенно полезно, если вы занимаетесь реверс-инжинирингом с помощью ИИ-агентов, где важно видеть не только логику функций, но и то, как они манипулируют данными в БД.

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

json
{
  "include": ["src/**/*.ts", "schema/*.sql"],
  "exclude": ["**/node_modules/**", "**/dist/**", "**/*.test.ts"],
  "parser": "ast",
  "output": {
    "format": "json",
    "path": "./build/graph"
  }
}

Использование такого конфига гарантирует, что каждый член команды (и каждый запущенный агент) будет работать с идентичной моделью знаний. Это избавляет от ситуации, когда один агент «знает» о существовании модуля, а другой — нет, просто потому что путь к нему не был учтён при индексации.

Практическое применение графа знаний

Анализ сложных SQL-схем и конфигов

Когда база данных разрастается до десятков таблиц со сложными связями, даже опытный DBA может упустить из виду косвенные зависимости. С точки зрения AI-агента, обычный текстовый дамп SQL — это просто массив строк. Чтобы агент мог не просто «видеть» код, а понимать архитектуру, ему нужен контекст, представленный в виде графа.

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

Для анализа схемы достаточно направить Graphify на файл с дампом структуры. Например, если у нас есть файл schema.sql, команда для генерации графа будет выглядеть так:

bash
# Извлекаем структуру SQL в формат графа знаний
graphify analyze --input ./database/schema.sql --format json --output schema_graph.json

С практической точки зрения, это даёт предсказуемость. Если вы попросите агента «добавить поле в таблицу пользователей и обновить все связанные триггеры», он не будет искать по тексту. Он пройдёт по ребрам графа от узла users к зависимым объектам. Это минимизирует риск того, что агент предложит решение, которое «сломает» базу в рантайме.

Поиск зависимостей в больших репозиториях

В крупных проектах проблема «спагетти-кода» стоит особенно остро. Когда репозиторий разрастается, понимание того, какой модуль вызывает какой сервис, превращается в детективную работу. Использование AST (Abstract Syntax Tree) позволяет Graphify заглянуть глубже простого текстового поиска.

Если мы посмотрим на типичный микросервисный проект, где компоненты связаны через интерфейсы или конфигурационные файлы, граф знаний станет своего рода картой местности. Это особенно полезно при использовании инструментов для глубокого анализа, таких как morluto/rea.

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

bash
# Анализ Python-проекта для построения графа зависимостей модулей
graphify analyze --path ./src --language python --output project_map.json

После этого вы можете передать полученный project_map.json в контекст вашего AI-агента. Это позволяет реализовать сценарии, подобные тем, что описаны в статье про Ponytail: агент понимает границы ответственности модулей и не пытается переписать весь проект там, где достаточно точечного изменения.

С точки зрения инженера, это решает две задачи:

Impact Analysis: вы точно знаете, какие части системы затронет изменение конкретной функции.
Onboarding: новый разработчик (или агент) получает структурированное представление о связях, а не просто набор файлов.

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

Сравнение подходов к контексту для LLM

Когда мы работаем с ИИ-агентами, вроде Claude Code, основной проблемой становится «разрыв контекста». Если вы просто скормите агенту содержимое папки с проектом, он быстро захлебнётся в объёме данных или, что ещё хуже, начнёт галлюцинировать, не понимая связей между файлами.

Обычно разработчики используют один из трёх подходов:

Raw Context: передача файлов целиком. Это работает для маленьких скриптов, но на больших проектах упирается в лимиты токенов.
RAG (Retrieval-Augmented Generation): поиск по векторной базе данных. Хорошо находит похожие куски кода, но плохо понимает структуру — например, он может найти определение функции, но не поймёт, как она влияет на состояние базы данных через три слоя абстракции.
Graph-based Context: использование графа знаний. Это то, что предлагает Graphify, превращая AST (Abstract Syntax Tree) и схемы БД в единую топологию.

Преимущества графовых структур

С практической точки зрения, граф позволяет агенту не просто «читать» код, а «навигировать» по нему. Если в RAG мы ищем сходство векторов, то в графе мы следуем по ребрам связей.

Представьте, что вам нужно изменить тип поля в PostgreSQL. В обычном подходе агент может обновить только миграцию. В графовом подходе, благодаря связям между SQL-схемой и кодом приложения, агент увидит цепочку: Table -> Column -> ORM Model -> Service Layer -> API Endpoint.

Основные плюсы такого подхода:

Точность навигации: вместо того чтобы гадать, какой метод вызывает другой, агент запрашивает конкретный путь в графе.
Понимание зависимостей: граф подсвечивает побочные эффекты. Если вы меняете сигнатуру функции, граф сразу покажет все узлы, которые «сломаются».
Сжатие контекста: вместо передачи 10 файлов по 500 строк, мы передаем компактное описание узлов и их связей, что критически важно для таких инструментов, как Ponytail.

Для понимания того, как это работает на низком уровне, стоит изучить, как инструменты code-analysis строят AST. Graphify берет этот фундамент и накладывает на него семантику вашего проекта.

Ограничения текущей реализации

Несмотря на перспективность, Graphify — это не «серебряная пуля», и у него есть свои нюансы, которые нужно учитывать при проектировании инфраструктуры для агентов.

Во-первых, это стоимость построения графа. Глубокий анализ кода через AST требует вычислительных ресурсов. Если у вас монолит на миллион строк кода, построение графа в реальном времени станет узким местом. Во-вторых, проблема динамического языка. В Python или JavaScript связи часто определяются во время выполнения (runtime), и статический анализ графа может их упустить.

Если вы используете сложные паттерны вроде Dependency Injection, граф может оказаться неполным. Чтобы минимизировать эти риски, я рекомендую комбинировать графовый подход с четкой документацией проекта. Например, правильная настройка CLAUDE.md помогает агенту быстрее сориентироваться в тех местах, где граф может быть неточным.

Также стоит учитывать:

Актуальность данных: при каждом коммите граф нужно перестраивать. Если агент работает со старой версией графа, он будет предлагать решения, которые уже не применимы.
Сложность интеграции: внедрение графа в существующий пайплайн требует настройки дополнительных сервисов. Это не просто «подключил библиотеку», а создание полноценного слоя знаний.

Для тех, кто занимается глубоким анализом систем, этот опыт будет близок к работе с инструментами вроде morluto/rea, где точность понимания структуры системы определяет успех всей операции.

FAQ

Нужно ли разворачивать векторное хранилище?

Для базовой работы Graphify не требуется разворачивать полноценную векторную базу данных вроде Chroma или Qdrant. Инструмент создаёт локальный индекс, который хранит структуру графа и семантические связи. Это делает процесс запуска предсказуемым: вам не нужно управлять дополнительными сервисами или настраивать сетевое взаимодействие между контейнерами.

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

Какие типы файлов поддерживает Graphify?

Инструмент ориентирован на извлечение структуры из кода и схем данных. Основной упор сделан на файлы, которые можно разобрать с помощью AST (Abstract Syntax Tree).

Исходный код: Поддерживаются языки с развитой экосистемой парсеров, такие как Python, JavaScript/TypeScript, Go и Rust.
Базы данных: SQL-дампы и файлы схем (.sql), которые позволяют выстроить связи между таблицами.
Документация: Файлы в формате Markdown (.md), которые Graphify превращает в узлы графа, связывая описание функций с их реализацией.

Если вы работаете с проектами, где логика сильно завязана на специфических DSL, возможности инструмента могут быть ограничены качеством доступных парсеров.

Как инструмент объясняет связи в графе?

Связи в графе — это не просто указатели на строки кода, а логические зависимости. Graphify анализирует контекст: например, если функция calculate_total вызывает метод get_price, в графе создаётся ребро CALLS.

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

yaml
# graphify.config.yaml
analysis:
  depth: 3 # глубина обхода связей при построении графа
  include_dependencies: true # учитывать внешние библиотеки
  extract_comments: true # извлекать docstrings для обогащения узлов

Можно ли использовать его для анализа документации?

Да, это один из самых эффективных сценариев. Graphify позволяет «склеить» техническую документацию с реальным кодом. Когда вы добавляете .md файлы в область сканирования, инструмент создает связи между описанными концепциями и конкретными реализациями в коде.

Это значительно упрощает работу агентов, когда им нужно не просто написать код, а следовать архитектурным гайдлайнам. Подобный подход к структурированию знаний полезен и при настройке CLAUDE.md для Claude Code, где важно предоставить модели четкие правила и контекст проекта.

Если ваша задача — глубокий реверс-инжиниринг, то использование графа знаний станет отличным дополнением к специализированным инструментам, таким как morluto/rea.

Часто задаваемые вопросы

Чем Graphify отличается от стандартного RAG-подхода

В классическом RAG код разбивается на фрагменты и ищется по семантическому сходству, что часто приводит к потере структурных связей. Graphify использует абстрактные синтаксические деревья (AST) для построения точной карты зависимостей между классами, методами и модулями. Это позволяет ИИ-агенту не просто находить «похожий» текст, а понимать реальную архитектуру проекта и цепочки вызовов.

Можно ли использовать Graphify для анализа SQL-схем

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

Как Graphify помогает избежать галлюцинаций ИИ-агента

Галлюцинации часто возникают, когда модели не хватает точного контекста и она начинает «додумывать» связи между компонентами. Благодаря детерминированному подходу, Graphify предоставляет агенту готовую и проверенную карту связей, извлеченную напрямую из синтаксиса кода. Когда у модели есть четкая структура вместо разрозненных кусков текста, предсказуемость её ответов значительно возрастает.

Подойдет ли этот инструмент для очень больших репозиториев

Эффективность работы с крупными кодовыми базами напрямую зависит от того, насколько точно инструмент выстраивает иерархию. Поскольку Graphify опирается на AST, он строит глубокую структуру, которая позволяет агенту перемещаться по графу от высокоуровневых модулей к конкретным выражениям. Это делает его более подходящим для сложных систем, чем простые векторные поисковики, которые быстро теряют нить логики при масштабировании.

Создание графа знаний из кода с помощью Graphify