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

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

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

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

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

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

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

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

С практической точки зрения это означает, что если у вас есть функция process_order(order_id), Graphify не просто найдет её текст, а поймёт, что order_id — это внешний ключ, ссылающийся на таблицу orders в вашей базе данных.

Для запуска базового анализа проекта можно использовать CLI-интерфейс. Сначала убедитесь, что у вас установлена актуальная версия инструмента:

bash
pip install graphify-tool

Затем запустите сканирование директории с кодом. Для предсказуемости результата стоит явно указать входные пути:

bash
# Сканирование исходников и SQL-миграций для построения единого графа
graphify scan --src ./src --sql ./migrations --output ./knowledge_graph.json

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

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

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

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

Graphify сознательно отказывается от векторного поиска в пользу графовой структуры по нескольким причинам:

Детерминизм. В графе связь между функцией и её определением либо есть, либо её нет. Здесь нет места «вероятности сходства». Это обеспечивает ту самую предсказуемость, которая критически важна при автоматизации AI-агентов.
Глубина контекста. Векторный поиск ограничен «близостью» векторов. Граф же позволяет делать многошаговые запросы: «Найди все функции, которые косвенно влияют на таблицу users через цепочку вызовов».
Производительность и стоимость. Вам не нужно поднимать тяжеловесный сервис вроде Chroma или Pinecone и тратить ресурсы на генерацию эмбеддингов для каждого изменения в коде. Граф строится на основе структуры самого кода, что гораздо дешевле и быстрее.

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

Возможности анализа различных типов данных

Работа с исходным кодом и конфигурациями

Главное отличие Graphify от классических RAG-систем (Retrieval-Augmented Generation) заключается в том, как именно инструмент «понимает» структуру проекта. Вместо того чтобы просто нарезать файлы на куски и превращать их в векторы, Graphify использует AST-парсинг (Abstract Syntax Tree). С практической точки зрения это означает, что инструмент видит не просто текст, а логические связи: где объявляется функция, где она вызывается и какие зависимости у неё есть.

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

Инструмент одинаково эффективно обрабатывает и логику, и конфигурацию. Например, если у вас есть сложный docker-compose.yml или конфигурационные файлы nginx.conf, Graphify извлечёт зависимости между сервисами. Это позволяет составить полную карту того, как инфраструктурный слой связан с прикладным кодом.

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

yaml
# Пример конфигурации graphify.yaml
analysis:
  include_extensions:
    - .py
    - .go
    - .yaml
    - .conf
  exclude_dirs:
    - node_modules
    - .git
    - venv
  parser_settings:
    ast_depth: 5 # Глубина вложенности для анализа связей

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

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

При анализе SQL-схем инструмент парсит DDL-запросы (Data Definition Language). Он строит связи между таблицами через FOREIGN KEY, что позволяет графу знаний понимать, как данные перемещаются через систему. Если в коде есть метод update_user_profile, граф позволит проследить, к какой именно таблице в базе данных этот метод обращается.

С PDF-документацией ситуация сложнее, так как это неструктурированные данные. Здесь Graphify использует комбинированный подход: извлечение сущностей и попытка сопоставить их с уже существующими узлами в графе кода. Это приближает инструмент к концепции AI Agent Harness, где агент должен обладать максимально полным контекстом для принятия решений.

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

bash
# Пример экспорта схемы PostgreSQL для последующего анализа Graphify
pg_dump -s my_database > schema_dump.sql

После этого Graphify просканирует файл и добавит узлы таблиц в общий граф. В итоге вы получаете единую карту знаний, где:

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

Такой системный подход исключает ситуацию, когда агент предлагает решение, которое технически верно для кода, но нарушает правила, описанные в документации или архитектуре БД.

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

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

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

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

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

bash
# Генерация графа знаний для текущей директории
graphify scan --path ./src --include-sql ./schema.sql --output ./knowledge_graph.json

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

markdown
# Project Context: Knowledge Graph
Always refer to `knowledge_graph.json` when analyzing function calls or database dependencies. 
The graph provides AST-based truth about how modules interact.

В Cursor интеграция происходит через добавление сгенерированного JSON-файла в индекс проекта (Codebase Indexing). Поскольку Graphify выдаёт плоский или древовидный список связей, Cursor быстрее находит нужные узлы, не тратя токены на перечитывание всего репозитория. Это особенно полезно в больших проектах, где стандартный поиск по символам может давать слишком много шума.

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

Если ваш рабочий процесс завязан на терминале и вы используете Gemini CLI для автоматизации задач, Graphify можно встроить в конвейер (pipeline) обработки данных. Здесь важна предсказуемость: мы подаём на вход структурированный граф, а на выходе получаем осмысленный ответ от модели без лишних рассуждений о структуре кода.

Для этого удобно использовать связку из graphify и стандартных инструментов обработки JSON, таких как jq. Сначала подготовим контекст, отфильтровав только нужные нам зависимости (например, только связи между сервисами), и передадим это в Gemini.

Пример скрипта для анализа потенциальных регрессий при изменении схемы БД:

bash
#!/bin/bash

# 1. Генерируем актуальный граф
graphify scan --path ./services --include-sql ./db/migrations --output ./temp_graph.json

# 2. Извлекаем только связи, связанные с таблицей 'users'
CONTEXT=$(jq '.nodes[] | select(.type == "table" and .name == "users") | .edges' ./temp_graph.json)

# 3. Отправляем запрос в Gemini CLI
gemini ask "Analyze the following dependencies for the 'users' table and identify potential breaking changes: $CONTEXT"

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

Если вы планируете развивать подобные инструменты самостоятельно, рекомендую взглянуть на архитектурные решения в проектах вроде Claw-Code, где также уделяется внимание эффективной работе с кодом на низком уровне.

Практическое применение в инженерных задачах

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

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

Graphify решает эту задачу иначе. Вместо того чтобы превращать код в набор абстрактных векторов, он строит точный граф на основе AST (Abstract Syntax Tree). Для AI-агента это означает переход от «угадывания» к «навигации». Если вы используете Claude Code, наличие структурированного графа знаний позволяет агенту не просто читать файлы, а понимать архитектурные связи.

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

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

yaml
# Пример конфигурации Graphify для фокуса на связях методов и типов
analysis:
  include_patterns:
    - "src/**/*.ts"
    - "lib/**/*.py"
  extract:
    - function_definitions
    - class_hierarchies
    - type_aliases
  graph_output:
    format: jsonld
    path: ./build/knowledge_graph.jsonld

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

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

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

Graphify позволяет объединить три разных мира в одну модель:

Исходный код (через AST-парсинг).
Документацию (Markdown/Docstrings).
Схемы БД (SQL DDL).

Если мы посмотрим на типичную задачу — отслеживание влияния изменения схемы — процесс выглядит так. Сначала мы извлекаем структуру БД, а затем сопоставляем её с объектами в коде (например, ORM-моделями).

Предположим, у нас есть SQL-файл со схемой:

sql
-- schema.sql
CREATE TABLE users (
    id UUID PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    status VARCHAR(50) DEFAULT 'active'
);

Graphify проанализирует этот файл и создаст узлы для таблицы users и её колонок. При сопоставлении с кодом на Python (например, через SQLAlchemy), инструмент выстроит ребро между узлом users.email и соответствующим атрибутом класса в коде.

Это критически важно при проведении аудита безопасности или рефакторинга. Вместо того чтобы использовать grep и надеяться на точность совпадений, вы можете построить запрос к графу. Если вы хотите найти все функции, которые напрямую или косвенно работают с конфиденциальными данными (например, email), граф покажет полный путь: от SQL-колонки до конечного API-эндпоинта.

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

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

Заключение

Когда Graphify оправдан

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

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

Аудит безопасности: поиск путей данных от входа в API до выполнения SQL-запроса.
Onboarding новых инженеров: создание карты проекта, чтобы понять, какой модуль за что отвечает.
Рефакторинг: выявление скрытых зависимостей, которые не видны при обычном поиске по тексту.

Ограничения подхода

Важно понимать, что отсутствие векторного хранилища — это не только преимущество в скорости и простоте, но и ограничение. Graphify отлично строит связи «объект — метод — вызов», но он не умеет работать с семантическим поиском по смыслу. Если вы спросите систему: «Где у нас обрабатывается логика скидок?», а в коде нет слова discount, а используется только price_modifier, граф может не дать ответа, если связь не прописана явно через вызовы функций.

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

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

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

Если вы планируете внедрять подобные решения в свои пайплайны, рекомендую начать с небольшого микросервиса. Проверьте, насколько точно парсер отрабатывает ваши специфические паттерны (например, использование декораторов или сложных макросов). Для тех, кто интересуется более глубокой оптимизацией работы с AI-агентами, полезно будет изучить ECC: AI Agent Harness Performance Optimization, чтобы понимать, как архитектура данных влияет на скорость ответа системы.

FAQ

Как Graphify понимает связи в коде?

Инструмент не пытается «угадать» связи на основе семантической близости слов, как это делают классические RAG-системы. Вместо этого он использует AST-парсинг (Abstract Syntax Tree — абстрактное синтаксическое дерево).

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

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

Нет, для работы Graphify векторное хранилище не требуется. В этом и заключается одно из ключевых отличий инструмента от стандартных AI-агентов, которые часто требуют развёртывания тяжеловесных решений вроде Chroma или Pinecone.

Вместо поиска по векторам (similarity search), Graphify использует графовую структуру. Это упрощает архитектуру вашей домашней лаборатории: вам не нужно выделять дополнительные ресурсы под базу эмбеддингов. Если вы уже используете Claw-Code или другие инструменты на Rust, вы заметите, что такой подход гораздо легче вписывается в общую экосистему благодаря низкой нагрузке на память.

Какие типы файлов поддерживает инструмент?

На текущий момент Graphify ориентирован на структуры, которые можно однозначно разобрать через AST или схемы. Основной упор сделан на:

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

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

Можно ли использовать Graphify локально?

Да, инструмент спроектирован с учётом возможности локального запуска. Поскольку он не полагается на векторные БД, его можно развернуть в виде легковесного процесса или контейнера.

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

yaml
services:
  graphify:
    image: graphify/core:latest
    volumes:
      # Монтируем директорию с вашим проектом
      - ./my-project:/app/code:ro
      # Папка для сохранения результатов графа
      - ./output:/app/graph
    command: ["--analyze", "/app/code", "--output", "/app/graph"]

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

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

Чем AST-парсинг лучше векторного поиска для анализа кода

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

Можно ли использовать Graphify для анализа динамических языков

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

Как инструмент связывает код с SQL-схемами

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

Требует ли Graphify наличия работающей базы данных

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

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