Построение графа знаний из кода с Graphify

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

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

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

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

Принцип работы детерминированного AST-парсинга

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

Когда компилятор или линтер анализирует файл, он строит дерево, где каждый узел — это конкретный элемент языка: объявление функции, класс, переменная или вызов метода. Graphify проходит по этому дереву и извлекает не просто текст, а семантические связи. Например, если в файле auth.py функция validate_token вызывает метод check_expiry из модуля utils.py, в графе знаний появится направленное ребро между этими узлами.

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

Процесс можно представить как построение карты города: вместо того чтобы описывать «красивые здания» (эмбеддинги), мы рисуем точную схему дорог, перекрестков и тупиков.

Для запуска анализа локальной директории достаточно использовать CLI. Сначала убедитесь, что у вас установлен Python и необходимые зависимости:

bash
pip install graphify

Затем можно запустить построение графа для конкретного проекта:

bash
# Анализируем текущую директорию и сохраняем результат в формате JSON
graphify build --path ./my-project --output graph.json

В результате graph.json будет содержать четкую иерархию: от файлов и классов до конкретных определений и вызовов.

Почему отсутствие векторного хранилища — это преимущество

Многие современные решения для ИИ-агентов полагаются на векторные базы данных (Chroma, Pinecone и др.). Это удобно для поиска по смыслу, но создает две проблемы: «размытие» контекста и избыточность инфраструктуры.

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

Точность связей. Векторный поиск работает на основе семантической близости. Если две функции используют похожие термины, поиск решит, что они связаны. Graphify же знает, что они связаны только в том случае, если одна действительно вызывает другую. Это исключает ложные срабатывания при работе с AI-агентами.
Минимальный оверхед. Вам не нужно разворачивать и поддерживать тяжелую базу данных с эмбеддингами. Граф — это, по сути, структурированный файл или легковесная графовая БД, которую можно хранить рядом с кодом. Это делает инструмент идеальным для встраивания в пайплайны, где важна скорость и отсутствие лишних зависимостей.
Прослеживаемость (Traceability). Если агент находит ошибку, он может не просто сказать «похоже на проблему в этом файле», а выстроить цепочку: «Ошибка в функции А, потому что она получает некорректный тип данных из функции Б, которая зависит от схемы SQL таблицы С».

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

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

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

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

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

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

Для эффективной работы в связке с Claude Code рекомендую сначала подготовить индекс проекта. Сначала убедитесь, что у вас установлена актуальная версия Graphify, а затем выполните экспорт графа в формате JSON:

bash
# Генерация графа знаний для текущей директории
graphify index ./src --output project_graph.json --format json

После этого вы можете использовать этот файл как контекстную карту. Если вы используете GStack: набор инструментов Claude Code, Graphify станет отличным дополнением к пайплайну, предоставляя агенту семантическую разметку кода.

С Cursor ситуация иная. Поскольку это полноценная IDE, здесь Graphify работает как «внешний мозг» для индексации. Вы можете настроить .cursorrules, чтобы агент при каждом запросе обращался к структуре, которую подготовил Graphify. Это повышает предсказуемость ответов: агент не будет предлагать импорты, которых не существует, или функции, которые не соответствуют сигнатуре в AST.

Поддержка CLI для Gemini и Codex

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

С практической точки зрения, CLI позволяет встроить анализ кода в CI/CD или в локальные скрипты подготовки окружения. Например, если вы работаете с моделями семейства Gemini или Codex через API, вы можете генерировать компактные представления кода (embeddings на основе графа), что значительно дешевле и эффективнее, чем передавать весь исходный код целиком.

Пример конфигурации для автоматического обновления графа при изменениях в SQL-схемах:

yaml
# config.yaml для автоматизации анализа
pipeline:
  sources:
    - path: "./migrations/*.sql"
      type: "sql"
    - path: "./src/**/*.ts"
      type: "typescript"
  output:
    format: "graphml"
    destination: "./knowledge_base/latest_graph.graphml"
  engine:
    ast_parser: "deterministic"
    depth: 3 # Глубина анализа связей для оптимизации контекста

Если ваша задача — реверс-инжиниринг с помощью AI-агентов, то использование CLI Graphify позволяет быстро «прощупать» структуру бинарного проекта или обфусцированного кода, предварительно собрав AST-дерево.

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

Источники данных для анализа

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

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

Одной из сильных сторон Graphify является работа с детерминированным AST-парсингом. В отличие от LLM, которые могут галлюцинировать структуру таблиц, парсер строит точную модель на основе синтаксиса. Если мы подаём на вход SQL-дамп или файлы миграций, инструмент извлекает связи FOREIGN KEY, типы данных и ограничения (constraints).

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

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

Пример типичного файла конфигурации для анализа:

yaml
# config/services.yaml
services:
  database:
    driver: postgresql
    port: 5432
    tables:
      - users
      - orders
  api_gateway:
    upstream: database
    timeout: 30s

Чтобы добавить такие файлы в область видимости парсера, в конфигурационном файле Graphify (graphify.yaml) нужно явно указать расширения:

yaml
analysis:
  include_extensions:
    - .sql
    - .yaml
    - .yml
    - .json
  exclude_paths:
    - **/node_modules/**
    - **/venv/**

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

Работа с документацией и PDF-файлами

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

Когда мы занимаемся реверс-инжинирингом с помощью AI-агентов, документация становится ключевым связующим звеном. Например, если в PDF-схеме описан процесс авторизации, Graphify сопоставит текстовое описание «User must provide a JWT token» с конкретным middleware в коде.

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

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

Процесс добавления документации в пайплайн выглядит так:

bash
# Команда для индексации директории с документацией
graphify index ./docs --format markdown --include-pdf

После этого инструмент создаст узлы в графе, представляющие концепции из текста, и попытается провести ребра (edges) к соответствующим участкам кода. Это превращает разрозненные файлы в единую базу знаний, где вопрос «как работает этот модуль?» получает ответ, объединяющий и код, и описание из документации.

Практическое применение и ограничения

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

Когда графа знаний достаточно для контекста LLM

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

С практической точки зрения, это работает в следующих случаях:

Навигация по кодовой базе. Вместо того чтобы скармливать модели тысячи строк кода, вы передаёте ей топологию: «Метод process_order вызывает validate_payment, который обращается к таблице transactions». Это минимизирует галлюцинации, так как связи детерминированы парсером, а не вероятностной моделью.
Генерация документации и схем. Если у вас есть разрозненные SQL-миграции и Python-скрипты, Graphify свяжет их в единую логическую цепочку. Это критически важно при реверс-инжиниринге с помощью AI-агентов, когда нужно восстановить логику работы системы по косвенным признакам.
Анализ влияния (Impact Analysis). Когда вы меняете сигнатуру функции, граф позволяет мгновенно вычислить все узлы, которые зависят от этого изменения.

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

yaml
# Пример конфигурации глубины анализа для Graphify
analysis_settings:
  depth: 3                # Глубина рекурсивного обхода зависимостей
  include_external: false # Не включать зависимости из site-packages
  focus_nodes:
    - type: "class"
    - type: "sql_table"
  output_format: "json-ld" # Формат для легкого парсинга LLM

Сценарии, где традиционный RAG может уступать

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

Если мы посмотрим на типичный сценарий поиска ошибки, разница становится очевидной.

Пример: Поиск причины падения транзакции.

Традиционный RAG: Вы спрашиваете: «Почему падает транзакция?». Система находит куски логов и документации, где упоминается слово «транзакция». Она может выдать описание процесса, но не поймёт, что конкретный метод в services/payment.py вызывает исключение из-за отсутствия индекса в таблице orders.
Graph-based подход (Graphify): Система видит путь: API Endpoint $\to$ Service Layer $\to$ Repository $\to$ Database Schema. Она понимает структурную связь между кодом и схемой данных.

Традиционный RAG уступает в задачах, требующих логического вывода по цепочке:

Сложные рефакторинги. RAG не знает, что удаление одного поля в базе данных «сломает» метод в другом микросервисе, если эти сервисы не описаны в одном текстовом блоке. Граф же видит эту связь через общую схему.
Проверка консистентности. Если вы используете Omnara для управления агентами, им нужно понимать не только «что» делает инструмент, но и «как» он связан с остальной инфраструктурой. Граф обеспечивает эту предсказуемость.
Безопасность и аудит. При настройке доступа для AI-агентов с помощью Alter, важно точно знать, к каким именно объектам (таблицам, методам) агент может получить доступ. Семантический поиск здесь слишком неточен — нам нужна строгая идентификация объектов.

Однако стоит помнить об ограничении: Graphify не заменит RAG полностью. Для поиска по «смыслу» (например, «как реализована политика обработки ошибок в проекте?») лучше использовать векторный поиск. Идеальная архитектура сегодня — это гибридный подход, где векторный индекс отвечает за поиск по описаниям, а граф — за навигацию по структуре.

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

Чем Graphify отличается от обычного RAG с векторным поиском

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

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

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

Насколько точно инструмент определяет зависимости в больших проектах

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

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

На текущий момент возможности инструмента зависят от наличия стабильных парсеров для конкретных языков. Поскольку работа строится на извлечении абстрактного синтаксического дерева, поддержка расширяется по мере добавления новых грамматик. Для полноценного использования важно убедиться, что используемый язык имеет зрелую экосистему инструментов для статического анализа.

Построение графа знаний из кода с Graphify