Средний

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

Алексей Кузнецов
Алексей Кузнецов
Системный администратор21 октября 2026 г.11 мин чтения

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

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

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

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

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

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

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

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

С практической точки зрения это означает, что граф получается предсказуемым. Если функция calculate_total вызывает метод get_price из другого модуля, в графе появится явная ребро (edge) между этими узлами. Это не «мнение» нейросети, а математический факт, извлечённый из структуры кода.

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

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

yaml
# graphify-config.yaml
analysis:
  languages:
    - python
    - typescript
  include_patterns:
    - "src/**/*.py"
    - "lib/**/*.ts"
  exclude_patterns:
    - "**/tests/*"
    - "**/venv/*"
  # Указываем, какие элементы AST считать критически важными
  depth: 3
  extract_metadata: true

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

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

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

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

Это дает несколько преимуществ:

  1. Предсказуемость. Вы точно знаете, почему агент пришёл к конкретному файлу. Он не «почувствовал сходство», он проследил путь по вызовам.
  2. Легкость развертывания. Вам не нужно поднимать отдельный инстанс векторной базы. Граф может быть представлен в виде компактного файла или легковесной графовой структуры, что критично, если вы настраиваете AI-агентов из .agents в изолированной среде.
  3. Точность связей. Векторный поиск плохо справляется с мелкими, но важными деталями, вроде импортов или специфических декораторов. Граф же фиксирует их как жесткие правила.

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

Возможности построения графа знаний

Возможности построения графа знаний

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

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

Одной из самых сильных сторон Graphify является умение работать со структурированными данными, которые обычно выпадают из контекста при простом индексировании текста. Вместо того чтобы просто «скармливать» SQL-дамп модели, инструмент анализирует связи между таблицами, внешние ключи (foreign keys) и ограничения (constraints).

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

Например, если у вас есть файл schema.sql, Graphify не просто прочитает его, а построит топологию:

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),
    status VARCHAR(50)
);

В графе знаний возникнет ребро (edge) между узлами users.id и orders.user_id. Для AI-агента это означает, что при вопросе «какие заказы принадлежат пользователю X?» он не будет гадать по текстовому сходству, а пойдёт по прямому пути в графе. Это обеспечивает предсказуемость ответов — критически важный параметр, когда вы используете RL-модель flow-1 для поиска ошибок в трейсах агентов.

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

Обработка документации и PDF

Документация часто существует отдельно от кода, что создаёт разрыв в знаниях агента. Graphify пытается преодолеть этот барьер, связывая текстовые описания с конкретными объектами в коде.

При обработке PDF-файлов или Markdown-документации инструмент использует семантический разбор для выделения сущностей. Если в документации упоминается метод process_payment, Graphify ищет соответствующее определение в AST кодовой базы и создает связь. Это напоминает подход, описанный в материале про использование DESIGN.md для AI-агентов, где структурированное описание архитектуры служит ориентиром для модели.

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

bash
# Индексация документации с привязкой к контексту проекта
graphify index ./docs --format markdown --output ./knowledge_graph

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

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

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

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

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

В случае с Claude Code (интерфейс командной строки от Anthropic), Graphify выступает в роли поставщика контекста. Вместо того чтобы скармливать агенту сотни файлов через cat или grep, мы передаём ему уже извлечённую структуру.

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

bash
# Генерация графа знаний для текущей директории
graphify build --path ./src --output ./knowledge-graph.json

Теперь, когда вы запускаете Claude Code, вы можете использовать этот JSON как файл контекста. С практической точки зрения, это работает эффективнее, чем простое чтение файлов, потому что агент сразу видит зависимости (AST-связи), а не просто текст.

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

Это особенно актуально, если вы уже используете DESIGN.md для AI-агентов. В такой связке DESIGN.md задаёт высокоуровневую архитектуру, а граф от Graphify — низкоуровневую реализацию.

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

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

Чтобы интегрировать граф в пайплайн работы с Gemini, я рекомендую использовать промежуточный скрипт, который будет извлекать нужные подграфы. Например, если вам нужно проанализировать конкретный модуль, не стоит отправлять весь JSON на 50 МБ.

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

bash
# Извлекаем только связи, относящиеся к модулю 'auth', и сохраняем в компактный формат
graphify query --input ./knowledge-graph.json --filter "module == 'auth'" > auth_context.txt

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

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

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

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

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

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

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

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

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

  1. Точность связей. Мы не гадаем, похож ли файл на запрос, мы точно знаем, что UserService.ts импортирует UserRepository.ts.
  2. Предсказуемость контекста. Агент получает не случайный кусок кода, а цепочку вызовов. Это критично, если вы используете настройку ИИ-агентов из .agents, где логика поведения должна опираться на жесткую структуру проекта.
  3. Экономия на инфраструктуре. Нам не нужно разворачивать и поддерживать векторную базу данных. Граф — это, по сути, расширенная карта зависимостей, которую можно прочитать напрямую.

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

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

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

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

json
{
  "include": [
    "src/**/*.ts",
    "schema/*.sql",
    "docs/**/*.md"
  ],
  "exclude": [
    "**/node_modules/**",
    "**/dist/**",
    "**/*.test.ts"
  ],
  "parser": "ast-enhanced"
}

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

bash
npm install -g @graphify/cli

Затем выполните индексацию вашего репозитория:

bash
graphify index ./my-complex-project --output ./knowledge-graph

С полученным графом агент может выполнять задачи уровня REAE: реинжиниринг через агентов. Например, вместо вопроса «напиши функцию для удаления пользователя», вы можете спросить: «какие компоненты системы пострадают, если я изменю тип поля user_id в таблице orders?».

Граф позволит агенту пройти по цепочке: SQL Schema $\to$ Type Definition $\to$ Service Layer $\to$ API Controller. Это превращает AI из простого «писателя кода» в полноценного архитектурного консультанта. Однако стоит помнить, что для очень динамических языков с сильной рефлексией точность AST-парсинга может снижаться, и здесь всё ещё потребуется ручная проверка через использование DESIGN.md для AI-агентов.

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

Чем Graphify отличается от классического RAG с векторными базами данных?

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

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

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

Как инструмент справляется с проектами на нескольких языках программирования?

Graphify поддерживает мультиязыковую среду через парсинг AST для каждого конкретного языка, указанного в конфигурации. Вы можете настроить разные правила обработки для Python и TypeScript в одном файле graphify-config.yaml, задав соответствующие паттерны включения и исключения файлов. Это позволяет собрать единый граф знаний, объединяющий логику бэкенда и фронтенда в общую структуру.

Можно ли использовать Graphify для анализа существующих баз данных?

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

Поделиться:TelegramX / TwitterVK

Читайте также