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

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

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

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

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

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

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

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

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

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

yamlКопировать
# Конфигурация Graphify для анализа Python-проекта
project:
  name: "my-backend-service"
  path: "./src"
  languages:
    - python
    - sql

parser:
  ast_depth: 5 # Глубина вложенности для анализа связей
  extract_docstrings: true # Извлекать документацию для обогащения узлов

output:
  format: "graphdb" # Сохранение в формате графовой базы данных
  storage: "./data/knowledge_graph"

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

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

Векторная база данных не знает о связях. Она знает только о близости векторов в многомерном пространстве. Граф же хранит топологию. Это дает несколько ключевых преимуществ:

1. Точность контекста. Когда AI-агент запрашивает информацию, он получает не случайный кусок кода, который «показался похожим», а цепочку связанных сущностей. Это напрямую влияет на то, насколько эффективно агент будет выполнять задачи, описанные в материалах про оптимизацию работы AI-агентов.
2. Навигация по зависимостям. В графе можно выполнить обход (traversal). Мы можем проследить путь от API-эндпоинта до конкретного SQL-запроса, проходя через слои бизнес-логики. Векторный поиск для такой задачи практически бесполезен.
3. Снижение шума. Вместо того чтобы скармливать модели огромные контекстные окна с кучей нерелевантного кода, мы передаем только те узлы графа, которые имеют прямое отношение к вопросу. Это помогает заставить AI-агента писать меньше лишнего кода.

Для понимания того, как это вписывается в общую экосистему инструментов, стоит взглянуть на обзор Corgi, который показывает, как агенты взаимодействуют с окружением. Граф знаний от Graphify становится для такого агента не просто набором документов, а полноценной ментальной моделью системы.

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

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

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

С практической точки зрения, Graphify не пытается заменить IDE или терминальный интерфейс агента, а выступает в роли «внешнего мозга», поставляющего контекст. Если вы используете Claude Code, инструмент позволяет избежать типичной проблемы «галлюцинаций» из-за неполного понимания связей в проекте. Вместо того чтобы скармливать модели сотни файлов через RAG, вы даёте ей доступ к структурированному графу.

В Cursor интеграция происходит через кастомные инструкции (Rules for AI). Чтобы агент понимал структуру вашего проекта через Graphify, добавьте в .cursorrules указание использовать сгенерированный граф для уточнения зависимостей.

Пример того, как можно настроить контекст для агента, чтобы он опирался на AST-анализ, а не на случайные куски кода:

markdownКопировать
# Context Integration Rule
When analyzing code dependencies or architectural patterns, 
always refer to the graph generated by Graphify in the /docs/graph/ directory.
Do not rely solely on file content; prioritize the relationship map 
to ensure structural accuracy.

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

Поддержка CLI для Gemini и Codex

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

Если вы работаете с моделями семейства Gemini или Codex через API, вы можете использовать Graphify для предварительной подготовки «карты» проекта. Вместо того чтобы заставлять модель самостоятельно обходить дерево каталогов, вы передаёте ей компактный JSON-представление графа.

Для генерации графа из текущей директории выполните:

bashКопировать
# Генерация графа знаний на основе AST и SQL-схем
graphify build --path ./src --output ./docs/graph/project_map.json --include-sql

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

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

bashКопировать
#!/bin/bash
# Скрипт для автоматического обновления графа знаний в репозитории

TARGET_DIR="./src"
OUTPUT_FILE="./docs/graph/knowledge_graph.json"

echo "Starting Graphify analysis..."

if graphify build --path "$TARGET_DIR" --output "$OUTPUT_FILE"; then
    echo "Graph successfully updated: $OUTPUT_FILE"
else
    echo "Error: Graph generation failed"
    exit 1
fi

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

Практическое применение для инженера

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

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

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

Предположим, у нас есть типичная схема для микросервиса. Чтобы Graphify проанализировал её, достаточно указать путь к файлам. Если вы используете Docker для локальной разработки, запуск анализа может выглядеть так:

bashКопировать
# Запуск генерации графа из директории с SQL-схемами
docker run --rm -v $(pwd)/sql:/data graphify/cli analyze /data --format graphml --output schema_graph.graphml

В результате мы получаем не просто текстовое описание, а структуру, где каждая таблица — это узел, а связи FOREIGN KEY — ребра. Это критически важно для оптимизации работы AI-агентов, так как агент начинает «понимать» топологию базы данных.

Если в вашей инфраструктуре конфигурации разбросаны по разным файлам (например, Nginx конфиги и Docker Compose), Graphify может связать их в единую карту. Это позволяет избежать ситуаций, когда агент предлагает изменить порт в приложении, не зная, что в конфигурации прокси он жестко зашит на другой. Такая предсказуемость конфигураций — залог того, что автоматизация не превратится в хаос.

Построение контекста из документации и PDF

Вторая область применения — это превращение разрозненной документации в структурированный источник знаний. Обычно инженеры сталкиваются с тем, что документация живет отдельно от кода: часть в README.md, часть в Notion, а часть — в старых PDF-файлах с описанием архитектуры.

Graphify позволяет извлечь сущности из текстовых документов и связать их с реальными компонентами системы. Если в PDF-файле описан процесс обработки заказов, инструмент сопоставит термины из текста с названиями функций или классов в коде.

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

yamlКопировать
sources:
  - type: filesystem
    path: ./docs
    extensions: [md, txt]
  - type: pdf
    path: ./architecture_specs
    extract_tables: true # Извлекаем таблицы, так как в них часто зашита логика состояний

output:
  engine: memory
  storage: local_graph

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

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

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

Ограничения и особенности метода

Локальная обработка данных

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

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

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

Для инициализации анализа локальной директории достаточно запустить команду:

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

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

Точность объяснения связей (edges)

Главная ценность графа не в самих узлах (функциях или классах), а в связях между ними. В Graphify эти связи (edges) строятся на основе статического анализа. Если один класс наследуется от другого или функция вызывает метод из соседнего модуля, это фиксируется как явная зависимость.

Однако стоит учитывать, что метод имеет свои границы. Graphify отлично справляется с явными вызовами, но может упускать динамические зависимости, которые определяются только во время выполнения (runtime). Например, если вы используете сложные паттерны внедрения зависимостей (Dependency Injection) или динамический импорт в Python, граф может не увидеть связь, пока код не будет запущен.

Чтобы повысить точность, я рекомендую комбинировать Graphify с качественной документацией. Если в коде есть сложные участки, описание которых трудно восстановить через AST, добавьте их в файлы документации (например, в формате Markdown). Graphify подтянет эти текстовые блоки и свяжет их с соответствующими узлами кода.

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

jsonКопировать
{
  "analysis_rules": {
    "include_docstrings": true,
    "depth": 3,
    "connection_types": ["inheritance", "composition", "call_graph"]
  }
}

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

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

Заключение

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

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

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

1. Анализ архитектуры. Когда нужно понять, как изменение в одном модуле повлияет на цепочку вызовов в других частях системы.
2. Работа с базами данных. Построение графа на основе SQL-схем позволяет AI-агентам понимать зависимости между таблицами лучше, чем при простом чтении DDL-файлов.
3. Генерация документации. Граф позволяет извлекать контекст не кусками, а логическими блоками.

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

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

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

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

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

Итоговый чек-лист внедрения

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

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

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

bashКопировать
# Обновляем граф только для измененных файлов, чтобы сэкономить ресурсы
graphify update --path ./src --include-sql --output ./knowledge-graph.json

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

FAQ

Нужна ли векторная база данных для Graphify?

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

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

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

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

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

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

jsonКопировать
{
  "include": ["src/**/*.ts", "schema/*.sql"],
  "exclude": ["**/node_modules/**", "**/dist/**"],
  "depth": 3 // глубина обхода связей для построения графа
}

Как Graphify помогает при работе с большими репозиториями?

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

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

С практической точки зрения, это дает два преимущества:

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

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

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

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

Можно ли использовать Graphify для анализа больших монолитов?

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

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

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

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

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