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

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

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

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

Принцип работы AST-парсинга

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

С практической точки зрения это означает, что инструмент понимает иерархию. Если в коде есть вызов метода calculate_metrics(), Graphify не просто найдёт это слово, он проследит связь от места вызова до места определения, учитывая область видимости и зависимости модулей.

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

Пример того, как парсер видит простую функцию на Python:

python
def process_data(payload: dict) -> bool:
    # Логика обработки
    return True

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

FunctionDefinition (имя: process_data)
Argument (имя: payload, тип: dict)
ReturnType (тип: bool)
Edge (связь между функцией и её аргументами)

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

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

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

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

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

Характеристика	Векторные хранилища (RAG)	Graphify (AST-based)
Тип связи	Семантическая близость (вероятностная)	Структурная зависимость (детерминированная)
Точность	Может «галлюцинировать» связи	Всегда следует правилам грамматики языка
Контекст	Ограничен окном контекста и качеством эмбеддинга	Полный охват всей топологии проекта
Предсказуемость	Низкая (результат зависит от модели)	Высокая (результат зависит от кода)

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

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

Возможности анализа кодовой базы

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

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

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

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

Если вы используете REAE: реинжиниринг через агентов, вы знаете, как важно иметь полную картину связей. Graphify парсит .sql файлы, извлекая из них определения таблиц, внешние ключи (foreign keys) и индексы. Это позволяет связать, например, сущность User в коде на Python с соответствующей таблицей users в PostgreSQL.

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

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

yaml
# graphify-config.yaml
analysis:
  targets:
    - path: "./infrastructure/db"
      type: "sql"
      dialect: "postgresql" # Указываем диалект для корректного парсинга
    - path: "./configs"
      type: "yaml"
  
  graph_options:
    include_constraints: true # Сохраняем связи через foreign keys
    depth: 3 # Глубина обхода связей для построения графа

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

Интеграция с документацией и PDF

Проблема «разрыва знаний» заключается в том, что документация часто живет отдельно от кода. Архитектурные решения описываются в DESIGN.md, требования — в PDF-файлах, а реализация — в репозитории.

Graphify пытается навести мосты между этими мирами. Благодаря интеграции с текстовыми форматами, инструмент может сопоставлять сущности из документации с объектами в коде. Если в вашем DESIGN.md описан процесс обработки платежей, Graphify постарается найти соответствующие классы и методы, используя семантический анализ, но с опорой на уже построенный AST-граф.

Это особенно полезно при использовании DESIGN.md для AI-агентов. Агент, имеющий доступ к графу знаний, не просто читает файл, он понимает, к каким узлам графа (функциям, таблицам, API-эндпоинтам) относятся описанные в документе правила.

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

Пример команды для запуска комплексного анализа проекта:

bash
# Запуск анализа кодовой базы, схем БД и документации
graphify analyze --config graphify-config.yaml --docs ./docs/architecture.pdf

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

Использование в современных AI-инструментах

Подключение к Claude Code и Cursor

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

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

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

Для интеграции в рабочий процесс можно подготовить JSON-экспорт графа, который будет служить «картой местности» для агента:

json
// Пример фрагмента экспорта графа для передачи в контекст агента
{
  "node": "UserService.ts",
  "type": "class",
  "dependencies": [
    { "target": "UserRepository.ts", "relation": "instantiates" },
    { "target": "user_schema.sql", "relation": "maps_to" }
  ],
  "methods": ["createUser", "findUserByEmail"]
}

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

Автоматизация через Gemini CLI

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

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

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

Graphify сканирует репозиторий и строит граф (AST + SQL + Docs).
Результат сохраняется в локальный файл.
Gemini CLI считывает этот файл и выполняет запрос по анализу связей.

Пример команды для запуска анализа через CLI (предположим, что мы используем обёртку для работы с Gemini):

bash
# 1. Генерируем граф проекта
graphify build ./src --output graph.json

# 2. Отправляем граф и запрос на анализ в Gemini CLI
gemini-cli prompt "Проанализируй зависимости в graph.json и найди потенциальные точки отказа при изменении схемы базы данных" --context graph.json

Такой метод позволяет автоматизировать настройку ИИ-агентов из .agents, создавая для них автоматические пресеты контекста. Вместо того чтобы каждый раз вручную объяснять агенту структуру проекта, вы просто подкладываете ему актуальный граф.

Если вы строите сложную систему мониторинга или отладки, где агенты должны анализировать не только код, но и поведение системы, обратите внимание на RL-модель flow-1 для поиска ошибок в трейсах агентов. Совмещение структурного графа кода и данных из трейсов даёт максимально полную картину происходящего в приложении.

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

Когда графа знаний становится достаточно

При работе с Graphify важно понимать, где заканчивается польза детерминированного AST-парсинга и начинается избыточность. Основная ценность инструмента — в предсказуемости. В отличие от RAG-систем (Retrieval-Augmented Generation), которые полагаются на семантический поиск по векторным эмбеддингам, Graphify строит жесткие связи: «функция А вызывает функцию Б», «таблица С связана с полем D через внешний ключ».

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

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

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

Однако, если вы работаете с огромным массивом неструктурированного текста (например, сотен страниц разрозненных Wiki-документов без единой логики), Graphify может не хватить глубины. В таких случаях граф лучше дополнять классическим семантическим поиском.

Сценарии для сложных инфраструктурных проектов

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

Анализ связей между кодом и схемой БД

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

Если вы планируете REAE: реинжиниринг через агентов, наличие такого графа критически важно. Агент сможет не просто «читать код», а понимать, что изменение типа данных в одной таблице затронет конкретный метод в сервисе.

Пример конфигурации для запуска анализа связей (условно):

yaml
# config.yaml для Graphify
project:
  name: "infrastructure-audit"
  sources:
    - path: "./src/services"
      type: "python"
    - path: "./migrations"
      type: "sql"
  output:
    format: "json-graph"
    path: "./build/knowledge-graph.json"
  parsing:
    ast_depth: 5 # глубина обхода дерева зависимостей
    include_sql_constraints: true # учитывать FK и уникальные индексы

Подготовка контекста для AI-агентов

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

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

Объект: UserAuthService
Зависимости: PostgreSQL_DB (через UserTable), Redis_Cache (через SessionStore).

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

В конечном счете, Graphify — это инструмент для тех, кто ценит структурный подход. Он не заменяет понимание кода, но создает надежный фундамент, на котором можно строить автоматизацию любой сложности, от простых скриптов до продвинутых систем мониторинга ошибок, подобных RL-модели flow-1.

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

Чем Graphify отличается от классического семантического поиска

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

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

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

Насколько предсказуемы результаты парсинга

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

Требуется ли развёртывание векторной базы данных для работы системы

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

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