Создание графа знаний из кода с помощью Graphify

Создание графа знаний из кода с помощью Graphify

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

Проблема контекста при работе с AI

Проблема контекста при работе с AI

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

Ограничения векторных хранилищ

Большинство современных систем используют векторный поиск (Semantic Search) для предоставления контекста модели. Суть метода проста: код разбивается на куски (chunks), превращается в векторы и сохраняется в базу данных. Когда агент задаёт вопрос, система ищет наиболее похожие по смыслу фрагменты.

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

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

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

Почему RAG не всегда справляется с кодом

Классический RAG (Retrieval-Augmented Generation) работает по принципу: «нашёл похожий кусок — отдал модели». В случае с обычным текстом это работает. В случае с кодом — нет.

Код — это не текст, это древовидная структура. Чтобы понять, как работает метод в классе, вам нужно знать:

1. Определение этого класса.
2. Наследование (от каких классов он происходит).
3. Интерфейсы, которые он реализует.
4. Типы данных, которые передаются в аргументы.

Стандартный RAG часто разбивает файл на куски по 500–1000 токенов. В результате получается ситуация, когда определение функции находится в одном чанке, а её использование — в другом, и они физически не попадают в один запрос к модели. Это убивает предсказуемость ответов.

Возьмём типичный пример. Вы используете инструменты вроде Claude Code и хотите, чтобы агент отрефакторил SQL-схему. Если RAG подтянет только описание таблицы, но не подтянет связи FOREIGN KEY из другого файла, агент предложит решение, которое сломает целостность базы данных.

Проблема в том, что для кода важна не семантическая близость слов, а синтаксическая точность. Чтобы агент не писал лишнего и не ошибался, ему нужен не просто поиск по сходству, а полноценный AST (Abstract Syntax Tree) — абстрактное синтаксическое дерево. Именно здесь на сцену выходит Graphify, который переходит от поиска «похожих слов» к навигации по графу зависимостей. Это позволяет избежать проблем, описанных в материале про Ponytail, где избыточность кода часто является следствием непонимания агентом существующей структуры.

Принцип работы Graphify

Принцип работы Graphify

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

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

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

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

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

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

1. Модуль.
2. Класс.
3. Метод.
4. Аргументы и возвращаемые типы.

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

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

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

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

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

• SQL-схемы: извлекает структуру таблиц, связи (Foreign Keys) и ограничения.
• Документацию: сопоставляет описания в .md файлах с именами функций и классов.
• Исходный код: выявляет импорты и вызовы.

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

yamlКопировать
# graphify.config.yaml
sources:
  code:
    paths: ["./src"]
    languages: ["typescript", "python"]
  database:
    type: "postgres"
    schema_path: "./migrations"
  docs:
    paths: ["./docs"]
    format: "markdown"

output:
  format: "json-graph"
  path: "./build/knowledge-graph.json"

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

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

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

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

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

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

Чтобы интегрировать Graphify в работу с Claude Code, я рекомендую использовать подход с предварительной генерацией контекстного файла. Вместо того чтобы заставлять агента сканировать весь репозиторий (что дорого и медленно), мы подсовываем ему готовый «снимок» структуры.

Если вы уже используете настройку GStack, добавьте этап генерации графа в ваш рабочий цикл. Для Cursor это можно реализовать через создание .cursorrules, где вы укажете путь к экспортированному JSON-графу.

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

markdownКопировать
# Context Rules
Always refer to the project knowledge graph located at `./docs/knowledge_graph.json`.
When analyzing code changes, check the 'dependencies' field in the graph 
to ensure no breaking changes are introduced in downstream services.

Это повышает предсказуемость работы агента. Вместо того чтобы гадать, он обращается к структурированным данным, полученным через AST-анализ.

Подключение через CLI

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

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

Чтобы создать граф только для части проекта (например, только для папки с бизнес-логикой), используйте команду:

bashКопировать
# Генерация графа для папки src/services с экспортом в JSON
graphify analyze ./src/services --format json --output ./docs/services_graph.json

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

Для интеграции в автоматизированный процесс (например, перед выполнением тестов или линтинга) я использую простую обертку в package.json или Makefile:

makefileКопировать
# Makefile для автоматизации подготовки контекста
graph-update:
	@echo "Updating knowledge graph..."
	graphify analyze ./src --format json --output ./docs/project_map.json
	@echo "Done. Graph is ready for AI agents."

pre-commit: graph-update
	git commit -m "Update context and commit changes"

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

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

Анализ сложных зависимостей в проекте

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

Инструмент использует AST (Abstract Syntax Tree) для построения связей. Это не просто поиск по тексту, а понимание того, что функция A вызывает класс B, который инициализируется в конфигурационном файле C. Если мы подготовим такой граф, AI-агент сможет не просто «угадывать» контекст, а точно знать область влияния (blast radius) любого изменения.

Для начала работы с анализом зависимостей, создайте конфигурационный файл graphify.config.json. Это обеспечит предсказуемость процесса: вы чётко определите, какие директории нужно сканировать, а какие — игнорировать (например, node_modules или venv).

jsonКопировать
{
  "include": ["src/**/*.ts", "lib/**/*.py"],
  "exclude": ["**/tests/**", "**/dist/**"],
  "output": "./knowledge-graph",
  "format": "json-ld"
}

После настройки запустите процесс генерации:

bashКопировать
graphify analyze --config graphify.config.json

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

Автоматизация понимания архитектуры

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

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

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

Схема автоматизации выглядит так:

1. Graphify сканирует код и SQL-схемы.
2. Формируется JSON-LD или GraphViz файл.
3. Скрипт-прослойка извлекает ключевые узлы (сущности, API-эндпоинты, связи БД).
4. Эти данные вставляются в системный промпт агента или в файлы документации.

Пример того, как может выглядеть фрагмент извлечённого контекста для агента:

markdownКопировать
## Архитектурный контекст (автоматически сгенерировано)
- Core Entity: `User` (Table: `users`)
- Dependencies: `User` -> `Order` (1:N), `User` -> `Profile` (1:1)
- Critical Path: `AuthService.validate()` calls `Redis.get()` and `PostgreSQL.query()`

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

Заключение

Когда Graphify оправдывает себя

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

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

Ограничения и нюансы внедрения

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

1. Глубина анализа AST. Инструмент опирается на абстрактное синтаксическое дерево. Если код написан с использованием чрезмерного количества динамических конструкций (например, глубокая рефлексия в Python или сложные метапрограммируемые макросы в Rust), граф может оказаться неполным.
2. Актуальность графа. Граф — это слепок состояния системы. Если вы изменили схему в SQL, но не пересобрали граф, AI-агент будет опираться на устаревшие данные. Я рекомендую добавить шаг генерации графа в ваш CI/CD пайплайн.

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

bashКопировать
# Запуск генерации графа для текущей директории с экспортом в JSON
graphify analyze ./src --output ./docs/knowledge-graph.json --format json

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

Итоговая стратегия использования

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

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

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

FAQ

FAQ

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

В классических RAG-системах (Retrieval-Augmented Generation) векторная база данных обязательна, так как она отвечает за поиск по семантическому сходству. Graphify работает иначе: он фокусируется на структурных связях через AST (Abstract Syntax Tree). Вместо поиска «похожих по смыслу» кусков текста, инструмент позволяет AI-агенту переходить от определения функции к её вызову или от колонки в SQL-схеме к связанной таблице.

Если ваша задача — просто дать агенту контекст проекта, достаточно экспортированного графа. Однако, если вы строите сложную систему, где нужно совмещать структурный поиск с семантическим, вам всё равно придётся интегрировать Graphify с чем-то вроде Chroma или Qdrant. Это позволит агенту сначала найти нужный узел в графе, а затем уточнить запрос через векторный поиск.

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

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

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

Если вы планируете использовать инструмент для анализа специфических DSL (Domain Specific Languages), вам может потребоваться дописать парсер. С точки зрения предсказуемости, лучше всего Graphify справляется с типизированными языками, где связи между компонентами выражены явно.

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

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

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

Для автоматизации этого процесса можно использовать конфигурацию в graphify.config.yaml:

yamlКопировать
analysis:
  depth: 3 # Глубина обхода зависимостей
  exclude:
    - "tests/*"
    - "venv/*"
  focus_nodes:
    - "public_api"

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

Можно ли использовать Graphify локально?

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

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

bashКопировать
graphify build --path ./src --output ./graph-data

Для тех, кто привык к системному подходу и автоматизации, Graphify отлично вписывается в пайплайны развертывания инструментов для работы с LLM. Если вы уже настраивали GStack: набор инструментов Claude Code, то добавление Graphify в ваш рабочий процесс станет логичным шагом для улучшения качества контекста, который получает агент.

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

Можно ли использовать Graphify вместо векторной базы данных?

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

Как Graphify помогает избежать галлюцинаций модели?

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

Какие типы данных лучше всего подходят для построения графа?

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

Нужно ли переписывать существующий проект для внедрения этого подхода?

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