Graphify: превращаем любой код в граф знаний

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

Что делает Graphify и зачем он инженеру

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

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

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

Локальный парсинг AST вместо векторной базы

Большинство инструментов для анализа кода сегодня строятся на векторных базах и эмбеддингах. Они превращают фрагменты кода в векторы, ищут близость по косинусу и выдают «вероятно связанное». Это удобно для поиска по смыслу, но плохо подходит для инженерии: вектор не скажет, что функция create_order вызывает validate_payment из другого микросервиса, а эмбеддинг может измениться после обновления модели.

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

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

yaml
sources:
  - path: ./services/billing
    language: go
    parser: ast
  - path: ./docs/api.md
    type: markdown
  - path: ./schema/postgres.sql
    type: sql
output:
  format: graphql
  storage: sqlite

После парсинга граф можно запросить напрямую. Ниже пример того, как может выглядеть запрос к графу зависимостей (синтаксис упрощён):

graphql
query {
  service(name: "billing") {
    calls {
      target {
        name
        language
      }
    }
    database {
      tables {
        name
        foreignKeys {
          targetTable
        }
      }
    }
  }
}

С практической точки зрения, важный момент: парсинг происходит локально, на машине инженера или в CI-контуре. Код не уходит на внешние серверы, нет необходимости поднимать отдельный кластер только для хранения эмбеддингов. Для команды, которая уже размещает сервисы на своём оборудовании, это существенная экономия инфраструктуры.

Какие источники поддерживает

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

Исходный код. Поддерживаются основные языки с чёткой грамматикой: Python, Go, JavaScript, TypeScript, Java, C#. Для каждого языка используется свой парсер AST, поэтому извлечение импортов и вызовов работает точно, без регулярных выражений по исходнику.

Документация. Markdown-файлы, README и технические спецификации парсятся на сущности: API-эндпоинты, переменные окружения, описание бизнес-логики. Связи между документацией и кодом устанавливаются по совпадению имён функций и путей.

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

PDF. Технические документы в формате PDF извлекаются через локальный парсер текста, после чего проходят ту же нормализацию, что и Markdown. Полезно, когда архитектура описана в PDF, а код в репозитории — Graphify соединяет их в одну модель.

Пример SQL-схемы и того, что из неё извлекается:

sql
CREATE TABLE orders (
    id UUID PRIMARY KEY,
    user_id UUID REFERENCES users(id),
    status VARCHAR(20) NOT NULL,
    created_at TIMESTAMP DEFAULT now()
);

В графе это станет узлом orders с полями id, user_id, status, created_at и ребром к узлу users по полю user_id.

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

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

Как подключить навык к Claude Code, Cursor и Codex

Установка через /graphify

Claude Code работает с навыками — это готовые промпты, привязанные к определённой команде. Graphify устанавливается как один из таких навыков, и после подключения становится доступен через /graphify.

Во-первых, ставим сам Graphify. Он парсит AST локально, поэтому код не уходит с вашего компьютера.

bash
pip install graphify-cli

Для проектов на JavaScript или TypeScript есть npm-вариант:

bash
npm install -g graphify

Проверяем, что команда доступна в системе:

bash
graphify --version
# 0.4.1

Теперь подключаем навык в Claude Code. Создаём файл ~/.claude/skills/graphify.json:

json
{
  "name": "graphify",
  "command": "/graphify",
  "description": "Построить граф знаний из локального кода",
  "args": {
    "path": {
      "type": "string",
      "description": "Путь к директории с проектом",
      "default": "."
    }
  }
}

Перезапускаем Claude Code. В чате появляется команда /graphify. Пишете /graphify проанализируй модуль auth — Graphify обходит AST, находит связи между функциями, классами и вызовами, и возвращает результат прямо в контекст сессии.

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

Если мы посмотрим на ограничения, Graphify поддерживает Python, JavaScript, TypeScript, Go, Rust и SQL. Смешанный стек даст частичный граф — только по тем языкам, которые парсер распознаёт.

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

Настройка для Gemini CLI

Gemini CLI не использует JSON-навыки как Claude Code. Здесь навык описывается в YAML и вызывает внешний бинарный файл.

Во-первых, проверяем, что graphify есть в PATH:

bash
which graphify

Если команда не найдена, добавляем директорию с бинарником:

bash
export PATH="$PATH:$HOME/.local/bin"

Потом создаём или правим ~/.gemini/skills.yaml:

yaml
skills:
  - name: graphify
    command: graphify
    args:
      - --input
      - "{{workspace}}"
      - --format
      - json
    description: "Построить граф знаний из кодовой базы"
    triggers:
      - "/graphify"
      - "graf znaniy"
      - "knowledge graph"

Сохраняем, перезапускаем Gemini CLI. Теперь при вызове /graphify или упоминании графа знаний Gemini CLI запустит Graphify локально и подставит результат в контекст.

Cursor и Codex не имеют встроенного механизма навыков, но Graphify можно подключить через MCP (Model Context Protocol). В Cursor добавляем в .cursor/mcp.json:

json
{
  "mcpServers": {
    "graphify": {
      "command": "graphify",
      "args": ["--mcp", "--workspace", "."]
    }
  }
}

Для Codex аналогично — через пользовательскую команду в терминале или обёртку над graphify. Главное: всё работает локально, код не попадает на сторонние серверы. Это критично для закрытых репозиториев.

Если нужно почитать про другие подходы к расширению ИИ-агентов плагинами, смотрите материал про DeepSeek Harness: DeepSeek Harness: Everything is a Plugin.

Проверяем результат:

bash
graphify --input ./src --format dot > knowledge-graph.dot

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

Что происходит внутри: рёбра и зависимости

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

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

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

Как объясняется каждая связь

Каждое ребро в Graphify имеет три обязательных поля: источник, цель и тип связи. Тип определяется на этапе обхода AST: например, вызов функции фиксируется как calls, импорт модуля — как imports, определение класса — как defines, а ссылка на таблицу в SQL-запросе — как references.

Помимо типа, Graphify прикрепляет к ребру краткое объяснение. Оно формируется по правилам, а не генерируется языковой моделью на лету — это важно для предсказуемости. Если связь выглядит неочевидно, Graphify добавляет контекст: номер строки, имя файла и фрагмент кода, из которого зависимость была извлечена.

Для обхода дерева Graphify использует стандартный подход к работе с AST, аналогичный тому, что описан в документации Python ast. Разница в том, что Graphify не останавливается на синтаксисе: он дополнительно связывает узлы кода с таблицами БД и разделами документации.

Пример записи ребра в формате, который Graphify отдаёт наружу:

json
{
  "source": "src/services/payment.py:process_payment",
  "target": "src/db/models.py:Order",
  "type": "references",
  "line": 42,
  "explanation": "SQL-запрос в&nbsp;строке 42 обращается к таблице orders через ORM-модель Order",
  "confidence": 0.95
}

Если Graphify не может достоверно определить тип связи, он помечает ребро как ambiguous и снижает confidence. Такие рёбра стоит проверять вручную, прежде чем принимать решение об удалении или рефакторинге.

Примеры запросов к графу

Graphify предоставляет CLI и HTTP API для обхода графа. Ниже — примеры, которые пригодятся при работе с кодом и при интеграции с AI-агентами.

Найти все функции, которые вызывают process_payment:

bash
graphify query --edge-type calls --target "src/services/payment.py:process_payment"

Показать все таблицы, на которые ссылается модуль отчётов:

bash
graphify query --edge-type references --source "src/reports/monthly.py" --target-type table

Найти потенциально мёртвый код — экспортированные функции, к которым нет входящих рёбер:

bash
graphify query --edge-type calls --direction incoming --empty --source-type function

Для Claude Code есть навык, который позволяет агенту ходить по графу прямо из сессии кодирования. Например, можно попросить Claude показать все зависимости выбранной функции перед рефакторингом:

Покажи все исходящие рёбра для функции src/api/users.py:create_user

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

Если нужно интегрировать Graphify в свой пайплайн, HTTP API отдаёт граф в формате JSON. Пример запроса к эндпоинту /edges:

bash
curl -s "http://localhost:8080/edges?source=src/services/payment.py&type=calls" | jq '.'

Ответ содержит массив рёбер, которые можно скормить в любой инструмент визуализации или в контекст AI-агента.

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

Ограничения и когда Graphify не подходит

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

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

Размер кодовой базы

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

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

С практической точки зрения, я бы не рекомендовал запускать Graphify на монорепозитории больше 5–10 миллионов строк без предварительной фильтрации. Лучше ограничить область сканирования. Например, создать файл .graphifyignore:

text
# .graphifyignore
node_modules/
target/
dist/
build/
*.md
*.lock

И запускать анализ только по нужным директориям:

bash
graphify analyze --path ./services/auth --output ./graph-auth.json

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

Языки программирования

Graphify полагается на парсеры AST для каждого поддерживаемого языка. Поддерживаются основные: Python, JavaScript, TypeScript, Go, Rust, Java, C#. SQL-схемы и PDF тоже обрабатываются, но через отдельные конвертеры, а не через полноценный AST.

Ограничение здесь не в количестве языков, а в зрелости парсеров. Для редких или только появившихся языков может не быть стабильной грамматики tree-sitter. Тогда Graphify либо пропустит файлы, либо построит неполный граф.

Пример: в проекте на Nim или OCaml Graphify, скорее всего, не распознает связи между модулями. Для таких языков придётся писать свой парсер или ждать поддержки сообществом.

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

bash
graphify languages --list

Если ваш стек включает экзотические языки, Graphify в текущем виде не подходит. Для основного стека — Python, Go, TypeScript — инструмент работает стабильно, и это то, на что можно ориентироваться при планировании интеграции с Claude Code или другими AI-агентами.

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

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

Graphify парсит код через AST, поэтому поддержка зависит от наличия парсера для конкретного языка. На старте работает с Python, JavaScript/TypeScript, Go и Java — этого достаточно для большинства микросервисных стеков. SQL-схемы и PDF обрабатываются отдельными модулями, не зависящими от языка кода.

Уходит ли код с компьютера при анализе?

Нет, весь парсинг происходит локально на вашем оборудовании. Graphify не отправляет исходники во внешние сервисы и не использует облачные эмбеддинги, что важно при работе под NDA. Граф остаётся на вашем диске, и вы контролируете доступ к нему.

Как подключить Graphify к Claude Code?

Graphify поставляется как навык для Claude Code и подключается через конфигурационный файл агента. После установки Claude Code может запрашивать граф напрямую, например уточнять, какие функции затрагивает изменение в модуле оплаты. Для других AI-агентов используется тот же API, но интеграцию нужно настраивать вручную.

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

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

Чем Graphify лучше обычного поиска по коду в IDE?

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

Graphify: превращаем любой код в граф знаний