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

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

Как работает Graphify

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

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

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

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

Когда Graphify сканирует репозиторий, он не просто читает текст. Он разбирает его на структурные элементы: определения классов, методы, импорты, типы данных и зависимости. Это позволяет инструменту понимать, что функция calculate_total() в файле orders.py не просто «похожа» на расчеты, а является частью класса OrderProcessor и вызывается в методе checkout().

С практической точки зрения это дает колоссальную разницу в точности. Для сравнения:

Векторный поиск: Находит куски кода, где упоминаются «заказы» и «цены».
Graphify (AST): Находит конкретный путь от HTTP-эндпоинта до SQL-запроса, прослеживая зависимости через все слои приложения.

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

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

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

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

Процесс построения графа можно представить как многоэтапный конвейер:

Parsing: Извлечение AST из файлов (Python, TypeScript, Go и др.).
Schema Extraction: Анализ SQL-схем для понимания структуры данных.
Relationship Mapping: Создание ребер графа (вызовы функций, наследование, связи в БД).
Graph Export: Формирование финального графа знаний.

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

yaml
# graphify.config.yaml
include:
  - "src/**/*.py"
  - "schema/*.sql"
exclude:
  - "tests/**"
  - "**/__pycache__"
  - "venv/**"
output:
  format: "json-ld"
  path: "./knowledge-graph/project_map.json"

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

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

Возможности инструмента

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

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

Большинство инструментов анализа кода фокусируются исключительно на AST (Abstract Syntax Tree). Graphify идет дальше и включает в граф не только синтаксическую структуру, но и семантику, описанную в документации и схемах БД.

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

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

yaml
# graphify.config.yaml
indexing:
  sources:
    - path: "./src/models"
      type: "python"
    - path: "./docs/api"
      type: "markdown"
    - path: "./migrations"
      type: "sql"
  
  # Указываем, какие именно сущности связывать
  relations:
    - type: "sql_to_code"
      description: "Связь таблиц БД с ORM-моделями"
    - type: "doc_to_code"
      description: "Связь описания API с реализацией эндпоинтов"

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

Интеграция с Claude Code и Cursor

Graphify спроектирован как связующее звено между вашей кодовой базой и инструментами разработки. Вместо того чтобы заставлять Claude Code или Cursor «проглатывать» весь репозиторий целиком (что дорого и неэффективно), вы предоставляете им контекст через граф.

Claude Code. Инструмент отлично работает в связке с CLI-интерфейсами. После генерации графа вы можете использовать его как локальный контекстный сервер. Это позволяет реализовать более глубокий набор инструментов Claude Code, где агент может запрашивать не просто «код файла», а «все зависимости функции X».
Cursor. В редакторе Cursor интеграция происходит на уровне индексации. Graphify может экспортировать данные в формате, который позволяет ИИ-функциям редактора лучше понимать зависимости. Это особенно полезно при проведении реверс-инжиниринга с помощью AI-агентов, когда нужно быстро восстановить цепочку вызовов в незнакомом проекте.

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

Для проверки того, как Graphify видит связи, можно использовать встроенную команду отладки:

bash
# Посмотреть связи для конкретного класса или таблицы
graphify analyze --target "UserRegistrationService" --depth 2

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

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

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

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

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

С практической точки зрения это выглядит так: агент не просто «читает» файл, он делает запрос к графу, чтобы понять связи. Например, если мы работаем с SQL-схемами, Graphify связывает определения таблиц с кодом ORM.

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

bash
# Инициализация сканирования проекта и построения графа
graphify index ./src --include-sql ./migrations --output ./knowledge-graph

После этого агент, работающий через Omnara, может получать не просто куски текста, а структурированные ответы. Вместо «Найди все функции, использующие таблицу users», запрос превращается в поиск по узлам графа, где Table(users) связан с Function(get_user_by_id). Это обеспечивает предсказуемость: агент видит реальную архитектуру, а не то, что ему удалось «выцепить» из контекстного окна.

Анализ сложных зависимостей в проекте

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

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

Рассмотрим пример конфигурации для глубокого анализа зависимостей. Мы можем настроить Graphify так, чтобы он уделял особое внимание связям между API-эндпоинтами и бизнес-логикой:

yaml
# graphify-config.yaml
analysis:
  depth: full           # Глубина анализа: от локальных связей до всего проекта
  extract_ast: true     # Использовать AST для построения графа
  include_types: true   # Учитывать типы данных для уточнения связей
  
mapping:
  - source: ./api/      # Откуда начинаем поиск
    target: ./services/ # Куда прослеживаем зависимости
    relation: calls     # Тип связи: вызов функции

Применение такого подхода позволяет решать задачи типа: «Какие компоненты системы затронет изменение типа поля status в таблице заказов?».

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

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

Итоги использования

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

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

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

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

Когда Graphify может не подойти

Не стоит ждать чудес, если ваша кодовая база представляет собой «спагетти» без внятной структуры. Граф будет точным настолько, насколько точен сам код. Если зависимости прописаны через динамические вызовы или сложные метапрограммируемые конструкции, которые AST не может разрешить статически, в графе появятся разрывы.

Также стоит учитывать нагрузку на ресурсы. Построение графа для монолита на несколько миллионов строк кода — это не мгновенная операция. Она требует памяти и времени CPU. Если вы планируете использовать это в CI/CD, рекомендую запускать процесс только при изменении ключевых схем или структуры директорий, а не на каждый пуш.

Для автоматизации процесса можно использовать простой скрипт, который запускает индексацию только для конкретных модулей:

bash
# Индексация только директории с бизнес-логикой и SQL-схем
graphify index ./src/core ./migrations --output ./knowledge-graph.json

Итоговая оценка

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

Если ваша задача — построить систему, где агенты не просто пишут код, а управляют инфраструктурой или проводят глубокий анализ, вам понадобятся дополнительные инструменты управления. Например, стоит изучить Omnara для управления ИИ-агентами или настроить контроль доступа через Alter, чтобы агенты не навели «порядка» там, где их не просили.

В конечном счёте, качество работы любого AI-инструмента напрямую зависит от качества входных данных. Graphify делает эти данные системными.

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

Чем Graphify отличается от обычного RAG?

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

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

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

Насколько сильно Graphify нагружает систему при сканировании репозитория?

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

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

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

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