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

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

Как работает построение графа знаний

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

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

Детерминированный парсинг AST

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

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

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

python
# Пример кода, который Graphify разложит на узлы графа
from fastapi import FastAPI, Depends
from .database import get_db

app = FastAPI()

@app.get("/users/{user_id}")
async def read_user(user_id: int, db = Depends(get_db)):
    return await db.fetch_user(user_id)

В графе это превратится в набор узлов:

App (тип: FastAPI instance)
read_user (тип: function, связана с App через декоратор)
get_db (тип: dependency, связана с read_user)
db (тип: parameter, связан с get_db)

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

Отказ от векторных хранилищ

Главное архитектурное отличие Graphify — сознательный отказ от использования векторных хранилищ в качестве основного источника истины.

В классическом RAG процесс выглядит так: код $\rightarrow$ чанки $\rightarrow$ эмбеддинги $\rightarrow$ векторная БД $\rightarrow$ семантический поиск. Проблема в том, что семантический поиск работает по принципу «похоже на то, что спрашивали». Если вы спросите: «Где обрабатывается ошибка авторизации?», векторный поиск может выдать вам файл auth.py, но пропустит важную логику в middleware.py, если слова в них не совпадают.

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

Calls (вызов функции)
Inherits (наследование класса)
Defines (определение переменной/типа)
References (ссылка на объект)

Это делает работу агентов гораздо более стабильной. Когда вы настраиваете CLAUDE.md для улучшения работы Claude Code, вы фактически даёте инструкции, как использовать этот контекст. С графом агент не гадает, а точно знает: «Чтобы понять, как работает этот метод, мне нужно посмотреть на три связанных с ним класса и схему таблицы в SQL».

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

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

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

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

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

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

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

Пример структуры .cursorrules с упоминанием графа:

markdown
# Context Awareness
Always refer to the knowledge graph located in `.graphify/schema.json` 
when analyzing cross-module dependencies. 

If a change affects a database schema, validate it against the 
relationships defined in the graph to prevent breaking downstream services.

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

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

Для тех, кто предпочитает автоматизацию и не хочет полагаться на GUI, Graphify предоставляет полноценный CLI. Это позволяет встроить создание графа в ваш CI/CD пайплайн или в локальные скрипты автоматизации.

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

Для базового анализа текущей директории достаточно выполнить:

bash
# Генерация графа из текущей папки с учетом файлов конфигурации
graphify index . --output ./docs/knowledge-graph

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

Пример более сложной команды для сборки графа, включающего SQL-схемы и документацию:

bash
graphify index ./src \
  --include-sql ./migrations \
  --include-docs ./docs \
  --format json \
  --output ./build/graph.json

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

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

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

Анализ сложных SQL-схем и конфигураций

Когда кодовая база разрастается, понимание того, как данные перетекают из одной таблицы в другую через цепочку связей, становится проблемой. Если вы пытаетесь скормить LLM (Large Language Model) сырой дамп базы данных, вы быстро столкнётесь с ограничением контекстного окна или, что ещё хуже, с галлюцинациями. Модель может «забыть» про промежуточную таблицу-связку или неверно интерпретировать внешние ключи.

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

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

Пример конфигурации для анализа SQL-схем в graphify.config.yaml:

yaml
sources:
  - type: sql
    path: "./migrations/*.sql"
    engine: postgresql # Указываем движок для корректной обработки диалекта
    extract_relations: true # Важно для построения связей между таблицами

output:
  format: json-graph
  destination: "./knowledge-graph/db-schema.json"

После запуска процесса анализа, агент сможет отвечать на вопросы вроде: «Какие таблицы затронет изменение типа поля user_id в таблице orders?». Благодаря предсказуемости графа, ответ будет базироваться на реальных связях, а не на вероятностном подборе слов.

Поиск связей в документации и PDF

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

Graphify позволяет объединить текстовую документацию с кодом в единый граф знаний. Инструмент парсит документы, извлекает сущности (Entity Extraction) и пытается сопоставить их с идентификаторами в коде.

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

Для индексации документации используйте следующий подход:

bash
# Запуск индексации папки с документацией и исходного кода
graphify index --docs ./docs/architecture --code ./src --output ./graph-data

В процессе работы Graphify создаёт узлы для концепций (например, «Auth Flow») и связывает их с конкретными функциями или классами в коде.

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

Это делает работу с AI-агентами более системной: вы не просто надеетесь, что модель «поймёт» ваш проект, а предоставляете ей проверенную структуру связей.

Ограничения и особенности метода

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

Предсказуемость связей против гибкости эмбеддингов

Основная сложность здесь заключается в выборе между семантической близостью и структурной точностью.

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

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

Однако за это приходится платить потерей контекста в неструктурированных данных. Граф отлично понимает связи между классами в Python или таблицами в SQL, но он пасует там, где логика описана в документации «человеческим» языком без явных ссылок. Чтобы сгладить этот переход, я рекомендую комбинировать графовый подход с качественной подготовкой контекста. Например, настройка CLAUDE.md для улучшения работы Claude Code помогает агенту лучше ориентироваться в правилах проекта, которые сложно формализовать в AST.

С практической точки зрения, это означает, что ваш пайплайн должен выглядеть так:

Извлечение структуры через AST (жесткие связи).
Генерация эмбеддингов для описаний узлов (семантическая гибкость).
Объединение в гибридный поиск.

Локальная обработка данных

Второй критический момент — это вопрос безопасности и производительности. Работа с кодовой базой через облачные API — это всегда риск утечки интеллектуальной собственности. Graphify спроектирован так, чтобы минимизировать передачу чувствительных данных вовне.

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

Если вы планируете использовать инструмент в рамках своего рабочего процесса, я советую запускать процесс индексации локально, чтобы избежать передачи исходников на сторонние сервера. Для управления такими процессами удобно использовать контейнеризацию. Вот пример базового docker-compose.yml для развертывания локального узла обработки:

yaml
services:
  graphify-indexer:
    image: graphify/indexer:latest
    volumes:
      # Монтируем кодовую базу для анализа
      - ./my-project:/app/code:ro
      # Папка для хранения сформированного графа
      - ./graph_data:/app/data
    environment:
      - LOG_LEVEL=info
      - MAX_MEMORY=4gb # Ограничиваем потребление, чтобы не «положить» хост
    deploy:
      resources:
        limits:
          memory: 8G

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

Также стоит учитывать, что локальная обработка накладывает ограничения на использование самых мощных моделей. Если вы используете локальный LLM через Ollama или vLLM для обогащения графа, убедитесь, что у вас достаточно видеопамяти (VRAM). В противном случае процесс превратится в бесконечное ожидание, и предсказуемость работы системы упадет до нуля. Для эффективной организации работы с такими инструментами можно использовать мультиплексоры для терминала и AI-агентов, чтобы контролировать несколько потоков анализа одновременно.

Заключение

Практические выводы

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

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

Когда стоит внедрять

Я рекомендую рассматривать Graphify в трёх сценариях:

Онбординг в legacy-проекты. Если вам нужно быстро разобраться в монолите, где зависимости запутаны, граф поможет визуализировать путь вызова функций и понять, какие части системы затронет изменение.
Подготовка контекста для AI-агентов. Если вы используете набор навыков для работы с AI-агентами, создание графа станет этапом препроцессинга данных.
Анализ архитектурных изменений. Инструмент помогает увидеть, как изменения в SQL-схемах влияют на логику приложения на уровне кода.

Однако стоит учитывать и ограничения. На текущий момент Graphify может потреблять значительный объём оперативной памяти при анализе сверхкрупных репозиториев. Если вы планируете запускать его на домашнем сервере с ограниченными ресурсами, лучше делать это в Docker-контейнере с чётко заданными лимитами:

yaml
# Пример конфигурации ресурсов в docker-compose.yml
services:
  graphify:
    image: graphify/core:latest
    deploy:
      resources:
        limits:
          memory: 4G # Ограничиваем потребление, чтобы не «положить» систему
    volumes:
      - ./src:/app/code
      - ./output:/app/graph

Итоговый чек-лист

Перед тем как интегрировать Graphify в свой рабочий процесс, убедитесь, что выполнены следующие шаги:

Проверена чистота исходников. Граф строится на основе AST, поэтому наличие синтаксических ошибок в коде может привести к неполному построению связей.
Настроены исключения. Обязательно добавьте в конфигурацию папки с зависимостями (node_modules, venv) и сгенерированный код, чтобы не раздувать граф мусорными узлами.
Выбран формат вывода. Для работы с агентами лучше всего подходит структурированный JSON или формат, совместимый с векторными базами данных.

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

FAQ

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

Вам не нужно поднимать отдельный инстанс базы вроде Chroma или Pinecone для базовой работы. Graphify спроектирован так, чтобы создавать локальный граф знаний, который хранит связи между сущностями в структурированном виде. Это обеспечивает предсказуемость: вы точно знаете, на основе каких связей AI-агент строит свой ответ.

Если же вы планируете интегрировать полученные данные в масштабную систему с RAG (Retrieval-Augmented Generation), вы можете экспортировать граф в стандартных форматах. С практической точки зрения, для локальной разработки и работы с Claude Code встроенных механизмов хранения Graphify вполне достаточно.

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

Инструмент работает на основе анализа AST (Abstract Syntax Tree), поэтому его возможности зависят от того, насколько глубоко он может «прочитать» структуру файла. На текущий момент основная поддержка сосредоточена на:

Код: TypeScript, JavaScript, Python, Go и Rust.
Схемы данных: SQL-файлы (DDL), которые позволяют связать логику приложения с архитектурой БД.
Документация: Markdown-файлы, которые превращаются в текстовые узлы графа.

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

ignore
# Игнорируем скомпилированные файлы и зависимости
node_modules/
dist/
*.pyc

Можно ли использовать инструмент локально?

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

Для быстрой проверки работоспособности в локальной среде достаточно выполнить:

bash
# Установка через npm (если доступно в вашем реестре)
npm install -g @antigravity/graphify

# Запуск индексации текущей директории
graphify index . --output ./knowledge-graph

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

Как Graphify помогает AI-агентам?

Обычные LLM часто «галлюцинируют» или теряют контекст в больших репозиториях, потому что пытаются работать с кодом как с плоским текстом. Graphify меняет парадигму: вместо поиска по кускам текста агент получает карту зависимостей.

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

Где эта функция объявляется.
Какие другие компоненты её вызывают.
Как это изменение затронет структуру базы данных через SQL-схемы.

Это делает работу агентов более осмысленной, что особенно заметно при использовании таких инструментов, как Corgi или при оптимизации через Ponytail. Граф превращает «угадывание» в точную навигацию по архитектуре.

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

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

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

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

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

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

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

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

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

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