Как дать агенту карту проекта через Graphify

Где взять

Когда это нужно

• Проект уже больше пары файлов, и агент каждый раз заново ищет, где что лежит.
• Claude Code, Codex или Cursor тратит контекст на перечитывание структуры вместо решения задачи.
• В кодовой базе много связей: сервисы, роуты, модели, схемы, документы, тесты.
• Нужно быстро понять, какие файлы, функции и концепты связаны между собой.
• Хочется перед сложной правкой сначала дать агенту карту проекта, а уже потом просить код.

Как установить

• Проверь, что установлен Python 3.10+.
• Поставь Graphify из официального пакета graphifyy.
• Зарегистрируй skill для своего ассистента командой graphify install.
• Если работаешь в Codex, используй установку под Codex или проектную установку.
• Если команда graphify не находится, обнови shell PATH или запусти через uvx --from graphifyy.

uv tool install graphifyy
graphify install

# проектная установка
graphify install --project
graphify install --project --platform codex

# если команда graphify не находится
uv tool update-shell
uvx --from graphifyy graphify install

Первый прогон проекта

• Открой терминал в корне проекта.
• Запусти построение графа для текущей папки.
• Дождись папки graphify-out.
• Открой graph.html, чтобы глазами проверить карту.
• Прочитай GRAPH_REPORT.md: там ключевые концепты, связи и вопросы по проекту.
• Сохрани graph.json: это база, по которой агент сможет отвечать без полного перечитывания файлов.

graphify .

# что должно появиться
graphify-out/
  graph.html
  GRAPH_REPORT.md
  graph.json

Как пользоваться с агентом

• Перед большой задачей попроси агента сначала изучить GRAPH_REPORT.md.
• Для вопроса по архитектуре проси не читать весь проект, а сначала найти нужные узлы в графе.
• После крупной правки обновляй граф, иначе агент будет работать по старой карте.
• Используй graphify explain, когда нужно понять конкретный модуль, класс, роут или сущность.
• Используй graphify path, когда нужно понять связь между двумя частями системы.

graphify explain "APIRouter"
graphify path "FastAPI" "ModelField"
graphify query "где в проекте создаётся пользователь и какие модули это используют?"

Что проверить после установки

• Агент ссылается на конкретные узлы, модули и связи, а не просто угадывает по названиям файлов.
• Повторный вопрос по проекту не заставляет его заново читать десятки файлов.
• В GRAPH_REPORT.md есть понятные концепты, а не пустой список файлов.
• В graph.html можно кликать по узлам, искать и фильтровать карту.
• После обновления проекта граф пересобирается без ошибок.

Когда не надо ставить

Смысл Graphify не в красивой картинке. Смысл в том, чтобы агент тратил контекст на решение, а не на вечное знакомство с проектом заново.