Graphify-Labs/graphify: Кодовая база в запросную графичес...

Graphify-Labs/graphify: Кодовая база в запросную графическую сеть

Инструмент, превращающий репозитории с документацией, SQL-скемами, конфигами и PDF-дилогий в детерминированный граф знаний. Локальный AST-парсинг без векторного хранилища.

Основные возможности

Основные возможности

Graphify не строит эмбеддинги и не полагается на векторную базу. Он парсит репозиторий локально — через AST — и собирает из результатов детерминированный граф. При одних и тех же входных данных ты получаешь один и тот же граф. Это важно, если ценишь предсказуемость в конфигурациях и не хочешь полагаться на неопределённость, которая часто встречается в решениях на базе LLM.

Подробнее про сам инструмент и его идею можно почитать в материале Graphify: Создание знаний из кода в виде графов.

Парсинг и моделирование

С практической точки зрения, парсинг здесь означает не поиск по тексту, а построение абстрактного синтаксического дерева для каждого поддерживаемого языка. Graphify понимает Python, TypeScript, SQL, конфигурационные файлы и markdown. Каждый класс, функция, таблица или настройка становится узлом графа, а связи между ними — рёбрами.

Например, если в репозитории есть бэкенд на Python и SQL-схема, команда выглядит так:

bashКопировать
graphify parse ./backend --parsers python,sql --output graph.json

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

Конфиг graphify.yaml позволяет зафиксировать, что именно парсить:

yamlКопировать
parsers:
  - python
  - typescript
  - sql
  - markdown

exclude:
  - node_modules
  - .git
  - dist
  - __pycache__

output:
  format: graphml
  path: ./knowledge-graph

Детерминированность здесь не маркетинговый термин. Если два разработчика запустят парсинг одного и того же коммита, они получат идентичный граф. Это упрощает отладку и делает инструмент пригодным для использования в CI/CD.

Работа с документацией

Код — это только половина картины. Без документации граф остаётся набором связей без контекста. Graphify подтягивает markdown-файлы, PDF и другие текстовые документы из репозитория и привязывает их к соответствующим узлам графа.

Например, если в папке docs/ лежит описание API, а в коде есть соответствующие эндпоинты, Graphify свяжет их автоматически. Ты получаешь не просто «документация лежит рядом», а явную связь между функцией в коде и её описанием.

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

yamlКопировать
documentation:
  sources:
    - path: ./docs
      include:
        - "*.md"
        - "*.pdf"
  relations:
    - from: code
      to: documentation
      type: documents

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

Если ты работаешь с AI-агентами, такой граф удобно использовать как источник контекста. Например, в связке с Claude Code или другими инструментами с плагинной архитектурой. Подробнее про настройку Ponytail для Claude Code можно почитать в руководстве по настройке Ponytail для Claude Code, а про плагинную архитектуру для AI-агентов — в материале DeepSeek Harness: Плагинная архитектура для AI-агентов.

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

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

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

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

В этом разделе разберём два способа интеграции: встроенную поддержку Claude Code и агентные рабочие процессы на базе .agents.

Поддержка Claude Code

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

Во-первых, нужно собрать граф для репозитория:

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

Затем экспортируем его в формат, удобный для Claude Code:

bashКопировать
graphify export --input ./graphify-data --format claude --output ./claude-context.json

Полученный файл можно положить в репозиторий и сослаться на него из CLAUDE.md. Пример такого файла:

markdownКопировать
# CLAUDE.md

Этот репозиторий имеет связанный граф знаний, собранный Graphify.
Перед работой с кодом ознакомьтесь с файлом ./claude-context.json — там
описаны все публичные API, их зависимости и места вызова.

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

CLAUDE.md для агента — это как инструкция к оборудованию: без неё он будет гадать, где какой кабель. С практической точки зрения, я обычно добавляю команду сборки графа в CI, чтобы контекст для агента обновлялся при каждом пуше. Так агент всегда работает с актуальной версией кода, а не с тем, что было неделю назад.

Если вы уже используете Ponytail для Claude Code, Graphify вписывается в ту же цепочку — см. Настройку Ponytail для Claude Code.

Агентные рабочие процессы

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

Пример типичного сценария: агент получает задачу «добавить валидацию к всем эндпоинтам пользователя». Без графа ему пришлось бы искать все маршруты вручную, рискуя пропустить что-то. С графом он обходит все узлы, связанные с модулем пользователя, и вносит изменения только там, где это необходимо.

Агент с графом — это как инспектор с чертежами здания: он знает, где несущие стены, а где перегородки. Для настройки таких процессов в Graphify используется формат .agents. Это YAML-файл, где описываются навыки агента, его инструменты и правила поведения. Пример:

yamlКопировать
name: code-reviewer
description: Агент для ревью кода на основе графа знаний
graph_path: ./graphify-data
tools:
  - name: graph_query
    description: Поиск узлов и рёбер в графе
  - name: file_read
    description: Чтение исходного кода по пути из графа
rules:
  - Перед изменением функции проверьте все её вызовы в графе
  - Не вносите изменения в файлы, не связанные с задачей
  - После изменения обновите граф командой graphify build

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

Ещё один полезный инструмент — плагинная архитектура для агентов. Она позволяет подключать собственные инструменты к графу, не меняя ядро Graphify. Подробнее об этом в статье DeepSeek Harness: Плагинная архитектура для AI-агентов.

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

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

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

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

Примеры использования

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

Подробнее о концепции Graphify читайте в обзорной статье: Graphify: Создание знаний из кода в виде графов.

Пример 1. Разбор Python-проекта с SQL-схемой и Markdown-документацией

Допустим, есть репозиторий с бэкендом на FastAPI, PostgreSQL-схемой в папке sql/ и описанием API в docs/. Чтобы собрать граф, достаточно запустить парсинг с нужными парсерами:

bashКопировать
graphify parse ./my-project \
  --parsers python,sql,markdown \
  --exclude "*/tests/*" "*/migrations/*" \
  --output knowledge.graph

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

dotКопировать
digraph Knowledge {
  "src/models.py:User" -> "sql/schema.sql:users_table" [label="определяет"];
  "src/routes.py:create_user" -> "src/models.py:User" [label="использует"];
  "docs/api.md#post-users" -> "src/routes.py:create_user" [label="описывает"];
  "sql/schema.sql:users_table" -> "sql/migrations/001_users.sql" [label="создаётся в"];
}

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

Пример 2. Интеграция с Claude Code и AI-агентами

Если вы используете Claude Code для работы с кодом, Graphify может стать источником контекста для агента. Вместо того чтобы кормить модель целым репозиторием, вы передаёте только relevant подграф. Это снижает количество токенов и делает ответы предсказуемее.

В коллекции навыков из .agents есть пример, как подключить Graphify к агенту: Навыки реальных инженеров: коллекция из .agents. А если настраиваете Ponytail для Claude Code, можно добавить шаг построения графа перед индексацией: Настройка Ponytail для Claude Code.

Если интересует плагинная архитектура для агентов, смотрите материал про DeepSeek Harness: Плагинная архитектура для AI-агентов.

Пример 3. PDF-диалоги и техническая документация

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

bashКопировать
graphify ingest ./contracts --parser pdf --lang ru --output contracts.graph

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

Ограничения и решения

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

Отсутствие семантического поиска

Граф детерминирован: если в документации написано «оплата», а в коде — «checkout», Graphify не свяжет эти понятия автоматически. Для семантического поиска нужен векторный индекс, а Graphify его не строит.

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

Разнобой в поддержке языков

AST-парсинг работает хорошо для Python, JavaScript, TypeScript и SQL. С менее популярными языками могут быть сложности: парсер либо отсутствует, либо даёт неполное дерево.

Перед внедрением проверьте список поддерживаемых парсеров в документации проекта. Если нужный язык отсутствует, можно написать свой парсер на Tree-sitter — это больше работы, но даёт полный контроль над разбором.

Разрастание графа в больших репозиториях

В репозитории на 2 000+ файлов граф может насчитать сотни тысяч узлов и рёбер. Визуализировать такое вручную невозможно, а запросы к графу начинают тормозить.

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

Проблемы с PDF и неструктурированным текстом

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

Для критичных документов лучше предварительно прогнать их через OCR или подготовить вручную. Graphify не заменит редактора, но сократит время на ручной перенос данных.

Актуальность данных

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

Автоматизируйте пересборку: добавьте шаг в CI/CD или настройте вебхук на репозиторий. Тогда граф всегда будет отражать текущее состояние кода, и вы не будете гадать, актуальна ли схема зависимостей.

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

Почему Graphify предпочтительнее решений на базе LLM?

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

Можно ли настроить, какие языки и файлы парсятся?

Да, через файл graphify.yaml можно указать список поддерживаемых языков (Python, TypeScript, SQL, markdown) и исключить ненужные директории. Например, можно добавить исключение для node_modules или .git, чтобы не парсить неактуальные файлы. Конфиг также позволяет задать формат вывода и путь к результату.

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

Graphify выдаёт JSON-файл, который можно открыть в любом инструменте визуализации или передать в AI-агента. Формат graphml подходит для импорта в Graphviz или других графических редакторов. Это позволяет не только строить интерактивные графы, но и использовать результаты в других системах обработки знаний.

Нужно ли постоянно подключаться к интернету для работы Graphify?

Нет, Graphify работает полностью локально. Инструмент парсит репозиторий на своём оборудовании через AST, поэтому не требует интернет-соединения. Это особенно важно для частых запусков, например, при каждом коммите, когда нужно отслеживать изменения в зависимостях. Вы можете запускать его на сервере Винни-Пух без внешних связей.