Создание графа знаний из кода с помощью Graphify

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

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

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

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

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

Процесс выглядит так:

Парсинг: Инструмент проходит по файлам и строит дерево синтаксических связей.
Извлечение сущностей: Из AST вычленяются узлы (nodes) — например, конкретный класс UserService — и ребра (edges) — например, связь UserService $\rightarrow$ calls $\rightarrow$ UserRepository.
Построение графа: Все эти связи объединяются в единую топологическую карту проекта.

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

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

bash
# Запуск индексации проекта для построения графа
graphify index ./my-python-project --language python --output ./graph-data

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

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

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

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

Graphify работает иначе. Вместо поиска «похожего», он ищет «связанное».

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

Если векторный поиск — это библиотека, где вы ищете книгу по описанию сюжета, то Graphify — это детальная схема метрополитена. Вам не нужно гадать, пересекаются ли линии; вы просто видите, на какой станции происходит пересадка.

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

Возможности анализа документации и схем

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

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

С практической точки зрения это превращает разрозненные .sql файлы в связную карту. Инструмент анализирует инструкции CREATE TABLE, ALTER TABLE и, что самое важное, внешние ключи (FOREIGN KEY). Это позволяет построить зависимости, которые потом можно использовать для реверс-инжиниринга с помощью ИИ-агентов.

Если у вас есть дамп схемы, вы можете добавить его в директорию индексации. Например, для обработки PostgreSQL-схемы конфигурация может выглядеть так:

yaml
# Пример части конфигурации для индексации SQL
indexing:
  sources:
    - type: sql
      path: "./infrastructure/db/schema/"
      dialect: postgresql # Указываем диалект для корректного парсинга
      include_constraints: true # Важно для построения связей в графе

Предсказуемость графа здесь обеспечивается тем, что инструмент не пытается «угадать» связи, а опирается на явные декларативные инструкции. Если в схеме прописаны связи, они станут узлами и ребрами в графе. Это особенно полезно, когда вы готовите набор навыков для работы с AI-агентами, чтобы агент понимал архитектуру БД до того, как начнёт писать запросы.

Интеграция с PDF и текстовыми файлами

Часто архитектурные решения или спецификации протоколов хранятся в документации, которая существует отдельно от кода. Проблема классических RAG-систем (Retrieval-Augmented Generation) в том, что они работают с кусками текста, теряя контекст связей. Graphify пытается решить это через извлечение сущностей из неструктурированных данных.

При работе с текстовыми файлами (Markdown, TXT) и PDF-документами инструмент ищет упоминания ключевых терминов, которые уже присутствуют в кодовой базе. Если в вашем README.md или техническом задании в формате PDF упоминается сервис auth-service, Graphify свяжет этот текстовый узел с соответствующим репозиторием или набором файлов.

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

yaml
# Настройка парсинга документации
documentation:
  formats:
    - pdf
    - md
  directories:
    - "./docs/architecture"
    - "./specs"
  entity_extraction:
    strict_mode: false # Позволяет находить потенциальные связи, даже если они не описаны явно

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

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

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

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

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

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

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

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

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

bash
# Сначала генерируем актуальный граф зависимостей проекта
graphify generate --format json --output ./context/project_graph.json

# Передаём описание графа в Claude Code как часть контекста
claude "Используй файл ./context/project_graph.json для понимания архитектуры. 
Исправь ошибку в модуле обработки платежей, учитывая связи с таблицей transactions"

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

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

Работа с Gemini через CLI открывает возможности для автоматизации глубокого анализа кода в CI/CD пайплайнах. В отличие от чат-интерфейсов, здесь важно обеспечить максимальную плотность полезной информации на один токен.

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

Пример скрипта для автоматического анализа изменений (diff) с использованием графа знаний:

bash
#!/bin/bash

# 1. Обновляем граф после изменений в коде
graphify generate --output ./graph.json

# 2. Формируем запрос к Gemini CLI
# Мы объединяем diff текущих изменений и структуру графа
echo "Проанализируй следующие изменения в коде, опираясь на структуру проекта: $(cat graph.json)" > prompt.txt
echo "Изменения: $(git diff HEAD~1)" >> prompt.txt

# 3. Отправляем запрос через Gemini CLI
gemini-cli prompt prompt.txt --model gemini-1.5-pro

С точки зрения системного инженера, такая интеграция обеспечивает высокую предсказуемость: модель не просто видит измененную строку, она понимает, что эта строка — часть цепочки вызовов, которая начинается в контроллере и заканчивается в триггере базы данных. Это критически важно при реализации сложных сценариев, где требуется управление AI-агентами с помощью Paperclip или других инструментов оркестрации.

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

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

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

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

С практической точки зрения это превращает работу агента из угадывания в навигацию по карте. Если вы используете Claude Code или другие инструменты автоматизации, наличие графа знаний позволяет агенту точнее определять область влияния (blast radius) при внесении изменений.

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

yaml
# config.yaml для Graphify
extraction:
  include_ast_nodes:
    - FunctionDefinition
    - ClassDefinition
    - ImportFrom
  include_sql_relations: true # Связываем код с архитектурой БД
  depth: 3 # Глубина обхода связей для формирования контекста

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

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

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

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

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

bash
pip install graphify-core

Затем можно запустить построение графа для конкретного модуля:

bash
# Построение графа для директории src с экспортом в формат JSON для анализа
graphify build ./src --output project_graph.json --format json

Полученный файл project_graph.json — это не просто список файлов, а структурированная карта. С её помощью можно автоматизировать задачи, которые раньше требовали часов ручного чтения кода. Например, это полезно при реверс-инжиниринге с помощью ИИ-агентов, когда документации нет вовсе, а нужно быстро понять, как устроена система.

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

Заключение

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

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

С практической точки зрения, этот подход решает главную проблему при анализе больших репозиториев: потерю контекста. Когда агент понимает, что функция calculate_total в одном файле напрямую зависит от структуры таблицы orders в SQL-миграции, точность его ответов возрастает на порядок.

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

Я бы рекомендовал использовать Graphify в следующих сценариях:

Анализ legacy-кода. Когда документация устарела, а архитектура превратилась в «спагетти», построение графа помогает быстро найти точки входа и зависимости. Это отличная база для реверс-инжиниринга с помощью ИИ-агентов.
Подготовка контекста для агентов. Если вы строите автономную систему, ей нужен структурированный доступ к знаниям. Вместо того чтобы скармливать агенту сотни файлов, вы даёте ему граф. Это логичный шаг, если вы уже изучаете набор навыков для работы с AI-агентами.
Аудит безопасности и схем данных. Понимание того, как данные текут через систему от API до базы данных, критически важно для предотвращения утечек.

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

Не стоит ждать чудес в следующих случаях:

Динамический код. Если логика приложения сильно завязана на runtime-манипуляциях, которые невозможно отследить через статический анализ (AST), граф будет неполным.
Неструктурированные данные. Graphify хорош в коде и SQL, но он не заменит полноценный поиск по текстовым документам, если в них нет четкой логической связи с кодом. Для таких задач лучше смотреть в сторону специализированных инструментов, подобных Agent-Reach.

Итоговая конфигурация для старта

Для быстрого тестирования на небольшом проекте достаточно инициализировать Graphify и указать пути к исходникам. Пример базового конфига graphify.yaml:

yaml
# Конфигурация индексации проекта
project:
  name: "my-service"
  root: "./src"

analysis:
  # Включаем парсинг AST для Python и TypeScript
  languages:
    - python
    - typescript
  # Добавляем схему базы данных для связки кода с данными
  sql_schemas:
    - "./migrations/*.sql"

output:
  # Формат графа для последующего использования агентами
  format: "json-graph"
  path: "./build/knowledge-graph.json"

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

FAQ

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

Нет, для работы Graphify векторное хранилище не требуется. В этом заключается одно из ключевых архитектурных отличий инструмента: вместо поиска по сходству векторов (semantic search), он использует структурный анализ через AST (Abstract Syntax Tree).

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

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

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

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

Чтобы добавить новый путь сканирования, достаточно отредактировать конфигурационный файл graphify.yaml. Например, если вы хотите, чтобы инструмент учитывал специфические директории с вашими SQL-миграциями:

yaml
# Конфигурация путей сканирования
sources:
  code:
    - "./src/**/*.ts"
    - "./services/**/*.py"
  database:
    - "./migrations/*.sql"
  docs:
    - "./docs/**/*.md"

Как инструмент помогает при работе с legacy-кодом?

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

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

Найти точки входа: Понять, какие функции являются критическими узлами.
Оценить область влияния: Увидеть, какие модули «сломаются», если вы измените сигнатуру метода в глубоко запрятанном классе.
Подготовить почву для автоматизации: Граф знаний служит фундаментом для набора навыков для работы с AI-агентами, позволяя агентам не «галлюцинировать» о структуре проекта, а опираться на реальные связи.

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

bash
# Генерация графа из текущей директории
graphify build --path ./my-legacy-project --output ./graph-data

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

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

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

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

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

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

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

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

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

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

Создание графа знаний из кода с помощью Graphify