Создание графа знаний из кода с Graphify

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

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

Принцип работы на основе AST

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

Процесс начинается с парсинга исходного кода. Вместо того чтобы просто «читать» файл, инструмент разбирает его на логические узлы: определения классов, функций, переменных и их взаимосвязей. Если мы возьмём типичный Python-проект, Graphify не просто увидит строку def process_data(payload):, а зафиксирует создание узла функции, его аргументы и то, какие другие объекты внутри этой функции вызываются.

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

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

bash
# Запуск анализа конкретной директории для построения графа
graphify analyze ./src --output-format dot

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

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

В последнее время в разработке AI-решений принято использовать векторные базы данных (Vector DB) и RAG (Retrieval-Augmented Generation). Идея кажется логичной: превратить код в векторы (эмбеддинги) и искать похожие куски через семантический поиск. Однако у такого подхода есть фундаментальный недостаток — потеря точности при работе со сложными структурами.

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

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

Предсказуемость связей. В графе связь между функцией и её вызовом — это не «вероятность сходства», а жесткий факт, извлеченный из AST. Если связь есть в коде, она будет в графе.
Точность навигации. Когда агент работает с графом, он может буквально «пройтись» по путям: от API-эндпоинта через сервисную прослойку к конкретному SQL-запросу. Это позволяет избежать галлюцинаций, которыми часто грешат модели при использовании чистого RAG.
Экономия ресурсов. Вам не нужно разворачивать тяжеловесную инфраструктуру вроде Chroma или Pinecone для хранения эмбеддингов. Граф — это структурированные данные, которые гораздо легче поддерживать в актуальном состоянии при изменении кодовой базы.

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

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

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

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

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

Graphify решает эту проблему, парся SQL-схемы и выстраивая связи между таблицами, индексами и внешними ключами. Это позволяет агенту не просто «гадать» по именам переменных, а точно знать, что поле user_id в таблице orders — это связь с первичным ключом в таблице users.

С практической точки зрения, лучше всего подавать на вход чистый DDL (Data Definition Language). Если у вас база работает в Docker, вы можете быстро выгрузить схему в файл для анализа:

bash
# Выгружаем только структуру таблиц без данных в файл schema.sql
docker exec postgres_container pg_dump -s -U admin my_database > schema.sql

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

Аналогичный подход работает и с конфигурационными файлами. Если в вашем проекте разбросаны .env файлы или сложные конфиги Nginx, Graphify может извлечь из них параметры и связать их с логикой приложения. Это добавляет ту самую предсказуемость, которой часто не хватает при работе с «черными ящиками» в инфраструктуре.

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

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

Graphify умеет индексировать текстовые файлы, превращая описательные предложения в семантические связи. Если в вашем README.md написано, что «сервис авторизации должен проверять токен через Redis», инструмент создаст связь между узлом AuthService и узлом Redis.

Для работы с PDF-документацией процесс выглядит следующим образом:

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

Пример базового конфига для включения документации в процесс построения графа:

yaml
# config.yaml для Graphify
analysis:
  include_paths:
    - "./src"          # Исходный код
    - "./docs"         # Markdown и текстовые файлы
  document_types:
    - pdf              # Поддержка PDF-схем и спецификаций
    - md               # Техническая документация
  sql_schemas:
    - "./schema.sql"   # Схема базы данных

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

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

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

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

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

Claude Code

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

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

Сначала сгенерируйте граф в формате JSON, который будет удобен для парсинга:

bash
# Генерация графа знаний для текущей директории
graphify build --format json --output ./docs/knowledge-graph.json

Затем в вашем CLAUDE.md пропишите инструкцию:

markdown
# Context Awareness
When analyzing the codebase structure or tracing function calls, 
always refer to the knowledge graph located at ./docs/knowledge-graph.json.
Use it to understand the relationships between modules before suggesting changes.

Это повышает предсказуемость ответов: вместо того чтобы угадывать, откуда пришла переменная, Claude будет опираться на точные данные AST-анализа.

Cursor

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

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

bash
# Экспорт графа в Markdown для индексации IDE
graphify build --format markdown --output ./docs/architecture-map.md

После этого создайте или обновите файл .cursorrules в корне проекта:

json
{
  "rules": [
    "Always consult ./docs/architecture-map.md to understand the dependency graph.",
    "If a change affects a core module, check the graph for downstream impacts."
  ]
}

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

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

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

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

Сценарий работы выглядит так: вы подаете запрос в Gemini CLI, но перед этим скрипт извлекает релевантный подграф из Graphify и добавляет его в системный промпт.

Пример простого Bash-скрипта для автоматизации этого процесса:

bash
#!/bin/bash

# 1. Извлекаем контекст конкретного модуля через graphify (условно)
CONTEXT=$(graphify query --module "auth-service" --format text)

# 2. Формируем запрос к Gemini CLI
# Предполагается, что gemini-cli — это установленный у вас инструмент
gemini-cli prompt "Analyze the following context and answer the question: $QUERY. Context: $CONTEXT"

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

Практическое применение в рабочих процессах

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

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

Graphify решает эту задачу иначе, чем классические RAG-системы (Retrieval-Augmented Generation) на базе векторных баз данных. Вместо того чтобы искать похожие куски текста, инструмент строит семантическую карту проекта. Это позволяет передавать агенту не «похожий код», а точную топологию: какие функции вызываются, какие таблицы в БД связаны через foreign keys и как документация соотносится с конкретными строками в коде.

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

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

yaml
# Конфигурация анализа для построения графа знаний
analysis:
  include:
    - "./src/**/*.ts"      # Анализируем только исходники TypeScript
    - "./docs/**/*.md"     # Подтягиваем документацию для контекста
  database:
    type: "postgres"
    schema_path: "./migrations/" # Graphify просканирует SQL-миграции
  exclude:
    - "**/node_modules/**"
    - "**/dist/**"

После генерации графа вы можете использовать его API для обогащения промптов. Это похоже на то, как работает Ponytail, но на более глубоком, структурном уровне.

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

В крупных проектах, где количество файлов переваливает за сотни, найти «точку входа» для изменения или понять последствия удаления функции становится нетривиальной задачей. Традиционный grep или поиск по IDE помогают найти упоминания, но они не дают понимания логической цепочки.

Graphify использует AST (Abstract Syntax Tree) для глубокого анализа. Это позволяет выстроить цепочку зависимостей, которая учитывает не только прямые импорты, но и косвенные связи через типы данных или SQL-схемы. Если вы измените тип поля в таблице users, граф покажет, какие именно функции в приложении зависят от этого поля, даже если связь идет через сложную бизнес-логику.

Рассмотрим пример. Допустим, у нас есть микросервис, и нам нужно понять, как изменение в схеме БД повлияет на API. Сначала мы запускаем сканирование проекта:

bash
# Запуск построения графа из корневой директории проекта
graphify scan --config graphify.yaml --output ./knowledge-graph

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

bash
# Поиск всех узлов, связанных с сущностью 'Order'
graphify query --find-dependencies "entity:Order"

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

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

Заключение

Когда Graphify оправдывает себя

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

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

Анализ legacy-кода, где документация отсутствует, а связи между модулями запутаны.
Генерация контекста для AI-агентов, когда нужно передать им не «облако смыслов», а строгую топологию системы.
Проектирование архитектуры, когда необходимо визуализировать зависимости между схемами SQL и бизнес-логикой.

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

Как внедрить инструмент в рабочий процесс

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

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

yaml
# Конфигурация области сканирования
include:
  - "./src/**/*.py"
  - "./schema/*.sql"
  - "./docs/*.md"

# Исключаем шумные директории
exclude:
  - "**/tests/**"
  - "**/venv/**"
  - "**/migrations/**"

# Параметры извлечения связей
extraction:
  depth: 3 # Глубина анализа зависимостей
  language_support: ["python", "sql", "markdown"]

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

bash
# Запуск построения графа с сохранением в формате JSON
graphify build --config graphify.yaml --output ./knowledge_graph.json

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

Итоговые рекомендации

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

Если ваша задача — глубокая автоматизация разработки, стоит рассмотреть связку Graphify с более широким стеком инструментов. Например, изучите обзор репозитория Skills, чтобы понять, как интегрировать полученные знания в цепочки действий AI-агентов. Для оптимизации работы самих агентов с этим контекстом полезно будет применить техники из статьи про Ponytail.

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

FAQ

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

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

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

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

Нет, в этом и заключается ключевое отличие архитектуры Graphify. Традиционные RAG-системы (Retrieval-Augmented Generation) требуют развёртывания векторных хранилищ вроде Chroma или Pinecone для хранения эмбеддингов. Graphify работает иначе: он преобразует код и документацию в структурированный граф знаний.

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

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

На текущий момент Graphify ориентирован на наиболее распространённые форматы, которые составляют основу любой кодовой базы:

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

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

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

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

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

bash
# Запуск индексации локального проекта
graphify index ./src --output ./knowledge-graph

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

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

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

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

Чем такой подход лучше обычного RAG?

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

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

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

Как Graphify помогает при рефакторинге?

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

Создание графа знаний из кода с Graphify