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

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

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

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

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

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

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

С практической точки зрения это даёт предсказуемость. Когда Claude Code или другой ИИ-агент запрашивает контекст, он получает не случайный фрагмент файла, а логически завершённый узел графа. Например, если в коде есть определение интерфейса, Graphify зафиксирует все точки, где этот интерфейс реализуется.

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

Сканирование файлов проекта.
Построение AST для каждого языка (поддерживаются Python, TypeScript, Go и др.).
Извлечение связей: «функция А вызывает функцию Б», «класс X наследует класс Y».
Объединение этих связей в единый направленный граф.

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

Отсутствие векторных хранилищ

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

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

Почему это важно для локальных ИИ-агентов:

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

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

json
{
  "include": ["src/**/*.ts", "lib/**/*.py"],
  "exclude": ["**/node_modules/**", "**/tests/**"],
  "depth": 3, // Глубина рекурсивного обхода связей
  "extract_sql": true // Парсинг схем БД для связки с кодом
}

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

Возможности анализа данных

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

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

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

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

Для анализа конфигурационных файлов (например, YAML или JSON) используется аналогичный подход. Если вы настраиваете сложную инфраструктуру, Graphify поможет агенту понять зависимости между сервисами.

Пример конфигурации для захвата схем в graphify.config.yaml:

yaml
sources:
  - type: sql
    path: "./infrastructure/db/schema.sql"
    format: "postgresql" # Указываем диалект для корректного парсинга
  - type: config
    path: "./deploy/docker-compose.yml"
    parser: "yaml"

Такой подход обеспечивает предсказуемость: агент не будет гадать, существует ли колонка user_id в таблице заказов, он увидит это в структуре графа.

Работа с документацией и PDF

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

Graphify использует методы извлечения сущностей для обработки неструктурированных данных. При работе с PDF он не просто делает OCR (оптическое распознавание символов), а пытается сопоставить термины из документации с объектами в коде.

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

Для обработки документации можно использовать CLI-команду, указав директорию с документами:

bash
# Запуск индексации папки с документацией
graphify index --source ./docs/manuals --format pdf

С точки зрения архитектуры, это работает следующим образом:

Chunking: текст разбивается на смысловые фрагменты.
Entity Extraction: из фрагментов извлекаются ключевые понятия (названия функций, параметров, архитектурных паттернов).
Linking: эти понятия связываются с существующими узлами из кодовой базы.

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

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

Интеграция с AI-инструментами

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

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

Наиболее эффективный сценарий — это работа с терминальными агентами вроде Claude Code или современными IDE, такими как Cursor. Эти инструменты полагаются на контекстное окно, которое ограничено. Если просто «скормить» им сотни файлов, модель быстро потеряет нить повествования или начнет галлюцинировать.

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

Чтобы интегрировать граф в рабочий процесс, можно экспортировать наиболее важные узлы (например, связи между API-эндпоинтами и моделями БД) в формате JSON или Markdown-карты.

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

bash
# Генерируем сжатый граф только для ключевых модулей, чтобы не раздувать контекст
graphify analyze ./src --depth 2 --format markdown > architecture_map.md

В Cursor этот файл можно добавить в .cursorrules. Таким образом, когда вы просите IDE «добавить новое поле в профиль пользователя», она не просто ищет слово user по всему проекту, а понимает через architecture_map.md, какие сервисы и таблицы задействованы в этом процессе. Это делает работу локальных ИИ-агентов гораздо более предсказуемой.

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

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

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

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

bash
# Сценарий: анализ влияния изменений в схеме БД
# 1. Обновляем граф
graphify update ./schema.sql

# 2. Отправляем запрос, прикрепляя граф как контекст
gemini-cli prompt \
  --system "$(cat graph_context.md)" \
  "Проанализируй, какие функции в сервисе 'auth' сломаются, если я изменю тип поля 'user_id' с UUID на Integer"

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

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

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

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

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

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

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

bash
# Установка Graphify для анализа текущей директории
pip install graphify

Затем запустите построение графа. Я рекомендую сразу указывать область сканирования, чтобы не тратить ресурсы на директории вроде venv или node_modules:

bash
# Генерация графа знаний для исходного кода
graphify build --path ./src --output ./knowledge_graph.json --exclude ./src/tests

После этого Graphify создаст JSON-структуру, где каждый класс, функция и переменная представлены как узлы, а вызовы и импорты — как ребра. Если вы используете автономную разработку на Rust с помощью Claw-Code, такой подход позволяет агенту мгновенно понять, какие макросы или трейты задействованы в конкретном модуле, не перечитывая весь исходный код.

Объяснение связей между компонентами

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

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

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

yaml
# Конфигурация Graphify для комплексного анализа
analysis:
  languages:
    - python
    - sql
  include_docs: true  # Включаем Markdown-файлы в граф
  ast_depth: high     # Глубина анализа абстрактного синтаксического дерева
  
mapping:
  sql_to_code: true   # Связывать таблицы БД с соответствующими ORM-моделями
  doc_to_code: true   # Связывать описания в документации с реализацией

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

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

Заключение

Итоговые соображения по Graphify

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

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

Когда инструмент покажет себя во всей красе

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

Анализ архитектурных связей. Когда нужно понять, как изменение в одной SQL-схеме отразится на логике приложения через слои абстракций.
Подготовка контекста для автономных агентов. Если вы используете локальные ИИ-агенты и инструменты, наличие графа знаний позволит им не «галлюцинировать» о несуществующих методах, а опираться на реальное AST-дерево.
Документирование legacy-кода. Инструмент помогает быстро восстановить логическую цепочку вызовов, которую сложно отследить вручную.

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

Как интегрировать граф в рабочий процесс

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

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

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

bash
# Обновляем индекс графа знаний для текущей ветки
graphify index ./src --output ./knowledge-graph/

# Проверяем целостность графа (если инструмент поддерживает валидацию)
graphify validate ./knowledge-graph/

Для тех, кто занимается автономной разработкой на Rust, использование Graphify вместе с инструментами анализа AST позволяет добиться ещё большей точности при работе с типами и макросами.

Резюме

Graphify — это шаг в сторону создания действительно умных систем разработки. Он переводит взаимодействие с кодом из плоскости «текст — это набор строк» в плоскость «код — это структура связей». Это делает работу с автономными агентами более предсказуемой и менее ресурсозатратной.

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

FAQ

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

В Graphify архитектура построена так, чтобы минимизировать порог входа. Если ваша задача — разовый анализ репозитория, инструмент может работать в режиме in-memory, сохраняя временные индексы в оперативной памяти. Это удобно для небольших проектов, где не требуется постоянное хранение графа.

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

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

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

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

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

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

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

Graphify подготавливает высокоуровневое описание связей, которое можно передать в контекстное окно. Чтобы Claude лучше понимал структуру вашего проекта, рекомендую также создать CLAUDE.md. В связке с этим файлом Graphify позволяет агенту не просто искать текст, а понимать, что вызов функции в auth.py напрямую зависит от структуры таблицы users в вашей SQL-схеме.

В чем преимущество использования AST перед простым поиском?

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

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

Простой поиск: Находит все места, где встречается слово process_order.
AST-анализ: Понимает, что process_order принимает объект класса Order, возвращает Result и вызывается внутри метода execute в модуле billing.

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

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

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

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

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

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

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

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

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

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

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