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

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

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

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

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

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

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

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

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

yamlКопировать
# graphify.config.yaml
indexing:
  languages:
    - python
    - typescript
  exclude:
    - "**/node_modules/**"
    - "**/venv/**"
    - "tests/"
  ast_depth: 3 # Глубина анализа связей в дереве

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

Связи между документацией и схемой БД

Одной из самых сложных задач при автоматизации разработки является связка «код — данные — описание». Обычно документация лежит в Markdown-файлах, схема базы данных — в SQL-миграциях, а логика работы — в исходном коде. Для AI-агента это три изолированных мира.

Graphify объединяет их в единый граф знаний. Процесс выглядит так:

1. Парсится SQL-схема (DDL), создаются узлы для таблиц, столбцов и связей (Foreign Keys).
2. Анализируется код (например, модели SQLAlchemy или Prisma), чтобы найти соответствие между классами и таблицами.
3. Извлекаются сущности из документации (Docstrings, README, Swagger/OpenAPI).

В результате получается граф, где узел «Таблица users» связан с «Классом User» в коде и с «Разделом Authentication» в документации. Если вы используете Ponytail для оптимизации работы AI-агентов, наличие таких связей позволяет агенту не гадать, какой столбец в базе отвечает за поле в API, а сразу обращаться к проверенному источнику истины.

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

bashКопировать
# Запуск индексации проекта с подключением схемы БД
graphify index ./my-project --db-schema ./migrations/postgres/

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

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

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

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

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

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

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

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

bashКопировать
# Генерация графа для текущего проекта с упором на зависимости модулей
graphify analyze ./src --output context_graph.json --depth 3

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

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

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

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

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

Пример логики интеграции через bash-скрипт:

bashКопировать
#!/bin/bash

# 1. Генерируем актуальный граф
graphify analyze ./src --output graph.json

# 2. Извлекаем только релевантную часть (например, связанные с модулем 'auth')
# Здесь используется условный jq для фильтрации графа
jq '.nodes[] | select(.module == "auth")' graph.json > auth_context.json

# 3. Отправляем запрос в Gemini CLI с использованием подготовленного контекста
gemini-cli prompt "Проанализируй логику аутентификации, опираясь на этот контекст: $(cat auth_context.json)"

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

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

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

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

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

В классическом подходе к RAG (Retrieval-Augmented Generation) поиск контекста происходит по векторному сходству. Это работает для документации, но плохо справляется с кодом. Векторный поиск может найти похожую функцию, но он не гарантирует, что поймёт, как именно эта функция модифицирует состояние базы данных.

Graphify меняет парадигму. Связи в графе строятся на основе жестких правил синтаксического анализа. Если функция update_user_balance вызывает метод db.execute, в графе появится ребро типа CALLS, которое не зависит от того, насколько «похожи» эти слова по смыслу. Это обеспечивает предсказуемость: вы точно знаете, что агент получит цепочку вызовов, а не просто набор кусков кода, которые «кажутся» ему релевантными.

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

yamlКопировать
analysis:
  depth: 3 # Глубина прохода по дереву вызовов
  include_types:
    - sql_schema
    - python_ast
  exclude_paths:
    - "tests/*"
    - "venv/*"

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

Объяснимость каждого ребра графа

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

В графе, построенном Graphify, каждое ребро обладает метаданными. Это не просто линия между двумя узлами, а объект, содержащий источник связи. Если мы анализируем SQL-схему, ребро между таблицей orders и users будет иметь атрибут FOREIGN KEY с указанием конкретной колонки.

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

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

bashКопировать
# Генерация графа знаний для директории src с выводом в JSON
graphify build ./src --format json --output graph_dump.json

После этого вы можете увидеть, что связь — это не галлюцинация, а результат парсинга:

jsonКопировать
{
  "edge": {
    "source": "app.services.payment_service.process",
    "target": "db.tables.transactions",
    "type": "WRITES_TO",
    "evidence": "line 42: cursor.execute('INSERT INTO transactions...')"
  }
}

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

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

Анализ сложных конфигурационных файлов

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

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

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

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

bashКопировать
# Создаём рабочую директорию для анализа
mkdir -p ./analysis/nginx-configs
cp -r /etc/nginx/sites-available/* ./analysis/nginx-configs/

# Запускаем Graphify для построения графа на основе AST (Abstract Syntax Tree)
graphify index ./analysis/nginx-configs/ --format json --output ./analysis/nginx-graph.json

После этого агент может получить доступ к структурированным данным. Если мы интегрируем этот граф в Ponytail, мы сможем задавать вопросы уровня: «Какие параметры proxy_set_header будут применены к запросам на домен api.example.com, учитывая общие настройки в nginx.conf?».

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

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

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

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

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

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

bashКопировать
# Извлекаем все зависимости для модуля 'auth_service'
graphify query --input ./analysis/nginx-graph.json \
  --match "module:auth_service" \
  --relation "calls" \
  --depth 3

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

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

Заключение

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

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

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

1. Onboarding новых агентов. Когда вы подключаете Claude Code или другие автономные системы, им крайне важно понимать не только синтаксис, но и семантику: «какая таблица в базе данных отвечает за профиль пользователя и как это отражено в API».
2. Анализ legacy-кода. Когда документация устарела, а единственный способ понять систему — это чтение кода, Graphify вытягивает связи, которые человек может упустить при беглом осмотре.

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

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

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

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

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

Начните с малого:

1. Сгенерируйте граф для одного конкретного модуля или подсистемы.
2. Проверьте, насколько точно описанные связи соответствуют реальности.
3. Настройте автоматическое обновление графа при изменении схемы БД или ключевых интерфейсов.

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

FAQ

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

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

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

yamlКопировать
storage:
  type: remote
  provider: qdrant # или milvus / pinecone
  endpoint: "http://your-vector-db:6333"
  api_key: ${VECTOR_DB_API_KEY}

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

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

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

• Код: Python, TypeScript, JavaScript, Go, Rust.
• Структуры данных: SQL-схемы (PostgreSQL, MySQL), JSON, YAML.
• Документация: Markdown.

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

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

Основная проблема современных LLM при работе с кодом — это «галлюцинации» из-за неполноты контекста. Агент видит один файл, но не знает, как изменение в этой функции повлияет на схему базы данных или на другой микросервис.

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

1. Снизить расход токенов: Агент запрашивает только те узлы графа, которые релевантны текущей задаче.
2. Повысить точность: При запросе «измени поле user_id в таблице заказов» агент сразу видит все зависимости в коде, которые затронет это изменение.
3. Улучшить навигацию: Это особенно полезно, если вы используете Claude Code или другие CLI-инструменты, которым нужен четкий план действий.

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

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

Чем Graphify отличается от обычного векторного поиска (RAG)?

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

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

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

Как ограничить область анализа, чтобы не индексировать лишнее?

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

На что влияет параметр ast_depth в конфигурации?

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