Средний

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

Алексей Кузнецов
Алексей Кузнецов
Системный администратор12 ноября 2026 г.16 мин чтения

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

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

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

Проблема контекста в работе с AI-агентами

Проблема контекста в работе с AI-агентами

Когда мы говорим об использовании локальных ИИ-агентов и инструментов для разработки, основной преградой становится не мощность модели, а её «зрение». Модель может обладать огромным объёмом знаний, но она не знает специфики вашего проекта: как связаны классы в Python, какие зависимости накладывает схема базы данных или какой метод вызывает конкретную функцию в глубоко вложенной директории.

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

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

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

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

Проблема в том, что код — это не текст. Это иерархическая структура. Если мы просто нарезаем файл server.py на куски по 500 токенов, мы неизбежно разрываем связи. В одном куске может оказаться определение класса, а в другом — его реализация. Для модели это превращается в набор разрозненных фактов, лишенных предсказуемости.

Почему RAG не всегда справляется с логикой кода

Главная беда стандартного RAG при работе с кодом — потеря топологии. Программирование — это не про то, «о чём этот текст», а про то, «как это работает».

Представьте, что вам нужно провести рефакторинг функции. Чтобы сделать это правильно, агент должен понимать:

  1. Какие аргументы принимает функция.
  2. Какие объекты она модифицирует.
  3. Кто является её вызывающей стороной (caller).
  4. Какие побочные эффекты она вызывает в других модулях.

Векторный поиск не видит этих связей. Он видит только сходство текста. Если вы используете автономную разработку на Rust с помощью Claw-Code, вы понимаете, насколько критична точность владения (ownership) и жизненного цикла объектов. Ошибка в контексте здесь — это не просто неверный ответ, это сломанная компиляция.

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

python
# Пример проблемы: разрыв контекста при нарезке на чанки
class DatabaseConnector:
    def __init__(self, uri: str):
        self.uri = uri  # Чанк №1: определение класса и метода

    def connect(self):
        # ... логика подключения ...
        print(f"Connecting to {self.uri}") # Чанк №2: использование атрибута

Если __init__ попал в один чанк, а connect — в другой, агент, анализирующий второй чанк, может не понять, откуда взялся self.uri. Он видит переменную, но не видит её происхождения.

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

Принцип работы Graphify

Принцип работы Graphify

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

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

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

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

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

Процесс анализа можно инициировать через CLI. Например, для базового сканирования директории используется команда:

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

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

Построение связей без использования векторных БД

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

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

С практической точки зрения это работает так:

  1. Синтаксический анализ: Извлекаются все определения (definitions) и вызовы (calls).
  2. Разрешение имен (Name Resolution): Инструмент сопоставляет вызов функции с её конкретным определением, даже если она импортирована из сторонней библиотеки или другого модуля.
  3. Формирование графа: Создаётся топологическая карта проекта.

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

yaml
# Конфигурация графа знаний
analysis:
  include_extensions: [.py, .rs, .go]
  depth: 3 # Глубина прохода по связям
  exclude_dirs:
    - venv
    - target
    - node_modules

graph:
  entities:
    - class
    - function
    - method
  relations:
    - calls
    - inherits
    - implements

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

Интеграция в рабочий процесс разработчика

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

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

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

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

Для пользователей Cursor процесс выглядит ещё проще. Вы можете импортировать экспорт графа как набор Markdown-файлов в папку .cursor/rules или просто держать сгенерированную документацию открытой в проекте. Это позволяет функции @Codebase работать не по принципу «найти похожие куски текста», а по принципу «следовать логическим связям».

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

bash
# Генерация графа только для ключевых директорий проекта
graphify analyze ./src --output ./docs/knowledge-graph --format markdown

Поддержка SQL-схем и конфигурационных файлов

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

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

С практической точки зрения, это работает так:

  1. Инструмент парсит SQL-схемы.
  2. Выявляет первичные и внешние ключи (PK/FK).
  3. Строит связи между сущностями в общем графе знаний.

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

Чтобы добавить SQL-схемы в область анализа, используйте флаг --include:

bash
# Анализ кода вместе со схемами базы данных
graphify analyze ./src ./sql --include-schemas --output ./graph-data

Такой подход позволяет создавать по-настоящему глубокие локальные ИИ-агенты и инструменты, которые понимают не только синтаксис, но и архитектурную логику всей системы — от бизнес-логики в Rust или Python до структуры хранения данных в PostgreSQL. Это делает разработку более системной и снижает вероятность ошибок при внесении изменений в существующую инфраструктуру.

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

Когда граф знаний эффективнее обычного поиска

Обычный поиск по кодовой базе — будь то grep, ripgrep или встроенный поиск в IDE — работает с текстом. Он ищет совпадения символов. Если вы ищете, где используется функция process_order, поиск выдаст вам список строк. Но он не скажет вам, что эта функция зависит от схемы таблицы orders в базе данных и вызывается только после успешного завершения транзакции в модуле payment_gateway.

Граф знаний, построенный через AST (Abstract Syntax Tree), работает иначе. Он оперирует связями. Вместо того чтобы просто найти текст, Graphify позволяет AI-агенту «пройтись» по цепочке зависимостей.

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

Сценарии использования

Я выделяю три основных сценария, где связка «код + граф знаний» даёт кратный рост эффективности.

1. Рефакторинг и анализ влияния (Impact Analysis) Если вам нужно изменить сигнатуру метода в крупном проекте, обычный поиск может упустить динамические вызовы или зависимости, описанные в документации. Граф позволяет построить дерево зависимостей. Вы видите не только, кто вызывает метод, но и какие объекты данных проходят через него. Это помогает избежать ситуации, когда после правки одного файла «рассыпается» половина системы.

2. Онбординг в сложную кодовую базу Для нового разработчика (или агента) проект выглядит как хаос из файлов. С помощью графа можно генерировать контекстные карты. Например, можно составить запрос, который вытянет из графа всю цепочку: API Endpoint -> Controller -> Service -> Repository -> SQL Schema.

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

3. Автоматизация написания тестов Агент, имеющий доступ к графу, понимает, какие граничные условия нужно проверить. Если граф показывает, что функция calculate_tax напрямую зависит от структуры объекта UserContext, агент сфокусируется на мокировании именно этого объекта, а не будет пытаться угадать его состав. Это особенно актуально при автономной разработке на Rust с помощью Claw-Code, где строгая типизация делает такие связи ещё более явными и полезными.

Сценарии, где инструмент не даст нужного результата

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

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

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

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

Если вы работаете с проектами на Rust, помните, что даже при высокой точности анализа, инструменты вроде Claw-code требуют четко структурированной документации, чтобы граф не превратился в набор разрозненных узлов без понимания их бизнес-роли.

Заключение

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

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

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

  1. Онбординг новых агентов. Вместо того чтобы скармливать Claude Code или другим локальным ИИ-агентам сотни разрозненных файлов, вы даёте им готовую карту зависимостей.
  2. Анализ архитектурных связей. Когда нужно понять, как изменение в одной таблице БД отразится на логике бизнес-слоя.
  3. Подготовка контекста для RAG. Граф позволяет извлекать не просто куски текста, а семантически связанные узлы, что критически важно для точности ответов.

Ограничения и нюансы эксплуатации

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

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

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

bash
# Сначала убедитесь, что вы находитесь в корне проекта
cd /path/to/your/project

# Запускаем индексацию с указанием путей к схемам и коду
graphify index --src ./src --db ./migrations --output ./knowledge-graph.json

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

Итоговая оценка подхода

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

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

FAQ

FAQ

Как Graphify понимает связи между файлами?

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

Связи выстраиваются на трёх уровнях:

  1. Синтаксический: зависимости внутри одного языка (импорты, вызовы функций, наследование классов).
  2. Структурный: связи между кодом и схемой базы данных (например, когда в коде упоминается поле, соответствующее колонке в SQL-миграции).
  3. Контекстный: сопоставление документации (Markdown) с конкретными участками кода.

Благодаря такому подходу, когда вы используете локальные ИИ-агенты и инструменты, они получают не «кусок текста», а понимание архитектурной логики проекта.

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

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

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

bash
# Генерация графа в JSON без использования внешних БД
graphify scan ./src --output graph.json

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

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

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

Если вы занимаетесь автономной разработкой на Rust с помощью Claw-Code, инструмент отлично справится с анализом макросов и сложных связей в Rust-проектах через AST.

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

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

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

yaml
# Пример docker-compose.yml для локального запуска Graphify
services:
  graphify:
    image: graphify/cli:latest
    volumes:
      - ./my-project:/app/project
    command: scan /app/project --format json

Такой подход позволяет интегрировать анализ кода непосредственно в ваш рабочий процесс, например, при настройке CLAUDE.md для улучшения работы Claude Code.

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

Можно ли использовать Graphify для проектов с очень большой кодовой базой?

Да, инструмент спроектирован с учётом иерархической структуры, что позволяет ему обрабатывать сложные зависимости лучше, чем обычный RAG. Вместо того чтобы пытаться «запихнуть» весь код в контекстное окно, Graphify создаёт структурную карту, где агент может перемещаться по связям между объектами. С практической точки зрения, это обеспечивает предсказуемость: модель будет понимать не только содержание файла, но и его роль в архитектуре всего проекта.

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

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

Какие типы данных Graphify может превратить в граф знаний?

Инструмент работает не только с исходным кодом, но и с сопутствующей технической документацией и схемами баз данных. Это позволяет создать единую систему знаний, где связи между логикой приложения в Python и структурой таблиц в PostgreSQL будут явно прописаны. Если мы посмотрим на это системно, то получаем полную картину проекта, а не разрозненные куски текста.

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

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

Поделиться:TelegramX / TwitterVK

Читайте также