Graphify: туториал — строим первый knowledge graph и читаем выходные файлы

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

Что понадобится

• Python 3.10+
• Репозиторий, который хотите отобразить в граф
• AI-ассистент: Claude Code, Cursor, Codex, Gemini CLI или любой из 20+ поддерживаемых

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

01 · Установка и регистрация

Установите CLI из PyPI (пакет graphifyy, команда graphify), затем зарегистрируйте навык /graphify в ассистенте.

$ uv tool install graphifyy
✓ installed graphify

$ graphify install
✓ /graphify skill registered

# если вы не на Claude Code, укажите ассистент явно:
# graphify cursor install · graphify codex install · graphify gemini install

Если возникли проблемы с установкой — официальный гайд покрывает pipx, обычный pip, правку PATH и команды под каждый ассистент.

02 · Построение графа

Откройте ассистент в репозитории и выполните:

/graphify .

Graphify распарсит код через tree-sitter (36 языков плюс Markdown, SQL и др.), извлечёт узлы и отношения, сгруппирует их в сообщества и запишет всё в graphify-out/. Время ожидания зависит от размера репозитория: маленькие проекты заканчиваются за минуты.

# внутри ассистента (для Codex: $graphify вместо /graphify)
/graphify .
✓ graphify-out/graph.html        interactive graph
✓ graphify-out/GRAPH_REPORT.md   architecture report
✓ graphify-out/graph.json        machine-readable graph

03 · Разбор выходных файлов

Три файла — для разных читателей. Начните с graph.html для обзора, пробегите GRAPH_REPORT.md для главного (он заканчивается полезными вопросами, которые стоит задать), а graph.json оставьте инструментам.

graphify-out/
├── graph.html       откройте в любом браузере: клик по узлам, фильтры, поиск
├── GRAPH_REPORT.md  ключевые концепции, неожиданные связи, предложенные вопросы
└── graph.json       полный граф; все запросы CLI и MCP читают этот файл

Важно: директория рассчитана на коммит. Коллега, сделавший git pull, получит готовую карту без повторного построения.

graph.html — интерактивный граф

Открывается в браузере, узлы кликабельны. Можно фильтровать по сообществам, искать узлы по имени, подсвечивать связи. Это лучший способ быстро увидеть «форму» незнакомого проекта.

GRAPH_REPORT.md — архитектурный отчёт

Markdown-документ с ключевыми концепциями (god nodes), обнаруженными подсистемами, неожиданными cross-community связями и списком вопросов, которые стоит задать графу. Заканчивается разделом «suggested questions» — отличная отправная точка для онбординга.

graph.json — машинно-читаемый граф

Полный граф в JSON: все узлы, рёбра, теги доверия, сообщества. Этот файл читают все команды CLI (query, path, explain) и MCP-сервер. Менять его вручную не нужно — он генерируется.

04 · Запросы из CLI

Спрашивайте обычным языком. Ответы — явные пути с цитатами file:line, каждое ребро помечено EXTRACTED, INFERRED или AMBIGUOUS.

$ graphify query "what connects auth to the database?"
AuthService → SessionStore → DatabasePool        [EXTRACTED]
  src/auth/service.py:42 → src/db/pool.py:17

$ graphify path "UserService" "DatabasePool"
UserService → UserRepository → DatabasePool      (2 hops)

$ graphify explain "RateLimiter"
RateLimiter · class · src/middleware/rate_limit.py
called by ApiGateway, WebhookHandler · calls RedisClient

Все команды и флаги (включая --dfs, --budget и дашборд PR) — в справочнике CLI.

05 · Запросы из ассистента

Те же запросы работают внутри ассистента через навык. Для нативных вызовов инструментов вместо shell-out — отдайте граф через MCP: 10 инструментов, включая query_graph, shortest_path и triage_prs.

# спросить через навык в чате ассистента:
/graphify query "how does a request reach the cache?"
/graphify path "ApiGateway" "RedisClient"
/graphify explain "SessionStore"

# или отдать граф через MCP для нативных вызовов:
$ python -m graphify.serve graphify-out/graph.json
# (нужен mcp-extra: uv tool install "graphifyy[mcp]")

06 · Поддержание графа в актуальном состоянии

Граф — это снимок, поэтому обновляйте его по мере движения кода. --update пересканирует только изменившееся; watch и git-хук автоматизируют процесс. Перестроения только по AST не требуют модели вовсе.

# пересканировать только изменившееся с прошлого запуска:
/graphify . --update

# перестроить граф кода при сохранении (без LLM):
$ graphify watch .

# или авто-перестроение после каждого коммита:
$ graphify hook install

Заметка практика: Git-хук graphify hook install — мой выбор для активных проектов: граф обновляется после каждого коммита автоматически, и ассистент всегда работает с актуальной картой. Для легаси-аудита, где код меняется редко, проще строить граф один раз руками и закоммитить graphify-out/ в репозиторий.

Дальше

• Справочник CLI — все команды и флаги
• MCP-сервер — нативные вызовы графа из ассистента
• Концепции графа — как строятся узлы, рёбра, сообщества и теги доверия

---

Локализованный туториал на основе официальной документации Graphify.