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

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

Как работает построение графа знаний

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

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

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

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

Если мы сравним это с навигацией, то векторный поиск — это попытка найти нужную комнату в здании по описанию «здесь пахнет кофе», а анализ AST — это использование точного архитектурного плана. Когда агент понимает, что Class A наследует Class B, а метод method_c вызывает function_d, он получает структурную точность, которую невозможно получить через эмбеддинги.

Это критически важно при настройке ИИ-агентов из .agents, где агенту нужно не просто «знать о коде», а понимать зависимости, чтобы не внести деструктивные изменения.

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

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

Синтаксический уровень: извлечение определений классов, методов, переменных и их типов.
Семантический уровень: сопоставление вызовов функций с их определениями.
Слой данных: парсинг SQL-схем и сопоставление их с моделями данных в коде.

Процесс парсинга можно представить как конвейер. Для языков вроде Python или TypeScript Graphify использует специализированные парсеры, которые превращают исходный текст в дерево узлов. Каждый узел в графе — это не просто текст, а объект с метаданными: его расположением, областью видимости и связями.

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

С практической точки зрения, работа с графом выглядит как обход узлов. Если вам нужно проанализировать влияние изменения в конкретной таблице БД, Graphify позволит агенту пройти путь: SQL Table $\to$ ORM Model $\to$ Service Layer $\to$ API Endpoint.

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

json
{
  "node_type": "function_definition",
  "identifier": "calculate_total_price",
  "location": "src/services/order_service.py:42",
  "dependencies": [
    {"type": "call", "target": "get_tax_rate", "location": "src/utils/tax.py:12"},
    {"type": "access", "target": "OrderModel.price", "location": "models/order.py:5"}
  ],
  "ast_context": {
    "complexity": 5,
    "is_async": true
  }
}

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

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

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

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

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

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

Пример того, как Graphify обрабатывает схему, можно увидеть, если скормить ему файл schema.sql:

sql
-- Graphify распознает эти связи и создаст ребра в графе знаний
CREATE TABLE users (
    id UUID PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL
);

CREATE TABLE orders (
    id UUID PRIMARY KEY,
    user_id UUID REFERENCES users(id), -- Связь будет зафиксирована в графе
    amount DECIMAL(10, 2) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Помимо SQL, инструмент эффективно работает с конфигурационными файлами (YAML, JSON, TOML). Это позволяет агенту понимать окружение: какие переменные окружения ожидаются, какие порты открыты и как связаны сервисы в Docker Compose. Если вы планируете настройку ИИ-агентов из .agents, наличие такой «карты» инфраструктуры в графе знаний значительно снизит количество галлюцинаций при попытках агента изменить конфигурацию.

Интеграция с документацией и PDF

Код без документации — это только половина картины. Часто бизнес-логика описана в README, файлах DESIGN.md или даже в PDF-спецификациях, которые лежат в репозитории. Graphify использует методы AST (Abstract Syntax Tree) для кода и семантический анализ для текста, чтобы объединить их в единую структуру.

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

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

yaml
# Пример конфигурации индексации документации
indexing:
  sources:
    - path: "./docs"
      type: "markdown"
    - path: "./specs/api_v2.pdf"
      type: "pdf"
  graph_options:
    semantic_linking: true # Включает поиск связей между текстом и кодом
    depth: 2               # Глубина связей для построения графа

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

Использование в AI-инструментах

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

Граф знаний превращает «просто текст» в структурированную карту, по которой агент может перемещаться, понимая зависимости.

Интеграция с Claude Code и Cursor

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

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

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

bash
# Сначала обновляем граф знаний для текущей директории
graphify build --path ./src --output ./docs/knowledge-graph.json

# Запускаем Claude Code, указывая на обновленный контекст
claude-code --context ./docs/knowledge-graph.json

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

markdown
# AI Context Rules
Always refer to the structural relationships defined in `./docs/knowledge-graph.json`.
When proposing changes to functions, verify their dependencies via the graph nodes 
to ensure no breaking changes in the call stack.

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

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

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

Чтобы интегрировать Graphify с Gemini CLI, удобнее всего использовать промежуточный скрипт, который извлекает нужный подграф (subgraph) на основе запроса. Например, если вам нужно проанализировать влияние изменения в схеме SQL, вы не должны отправлять весь код.

Пример логики работы через CLI:

bash
# Извлекаем только узлы, связанные с таблицей 'users' и её зависимостями
graphify query --input ./docs/knowledge-graph.json --target "table:users" --depth 2 > context_snippet.txt

# Передаём полученный контекст в Gemini для анализа
gemini-cli prompt "Проанализируй возможные последствия изменения типа поля 'email' в таблице 'users' на основе этого контекста:" --file context_snippet.txt

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

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

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

Когда граф знаний эффективнее RAG

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

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

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

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

Сценарии для сложных репозиториев

Я часто сталкиваюсь с тем, что при попытке внедрить AI-агентов в существующие проекты, они начинают «галлюцинировать» из-за неполного понимания архитектуры. Graphify помогает минимизировать этот риск в трёх сценариях:

1. Рефакторинг и поиск побочных эффектов В монолитах или крупных микросервисах изменение одного метода может вызвать каскад ошибок в модулях, которые на первый взгляд никак не связаны. Используя граф, агент может простроить путь: Function A $\to$ calls Module B $\to$ updates Table C $\to$ triggers Event D. Это критически важно, если вы используете методы реинжиниринга через агентов (REAE), где точность восстановления логики определяет успех всего процесса.

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

3. Синхронизация схемы БД и бизнес-логики Частая проблема: код ожидает одно поле в базе, а в миграциях указано другое. Поскольку Graphify анализирует и SQL-схемы, и код, он может выявить несоответствия.

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

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

bash
# Генерация графа для конкретного модуля с учетом SQL-схем
graphify build --path ./src/services/billing \
               --include-sql ./migrations \
               --output ./knowledge-graph/billing.json

# Проверка связей между модулями на предмет циклических зависимостей
graphify analyze --graph ./knowledge-graph/billing.json --type dependencies

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

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

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