Продвинутый

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

Алексей Кузнецов
Алексей Кузнецов
Системный администратор31 октября 2026 г.10 мин чтения

Как Graphify строит детерминированный граф знаний из кода, документации и схем БД без векторных хранилищ. Интеграция с Claude Code, Cursor и Gemini CLI.

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

Как Graphify строит детерминированный граф знаний из кода, документации и схем БД без векторных хранилищ. Интеграция с Claude Code, Cursor и Gemini CLI.

Как Graphify строит граф без векторного поиска

Как Graphify строит граф без векторного поиска

Парсинг AST вместо эмбеддингов

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

Пример: файл example.py содержит класс Service с методом run. После парсинга AST‑дерево выглядит так (упрощённо):

json
{
  "nodes": [
    {"id": "example.Service", "type": "class"},
    {"id": "example.run", "type": "method"}
  ],
  "edges": [
    {"from": "example.Service", "to": "example.run", "label": "has_method"}
  ]
}

Команда для получения такого JSON‑вывода:

bash
graphify parse --input example.py --output - | jq .

Graphify-Labs/graphify: локальный AST‑парсинг к знани‑графу

Определение связей между сущностями

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

Пример конфигурации, описывающей связь между модулем и базой данных:

yaml
connections:
  - type: uses
    source: module
    target: database
    match: "postgres"

Команда, использующая данный файл:

bash
graphify build --config connections.yaml --output knowledge_graph.dot

Результат — файл knowledge_graph.dot, который можно визуализировать в любом GraphViz‑совместимом инструменте. Всё построено детерминированно, без применения векторных хранилищ, что гарантирует воспроизводимость и предсказуемость связей.

Таким образом, Graphify строит граф знаний, опираясь на статический анализ кода и явные ссылки, а не на распределённые эмбеддинги, что упрощает отладку и обеспечивает предсказуемость работы в CI/CD‑конвейерах.

Интеграция с AI-ассистентами для кода

Настройка /graphify в Claude Code и Cursor

Во‑первых, Graphify представляет собой набор расширений, которые добавляют возможность генерировать граф знаний прямо в среде редактирования кода. Для работы требуется установленная последняя версия Claude Code (пакет claude‑code‑client ≥ 2.4) и Cursor 2024‑го выпуска.

  1. Инициализация конфигурации
    В корневой директории проекта создаётся файл .graphify.yml. Пример минимального набора:

    yaml
    graphify:
      sources:
        - type: code
          paths:
            - src/
        - type: docs
          paths:
            - docs/
      output:
        format: dot
        file: graph.dot
    

    Команда graphify init создаёт такой файл со всеми комментариями‑подсказками.

  2. Подключение в Claude Code
    После установки расширения в VS Code открываем контекстный меню «Graphify → Generate Knowledge Graph».
    В открывшемся диалогe указываем путь к конфигу и выбираем тип вывода (DOT или SVG).

    bash
    # Пример запуска из терминала внутри Claude Code
    graphify run --config .graphify.yml --output svg
    

    После завершения в папке ./output появляется файл knowledge.svg, который можно сразу просмотреть в браузере или импортировать в Claude Chat для дальнейшего анализа.

  3. Настройка в Cursor
    В Cursor переходим в раздел Extensions, находим Graphify (пакет graphify‑cursor) и нажимаем Install.
    В настройках проекта указываем переменную окружения GRAPHIFY_API_KEY, получаемую в кабинете Graphify‑Labs.

    bash
    export GRAPHIFY_API_KEY=ghp_XXXXXXXXXXXXXXXXXXXX
    graphify run --watch --output dot
    

    Параметр --watch отслеживает изменения в файлах src/ и docs/ и автоматически обновляет граф каждый раз, когда сохраняется изменённый файл.

Для более детального описания параметров см. Graphify‑Labs/graphify.

Практические рекомендации по использованию Graphify в реальных проектах – в Навыки реальных инженеров: практические практики из .agents.

Работа с Gemini CLI и Codex

Во‑вторых, Graphify может быть интегрирован в сторонние AI‑инструменты, такие как Gemini CLI и Codex, чтобы получать готовый граф в виде входных данных для генерации кода или документирования.

  1. Подготовка данных
    Graphify сохраняет граф в формате DOT. Gemini CLI умеет читать этот формат и преобразовывать в JSON‑схему, которую понимает его собственный движок.

    bash
    # Пример конвертации DOT → JSON для Gemini CLI
    dot -Tjson graph.dot -o graph.json
    gemini-cli --model gemini-1.5-pro --input graph.json --output prompt.txt
    

    Полученный prompt.txt содержит описание узлов и релейных связей, которое можно передать в любой LLM‑ассистент (Claude Code, GPT, Gemini Chat) для получения рекомендаций по рефакторингу, генерации тестов или создания документации.

  2. Интеграция с Codex
    Codex (инструмент, предоставляющий автодополнение и генерацию кода на основе запросов) поддерживает импорт пользовательских схем через параметр --schema.

    bash
    # Пример использования схемы, полученной от Graphify
    codex generate --language python --schema graph.json --output module.py
    

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

  3. Автоматизация в пайплайне CI
    Для полной автоматизации удобно добавить шаг в GitHub Actions или GitLab CI, который после каждого коммита генерирует граф, сохраняет его в артефакте и передаёт в Gemini CLI. Пример workflow‑файла:

    yaml
    name: Generate Knowledge Graph
    on:
      push:
        branches: [ main ]
    jobs:
      graphify:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - name: Install Graphify
            run: pip install graphify-cli
          - name: Generate DOT graph
            run: graphify run --config .graphify.yml --output dot
          - name: Convert to JSON
            run: dot -Tjson graph.dot -o graph.json
          - name: Feed to Gemini CLI
            env:
              GRAPHIFY_API_KEY: ${{ secrets.GRAPHIFY_API_KEY }}
            run: gemini-cli --model gemini-1.5-pro --input graph.json --output prompt.txt
    

    После выполнения артефакт prompt.txt можно использовать в downstream‑задачах: создание Pull Request, генерация тестов, обновление документации.

Подробные примеры использования Gemini CLI в сочетании с Graphify – в Навыки реальных инженеров: практические практики из .agents.

Симуляция прошивок для AI‑агентов, что часто требуется при работе с графовыми схемами, описана в Simantic: симуляция прошивок для AI‑агентов.

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

Таким образом, Graphify легко встраивается в существующие рабочие процессы Claude Code, Cursor, Gemini CLI и Codex, обеспечивая детерминированное построение графов знаний без привлечения векторных хранилищ. Всё, что остаётся – описать задачи, запустить генерацию и использовать полученный граф в дальнейшем анализе кода.

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

Код

Graphify умеет напрямую анализировать файлы исходного кода любых поддерживаемых языков.
Для быстрого старта достаточно указать каталог с проектом и получить JSON‑описание граф‑структуры.

bash
# Пример: парсим весь проект на Python и сохраняем граф в файл
graphify parse --input ./src --language python --output ./graph.json

В результате в graph.json появляются узлы — классы, функции, интерфейсы — и связи — наследование, вызовы, импорт.
Если нужно уточнить только определённый модуль, можно задать путь к файлу:

bash
graphify parse --input ./src/utils/helpers.py --output ./helpers.graph.json

Примечание. При работе с большими репозиториями удобно предварительно собрать список файлов в manifest.txt и передать его через параметр --files. Это уменьшает нагрузку на процессор и гарантирует детерминированность результата.

Подробнее о парсинге кода в Graphify‑Labs


SQL‑схемы и конфигурационные файлы

Помимо кода, Graphify принимает DDL‑описания баз данных и файлы конфигураций.
SQL‑скрипты, содержащие CREATE TABLE, ALTER, VIEW и т.п., преобразуются в сущности‑узлы, а их зависимости (внешние ключи, ссылки) фиксируются как ребра графа.

sql
-- Пример DDL‑скрипта, который будет обработан
CREATE TABLE users (
    id BIGSERIAL PRIMARY KEY,
    username VARCHAR(50) NOT NULL,
    email VARCHAR(100) UNIQUE,
    created_at TIMESTAMP DEFAULT now()
);

CREATE TABLE orders (
    id BIGSERIAL PRIMARY KEY,
    user_id BIGINT REFERENCES users(id),
    total NUMERIC(12,2) NOT NULL,
    status VARCHAR(20) DEFAULT 'pending',
    placed_at TIMESTAMP DEFAULT now()
);

Конфигурационные файлы поддерживаются в форматах YAML, TOML и JSON.
Каждая секция превращается в объект‑узел, а ссылки между секциями (например, references в YAML) автоматически становятся ребрами.

yaml
# Пример конфигурации, читаемой Graphify
services:
  api:
    image: myorg/api:1.2
    ports:
      - "8080:8080"
    environment:
      DB_HOST: postgres
      DB_PORT: 5432
  worker:
    image: myorg/worker:0.9
    depends_on:
      - api

Во‑первых, Graphify сохраняет оригинальный синтаксис в метаданных, так что потом легко отследить, откуда взялась конкретная сущность.
С практической точки зрения удобно хранить схемы и конфиги в отдельном каталоге schema/ и указывать его в параметре --configs.

См. как интегрировать схемы с другими источниками


Обработка PDF‑документации и Markdown

Техническая документация часто поставляется в PDF или Markdown.
Graphify умеет извлекать текст из PDF‑файлов, парсить структуру заголовков и сохранять её как набор узлов‑параграфов.

bash
# Импортировать PDF‑документацию и получить граф
graphify import --pdf ./docs/architecture.pdf --output ./docs.graph.json

Во время импорта Graphify использует OCR‑библиотеку для сканирования сканных PDF и затем применяет тот же AST‑парсер, что и для кода, чтобы выделить функции, классы и ссылки.

Для Markdown‑файлов процесс проще: каждый блок кода, заголовок # и список * преобразуются в соответствующие узлы.

markdown
# Сервис аутентификации

## Основные компоненты
- **AuthController** — обработка запросов
- **TokenService** — генерация JWT
- **UserRepository** — взаимодействие с БД
bash
# Парсим Markdown‑файл
graphify parse --input ./docs/README.md --output ./readme.graph.json

Если требуется объединить несколько источников (код, схемы, документацию), достаточно передать несколько путей через параметр --sources:

bash
graphify build \
  --sources ./src ./schema/ ./docs/architecture.pdf ./docs/README.md \
  --output ./full-graph.json

Таким образом, граф знаний становится единым источником правды, откуда можно генерировать автодокументацию, проверять целостность ссылок или питать AI‑агентов (Claude Code, Cursor, Gemini CLI).

Дополнительные практики из .agents


Готово.

Практические сценарии использования

Поиск зависимостей при рефакторинге

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

Следующий пример показывает, как запустить сканирование проекта и получить файл GraphML, который можно открыть в yEd или импортировать в Neo4j:

bash
graphify scan --project /path/to/project --output dependencies.graphml

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

bash
dot -Tpng dependencies.graphml -o dependencies.png

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

bash
graphify scan --project . --filter external --output external_deps.graphml

Во-вторых, результат сканирования удобно использовать в pull‑request’е: сравнивайте два файла GraphML, полученных до и после изменения, и видите, какие модули стали добавляться или удаляться.

Подробнее о работе с графом зависимостей

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

Автоматическое документирование архитектуры

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

Пример команды, генерирующей диаграмму системы на основе кода и SQL‑схемы:

bash
graphify generate \
  --source /path/to/source \
  --db schema.sql \
  --output architecture.svg

Полученный SVG можно включить в README‑файл репозитория или в Confluence‑страницу, где поддерживается живой процесс документирования.

Для интеграции с Claude Code, Cursor или Gemini CLI удобно добавить в конфигурацию проекта файл .graphify.yml, например:

yaml
project_root: /home/alexey/projects/myapp
output_format: svg
include:
  - src/
  - db/
  - docs/

После коммита в репозиторий CI‑pipeline автоматически запускает Graphify и публикует обновлённую диаграмму в артефактах сборки.

Пример использования Graphify в CI/CD

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

Если требуется более детальная настройка, см. раздел «Навыки реальных инженеров: практические практики из .agents».

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

Как Graphify строит граф знаний без векторных хранилищ?

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

Что требуется для определения связей между сущностями в коде?

Graphify использует импорты, комментарии, схемы баз данных и конфигурационные файлы, сопоставляя их с элементами AST. Правила связей задаются в YAML‑конфигурации, где указывается тип (например, uses), источник и цель. После сопоставления формируются ребра, отражающие реальные зависимости.

Как интегрировать Graphify с Claude Code, Cursor и Gemini CLI?

Интеграция осуществляется через командные строки, предоставляемые этими инструментами, которые вызывают Graphify parse или build с указанием входных файлов. Например, в Cursor можно добавить скрипт, который после парсинга AST сохраняет результат в файл знани‑графа. Аналогично, Gemini CLI принимает путь к проекту и генерирует dot‑файл для визуализации.

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

Сгенерированный граф хранится в формате DOT, совместимом с GraphViz, или в JSON‑структуре, которую можно импортировать в любые визуализационные инструменты. Для быстрой проверки удобно открыть DOT‑файл в VS Code с расширением GraphViz Preview или в онлайн‑редакторе. Форматы вывода настраиваются параметром --output в командах parse и build.

Поделиться:TelegramX / TwitterVK

Читайте также