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

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

Как Graphify превращает код в граф знаний

Когда мы говорим об анализе кодовой базы, большинство современных решений сразу уводят нас в сторону RAG (Retrieval-Augmented Generation) и векторных хранилищ. Но если ваша задача — не просто «спросить что-то у кода», а понять архитектурные связи, зависимости и логику переходов, то классический поиск по сходству векторов часто пасует. Он находит похожие куски текста, но не понимает, что функция calculate_tax в одном модуле напрямую зависит от схемы таблицы orders в базе данных.

Graphify работает иначе. Вместо того чтобы превращать код в набор абстрактных чисел, он строит структурную карту проекта.

Принцип работы на основе AST

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

Процесс выглядит следующим образом:

Парсинг: Graphify сканирует файлы и с помощью парсеров (для Python, JavaScript, Go и других языков) строит AST для каждого модуля.
Извлечение сущностей: На этом этапе инструмент находит не просто слова, а конкретные узлы: определения классов, функций, переменных, импорты и даже SQL-запросы внутри строк.
Построение связей: Это самый важный этап. Инструмент анализирует, как эти узлы взаимодействуют. Например, если функция A вызывает функцию B, в графе создаётся направленное ребро между ними. Если в коде есть SQL-запрос к таблице users, Graphify связывает этот узел кода с метаданными таблицы из вашей схемы.

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

Для инициализации процесса анализа в директории проекта достаточно запустить команду:

bash
# Инициализация графа из текущей директории
graphify index ./src --language python --output ./knowledge_graph

Здесь --language помогает инструменту выбрать правильный парсер для построения корректного AST.

Отличие от векторных баз данных

Главное отличие Graphify от традиционных векторных подходов заключается в способе представления знаний.

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

Graphify же строит топологическую карту. Сравните это с навигацией:

Векторный поиск — это поиск по картинкам: «Найдите мне фото, похожее на это».
Graphify — это работа с GPS-картой: «Как мне доехать из точки А в точку Б через все перекрестки и развязки».

Характеристика	Векторные БД (RAG)	Graphify (AST-based)
Тип данных	Семантические эмбеддинги	Структурные связи (узлы и ребра)
Точность связей	Вероятностная (похожесть)	Детерминированная (реальные зависимости)
Понимание контекста	Ограничено окном контекста	Глобальное (по всему графу)
Основная задача	Поиск похожих фрагментов	Анализ архитектуры и потоков данных

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

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

Возможности анализа документации и схем

Обработка SQL-схем и конфигураций

Когда мы говорим о графе знаний, многие сразу представляют себе разбор логики функций или классов. Но для системного инженера архитектура данных зачастую важнее, чем иерархия вызовов в коде. Graphify позволяет извлекать связи не только из синтаксического дерева (AST), но и из структурных описаний баз данных.

Инструмент анализирует SQL-дампы или файлы миграций, выявляя отношения между таблицами через внешние ключи (foreign keys) и индексы. Это превращает плоский список таблиц в топологическую карту, где связи one-to-many или many-to-many становятся узлами и ребрами графа. С практической точки зрения это решает проблему «слепоты» AI-агентов: когда модель пытается написать запрос, она понимает не только названия колонок, но и логическую зависимость объектов.

Чтобы добавить схему базы данных в процесс анализа, достаточно указать путь к .sql файлу в конфигурационном файле Graphify. Например, если вы используете Docker для развёртывания инструментов анализа, ваш config.yaml может выглядеть так:

yaml
analysis:
  sources:
    - type: sql_schema
      path: "./migrations/postgres/schema.sql"
      # Мы указываем тип диалекта, чтобы парсер корректно 
      # обрабатывал специфичные для Postgres конструкции
      dialect: "postgresql"
    - type: config_files
      path: "./nginx/conf.d/"
      extensions: [".conf"]

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

Интеграция с PDF и текстовыми файлами

Вторая важная задача — связать техническую документацию с реальным кодом. Часто бывает так, что описание API или архитектурные требования живут в PDF-файлах или Markdown-документах, которые никак не пересекаются с репозиторием. Graphify пытается сократить этот разрыв.

В отличие от классических RAG-систем (Retrieval-Augmented Generation), которые дробят текст на случайные куски (chunks) и складывают их в векторную базу, Graphify стремится найти сущности. Если в PDF-файле упоминается модуль AuthService, а в коде есть соответствующий класс, инструмент создает связь между текстовым описанием и программной реализацией.

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

bash
# Запуск анализа директории с документацией и кодом
graphify analyze --config ./graphify-config.yaml --input ./docs/specs/ --output ./knowledge-graph/

В конфигурации это описывается через секцию documentation:

yaml
documentation:
  formats:
    - pdf
    - md
    - txt
  extraction_rules:
    # Ищем упоминания ключевых компонентов системы
    entities:
      - name: "Database Cluster"
        aliases: ["PostgreSQL", "DB", "Storage"]

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

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

Интеграция с AI-инструментами

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

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

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

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

Для работы с Cursor процесс похож. Поскольку Cursor активно использует индексацию, Graphify помогает «подсказать» ему сложные связи, которые AST (Abstract Syntax Tree) может упустить при поверхностном сканировании. Вы можете добавить сгенерированный JSON-граф в .cursorrules, чтобы модель учитывала топологию проекта при генерации кода.

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

markdown
# Graph Context Rules
Always refer to `graph_export.json` to understand:
1. Service dependencies and call stacks.
2. Database schema relations extracted from SQL files.
3. Cross-module function calls.
Do not assume connections; verify them against the graph.

Подключение к Gemini CLI

Работа через терминал — это мой основной сценарий. Если вы используете Gemini CLI для автоматизации ревью или генерации документации, Graphify становится отличным поставщиком структурированных данных.

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

Чтобы интегрировать это в ваш пайплайн, можно использовать простой bash-скрипт, который сначала строит граф, а затем передаёт его содержимое в запрос к Gemini. Это особенно полезно, когда вы используете мультиплексоры для терминала и AI-агентов, чтобы разделять процессы сборки и анализа.

Пример команды для автоматизации анализа:

bash
# 1. Генерируем граф из текущей директории
graphify build --output ./context/project_graph.json

# 2. Передаём граф и запрос в Gemini CLI
# Мы используем cat, чтобы вставить содержимое графа прямо в prompt
gemini-cli prompt "Analyze the following project structure and identify potential bottlenecks in data flow: $(cat ./context/project_graph.json)"

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

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

Практическое применение в разработке

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

Когда проект разрастается до сотен модулей и тысяч файлов, классический поиск по тексту (grep) перестаёт давать предсказуемый результат. Вы можете найти упоминание функции init_session, но не поймёте, какие именно компоненты системы зависят от её конкретной реализации в текущем контексте.

Graphify решает эту проблему через построение абстрактного синтаксического дерева (AST). Вместо того чтобы просто искать строку, инструмент анализирует связи: где функция объявлена, где она вызывается и как это связано с типами данных в SQL-схемах. С практической точки зрения это превращает хаотичный набор файлов в структурированную карту.

Если вам нужно проанализировать связи в существующем репозитории, процесс начинается с генерации графа. Например, для проекта на Python это выглядит так:

bash
# Инициализируем анализ текущей директории
graphify analyze ./src --output-format dot --engine ast

Полученный файл в формате DOT можно визуализировать, чтобы увидеть «узкие места» — классы или модули, на которые завязано слишком много зависимостей. Это помогает при рефакторинге: вы заранее видите, что изменение сигнатуры метода в одном модуле «развалит» цепочку вызовов в трёх других.

В отличие от векторного поиска, который работает на вероятностях (похоже/не похоже), графовый подход даёт жёсткую логическую связь. Если в графе нет ребра между узлом AuthService и DatabaseConnector, значит, в коде нет прямого взаимодействия, как бы похожи их описания ни были.

Улучшение контекста для AI-агентов

Главная проблема при работе с AI-агентами вроде Claude Code — это ограниченное окно контекста. Вы не можете «скормить» агенту весь проект целиком, иначе он либо запутается, либо выйдет за лимиты токенов.

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

Для эффективной работы агента важно правильно подготовить среду. Если вы используете специализированные инструменты, стоит обратить внимание на настройку CLAUDE.md для улучшения работы Claude Code, чтобы агент понимал правила работы с проектом.

Сценарий использования выглядит следующим образом:

Агент получает задачу (например, «добавить новое поле в таблицу пользователей»).
Вместо полного сканирования файлов, он запрашивает у Graphify подграф, связывающий модель User в коде с её определением в SQL-миграциях.
Агент получает точный контекст: имя таблицы, типы полей и связанные внешние ключи.

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

Для интеграции в рабочий процесс удобно использовать терминальные решения, такие как Corgi, которые позволяют комбинировать вывод инструментов анализа и взаимодействие с агентом в одном интерфейсе.

Заключение

Итоги внедрения

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

Если ваша задача — обеспечить предсказуемость ответов агента при работе с легаси-кодом или сложными схемами БД, использование AST-анализа вместо векторного поиска оправдано. Граф не ошибается в связях: если функция A вызывает функцию B, это зафиксировано в структуре, а не в вероятностях нейросети.

Когда Graphify будет полезен

Инструмент лучше всего показывает себя в трёх сценариях:

Анализ сложных зависимостей. Когда проект разросся настолько, что понимание цепочки вызовов требует больше времени, чем написание кода.
Подготовка контекста для агентов. Если вы используете Claude Code или другие автономные инструменты, Graphify поможет сформировать компактный и точный набор данных, не перегружая контекстное окно лишним «шумом».
Документирование архитектуры. Автоматическое построение графа из SQL-схем и документации позволяет быстро увидеть пробелы в описании системы.

Однако стоит понимать и ограничения. Graphify не заменит полноценный RAG (Retrieval-Augmented Generation), если вам нужно искать по смыслу (semantic search), а не по структуре. Например, если вы ищете «функцию для обработки платежей», но в коде она называется process_transaction, векторный поиск найдёт её по смыслу, а граф — только если вы точно знаете имя или путь в дереве вызовов.

FAQ

Нужно ли мне настраивать векторную базу данных? Нет, Graphify работает на основе AST (Abstract Syntax Tree) и статического анализа. Он строит явные связи между объектами, что избавляет от необходимости разворачивать инфраструктуру для хранения эмбеддингов.

Поддерживает ли инструмент языки, кроме Python? Да, инструмент ориентирован на широкую поддержку популярных языков программирования и SQL-схем, извлекая структуру напрямую из синтаксического дерева.

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

FAQ

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

Нет, в этом и заключается одна из главных особенностей Graphify. В отличие от классических RAG-систем (Retrieval-Augmented Generation), которые требуют развёртывания и поддержки баз данных вроде Chroma или Pinecone, этот инструмент работает иначе. Вместо поиска по похожим векторам, он строит явные связи между сущностями на основе абстрактного синтаксического дерева (AST).

С практической точки зрения это даёт два преимущества:

Предсказуемость: вы точно знаете, почему модель связала функцию A с классом B, потому что между ними есть прямая ссылка в коде, а не «математическая близость» векторов.
Простота: вам не нужно выделять ресурсы под векторную БД.

Если вы планируете использовать Graphify в связке с инструментами вроде Claude Code, вам достаточно просто указать путь к репозиторию.

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

Инструмент ориентирован на извлечение структурных связей, поэтому его возможности зависят от наличия парсеров для конкретных языков. На текущий момент Graphify эффективно обрабатывает:

Исходный код: Python, TypeScript, JavaScript, Go и Rust. Он анализирует импорты, определения классов и вызовы функций.
SQL-схемы: файлы .sql с описанием таблиц, связей (Foreign Keys) и индексов. Это позволяет строить граф зависимостей данных.
Документацию: файлы в формате Markdown, которые помогают связать высокоуровневые описания с конкретными участками кода.

Чтобы добавить специфические файлы в область анализа, отредактируйте конфигурационный файл graphify.config.json:

json
{
  "include": [
    "src/**/*.ts",
    "schema/*.sql",
    "docs/**/*.md"
  ],
  "exclude": [
    "**/node_modules/**",
    "**/dist/**"
  ]
}

Как инструмент помогает при работе с legacy-кодом?

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

Если мы посмотрим на типичный монолит, написанный без использования современных паттернов, Graphify позволит:

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

Для глубокого анализа структуры legacy-проекта используйте команду:

bash
graphify analyze ./path/to/legacy-project --output graph.json

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

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

Нужно ли мне настраивать векторную базу данных для работы с Graphify?

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

Чем такой подход отличается от классического RAG?

Классический RAG ищет фрагменты кода, которые семантически похожи на ваш запрос, но он часто упускает логическую цепочку зависимостей. Graphify же фокусируется на архитектурных связях: он понимает, что конкретный класс взаимодействует с определённой таблицей в базе данных. Если RAG — это поиск по ключевым словам и смыслам, то Graphify — это построение точной карты того, как компоненты системы связаны друг с другом на уровне синтаксиса.

Какие языки программирования поддерживает инструмент?

На текущий момент Graphify использует парсеры для Python, JavaScript и Go, что позволяет извлекать сущности и связи в этих экосистемах. Возможности инструмента напрямую зависят от качества доступных AST-парсеров для конкретного языка. Если вам нужно анализировать специфический стек, стоит сначала проверить, насколько полно парсер может разобрать структуру вашего кода до построения графа.

Как Graphify связывает программный код с SQL-схемами?

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

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