Практика graphify: превращаем любой код в поисковую карту знаний

Средняя сложность | ~20 минут | Вы освоите end-to-end процесс, как graphify превращает любой репозиторий кода в поисковую карту знаний — забудьте про слепой grep и получите структурированное понимание кода со сжатием токенов в 71.5x.

Описание проекта

graphify — это skill для AI-разработчиков, разработанный Safi Shamsi, GitHub: safishamsi/graphify. Его основная идея очень проста: сжать любую папку (код, заметки, статьи, изображения и даже видео) в одну поисковую карту знаний, чтобы каждый ваш диалог с AI-ассистентом опирался на структурированные знания, а не на слепое сопоставление всего текста.

У него три ключевые особенности:

• Мультимодальный ввод: код (20 языков), документы, изображения, PDF, аудио/видео — всё поддерживается и попадает в одну и ту же карту
• Кластеризация без embedding: алгоритм обнаружения сообществ Leiden кластеризует напрямую по топологии графа, не нужен векторный хранилище и не нужно отдельно запускать model для embeddings
• Честная уверенность: для каждой грани связи указаны EXTRACTED / INFERRED / AMBIGUOUS, чтобы вы понимали, что найдено, а что выведено предположением

graphify можно использовать как команду /graphify в таких популярных AI-ассистентах для кодинга, как Claude Code, OpenClaw, Codex, Cursor, Trae, и т. д., а также вызывать отдельно через MCP Server или CLI.

Целевая аудитория

Вы уже работали минимум с одним средним проектом (тысяча строк и больше) и в повседневной работе используете Claude Code / OpenClaw / Codex или других AI-ассистентов. При работе с новым репозиторием вы обычно просите ассистента сразу прочитать исходники — но по мере роста числа файлов становится всё заметнее: токены тратятся слишком быстро, а контекст дробится. Эта статья как раз для решения этой проблемы.

Ключевые зависимости и окружение

Полная структура проекта

my-project/
├── graphify-out/
│   ├── graph.json          # персистентная карта знаний, доступна для запросов между сессиями
│   ├── GRAPH_REPORT.md     # структурированный аналитический отчёт (god nodes, неожиданные связи, рекомендованные вопросы)
│   ├── graph.html          # интерактивная карта (vis.js, открывается прямо в браузере)
│   ├── cache/              # каталог кэша SHA256
│   └── transcripts/        # кэш транскриптов аудио/видео (нужны зависимости video)
├── .graphifyignore         # правила исключения (синтаксис как у .gitignore)
└── .git/hooks/            # создаётся автоматически после установки graphify hook

Пошагово

Шаг 1 — Установите graphify

graphify состоит из двух этапов: сначала установить Python-пакет, затем — установить слой адаптации для вашего AI-ассистента.

# Шаг 1: установка PyPI-пакета
pip install graphifyy

# Шаг 2: установка адаптации под вашу платформу
# Пример для Claude Code:
graphify install

# Если у вас другая платформа — используйте соответствующую команду:
# graphify install --platform codex
# graphify install --platform opencode
# graphify install --platform claw        # OpenClaw
# graphify install --platform aider
# graphify install --platform droid       # Factory Droid
# graphify install --platform trae
# graphify install --platform cursor
# graphify install --platform gemini

# Для Windows, если возникают проблемы, явно укажите платформу:
graphify install --platform windows

После завершения установки ваш AI-ассистент распознает команду /graphify.

Шаг 2 — Первый запуск: генерация карты знаний

Перейдите в любую директорию с кодом, который хотите проанализировать, и запустите:

# анализ текущей директории
/graphify .

# анализ указанной директории
/graphify ./src

# анализ указанной директории и включение более агрессивного режима вывода
/graphify ./src --mode deep

# пропустить HTML-визуализацию, сделать только отчёт и JSON (быстрее)
/graphify ./src --no-viz

graphify проходит три этапа:

1. Извлечение AST (без LLM) — используем tree-sitter для парсинга файлов кода, извлекаем классы, функции, зависимости импортов, граф вызовов, docstring и поясняющие комментарии
2. Семантическое извлечение (вызов LLM) — для документов, статей, изображений и т.п. вызываем Claude, извлекаем понятия, отношения и дизайнерские мотивы
3. Построение графа и кластеризация — объединяем все результаты извлечения и кластеризуем с помощью алгоритма обнаружения сообществ Leiden (по плотности рёбер, embeddings не нужны)

После завершения в каталоге graphify-out/ появятся три артефакта:

ls graphify-out/
# graph.json  GRAPH_REPORT.md  graph.html  cache/

Шаг 3 — Как использовать три артефакта

graphify-out/graph.json — основа персистентной карты

Это ключевой компонент всей системы. Формат — стандартный экспорт NetworkX в JSON:

{
  "nodes": [
    {
      "id": "DigestAuth",
      "label": "DigestAuth",
      "source_file": "src/auth.py",
      "source_location": "L42",
      "community": "auth"
    }
  ],
  "edges": [
    {
      "source": "DigestAuth",
      "target": "Response",
      "relation": "imports",
      "confidence": "EXTRACTED",
      "confidence_score": 1.0
    },
    {
      "source": "Attention",
      "target": "Adam",
      "relation": "semantically_similar_to",
      "confidence": "INFERRED",
      "confidence_score": 0.87
    }
  ]
}

У каждого ребра есть метка confidence:

• EXTRACTED: связь напрямую присутствует в исходном коде (уверенность 1.0)
• INFERRED: разумный вывод, с confidence_score (0.0–1.0)
• AMBIGUOUS: неопределённая связь; она будет помечена в отчёте для ручной проверки

graphify-out/GRAPH_REPORT.md — структурированный аналитический отчёт

Это краткий обзор для AI-ассистента, включает:

• God Nodes: основные концепции с наибольшей степенью (через них проходит все остальное)
• Surprising Connections: неожиданные связи между файлами/типами с объяснением «почему»
• Suggested Questions: 4–5 вопросов, на которые карта может дать уникально точный ответ
• Design Rationale: дизайнерские мотивы, извлечённые из docstring и комментариев (# NOTE:、# WHY:、# HACK:)

graphify-out/graph.html — интерактивная карта

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

Шаг 4 — Запросы к карте: три команды

Одной карты недостаточно — нужно уметь её искать. В graphify встроены три команды запросов:

query — семантический запрос

# самое частое: найти узлы и пути, связанные с вопросом в карте
graphify query "what connects Attention to the optimizer?"

# ограничение бюджета токенов
graphify query "show the auth flow" --budget 1500

# отслеживание конкретного пути через DFS (а не случайную выборку)
graphify query "what connects DigestAuth to Response?" --dfs

# указать не стандартный путь к карте
graphify query "..." --graph path/to/another-graph.json

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

Use this graph query output to answer the question. Prefer the graph
structure over guessing, and cite the source files when possible.

path — путь между двумя узлами

# восстановить полный путь от узла A к узлу B
graphify path "DigestAuth" "Response"

explain — контекст для одного узла

# показать соседей узла, его сообщество и связанные рёбра
graphify explain "SwinTransformer"

Шаг 5 — Интеграция Always-On Hook (рекомендуется)

Каждый раз вручную вводить /graphify — немного утомительно. graphify умеет автоматически внедрять знания карты в контекст диалога AI-ассистента, чтобы при каждом вашем вопросе он в первую очередь смотрел карту, а не слепо искал по файлам.

Claude Code

graphify claude install

Он делает две вещи: записывает фрагмент правил в CLAUDE.md (чтобы Claude читал GRAPH_REPORT.md) и устанавливает PreToolUse hook в settings.json, чтобы перед каждым вызовом Glob и Grep внедрять подсказку карты:

graphify: Knowledge graph exists. Read GRAPH_REPORT.md for god nodes
and community structure before searching raw files.

OpenClaw / Aider / Trae и др.

Эти платформы не поддерживают tool hooks, поэтому используйте AGENTS.md:

graphify claw install   # OpenClaw
graphify aider install  # Aider
graphify trae install   # Trae

Cursor

graphify cursor install

Он записывает .cursor/rules/graphify.mdc и задаёт alwaysApply: true, так что Cursor будет подгружать правила автоматически в каждом диалоге.

Удаление выполняется соответствующей командой uninstall:

graphify claude uninstall
graphify cursor uninstall
# ...

Шаг 6 — Инкрементальные обновления: больше не пересобирать полностью

Кодовая база каждый день меняется, полная пересборка слишком медленная. graphify предлагает два механизма инкрементальных обновлений:

--update: инкрементальное извлечение на основе SHA256 cache

# обрабатывать только изменившиеся файлы и объединять с уже существующей картой
/graphify ./src --update

В каталоге cache/ по хешу содержимого файла хранятся результаты последней обработки. graphify сравнивает хеши файлов: только изменившиеся файлы заново проходят этапы извлечения AST и LLM.

--watch: автоматическое отслеживание изменений файлов

# запуск в фоне: как только сохраняете файлы с кодом — сразу перестраивается AST
/graphify ./src --watch

# при изменении документов/изображений он подскажет запустить --update вручную

Перестроение AST, вызванное изменениями кода, чисто AST — это очень быстро и не требует вызова LLM. А вот изменения документов и изображений по-прежнему требуют LLM, поэтому при watch он уведомит вас запускать --update.

Шаг 7 — git hooks: пересборка карты при каждом commit

Не хотите запускать вручную и не хотите держать фоновые процессы? Тогда возложите пересборку карты на сам git:

graphify hook install

Он запишет два хука в .git/hooks/: post-commit и post-checkout. Каждый раз при commit или переключении ветки git автоматически запустит пересборку карты. Если пересборка не удалась (ошибка AST, таймаут LLM и т.п.), хук завершится с ненулевым кодом и прервёт git-операцию, чтобы не было тихих провалов.

Проверить состояние и удалить:

graphify hook status
graphify hook uninstall

Шаг 8 — Продвинутое использование

MCP Server: доступ к карте «как у AI»

Если ваш AI-ассистент поддерживает протокол MCP, можно выставить карту как MCP-инструмент:

python -m graphify.serve graphify-out/graph.json

На выходе будет конфигурация MCP stdio: просто вставьте её в настройки MCP вашего AI-ассистента. Экспортированные инструменты включают:

• query_graph: семантический запрос к подграфу
• get_node: получение деталей узла
• get_neighbors: получение соседей узла
• shortest_path: поиск кратчайшего пути между двумя узлами

Экспорт в Neo4j

Хотите импортировать карту в Neo4j для более продвинутого граф-анализа?

# генерировать Cypher-скрипт (ручной импорт)
/graphify ./src --neo4j

# или сразу отправить в запущенный Neo4j
/graphify ./src --neo4j-push bolt://localhost:7687

Генерация Wiki, читаемой агентами

# экспортировать в Markdown-вики: AI-агент сможет навигировать по базе, читая файлы
/graphify ./src --wiki

Будут сгенерированы graphify-out/wiki/index.md (входная точка) + отдельная Markdown-статья для каждого сообщества и для каждого god node.

Поддерживаемые типы файлов (обзор)

Указание других провайдеров LLM

graphify по умолчанию использует встроенные на вашей платформе модели (Claude Code — Anthropic, Codex — OpenAI). Если вы хотите принудительно использовать другие модели, можно задать их через переменные окружения (см. соответствующий файл skill.md).

Частые проблемы и способы устранения

1. После установки команда graphify не находится

Обычно это проблема Python-окружения или PATH:

# проверить место установки пакета
pip show graphifyy

# вызвать через python -m (не зависит от PATH)
python -m graphify --help

# или поставить через pipx (рекомендуется для изоляции)
pip install pipx && pipx install graphifyy

2. Узлов в карте очень мало или почти нет

Проверьте, не исключает ли .graphifyignore целевые файлы по ошибке:

# посмотреть, какие файлы реально сканирует graphify
/graphify ./src --no-viz  # с --no-viz запускается только AST, без LLM — быстро

# проверить синтаксис .graphifyignore (он полностью как у .gitignore)
cat .graphifyignore

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

3. Таймаут на этапе LLM извлечения или ошибки API

Проблемы сети или неверная настройка API Key:

# убедиться, что API Key существует (обычно у пользователей Claude Code всё настраивается автоматически)
# для других платформ проверьте переменные окружения с API Key

# ограничьте токены через --budget, чтобы запрос не был слишком большим
/graphify ./src --budget 2000

# после таймаута принудительно пропустить и продолжить обработку других файлов (не блокирует весь запуск)

4. cache приводит к несоответствию после инкрементального обновления

Повреждение SHA256 cache или изменение файлов извне:

# очистить cache и принудительно пересобрать всё
rm -rf graphify-out/cache
/graphify ./src

# или очистить cache только для конкретных файлов
rm graphify-out/cache/<соответствующий хеш>.json
/graphify ./src --update

5. Hook Claude Code PreToolUse не срабатывает

Чаще всего это ошибка пути или формата в settings.json:

# проверить, что hooks действительно записались
cat ~/.claude/settings.json | grep graphify

# если IDE поменяла формат — добавьте часть с graphify hook вручную
# смотрите формат PreToolUse hook в graphify skill.md

6. --watch сообщает, что отсутствует watchdog

watchdog — необязательная зависимость:

pip install graphifyy[watch]

Дальнейшее чтение / направления для углубления

1. Пользовательский Extractor: добавление поддержки нового языка

Если в вашем репозитории используется язык, который graphify пока не поддерживает (например, Racket или Nim), можно добавить в extract.py новую функцию extract_<lang>. Она должна парсить AST через tree-sitter и следовать секции «Adding a new language extractor» в ARCHITECTURE.md. Процесс понятный: написать функцию → зарегистрировать суффиксы → добавить зависимости → написать тесты.

2. Pipeline GraphRAG: подключаем запросы к карте в RAG

graphify ценен тем, что при каждом запросе не нужно заново читать исходные файлы: токены тратятся не как O(n×размер файлов), а как O(размер подграфа). При интеграции с RAG Pipeline рекомендуемый способ подключения:

import json

# 1. Сначала определить высокоуровневый замысел через GRAPH_REPORT.md
# 2. Затем подтянуть релевантный подграф с помощью graphify query
# 3. Подать подграф как контекст в LLM

with open("graphify-out/graph.json") as f:
    graph = json.load(f)

# graph["nodes"] и graph["edges"] — это и есть контекст

3. Penpax: видение цифрового двойника на устройстве от автора graphify

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

4. Мультимодальное расширение: превращаем видеокурсы в карту

Если у вас есть tech-лекции, конференционные видео или аудиоподкасты, можно добавить их в карту знаний через зависимость --video:

pip install 'graphifyy[video]'
/graphify ./corpus --whisper-model medium

Whisper работает локально, а аудио не покидает вашу машину. Результаты транскрибации кэшируются в graphify-out/transcripts/, при повторных запусках они считываются из кэша.

5. Сотрудничество по картам: командный общий формат знаний

graphify генерирует артефакты ( graph.json, GRAPH_REPORT.md ), которые представляют собой чистый текст — их можно закоммитить в git. После того как участники команды pull’нут обновления, graphify hook install автоматически переиспользует ту же самую карту. Это означает, что архитектурные знания можно версионировать: при code review можно ссылаться на узлы карты, а в описании PR — прямо указывать god nodes. В итоге понимание знаний команды перестаёт зависеть от того, «кто у кого спрашивает».