Graphify: построение графа знаний из кода

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

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

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

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

Анализ через AST вместо векторных хранилищ

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

Если классический RAG ищет «похожие куски текста», то Graphify строит карту связей. Представьте, что вы просите агента найти все места, где используется метод calculate_tax(). Векторный поиск может выдать куски кода, где это слово просто упоминается в комментариях. AST-подход же точно укажет на все узлы дерева, где происходит фактический вызов этой функции.

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

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

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

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

Главная проблема эмбеддингов — их вероятностная природа. Вы никогда не можете быть на 100 % уверены, что векторный поиск вернёт именно тот фрагмент, который нужен для решения задачи. В инженерии такая неопределенность — это риск.

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

Точность навигации. Агент может «пройтись» по графу от функции к её определениям, не теряя ни одной детали.
Понимание области видимости. Инструмент четко разделяет, какие переменные доступны внутри блока, а какие являются глобальными.
Работа со схемами данных. Graphify не ограничивается только .py или .js файлами. Он анализирует SQL-схемы, превращая таблицы и внешние ключи в такие же узлы графа, что позволяет агенту понимать связи между кодом приложения и базой данных.

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

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

analysis:
  # Указываем языки, которые нужно парсить через AST
  languages:
    - python
    - sql
  # Какие типы связей включать в граф
  extract:
    - function_calls
    - class_inheritance
    - module_imports
    - sql_foreign_keys

output:
  # Формат графа для последующего использования AI-агентами
  format: "json-ld"
  destination: "./data/knowledge_graph.json"

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

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

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

Когда мы говорим об интеграции Graphify в рабочий процесс, важно понимать: инструмент не заменяет IDE или CLI-агента, он даёт им «карту местности». Без графа знаний Claude Code или Cursor вынуждены полагаться на контекстное окно, пытаясь прочитать как можно больше файлов целиком. Это неэффективно и часто приводит к галлюцинациям, когда агент теряет связь между определением функции в одном модуле и её вызовом в другом.

В Claude Code Graphify выступает в роли внешнего инструмента (tool), который позволяет агенту делать точечные запросы к структуре проекта. Вместо того чтобы сканировать весь репозиторий, агент запрашивает конкретные узлы графа.

Для интеграции в Cursor можно использовать механизм .cursorrules. Это позволяет задать агенту инструкции о том, как именно он должен взаимодействовать с данными, которые генерирует Graphify.

Пример содержимого .cursorrules для работы с графом:

markdown
# Graphify Integration Rules

When you need to understand the architecture or find dependencies:
1. Do not attempt to read all files in the directory to find a definition.
2. Use the `graphify-query` command (if available via terminal) to locate the specific AST node or relationship.
3. Prioritize information from the generated `knowledge_graph.json` to understand how modules interact.
4. If you encounter an unknown function, first check the graph for its implementation path.

С практической точки зрения, это повышает предсказуемость ответов. Если вы используете Ponytail для оптимизации контекста, связка Graphify + Cursor позволяет практически полностью исключить «мусорный» код из запросов, так как агент точно знает, какие части AST (Abstract Syntax Tree) ему действительно нужны.

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

Работа с Gemini CLI требует более явного подхода к определению инструментов. Здесь мы фактически создаём кастомный «навык», который позволяет модели обращаться к графу знаний через интерфейс командной строки.

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

Для настройки Gemini CLI под работу с графом, создайте конфигурацию навыка (skill definition), которая будет пробрасывать запросы к CLI-интерфейсу Graphify.

Пример конфигурации навыка в формате JSON для интеграции:

json
{
  "name": "query_code_graph",
  "description": "Позволяет искать связи между функциями, классами и схемами БД в текущем проекте через граф знаний.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Текстовый запрос или имя сущности (например, 'User model dependencies')"
      },
      "depth": {
        "type": "integer",
        "description": "Глубина обхода графа (1 — только прямые связи, 2 — с соседями и т. д.)",
        "default": 1
      }
    },
    "required": ["query"]
  },
  "command": "graphify cli query --query {{query}} --depth {{depth}}"
}

После того как вы добавите этот конфиг, Gemini сможет выполнять команды вроде graphify cli query --query "auth_service" --depth 2.

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

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

Практическое применение графа знаний

Анализ связей в SQL-схемах и конфигурациях

Когда мы работаем с инфраструктурой, данные редко живут в изоляции. Обычно это переплетённая сеть из таблиц базы данных, конфигурационных файлов Nginx и переменных окружения. Для AI-агента, который пытается разобраться в проекте, такая связность — главная проблема. Без понимания того, как поле user_id в таблице orders соотносится с конфигом микросервиса, агент будет гадать, а не действовать.

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

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

bash
# Генерация графа знаний на основе SQL-файлов в директории /sql
graphify build --source ./sql --format json --output schema_graph.json

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

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

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

Graphify строит граф зависимостей на основе анализа кода. Это не просто поиск строк, а понимание того, что функция A вызывает функцию B, которая использует объект C. Для AI-агентов, таких как Claude Code, наличие такого графа критически важно. Это позволяет им не просто «писать код», а понимать его место в системе, что напрямую коррелирует с принципами оптимизации работы AI-агентов.

Рассмотрим пример. Допустим, у нас есть сложная цепочка зависимостей в Python-проекте. Мы можем настроить Graphify так, чтобы он сфокусировался на поиске связей между модулями:

yaml
# Пример конфигурации для глубокого анализа зависимостей
analysis_config:
  include_patterns:
    - "src/**/*.py"
  depth: 5 # Глубина анализа дерева вызовов
  extract_ast: true
  output_format: graphviz # Для визуализации связей

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

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

Сравнение подходов к анализу контекста

Графы против RAG-систем

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

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

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

Если сравнить это на практике, то:

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

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

Предсказуемость связей в структуре проекта

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

Graphify строит граф, опираясь на жесткие правила синтаксиса. Если мы анализируем Python-проект, инструмент не просто читает .py файлы, он строит дерево зависимостей.

Рассмотрим пример. У нас есть типичная структура:

python
# models.py
class User:
    def __init__(self, id: int):
        self.id = id

# service.py
from models import User

def get_user_service(user_id: int) -> User:
    # Логика получения пользователя
    return User(id=user_id)

Обычный RAG может выдать фрагмент из service.py, но «забыть» про определение класса в models.py, если тот не попал в топ выдачи по вектору. Graphify же создаёт ребро (edge) между get_user_service и классом User.

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

Точка входа (функция/метод).
Все связанные определения (классы, интерфейсы).
Схемы данных (SQL-таблицы, связанные с этими объектами).

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

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

Заключение

Когда Graphify оправдан

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

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

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

Ограничения и риски

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

Основные проблемы, с которыми вы столкнётесь:

Галлюцинации на сложных связях. Если граф получается слишком разреженным или, наоборот, перегруженным шумом, AI-агент может начать строить ложные предположения о работе системы.
Стоимость токенов. Построение детального графа и его последующая передача в контекст увеличивает расход токенов. Если вы планируете использовать Claude Code или другие продвинутые инструменты, следите за тем, чтобы граф не превращался в «простыню» текста, в которой теряется суть.
Актуальность данных. Граф — это статичный слепок. Если вы изменили схему БД, но не перестроили граф, агент будет давать советы по устаревшей архитектуре.

Для поддержания предсказуемости системы рекомендую автоматизировать обновление графа через CI/CD. Например, можно добавить шаг генерации графа при каждом пуше в основную ветку:

bash
# Пример команды для обновления графа в рамках CI-пайплайна
graphify build --path ./src --output ./docs/knowledge-graph --format json

Итоговая оценка

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

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

FAQ

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

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

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

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

Инструмент ориентирован на извлечение структуры из файлов, которые определяют логику приложения. Основной упор сделан на:

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

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

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

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

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

С практической точки зрения это выглядит так:

Инструмент парсит Markdown.
Находит упоминания сущностей (например, UserEntity).
Создает ребро в графе от текстового узла «Описание модели пользователя» к узлу класса User в коде.

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

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

Чем подход Graphify отличается от классического RAG?

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

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

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

Насколько сильно Graphify нагружает систему при индексации?

Нагрузка зависит от объёма кодовой базы и сложности синтаксического дерева, которое необходимо построить. Процесс парсинга в AST требует вычислительных ресурсов, особенно на больших репозиториях, поэтому для крупных проектов стоит закладывать дополнительные мощности. Однако, в отличие от генерации эмбеддингов в классическом RAG, здесь основной упор делается на структурный анализ, что делает процесс более предсказуемым с точки зрения потребления памяти.

Поможет ли этот инструмент при рефакторинге больших проектов?

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

Graphify: построение графа знаний из кода