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

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

Как Graphify превращает код в структуру

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

Принцип работы AST-парсинга

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

Когда инструмент анализирует репозиторий, он не просто читает текст файла. Он запускает парсер, который разбирает синтаксис и понимает, что вот эта строка — это объявление метода в классе UserService, а вот эта — вызов этого метода в другом модуле.

С практической точки зрения это дает колоссальную предсказуемость. Если мы используем локальные ИИ-агенты и инструменты, им критически важно знать не только «о чём» этот код, но и «как» он связан с остальной системой.

Процесс можно представить так:

Сканирование: Инструмент обходит файлы проекта.
Парсинг: На основе грамматики языка (Python, TypeScript, Rust и др.) строится AST.
Извлечение сущностей: Из дерева вытягиваются узлы (классы, функции) и ребра (вызовы, наследование, импорты).
Построение графа: Эти связи объединяются в единый граф знаний.

Для понимания того, как глубоко современные инструменты могут погружаться в логику проекта, рекомендую изучить материал про автономную разработку на Rust с помощью Claw-Code. Там показано, как важно учитывать контекст языка при автоматизации.

Отличие от векторных баз данных

Большинство современных решений для работы с LLM полагаются на векторные хранилища. Там код разбивается на куски (chunks), каждый из которых превращается в вектор — математическую точку в многомерном пространстве. Поиск работает по принципу «найти куски текста, которые по смыслу похожи на запрос».

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

Graphify работает иначе. Вместо поиска «похожих по смыслу кусков», он выполняет обход графа.

Характеристика	Векторные БД (RAG)	Graphify (Knowledge Graph)
Тип связи	Вероятностная (семантическая близость)	Детерминированная (структурная связь)
Точность навигации	Может «галлюцинировать» связи	Строго следует AST и графу импортов
Контекст	Ограничен размером чанка	Охватывает всю цепочку вызовов
Предсказуемость	Низкая (зависит от эмбеддингов)	Высокая (основана на синтаксисе)

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

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

Возможности анализа документации и схем

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

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

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

С практической точки зрения, это работает так же, как парсинг кода: инструмент читает файл, находит ключевые паттерны и преобразует их в триплеты (субъект — предикат — объект). Для работы с конфигурациями, например, YAML-файлами Kubernetes или Nginx, Graphify извлекает зависимости между сервисами, портами и томами.

Пример того, как инструмент может интерпретировать упрощенную схему в контексте графа:

sql
-- Входящий SQL-файл (schema.sql)
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)
);

В графе это превратится в структуру, где узел orders имеет направленную связь belongs_to к узлу users. Такая предсказуемость связей позволяет локальным ИИ-агентам гораздо точнее отвечать на вопросы вроде «какие таблицы затронет изменение типа данных в поле user_id».

Интеграция с PDF и текстовыми файлами

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

При анализе текстовых файлов (README, Markdown, технические спецификации) инструмент ищет семантические связи. Если в README.md написано, что сервис «Пятачок» отвечает за обработку очередей, а в коде мы видим запуск RabbitMQ, Graphify может связать эти сущности в единый узел знаний.

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

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

yaml
# config.yaml
analysis:
  sources:
    - path: "./src"
      type: "source_code"
    - path: "./docs/architecture"
      type: "documentation"
      formats: ["md", "pdf", "txt"]
  graph:
    output: "./knowledge_graph.json"

Важно понимать: Graphify не пытается «понять» смысл текста так, как это делает LLM. Он ищет совпадения сущностей и паттернов. Если в PDF упоминается компонент AuthService, а в коде есть класс AuthService, инструмент создаст связь между ними. Это создает фундамент, на котором автономная разработка может опираться на реальные факты, а не на галлюцинации модели.

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

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

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

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

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

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

Для Cursor процесс выглядит ещё проще. Вы можете экспортировать граф в формате JSON или Markdown и добавить этот файл в .cursorrules. Это даст модели понимание того, как изменения в одном модуле могут затронуть другие части системы.

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

bash
# Генерируем граф и сохраняем его в компактный Markdown для контекста агента
graphify ./src --format markdown > .cursor/architecture_context.md

После этого в Cursor или Claude Code вы можете просто сослаться на этот файл: «Используй .cursor/architecture_context.md, чтобы понять зависимости перед рефакторингом модуля auth». Это обеспечивает предсказуемость: агент не будет гадать, как связаны компоненты, а увидит их явную топологию.

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

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

Проблема многих CLI-инструментов заключается в том, что они ограничены окном контекста. Если проект разросся, вы не сможете отправить весь AST (Abstract Syntax Tree) целиком. Здесь Graphify решает задачу сжатия информации: вместо передачи сырого кода мы передаём высокоуровневую схему связей.

Чтобы интегрировать это в ваш рабочий процесс, можно настроить пайплайн, где сначала отрабатывает анализ, а затем результат передаётся в Gemini.

Пример сценария для автоматизации анализа (bash-скрипт):

bash
#!/bin/bash
# Скрипт для передачи архитектурного графа в Gemini CLI

PROJECT_DIR="./my-project"
GRAPH_FILE="temp_graph.json"

echo "Сначала строим граф знаний..."
graphify "$PROJECT_DIR" --format json > "$GRAPH_FILE"

echo "Передаем граф в Gemini для анализа архитектурных рисков..."
# Предполагаем, что gemini-cli настроен в системе
gemini-cli prompt "Проанализируй этот граф связей и найди потенциально слабые места в архитектуре: $(cat $GRAPH_FILE)"

# Удаляем временный файл
rm "$GRAPH_FILE"

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

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

Практическое применение в инженерных задачах

Улучшение контекста для AI-агентов

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

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

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

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

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

В полученном graph.json связи между классами и методами прописаны явно. Это обеспечивает предсказуемость: агент не «додумает» связь, которой нет, а будет опираться на жесткую структуру AST.

Поиск связей в сложных репозиториях

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

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

Рассмотрим пример конфигурации для глубокого анализа проекта, где нужно учитывать не только код, но и документацию (например, Markdown-файлы в папке /docs):

yaml
# config.yaml для Graphify
analysis:
  include_dirs:
    - "./src"
    - "./docs"
  extract_ast: true
  include_comments: true
  relations:
    - type: "calls"      # связи вызова функций
    - type: "inherits"   # наследование классов
    - type: "imports"    # импорты модулей
    - type: "references" # ссылки в документации

При таком подходе инструмент связывает текстовое описание в документации с конкретными реализациями в коде. Если в документации указано, что «модуль X управляет состоянием Y», Graphify найдет в AST определение переменной или структуры, отвечающей за это состояние, и создаст ребро в графе.

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

Заключение

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

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

Однако, если вы строите локальных ИИ-агентов и инструменты для глубокого анализа архитектуры, где критически важно понимать, что функция A вызывает метод B, который изменяет состояние объекта C, то без графа знаний не обойтись. Graphify позволяет получить ту самую предсказуемость, которой не хватает векторным эмбеддингам. Векторы «сглаживают» детали, превращая код в облако смыслов, а граф сохраняет жесткую структуру AST (Abstract Syntax Tree).

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

Аудит безопасности: отслеживание потоков данных (data flow) от входа в систему до критических функций.
Рефакторинг больших монолитов: когда нужно понять масштаб последствий изменения одной сигнатуры метода.
Генерация документации: создание точных схем зависимостей, которые не галлюцинируют.

Ограничения и подводные камни

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

Во-первых, при работе с динамически типизированными языками (например, Python) точность графа будет ниже, чем в строго типизированном Rust. Если связи между объектами определяются только в рантайме, Graphify может упустить часть ребер графа.

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

Итоговый алгоритм внедрения

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

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

bash
# Анализ конкретной директории с сохранением графа в формате JSON
graphify analyze ./src --output ./build/knowledge-graph.json --format json

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

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

FAQ

Нужно ли настраивать векторное хранилище?

Нет, в этом и заключается одно из главных архитектурных отличий Graphify. Большинство современных RAG-систем (Retrieval-Augmented Generation) полагаются на векторные базы данных вроде Chroma или Pinecone, где информация хранится в виде эмбеддингов. Это часто усложняет инфраструктуру и требует дополнительного контроля за качеством индексации.

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

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

На текущем этапе инструмент фокусируется на языках с развитой структурой AST, чтобы обеспечить высокую точность связей. В основном это языки семейства C, Python и Rust. Поддержка Rust особенно актуальна, если вы занимаетесь автономной разработкой на Rust с помощью Claw-Code.

Помимо исходного кода, Graphify умеет обрабатывать:

Файлы документации в формате Markdown;
Схемы архитектуры (например, в формате Mermaid или PlantUML);
Конфигурационные файлы (YAML, JSON), если они описывают зависимости компонентов.

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

yaml
# Пример настройки фильтрации файлов
analysis:
  include:
    - "**/*.rs"      # Исходный код на Rust
    - "**/*.md"      # Документация
    - "architecture/*.puml" # Схемы PlantUML
  exclude:
    - "**/target/**" # Исключаем артефакты сборки
    - "**/node_modules/**"

Как инструмент влияет на точность ответов AI?

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

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

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

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

Для локального запуска через Docker выполните следующую команду:

bash
# Запуск Graphify в контейнере с пробросом текущей директории
docker run --rm -v $(pwd):/app graphify/cli:latest analyze /app/src

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

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

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

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

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

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

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

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

Как точность графа знаний влияет на работу ИИ-агента

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

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