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

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

Как Graphify работает с кодом

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

Детерминированный парсинг AST

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

Когда инструмент анализирует, например, Python-скрипт или TypeScript-файл, он не просто ищет ключевые слова. Он строит дерево, где каждый узел — это конкретный элемент языка: определение класса, функция, аргумент или даже декоратор. Это позволяет добиться предсказуемости: мы точно знаем, что функция calculate_metrics вызывает метод get_data из соседнего модуля, потому что это зафиксировано в структуре AST.

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

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

bash
# Анализ текущей директории и экспорт графа в формате JSON
graphify analyze ./src --output ./knowledge-graph.json --format json

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

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

Часто возникает вопрос: зачем строить граф, если есть векторные базы данных (RAG — Retrieval-Augmented Generation)? Чтобы ответить на него, нужно понять фундаментальную разницу в подходе.

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

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

Сравним подходы:

Характеристика	Векторное хранилище (RAG)	Граф знаний (Graphify)
Тип данных	Семантическая близость (смысл)	Структурные связи (логика)
Точность	Вероятностная (может ошибаться)	Детерминированная (всегда точно)
Сложные запросы	Плохо понимает иерархию и зависимости	Идеально работает с деревом вызовов
Применение	Поиск по смыслу, общие вопросы	Рефакторинг, аудит, глубокий анализ

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

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

Возможности анализа данных

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

Когда мы говорим о подготовке данных для AI-агентов, главная проблема — это контекст. Агенту мало просто видеть текст запроса, ему нужно понимать структуру связей. Если вы скормите модели сырой SQL-дамп, она может запутаться в именовании колонок или пропустить неявные связи между таблицами.

Graphify решает это через построение AST (Abstract Syntax Tree) для SQL-схем. Инструмент анализирует CREATE TABLE, ALTER TABLE и ограничения FOREIGN KEY, превращая их в узлы и ребра графа. Это позволяет агенту не просто «угадывать» структуру, а точно знать, что поле user_id в таблице orders ссылается на id в таблице users.

С практической точки зрения, это критически важно при использовании таких инструментов, как Claude Code или при настройке GStack. Предсказуемость ответов модели напрямую зависит от того, насколько чисто описана схема данных.

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

bash
# Анализ локального SQL-файла для генерации графа
graphify analyze ./sql/schema.sql --output ./graphs/db_structure.json

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

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

Код — это только половина правды. Вторая половина обычно спрятана в документации, README-файлах или даже в PDF-спецификациях, которые лежат в папке docs. Проблема в том, что стандартные методы RAG (Retrieval-Augmented Generation) часто работают с документацией как с набором несвязанных кусков текста.

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

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

Пример конфигурационного файла graphify.yaml для объединения кода и документации:

yaml
sources:
  - path: "./src"
    type: "source_code"
  - path: "./docs"
    type: "documentation"
  - path: "./specs/api_spec.pdf"
    type: "pdf"

output:
  format: "graphml"
  destination: "./knowledge_graph/project_map.graphml"

# Настройка глубины анализа связей
options:
  semantic_linking: true
  include_comments: true

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

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

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

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

С практической точки зрения, Graphify не заменяет AI-агентов, а даёт им «карту местности». Без контекста графа такие инструменты, как Claude Code, часто галлюцинируют, пытаясь угадать связи между модулями, которые на самом деле разделены сложной иерархией импортов или SQL-схемами.

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

В Cursor интеграция происходит на уровне контекстных файлов. Поскольку Cursor отлично понимает структуру проекта, вы можете экспортировать подграф в формате JSON или Markdown и добавить его в .cursorrules. Это обеспечит предсказуемость ответов: модель будет опираться на реальные связи AST (Abstract Syntax Tree), а не на предположения.

Пример конфигурации для интеграции через CLI-обёртку, чтобы агент мог запрашивать связи:

json
{
  "tools": [
    {
      "name": "query_code_graph",
      "description": "Запрашивает связи между компонентами кода через Graphify",
      "parameters": {
        "type": "object",
        "properties": {
          "node_id": {
            "type": "string",
            "description": "ID узла (например, имя класса или таблицы)"
          },
          "depth": {
            "type": "integer",
            "description": "Глубина обхода графа"
          }
        },
        "required": ["node_id"]
      }
    }
  ]
}

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

Настройка навыков для Gemini CLI

Работа с Gemini CLI требует более строгого подхода к определению навыков (skills). Если вы используете Набор навыков для инженеров из репозитория Skills, то Graphify станет для Gemini внешним источником истины (Source of Truth) при анализе архитектуры.

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

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

yaml
skill:
  name: code_architecture_analyzer
  description: Анализ архитектурных связей и зависимостей в кодовой базе
  capabilities:
    - graph_traversal
  execution:
    command: "graphify-cli query --node ${input_node} --depth ${input_depth}"
    args:
      - "--format"
      - "json"
  prompt_template: |
    Используй полученные данные из графа знаний, чтобы ответить на вопрос: 
    "${user_query}". 
    Если в графе указаны зависимости между SQL-схемами и кодом, обязательно учти их.

Если мы посмотрим на процесс выполнения, то агент сначала получает запрос, извлекает идентификатор узла, выполняет команду graphify-cli и получает структурированный ответ. Это превращает Gemini из простого генератора текста в полноценного архитектурного аудитора.

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

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

Улучшение контекста для LLM

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

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

С практической точки зрения, это позволяет реализовать паттерн RAG (Retrieval-Augmented Generation) не на уровне кусков текста, а на уровне семантических узлов. Если вы используете настройку GStack: набор инструментов Claude Code, интеграция графа знаний позволит агенту понимать зависимости между компонентами ещё до того, как он начнет писать код.

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

yaml
# graphify-config.yaml
analysis:
  depth: 3 # глубина рекурсивного обхода зависимостей
  include_types:
    - interfaces
    - abstract_classes
    - sql_schemas
  exclude_paths:
    - "**/tests/**"
    - "**/node_modules/**"

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

Поиск зависимостей в больших проектах

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

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

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

bash
# Генерация графа связей между кодом и схемой БД
graphify analyze --source ./src --schema ./migrations/schema.sql --output ./graph-data

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

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

Заключение

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

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

С практической точки зрения, использование AST (Abstract Syntax Tree) для построения графа позволяет избежать галлюцинаций модели при анализе зависимостей. Вместо того чтобы угадывать, откуда пришла функция, агент получает четкую карту вызовов. Это делает работу таких инструментов, как Claude Code, значительно более предсказуемой.

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

Я рекомендую внедрять генерацию графов в следующих сценариях:

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

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

Что делать дальше

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

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

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

FAQ

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

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

Если ваша задача — просто дать агенту понимание архитектуры, достаточно локального запуска. Однако, если вы строите долгосрочную систему с огромным объёмом данных, вам может понадобиться интеграция с внешними хранилищами. В этом случае стоит изучить Ponytail: оптимизация работы AI-агентов, где описываются подходы к управлению контекстом.

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

Инструмент ориентирован на извлечение смыслов из структуры проекта, поэтому основной упор сделан на:

Исходный код: файлы .py, .js, .ts, .go, .rs и другие, поддерживаемые парсерами AST.
Схемы данных: .sql файлы, позволяющие восстановить связи между таблицами.
Документация: .md и .txt, которые помогают связать логику кода с описанием бизнес-процессов.

Для корректного анализа убедитесь, что ваши файлы имеют стандартную кодировку UTF-8. Если вы работаете в специфической среде, проверьте конфигурацию в graphify.config.json:

json
{
  "include": ["src/**/*.ts", "schema/*.sql"],
  "exclude": ["node_modules/**", "dist/**"],
  "parser_options": {
    "strict_mode": true
  }
}

Как инструмент помогает при работе с Claude Code?

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

Вместо того чтобы искать по ключевым словам, Claude Code получает структурированный граф, где четко видно: «функция А вызывает метод Б, который обращается к таблице В». Это критически важно при использовании комплексных связок, таких как Настройка GStack: набор инструментов Claude Code.

В чем преимущество использования AST перед обычным поиском?

Обычный поиск (grep или поиск по строкам) работает на уровне текста. Он находит совпадения, но не понимает их смысла. Если вы ищете переменную user_id, поиск выдаст вам всё, где встречается эта строка, включая комментарии и похожие названия в других контекстах.

Использование AST (Abstract Syntax Tree) позволяет работать на уровне синтаксиса языка. Graphify строит дерево, которое понимает:

Где именно объявлена переменная.
Является ли это определением функции или её вызовом.
В какой области видимости находится объект.

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

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

Чем граф знаний отличается от обычного индекса поиска по коду

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

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

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

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

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

В каком формате можно получить результат анализа

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

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