Graphify: код, конфиги и PDF в графе знаний

Graphify: код, конфиги и PDF в графе знаний

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

Что делает Graphify и зачем это нужно

Что делает Graphify и зачем это нужно

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

Graphify делает иначе. Он парсит исходный код локально через AST, извлекает SQL-схемы, конфиги и даже текст из PDF, а затем связывает всё это в один ориентированный граф. В узлах — файлы, классы, функции, таблицы, переменные окружения. В рёбрах — зависимости, импорты, ссылки, использование. Нет векторной базы, нет эмбеддингов, нет неопределённости с cosine similarity. Есть предсказуемая структура, которую можно обойти алгоритмом или визуализировать.

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

От репозитория к графу знаний

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

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

yamlКопировать
# graphify.yaml
repository: ./my-project
output: ./graph-output
format: graphml

parsers:
  - python
  - typescript
  - sql
  - pdf

include:
  - "src/**"
  - "configs/**"
  - "docs/**/*.pdf"

exclude:
  - "node_modules/**"
  - "venv/**"
  - "*.lock"

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

bashКопировать
graphify analyze --config graphify.yaml

Инструмент обходит указанные директории, парсит каждый файл и записывает узлы и рёбра в выходной файл. Для Python-проекта узлом может быть класс с методом, для SQL — таблица с колонками, для PDF — страница с извлечённым текстом. Рёбра связывают их: импорт в коде, внешний ключ в базе, ссылка в документе.

Практический пример. Допустим, у вас есть Django-проект с PostgreSQL и парой сервисных PDF-документов. Graphify покажет, что модель Order из models.py связана с таблицей orders в схеме public, которая référencруется из SQL-файла миграции, а документация по бизнес-логике из docs/order-flow.pdf ссылается на тот же класс OrderService. Без графа вам пришлось бы искать эти связи вручную, переключаясь между редактором кода, клиентом базы и просмотрщиком PDF.

Почему не векторная база

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

AST-парсинг работает иначе. Он не угадывает, он извлекает точную структуру. Если в коде есть импорт from auth.service import validate_token, граф будет содержать ребро от файла импорта к файлу с функцией validate_token. Это не вероятность, это факт.

Вот сравнение, которое я использую, когда объясняю разницу коллегам:

Задача	Векторная база	Graphify (AST + граф)
Найти похожий по смыслу код	Да	Нет
Найти все места вызова функции	Приблизительно	Точно
Показать зависимости между модулями	Нет	Да
Связать SQL-таблицу с моделью ORM	Нет	Да
Обойти граф от точки входа к выходу	Нет	Да

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

Ещё один практический момент: векторные базы требуют инфраструктуры — Qdrant, Milvus, Pinecone или что-то ещё. Graphify работает локально, без внешних зависимостей. Это важно, если код не должен покидать периметр компании или если вы просто не хотите поднимать ещё одну базу ради разового анализа.

Если хотите увидеть, как выглядит готовый граф из реального проекта, смотрите Graphify: локальный граф знаний из кода и PDF и Graphify: превращаем любой код в граф знаний. Там разобраны конкретные примеры с конфигами и результатами обхода.

Как работает локальный парсинг кода

Как работает локальный парсинг кода

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

AST и дерево зависимостей

Главный шаг парсинга — преобразование исходного кода в абстрактное синтаксическое дерево (AST). Для этого Graphify использует встроенные в свою инфраструктуру парсеры, настроенные под популярные языки программирования.

Поддержка языков и форматов

Система поддерживает широкое спектр языков и файловых форматов, что позволяет строить граф знаний из кода, SQL-схем, конфигурационных файлов и даже PDF-документов.

yamlКопировать
# Пример конфига для Graphify с указанием источников
graphify_config:
  source_types:
    - python
    - javascript
    - go
    - rust
    - java
    - cpp
    - sql
    - yaml
    - json
    - pdf
  output_format:
    - graphml
    - dag
    - json

При анализе кода Graphify создаёт два взаимосвязанных представления:

1. AST-дерево — иерархическая структура, отражающая синтаксическую структуру программы. Каждый узел представляет один токен или конструкцию (функция, класс, переменную, вызов метода и т.д.). Это позволяет делать точный анализ зависимостей между элементами кода.

2. Дерево зависимостей — граф, где узлы — это сущности (функции, классы, таблицы), а ребра — связи между ними. Зависимости могут быть прямых (вызов функции) или косвенными (использование типа из другой библиотеки).

pythonКопировать
# Пример того, как AST выглядит для простого кода
code = """
def calculate_sum(a, b):
    return a + b

def process_data(data):
    result = calculate_sum(data['x'], data['y'])
    return result
"""

# Внутреннее представление (псевдокод)
ast = parse_code(code)
# AST содержит:
# - функцию calculate_sum (узел с токенами: def, calculate_sum, (a, b), return)
# - функцию process_data (узел с токенами: def, process_data, (data), return)
# - связь: process_data вызывает calculate_sum

Как строится граф зависимостей

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

1. Идентификация сущностей — каждая функция, класс, переменная или таблица получает уникальный идентификатор.
2. Выявление вызовов — для каждой функции определяются вызываемые выражения.
3. Построение ребер — если функция A вызывает функцию B, создаётся ребро A → B в графе зависимостей.
4. Определение типов связей — прямая зависимость (вызов), обратная зависимость (использование типа) и зависимости по данным.

markdownКопировать
[CLAUDE.md: Улучшение поведения Claude Code на основе наблюдений Андрея Карпаты](/guides/claudemd-uluchshenie-povedeniya-claude-code-na-osnove-nablyudeniy-andreya-karpat-wi6gcq)

Поддерживаемые форматы и языки

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

• Python — наиболее частый выбор для анализа логики приложений
• JavaScript / TypeScript — для фронтенд- и бэкенд-кода
• Go — для системного программирования
• Rust — для высокопроизводительных проектов
• Java — для корпоративных приложений
• C++ — для низкоуровневого кода
• SQL — для анализа структуры баз данных
• YAML / JSON — для конфигурационных файлов
• PDF — для обработки документации и спецификаций

markdownКопировать
[Graphify: локальный граф знания из кода и PDF](/articles/graphify-lokalnyy-graf-znaniy-iz-koda-i-pdf-e8e1fj)
[Graphify: превращаем любой код в граф знаний](/articles/graphify-prevraschaem-lyuboy-kod-v-graf-znaniy-pbm6c6)

Форматы, которые Graphify понимает

Формат	Тип данных	Пример использования
Python	Исходный код	Анализ логики приложения, поиск зависимостей между модулями
JavaScript / TypeScript	Исходный код	Обработка фронтенд-компонентов, анализ API-вызовов
Go	Исходный код	Анализ архитектуры микросервисов
Rust	Исходный код	Проверка качества кода и зависимостей
Java	Исходный код	Анализ больших корпоративных проектов
SQL	Схема БД	Построение графа таблиц и связей
YAML / JSON	Конфигурации	Связь параметров проекта с логикой
PDF	Документация	Извлечение структуры и связей из технической документации

Пример обработки SQL-схемы

bashКопировать
# Загрузка SQL-файла и построение графа
graphify parse --format sql --output graphml schema.sql

# Результат — граф, где узлы — таблицы, ребра — связи по ключам

Пример обработки PDF-документации

bashКопировать
# Извлечение структуры из PDF и построение графа знаний
graphify parse --format pdf --output dag project.pdf

# PDF превращается в граф, где узлы — главные разделы или сущности, 
# а ребра — ссылки между ними

Заключение подраздела

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

Интеграция с Claude Code, Cursor и другими IDE

Интеграция с Claude Code, Cursor и другими IDE

Graphify-Labs/graphify позволяет не только строить графы знаний из кода, SQL-схем и конфигов, но и использовать их как источник информации для AI-агентов. Ниже описаны основные способы подключения Graphify к Claude Code, Cursor и другим IDE.

Навык /graphify для агентов

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

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

Базовая настройка

Создайте файл конфигурации graphify.agent в директории вашего проекта:

yamlКопировать
# graphify.agent
agent:
  name: graphify
  enabled: true
  source_dirs:
    - ./src
    - ./config
    - ./data
  query_priority: high
  cache_ttl: 3600

Запуск Graphify в режиме агента

Чтобы Graphify работал как помощник внутри Claude Code, нужно запустить его как вспомогательный процесс. Для этого используйте команду:

bashКопировать
graphify agent start --config graphify.agent

После старта вы получите UDP-порт, который можно использовать для обмена сообщениями между Claude Code и Graphify:

bashКопировать
# Узнайте текущий порт агента
graphify agent status

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

Cursor поддерживает расширения для Python и других языков. Graphify можно запустить как внешний процесс и передавать ему запросы через stdin/stdout или используя API Graphify.

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

bashКопировать
graphify query --config graphify.agent --question "Какие функции определены в API-интерфейсе проекта?"

Если вы хотите автоматизировать этот процесс, можно создать скрипт-обёртку:

pythonКопировать
# cursor_graphify_helper.py
import subprocess
import json

def run_graphify_query(question: str, config_path: str = "graphify.agent") -> str:
    """Запускает Graphify и возвращает ответ из графа знаний."""
    result = subprocess.run(
        ["graphify", "query", "--config", config_path, question],
        capture_output=True,
        text=True
    )
    return result.stdout

if __name__ == "__main__":
    question = input("Введите вопрос к графу знаний: ")
    answer = run_graphify_query(question)
    print(answer)

Запустите скрипт в Cursor для интеграции с вашим IDE:

bashКопировать
python cursor_graphify_helper.py

Использование Graphify в IDE через плагины

Graphify также поддерживает плагин для VS Code (от разработчика проекта). Если вы используете VS Code, установите плагин graphify-vs-code и настройте подключение к локальному графу:

jsonКопировать
// .graphify/vscode.json
{
  "graphify": {
    "enabled": true,
    "source_dirs": [
      "${workspaceFolder}/src",
      "${workspaceFolder}/config"
    ],
    "query_interval_seconds": 60
  }
}

После перезагрузки IDE вы сможете использовать Graphify как встроенный инструмент для поиска связей между сущностями.

Примеры запросов к графу

Поиск связанных функций

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

bashКопировать
# Найти все функции, использующие репозиторий "payment-service"
graphify query --config graphify.agent \
  --type function \
  --source "payment-service" \
  --limit 10

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

Функция	Описание	Связанные сущности
process_payment	Обрабатывает платежи через Stripe	PaymentGateway, StripeClient
refund_order	Выполняет возвраты заказов	Order, RefundPolicy
validate_inventory	Проверяет наличие товаров	Inventory, StockLevel

Анализ конфигураций

Graphify может анализировать конфигурационные файлы и выводить зависимости между ними:

bashКопировать
# Показать все конфиг-совместимые сущности
graphify query --config graphify.agent --type config

Вывод покажет структуру конфигов и их взаимосвязи:

config:
  - database.yaml -> db: postgresql, pool_size: 10
  - api.yaml -> api: rest, rate_limit: 100/hour
  - redis.yaml -> cache: redis, ttl: 3600

Интеграция с SQL-схемами

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

bashКопировать
# Сканировать SQL-файлы и построить граф
graphify analyze --type sql --source ./sql --output graph.cyber

# Открыть результат в Graphviz
graphviz -Tpng graph.cyber -o graph.png

Это полезно для понимания архитектуры данных и поиска узких мест.

Пример запроса к графу в Cursor

Вот готовый пример, который можно скопировать в Cursor для быстрой проверки:

bashКопировать
graphify query --config graphify.agent \
  --type entity \
  --source "User" \
  --limit 5 \
  --fields "id, name, role, dependencies"

Этот запрос вернёт информацию о сущностях типа User и их связях, что может помочь при навигации по проекту.

Полезные ссылки

• CLAUDE.md: Улучшение поведения Claude Code на основе наблюдений Андрея Карпаты
• Навыки для инженеров из .agents директории
• Graphify: локальный граф знаний из кода и PDF
• Graphify: превращаем любой код в граф знаний

Заключение

Интеграция Graphify с Claude Code и Cursor обеспечивает бесшовное взаимодействие между AI-агентом и локальным графом знаний. Благодаря локальному парсингу AST без внешних векторизационных баз, Graphify работает быстро и предсказуемо. Настройте конфиг graphify.agent под структуру вашего проекта, и агент будет мгновенно предоставлять контекст при работе с кодом, SQL и PDF-диаграммами.

Ограничения и границы применения

Ограничения и границы применения

Graphify строит граф на основе статического анализа — AST-дерева кода, структуры SQL-таблиц и извлечённого текста из PDF. Это даёт предсказуемость результатов: тот же входной набор файлов всегда выдаст одинаковый граф. Но статический анализ — это только половина картины.

Что Graphify не умеет

Во-первых, Graphify не понимает семантику кода на уровне выполнения. AST-парсер покажет, что функция process_order вызывает validate_payment, но не скажет, что валидация падает при превышении лимита в 10 000 рублей. Для этого нужен динамический анализ или хотя бы логи приложения.

bashКопировать
# Graphify увидит вызов, но не бизнес-правило внутри функции
grep -r "validate_payment" src/
# src/payment/service.py:45:def validate_payment(amount):
# Что внутри функции — вопрос к автору кода, а не к Graphify

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

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

yamlКопировать
# Пример конфига индексации PDF
pdf_indexing:
  paths:
    - ./docs/specifications
  extract_tables: true
  ocr: false          # рукописный текст и сканы не распознаются
  max_file_size_mb: 50

В-третьих, Graphify не отслеживает изменения в реальном времени. Пересборку графа нужно запускать вручную или по расписанию. Если разработчик переименовал метод в ветке, графа это не узнает до следующего запуска парсинга.

Когда инструмент не подходит

С практической точки зрения, Graphify не стоит использовать, если основная задача — семантический поиск по смыслу. Для «почему этот сервис падает ночью?» лучше подойдёт комбинация логов, трейсинга и мониторинга, а не граф зависимостей. Настройку агентов для анализа логов можно посмотреть в материале про поведение Claude Code: CLAUDE.md: Улучшение поведения Claude Code на основе наблюдений Андрея Карпаты.

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

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

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

yamlКопировать
graphify:
  source_paths:
    - ./src
    - ./sql
    - ./docs
  parsers:
    - python
    - sql
    - pdf
  output_format: graphml
  exclude:
    - "**/node_modules/**"
    - "**/venv/**"
    - "**/migrations/**"

Если мы посмотрим на альтернативы, для семантического поиска подойдут инструменты с векторными базами, а для runtime-анализа — APM-системы. Graphify занимает свою нишу: статический граф знаний без лишней инфраструктуры. Это его сила и его граница одновременно.

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

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

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

Уходит ли код с моего компьютера при анализе?

Нет. Graphify парсит файлы локально через AST и не отправляет исходный код на внешние серверы. Весь граф строится на вашем оборудовании, а результат сохраняется в GraphML или JSON в указанную папку. Это важно, если вы работаете с приватным репозиторием или кодом под NDA.

Как попадают в граф PDF и конфиги?

Graphify извлекает текст из PDF и парсит YAML, JSON и SQL-файлы, превращая каждую сущность в узел. Из конфига он вытаскивает переменные окружения и ссылки на сервисы, из SQL — таблицы и связи, из PDF — текстовые блоки, которые можно связать с соответствующими разделами кода. На выходе получается один ориентированный граф без разрыва между документацией и реализацией.

В каком формате экспортируется граф и как его смотреть?

По умолчанию Graphify сохраняет результат в GraphML или JSON — оба формата открываются обычными текстовыми редакторами. Для визуализации можно использовать Gephi, yEd или любой инструмент, поддерживающий GraphML; я обычно смотрю структуру через Graphviz, чтобы сразу видеть циклы и тупиковые зависимости. Сам по себе JSON удобен для скриптов и интеграции с AI-агентами.

Нужно ли в ручную настраивать парсеры под каждый язык?

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