Создание графа знаний из кода с помощью Graphify
Разбираем Graphify: инструмент для построения графа знаний из кодовой базы, документации и схем SQL без использования векторных хранилищ.
Как Graphify превращает код в граф знаний
Как Graphify превращает код в граф знаний
Когда мы говорим об анализе больших кодовых баз, основная проблема — это потеря контекста. LLM отлично справляются с отдельными функциями, но когда нужно понять, как изменение в схеме базы данных повлияет на логику высокоуровневого сервиса, стандартный подход с «нарезанием» кода на куски (chunking) даёт сбой. Graphify решает эту задачу иначе: он не просто скармливает текст модели, а строит структурную карту проекта.
Принцип работы на основе AST
В основе Graphify лежит использование абстрактного синтаксического дерева (AST). Вместо того чтобы воспринимать код как набор строк, инструмент разбирает его на логические узлы: определения классов, функций, переменных и их взаимосвязей.
Если мы посмотрим на процесс под капотом, то увидим, что Graphify проходит по файлам и строит связи на уровне синтаксиса. Например, если в одном файле объявлен класс OrderService, а в другом он импортируется и используется для вызова метода calculateTotal(), в графе знаний появится направленная связь между этими сущностями.
С практической точки зрения это позволяет AI-агентам не «гадать» по смыслу слов, а точно знать структуру проекта. Это критически важно, когда вы используете набор навыков для работы с AI-агентами, где точность навигации по коду определяет успех выполнения задачи.
Процесс анализа можно запустить через CLI, указав директорию с проектом. Для базового сканирования Python-проекта команда будет выглядеть так:
bash# Запуск построения графа для текущей директории
graphify analyze ./src --language python --output ./knowledge-graph.json
В результате вы получаете не просто текстовый поиск, а структурированный JSON, где каждый узел имеет тип (например, FunctionDefinition или ClassDefinition) и список связей (calls, inherits, defines). Это делает работу агентов предсказуемой: они обращаются к конкретным узлам графа, а не пытаются угадать контекст по похожим фрагментам текста.
Почему отсутствие векторного хранилища — это плюс
Обычно для создания систем поиска по знаниям используют векторные базы данных (Vector DB). Код разбивается на эмбеддинги, которые хранятся в таких решениях, как Chroma или Pinecone. Однако у этого подхода есть существенный недостаток: семантическая близость не равна структурной корректности. Векторный поиск может найти функцию, которая «похожа» по смыслу на ваш запрос, но он не поймет, что эта функция является единственным наследником интерфейса, от которого зависит стабильность всей системы.
Graphify сознательно отказывается от обязательного использования векторных хранилищ в пользу графовых структур. И вот почему это важно для инженера:
- Точность связей. В графе связь между определением функции и её вызовом — это жесткий факт, а не вероятность, которую выдает векторный поиск.
- Снижение галлюцинаций. Когда AI-агент опирается на граф, он следует по существующим путям в коде. Это особенно полезно при оптимизации работы AI-агентов, когда нужно минимизировать лишние запросы к модели.
- Простота развёртывания. Вам не нужно поднимать отдельный тяжеловесный сервис для хранения векторов. Граф — это компактная структура, которую можно хранить локально или передавать в контексте запроса.
Если вы настраиваете рабочее окружение для глубокого анализа, например, через Claude Code, наличие графа позволяет передавать агенту не «всё подряд», а только те узлы и их ближайших соседей, которые непосредственно относятся к текущей задаче.
Сравните два подхода: векторный поиск ищет «что-то про обработку заказов», а Graphify находит «класс OrderProcessor, его метод process() и все зависимости, которые он использует в методе validate()». Для системного инженера второй вариант всегда предпочтительнее, так как он обеспечивает ту самую предсказуемость, на которой строится надёжная инфраструктура.
Поддержка различных типов данных
Анализ SQL-схем и конфигурационных файлов
Главное преимущество Graphify — это способность работать не только с абстрактным текстом, но и со структурными данными. В моей практике часто случается так: разработчики пишут отличный код, но логика взаимодействия данных запрятана в сложных SQL-миграциях или конфигурациях Nginx, которые AI-агент при обычном сканировании может просто пропустить.
Инструмент использует AST (Abstract Syntax Tree) для разбора синтаксиса. Когда мы подаём ему файл .sql, он не просто читает строки, а выстраивает связи между таблицами, внешними ключами (foreign keys) и индексами. Это позволяет создать граф, где узлами являются сущности базы данных, а ребрами — связи между ними.
Если вы используете Claude Code или других агентов, наличие такого графа критически важно для предсказуемости. Агент не будет гадать, есть ли связь между users и orders, он увидит её в графе знаний.
Для анализа конфигурационных файлов Graphify можно настроить через файл конфигурации проекта. Например, чтобы включить парсинг директории с конфигами вашей домашней лаборатории, добавьте соответствующий путь в graphify.config.yaml:
yaml# Пример конфигурации для включения анализа инфраструктурных файлов
include:
- "./src/**/*.ts" # Исходный код приложения
- "./db/migrations/*.sql" # SQL-схемы для построения связей БД
- "./nginx/conf.d/*.conf" # Конфигурации веб-сервера
parsers:
sql:
enabled: true # Включаем AST-парсинг для SQL
nginx:
enabled: true # Анализ директив Nginx для понимания маршрутизации
С практической точки зрения, это превращает разрозненные файлы в единую карту системы. Если вы меняете структуру таблицы в миграции, граф обновляется, и AI-агент сразу понимает, какие части кода затронуты изменениями.
Обработка документации и PDF-файлов
Часто бывает, что архитектурные решения или спецификации API хранятся в виде PDF-документов или Markdown-файлов в папке docs. Проблема классических RAG-систем (Retrieval-Augmented Generation) в том, что они дробят текст на куски (chunks) без понимания контекста. Graphify пытается подойти к этому иначе, связывая текстовые описания с реальными объектами в коде.
Когда инструмент обрабатывает документацию, он ищет упоминания функций, классов или эндпоинтов, которые уже есть в графе из исходного кода. Это создает мост между «как это должно работать» (документация) и «как это работает на самом деле» (код).
Для работы с PDF требуется предварительная подготовка окружения. Graphify использует специализированные библиотеки для извлечения текста, сохраняя при этом иерархию заголовков. Чтобы запустить процесс индексации документации, используйте команду:
bash# Запуск индексации конкретной папки с документацией
graphify index ./docs --format pdf
Если ваша документация разбросана по разным местам, рекомендую сначала систематизировать её. Это поможет не только Graphify, но и вашим AI-агентам, которым гораздо проще работать с чистыми, структурированными данными.
При обработке больших объемов документации важно помнить о качестве исходников. Если в PDF-файле нарушена кодировка или текст представлен в виде картинок без текстового слоя, граф получится неполным. В таких случаях лучше привести документацию к формату Markdown — это обеспечит максимальную точность связей.
Интеграция с AI-инструментами
Использование в Claude Code и Cursor
Сама по себе структура графа знаний бесполезна, если она не передаётся модели в контекстном окне. Основная ценность Graphify проявляется тогда, когда мы превращаем разрозненные файлы проекта в структурированную карту связей, которую AI-агент может «прочитать» за один проход.
В случае с Claude Code, создание графа позволяет избежать типичной проблемы: когда агент начинает галлюцинировать о зависимостях, потому что не видит импортов в соседних модулях. Чтобы интегрировать Graphify, я рекомендую использовать подход с генерацией контекстного файла, который будет служить «картой местности» для Claude.
Сначала сгенерируйте граф в формате JSON или Markdown (в зависимости от того, какой вывод настроен в вашей версии Graphify):
bash# Генерируем карту связей проекта для передачи в контекст
graphify ./src --output context_map.md
После этого добавьте этот файл в инструкции вашего агента. Если вы используете настройку CLAUDE.md, пропишите в секции Context следующее:
markdown## Project Structure & Knowledge Graph
Always refer to `context_map.md` to understand the relationships between modules,
SQL schemas, and service dependencies before proposing architectural changes.
С Cursor ситуация похожая. Инструмент не умеет «на лету» перестраивать свой индекс, но вы можете использовать сгенерированный граф как файл-подсказку. Если вы добавите context_map.md в .cursorrules, агент будет использовать его как высокоуровневую схему. Это особенно полезно при работе с набором навыков для работы с AI-агентами, когда задача требует понимания не только синтаксиса, но и логики взаимодействия компонентов.
Подключение к Gemini CLI
Работа через CLI требует более прямого подхода. Если вы используете инструменты вроде Corgi для управления сессиями или напрямую вызываете Gemini через терминал, Graphify может выступать в роли «препроцессора».
Вместо того чтобы скармливать модели сотни строк кода, мы передаём ей сжатый граф. Это экономит токены и, что важнее, повышает предсказуемость ответов. С практической точки зрения, эффективнее всего объединить вывод Graphify и ваш запрос в один пайплайн.
Пример того, как можно сформировать запрос к Gemini CLI, используя граф как контекст:
bash# Объединяем карту проекта и конкретный вопрос в один поток
cat context_map.md | gemini-cli "Based on this knowledge graph, where should I add a new
handler for the user-registration event?"
Если вы стремитесь к автоматизации, как это предлагает Ponytail, можно написать небольшой скрипт-обёртку. Он будет запускать graphify при каждом изменении структуры директорий (например, через fswatch), обновлять файл графа и подкладывать его в контекст CLI-инструмента.
Такой подход превращает AI из простого «помощника по коду» в полноценного архитектора, который понимает, как изменение в одной таблице базы данных повлияет на логику в конкретном сервисе.
Практическое применение в разработке
Улучшение контекста для AI-агентов
Когда мы работаем с AI-агентами вроде Claude Code, основной проблемой становится «галлюцинация» из-за неполного контекста. Агент видит только те файлы, которые вы явно передали, или пытается угадать зависимости, полагаясь на статистические вероятности. Это приводит к тому, что он может предложить изменить функцию, не понимая, что она используется в десяти других модулях.
Graphify решает эту проблему на уровне структуры. Вместо того чтобы скармливать агенту огромные куски текста (raw text), мы даём ему карту связей. Инструмент анализирует AST (Abstract Syntax Tree) и строит граф, где узлами являются классы, функции и переменные, а ребрами — вызовы и зависимости.
С практической точки зрения это меняет подход к промптингу. Вместо того чтобы просить агента «проанализировать проект», вы можете направить его по конкретному пути в графе. Если вы используете набор навыков для работы с AI-агентами, вы заметите, что точность выполнения задач возрастает, когда агент понимает топологию кода.
Для интеграции графа в рабочий процесс можно использовать конфигурационный файл, который определяет глубину анализа. Например, чтобы агент не утонул в деталях реализации, но понимал интерфейсы, настройте параметры сканирования:
yaml# graphify-config.yaml
analysis:
depth: 3 # Глубина прохода по дереву вызовов
include_types:
- class
- function
- method
exclude_paths:
- "**/tests/**"
- "**/vendor/**"
ast_parsing: true # Обязательно для построения точных связей
Когда у агента есть такая база, он перестаёт работать «вслепую». Это особенно критично при использовании инструментов вроде Claude Code, где важно сохранять предсказуемость изменений в кодовой базе.
Навигация по сложным проектам
В больших монорепозиториях или legacy-проектах поиск точки входа для изменения логики превращается в детективное расследование. Вы знаете, что ошибка происходит при обработке SQL-запроса, но не знаете, через какие слои абстракции проходит этот запрос.
Graphify позволяет визуализировать путь данных. Если мы добавим в граф схемы SQL, мы получим сквозную навигацию: от API-эндпоинта через бизнес-логику сервисов до конкретных таблиц в базе данных. Это гораздо эффективнее, чем просто поиск по строкам (grep), который часто выдаёт слишком много шума.
Представьте, что вам нужно провести рефакторинг метода. С помощью графа вы можете выполнить команду анализа, чтобы увидеть всех «потребителей» этого метода:
bash# Построение графа для конкретного модуля и экспорт в JSON для анализа
graphify analyze ./src/services/order_service.py --format json > order_context.json
Полученный файл можно использовать для автоматизированного аудита. Если вы используете терминальные решения вроде Corgi, вы можете интегрировать этот процесс в свой workflow, быстро переключаясь между контекстами разных модулей.
С точки зрения системного инженера, использование графа знаний — это переход от работы с «текстом» к работе со «структурой». Это обеспечивает ту самую предсказуемость, которой так не хватает при попытках автоматизировать разработку. Вместо того чтобы надеяться на интуицию LLM, мы опираемся на математически выверенную структуру связей кода.
Заключение
Когда Graphify оправдывает себя
С практической точки зрения Graphify — это не универсальная замена векторным базам данных, а узкоспециализированный инструмент для тех, кому важна структурная точность. Если ваша задача — просто «поболтать» с документацией, стандартного RAG (Retrieval-Augmented Generation) на эмбеддингах будет достаточно. Но если вы строите сложную систему, где AI-агент должен понимать зависимости между функциями, таблицами в базе и схемами API, то без графа знаний не обойтись.
Инструмент показывает себя лучше всего в двух сценариях:
- Анализ legacy-кода, где документация устарела, а связи между модулями запутаны.
- Подготовка контекста для AI-агентов, которым нужно не просто находить похожие куски текста, а понимать архитектурную логику проекта.
Если вы уже используете продвинутые инструменты вроде Claude Code, добавление графа знаний позволит агенту совершать меньше логических ошибок при рефакторинге.
Ограничения и нюансы внедрения
Не стоит ожидать, что Graphify решит все проблемы с контекстом. У подхода есть свои границы, которые важно учитывать при проектировании инфраструктуры:
- Вычислительная сложность. Построение графа на основе AST (Abstract Syntax Tree) требует ресурсов. На огромных монолитах процесс может занимать значительное время.
- Глубина анализа. Graphify отлично справляется со статическим анализом, но он не видит динамику выполнения программы. Если логика завязана на сложные runtime-состояния, граф может оказаться неполным.
- Поддержка языков. Качество графа напрямую зависит от того, насколько хорошо парсер понимает синтаксис вашего языка.
Для минимизации этих рисков я рекомендую не скармливать инструменту весь репозиторий целиком, а сегментировать его. Например, можно настроить сбор графа только для критических модулей ядра или схем БД.
Итоговая конфигурация для старта
Чтобы получить предсказуемый результат, я советую начинать с минимально необходимого набора источников. Вот пример базового конфигурационного файла graphify.yaml, который фокусируется на коде и SQL-схемах, игнорируя лишний шум вроде логов или временных файлов:
yaml# Конфигурация для построения графа знаний
project_name: "my-core-service"
sources:
- path: "./src"
type: "ast"
languages: ["python", "typescript"]
- path: "./migrations"
type: "sql"
exclude:
- "**/tests/**"
- "**/node_modules/**"
- "**/venv/**"
output:
format: "json-ld"
destination: "./graph_data/knowledge_graph.json"
Для запуска процесса анализа используйте команду:
bash# Запуск построения графа с указанием конфига
graphify build --config graphify.yaml
После этого полученный файл можно подключать к вашим агентам. Это станет важным шагом в развитии вашей инфраструктуры для работы с AI-агентами, превращая хаотичный набор файлов в структурированную базу знаний.
FAQ
Чем Graphify отличается от классического RAG с векторными базами данных?
Главное отличие — в способе представления данных. Традиционный RAG (Retrieval-Augmented Generation) разбивает код на куски (chunks), превращает их в векторы и ищет похожие фрагменты по семантическому сходству. Это часто приводит к потере контекста: модель может найти похожую функцию, но не поймёт, как она связана с архитектурой всего проекта.
Graphify работает иначе. Он использует AST (Abstract Syntax Tree) для построения графа связей. Вместо «похожего текста» мы получаем четкую структуру: «функция А вызывает функцию Б, которая использует таблицу C в базе данных». Это даёт предсказуемость, которой так не хватает векторному поиску при работе со сложным кодом. Если вы уже используете набор навыков для работы с AI-агентами, то понимаете, что агенту гораздо проще ориентироваться в графе зависимостей, чем в разрозненных кусках текста.
Как Graphify понимает структуру SQL-схем?
Инструмент анализирует DDL-файлы (Data Definition Language) и строит связи между таблицами, колонками и внешними ключами. Это позволяет агенту не просто «знать» о существовании таблицы users, а понимать, что поле user_id в таблице orders является ссылкой на первичный ключ.
С практической точки зрения это выглядит так: Graphify парсит схему и создает узлы графа для каждой сущности. Если вы планируете использовать полученный граф для автоматизации через Claude Code, агент сможет генерировать корректные JOIN-запросы, потому что он видит топологию базы, а не гадает по названиям столбцов.
Можно ли использовать Graphify для анализа документации?
Да, но результат будет зависеть от качества разметки. Graphify пытается выстроить связи между концепциями в Markdown-файлах. Если в документации есть прямые ссылки на функции или типы данных, инструмент свяжет текстовые узлы с узлами из AST-графа кода.
Для улучшения качества анализа рекомендую придерживаться единого стиля описания компонентов. Это во многом пересекается с тем, как работает оптимизация работы AI-агентов — чем меньше двусмысленности в исходных данных, тем меньше галлюцинаций будет выдавать модель при обращении к графу.
Как интегрировать полученный граф в рабочий процесс?
Graphify не является изолированным сервисом, это инструмент подготовки контекста. Вы можете экспортировать граф в форматах, которые понимают современные LLM-агенты.
Например, если вы используете терминальные решения вроде Corgi, вы можете передавать структурированные выжимки из графа в качестве системного промпта или контекстного файла.
Типовой процесс выглядит так:
- Запуск сканирования кодовой базы:
bash# Пример команды для инициализации анализа
graphify scan ./src --output ./graph-data
- Генерация контекстного файла для агента (например, в формате JSON или специализированного
.md). - Подключение этого файла к сессии работы с кодом.
Требует ли Graphify больших вычислительных ресурсов?
Поскольку инструмент не занимается обучением моделей или созданием тяжелых векторных индексов, нагрузка на систему умеренная. Основной расход ресурсов уходит на парсинг AST и построение графа в оперативной памяти.
Для небольших и средних проектов вполне достаточно обычного ноутбука или даже домашнего сервера на базе Raspberry Pi, если проект не разрастается до миллионов строк кода. Главное — следить за объёмом оперативной памяти при анализе очень глубоких деревьев зависимостей.
Часто задаваемые вопросы
Чем Graphify отличается от классического RAG с векторными базами данных?
В традиционном RAG код нарезается на фрагменты (chunks), что часто приводит к потере логических связей между файлами. Graphify использует AST для построения структурной карты, где узлами выступают реальные сущности — классы или функции, а ребрами — их зависимости. Это обеспечивает предсказуемость: модель понимает не просто схожесть текста, а точную архитектурную связь между компонентами.
Можно ли использовать Graphify для анализа SQL-схем?
Да, инструмент поддерживает анализ схем баз данных для интеграции их в общий граф знаний. Это позволяет связать логику приложения с физической структурой данных, например, проследить путь от вызова метода в коде до конкретной таблицы или колонки. С практической точки зрения это решает проблему разрыва контекста между слоем бизнес-логики и слоем хранения.
Какие языки программирования поддерживает инструмент?
На текущий момент Graphify опирается на возможности парсеров AST для конкретных языков, таких как Python. Возможности инструмента напрямую зависят от того, насколько полно парсер может извлечь синтаксические связи. Если вы планируете использовать его для крупного проекта, убедитесь, что целевой язык входит в список поддерживаемых версий парсера.
В каком формате можно получить результат анализа?
Результат работы инструмента сохраняется в структурированный JSON-файл, который содержит описание узлов и связей. Такой формат удобен для последующей передачи в AI-агентов или для визуализации графа в сторонних инструментах. Вы можете передать этот файл в контекст модели, чтобы она получила точную карту проекта вместо разрозненных кусков кода.