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

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

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

Как Graphify строит структуру проекта

Анализ через AST вместо векторного поиска

Когда мы говорим об анализе кода с помощью ИИ, стандартный подход — это создание эмбеддингов и сохранение их в векторной базе данных. Это работает для поиска по смыслу, но совершенно не подходит для понимания структуры. Если вы спросите векторную базу: «Где объявляется класс User и какие методы его наследуют?», она может выдать похожие по смыслу куски кода, но она не понимает иерархию.

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

С практической точки зрения это означает, что Graphify строит не «облако смыслов», а точную карту связей. Когда инструмент проходит по файлам, он парсит их и понимает, что функция calculate_total не просто «какой-то текст про расчеты», а конкретный узел, который вызывает метод get_price из другого модуля. Такая точность критически важна для оптимизации Claude Code с помощью CLAUDE.md, где агенту нужно не гадать, а точно знать контекст вызова.

Связи между кодом, SQL и документацией

Главная проблема при работе с крупными проектами — это разрыв контекста. Код живет в .py или .go файлах, структура данных — в миграциях SQL, а логика работы — в README.md или DESIGN.md. Для ИИ-агента это разрозненные куски информации.

Graphify решает эту задачу, объединяя эти сущности в единый граф. Процесс выглядит так:

1. Код: Извлекаются определения классов, функций и их зависимости через AST.
2. SQL: Парсятся схемы таблиц, связи FOREIGN KEY и индексы.
3. Документация: Текстовые файлы анализируются на наличие упоминаний ключевых сущностей проекта.

В результате получается структура, где узел «Таблица orders» связан с узлом «Класс OrderService» через логическое соответствие, а тот, в свою очередь, связан с разделом в документации, описывающим процесс оформления заказа.

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

yamlКопировать
# Конфигурация источников для построения графа
sources:
  code:
    path: "./src"
    languages: ["python", "typescript"]
  database:
    path: "./migrations"
    type: "postgresql"
  docs:
    path: "./docs"
    patterns: ["*.md", "DESIGN.md"]

# Настройка глубины анализа связей
analysis:
  depth: 3
  include_external_libs: false

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

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

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

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

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

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

В современных AI-native редакторах, таких как Cursor, или при работе через терминальный агент Claude Code, основной сложностью является передача структуры проекта. Когда вы просите агента «сделать рефакторинг этого модуля», он видит только открытые файлы.

Чтобы повысить предсказуемость ответов, Graphify можно интегрировать в рабочий процесс через файлы конфигурации контекста. Например, в Claude Code полезно создать файл CLAUDE.md, который будет содержать не только инструкции по стилю, но и путь к экспортированному графу.

Для Cursor можно использовать подход с генерацией локального индекса. Вместо того чтобы полагаться только на встроенный RAG (Retrieval-Augmented Generation), который часто ошибается в глубоких зависимостях, вы можете подавать сгенерированный Graphify JSON-файл в качестве контекста для чата.

Пример структуры файла контекста для агента:

markdownКопировать
# Project Knowledge Graph Context
The following structure represents the core dependencies of the service.
Use this graph to resolve imports and understand data flow.

[path/to/generated/graph.json]

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

Работа через CLI для Gemini и Codex

Если вы строите автоматизированный пайплайн или используете модели вроде Gemini через API, вам понадобится способ быстро получать актуальный снимок структуры кода. Здесь Graphify раскрывается как CLI-инструмент.

С практической точки зрения, удобнее всего встроить генерацию графа в ваш pre-commit hook или в CI/CD процесс. Это гарантирует, что контекст, который получает модель, всегда соответствует текущему состоянию ветки.

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

bashКопировать
# Генерация графа только для директории src с исключением тестов
graphify scan ./src --exclude ./src/**/*.test.ts --output ./docs/knowledge-graph.json

Если вы работаете с SQL-схемами для подготовки контекста под Codex или другие модели, работающие с данными, команда будет выглядеть так:

bashКопировать
# Создание графа на основе схемы базы данных
graphify schema ./migrations/ --format json > ./context/db_structure.json

Полученный JSON-файл можно передавать в системный промпт при вызове API. Это гораздо эффективнее, чем пытаться скормить модели десятки файлов .sql по отдельности. Такой подход позволяет реализовать оптимизацию ИИ-агентов с помощью системы ECC, где точность передачи структуры напрямую влияет на качество выполнения задачи.

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

Преимущества детерминированного подхода

Преимущества детерминированного подхода

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

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

Предсказуемость связей и отсутствие галлюцинаций

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

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

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

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

jsonКопировать
{
  "node": "OrderService.process",
  "type": "function",
  "calls": [
    {
      "target": "Database.commit",
      "relation": "direct_call"
    },
    {
      "target": "Logger.info",
      "relation": "direct_call"
    }
  ]
}

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

Локальная обработка данных и конфиденциальность

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

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

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

bashКопировать
# Запуск локального анализа без передачи данных во внешние хранилища
docker run --rm -v $(pwd)/src:/app/src graphify-cli:latest analyze /app/src --output graph.json

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

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

Быстрый онбординг в сложные репозитории

Когда вы впервые открываете проект, над которым работала команда из двадцати человек в течение трёх лет, основной проблемой становится не синтаксис языка, а понимание связей. Вы видите функцию process_order(), но не понимаете, какие именно состояния базы данных она меняет и какие побочные эффекты вызывает в других сервисах.

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

С практической точки зрения, это позволяет мгновенно увидеть «точки входа» в логику. Если вы планируете внедрять новые правила через использование DESIGN.md для генерации UI через AI, вам важно понимать, как изменения в схеме данных отразятся на существующих компонентах.

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

bashКопировать
# Генерация графа на основе исходного кода
graphify analyze ./src --output-format dot --out graph.dot

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

Анализ зависимостей в больших системах

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

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

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

yamlКопировать
# Конфигурация для глубокого анализа зависимостей
analysis:
  include_dirs:
    - ./services
    - ./migrations
  parsers:
    - sql: ./schema.sql    # Связываем SQL-схемы с кодом
    - python: ./services   # Парсим бизнес-логику
  depth: 3                 # Глубина обхода графа для поиска косвенных связей

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

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

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

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

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

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

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

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

Как инструмент связывает SQL-схемы с логикой в коде?

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

Нужно ли отдельно настраивать парсинг документации?

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