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

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

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

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

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

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

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

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

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

bashКопировать
# Анализируем директорию с проектом и сохраняем граф в формате JSON
graphify analyze ./my-project --output graph.json --format ast

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

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

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

Инструмент умеет сопоставлять сущности из разных источников. Если в вашей документации (например, в формате Markdown) упоминается сущность Order, а в схеме PostgreSQL есть таблица orders, Graphify через AST-анализ кода находит связи между этими объектами. Он видит, что модель Order в коде маппится на таблицу orders в базе, и связывает это с описанием бизнес-логики в документации.

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

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

yamlКопировать
# Пример конфигурации Graphify для объединения контекста
sources:
  code:
    path: "./src"
    language: "typescript"
  database:
    type: "postgres"
    connection_string: "postgresql://user:password@localhost:5432/mydb"
    schema_path: "./db/schema.sql"
  docs:
    path: "./docs"
    format: "markdown"

output:
  format: "jsonl"
  path: "./knowledge_graph/project_context.jsonl"

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

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

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

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

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

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

Для Cursor процесс выглядит ещё более нативно. Поскольку Cursor активно использует RAG (Retrieval-Augmented Generation), наличие предварительно построенного графа через AST (Abstract Syntax Tree) позволяет индексации работать точнее. Вместо того чтобы полагаться на семантический поиск по кускам текста, IDE получает карту зависимостей.

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

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

После этого файл project_graph.json можно подкладывать в контекстное окно или использовать в кастомных инструкциях (rules) для Cursor, чтобы агент понимал, какие модули критически важны для текущей задачи. Это во многом напоминает оптимизацию работы AI-агентов через Ponytail, где ключевым фактором является плотность и релевантность передаваемого контекста.

Подключение к CLI-интерфейсам

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

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

Сначала убедитесь, что у вас установлены необходимые зависимости для парсинга SQL:

bashКопировать
# Пример интеграции анализа схемы БД и кода в один поток
graphify analyze ./schema.sql --type sql > db_graph.json
graphify analyze ./app --type ast >> db_graph.json

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

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

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

bashКопировать
#!/bin/sh
# .git/hooks/post-commit

# Обновляем граф знаний, чтобы AI-агент всегда видел актуальную структуру
echo "Updating knowledge graph..."
graphify analyze ./src --format json --output ./docs/graph.json

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

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

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

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

Предсказуемость структуры графа

В отличие от векторных баз данных (RAG), где поиск строится на семантической близости векторов, Graphify использует детерминированный подход. Это значит, что если в коде есть вызов функции calculate_metrics(), в графе обязательно появится ребро, соединяющее вызывающий узел с целевым. Здесь нет вероятностей или «похожести» — только прямой факт наличия связи.

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

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

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

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

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

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

Мы не просто говорим: «Эти два узла связаны». Мы фиксируем: «Узел А вызывает функцию в узле Б с аргументами X и Y». Это превращает «черный ящик» нейросети в прозрачную систему. Если агент предлагает изменение, вы можете проследить по графу всю цепочку зависимостей, которые это изменение затронет.

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

jsonКопировать
{
  "analysis_rules": {
    "include_types": ["function_call", "class_inheritance", "module_import"],
    "exclude_patterns": ["**/tests/*", "**/vendor/*"],
    "depth": 3
  }
}

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

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

Когда графа знаний становится недостаточно

Граф знаний, построенный через AST (Abstract Syntax Tree) и анализ схем БД, даёт AI-агенту отличную «карту местности». Он понимает, что функция calculate_tax зависит от модели Order, а не просто ищет похожие слова в тексте. Но важно понимать: наличие карты не означает, что агент знает, как ехать по этой дороге в реальном времени.

С практической точки зрения, вы столкнётесь с тремя типами ограничений:

1. Динамическое поведение. Граф статичен. Он описывает структуру, но не состояние. Если логика приложения сильно зависит от runtime-параметров или специфических данных в базе, которые не описаны в схемах, агент может построить верный путь по графу, но прийти к неверному выводу.
2. Скрытые зависимости. Graphify отлично справляется с явными связями в коде, но пасует перед «магией»: рефлексией, динамической загрузкой модулей или зависимостями, которые прописаны в инфраструктурных манифестах, а не в самом коде.
3. Проблема контекстного окна. Даже если у вас есть идеальный граф, вы не можете скормить его целиком в Claude или GPT. Вам всё равно придётся использовать стратегии селекции, такие как Ponytail, чтобы подавать агенту только те узлы графа, которые релевантны текущей задаче.

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

Подготовка инфраструктуры для локального запуска

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

Для локального тестирования я рекомендую использовать Docker Compose. Это позволит отделить процесс анализа кода от вашей основной системы и легко сбросить состояние, если граф «поплывёт» из-за ошибок в парсинге.

Сначала создайте директорию для проекта и подготовьте файл docker-compose.yml. Нам понадобится контейнер с Graphify и база данных (например, PostgreSQL), чтобы хранить результаты анализа.

yamlКопировать
version: '3.8'

services:
  # Контейнер для хранения графа и метаданных
  graph-db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: password123
      POSTGRES_DB: knowledge_graph
    volumes:
      - pgdata:/var/lib/postgresql/data

  # Сервис анализа
  graphify:
    image: graphify/analyzer:latest
    depends_on:
      - graph-db
    volumes:
      # Монтируем ваш исходный код для анализа
      - ./my-project:/app/code:ro
    environment:
      DATABASE_URL: postgresql://admin:password123@graph-db:5432/knowledge_graph
    command: ["run", "--path", "/app/code", "--output", "db"]

volumes:
  pgdata:

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

bashКопировать
docker compose up -d

Чтобы убедиться, что процесс анализа завершён корректно, проверьте логи контейнера. Если вы видите ошибки парсинга AST, значит, в коде есть конструкции, которые текущая версия инструмента не может переварить:

bashКопировать
docker compose logs -f graphify

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

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

Заключение

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

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

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

Когда Graphify будет полезен, а когда — нет

Чтобы не тратить время на внедрение инструмента там, где он не даст профита, давайте разделим сценарии использования.

Вам стоит использовать Graphify, если:

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

Инструмент будет избыточен, если:

• У вас небольшой скриптовый проект или монолит на 5–10 файлов. Здесь обычный RAG (Retrieval-Augmented Generation) справится быстрее и дешевле.
• Вы только начинаете экспериментировать с агентами и ещё не определились с их набором навыков (skills).

Как поддерживать актуальность графа

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

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

Пример упрощённого шага в GitHub Actions для обновления графа:

yamlКопировать
jobs:
  update-knowledge-graph:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Graphify
        run: npm install -g graphify # Установка инструмента

      - name: Generate Graph
        run: |
          # Генерируем граф из текущего состояния репозитория
          graphify analyze ./src --output ./docs/knowledge-graph.json
          
      - name: Commit updated graph
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add ./docs/knowledge-graph.json
          git commit -m "chore: update knowledge graph"
          git push

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

Граф знаний — это фундамент. Если фундамент кривой, никакие продвинутые модели не спасут архитектуру вашего взаимодействия с AI.

FAQ

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

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

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

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

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

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

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

yamlКопировать
# Пример настройки путей для анализа
include:
  - "src/**/*.ts"
  - "schema/*.sql"
  - "docs/**/*.md"
exclude:
  - "**/node_modules/**"
  - "**/dist/**"

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

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

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

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

Можно ли использовать его с Gemini CLI?

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

Типовой сценарий выглядит так: вы генерируете граф, экспортируете его описание и скармливаете его Gemini вместе с вашим вопросом. Это превращает «слепой» запрос в осознанную задачу.

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

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

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

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

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

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

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

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

Насколько точными будут ответы AI-агента при использовании графа?

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