Graphify для Claude Code: превращение репозитория в граф с поддержкой запросов

Graphify Claude Code: превращаем репозиторий в граф с поддержкой запросов

В репозитории с 800,000 строками кода ответ на, казалось бы, простой вопрос может находиться в шести разных местах: в модуле Terraform, миграции базы данных, сгенерированном клиенте, документе OpenAPI, манифесте развёртывания и инструкции по эксплуатации, написанной два года назад.

Claude Code может искать и читать эти файлы, но работа в масштабе репозитория часто ограничена тем, насколько быстро агент способен обнаружить связи между ними. Текстовый поиск по customer_id находит вхождения. Он не объясняет автоматически, что:

• customer_id объявляется в миграции базы данных,
• предоставляется через схему API,
• отображается в модели ORM,
• копируется в полезную нагрузку события,
• используется фоновым обработчиком,
• и упоминается в процедуре отката в производственной среде.

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

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

Что Graphify добавляет к Claude Code

В Claude Code уже есть несколько полезных способов разобраться в проекте:

• Прямое чтение файлов
• rg и другие средства поиска в командной оболочке
• История Git и различия между версиями
• Инструкции проекта в CLAUDE.md
• Навыки для повторяемых рабочих процессов
• Серверы MCP для внешних инструментов и данных

Graphify добавляет другой способ доступа: поиск на основе связей.

Обычный поиск задаёт вопрос:

Где встречается этот символ?

Запрос к графу задаёт вопрос:

Какие сервисы зависят от этой схемы, какая инфраструктура развёртывает эти сервисы и какие документы описывают последствия для эксплуатации?

Это различие важно, когда задача затрагивает несколько зон ответственности или форматов файлов.

Типичный граф может содержать такие узлы:

Рёбра могут представлять такие связи, как:

• imports
• calls
• implements
• extends
• reads_from
• writes_to
• publishes
• consumes
• deploys
• configured_by
• documented_by
• owned_by
• depends_on

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

Установка Graphify для Claude Code

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

git clone https://github.com/Graphify-Labs/graphify.git
cd graphify

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

graphify --help
graphify version
graphify config --help

Приведённые выше команды иллюстрируют необходимые проверки; используйте исполняемый файл и подкоманды, доступные в установленном вами выпуске.

Для безопасного первого запуска выберите небольшой тестовый репозиторий:

mkdir -p /tmp/graphify-fixture
cd /tmp/graphify-fixture

git init
printf 'def charge(order):\n    return order.total\n' > billing.py
printf 'from billing import charge\n' > worker.py

graphify index .

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

• Локальный или размещённый на сервере
• Обновляемый инкрементально или полностью перестраиваемый
• Сохраняемый в базе данных, файлах или встроенном хранилище
• Безопасный для одновременной работы с другим индексатором
• Позволяющий исключать секреты, артефакты сборки и каталоги сторонних зависимостей

Для интеграции с Claude Code Graphify необходимо подключить через механизм интеграции, поддерживаемый проектом, обычно MCP. Локальный файл .mcp.json может выглядеть так:

{
  "mcpServers": {
    "graphify": {
      "command": "graphify",
      "args": ["mcp", "--project", "."],
      "env": {
        "GRAPHIFY_INDEX": ".graphify/index"
      }
    }
  }
}

Не считайте эту конкретную подкоманду универсальной. Уточните точку входа MCP с помощью:

graphify mcp --help

Затем проверьте сервер из Claude Code:

/mcp

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

Частая ошибка — запуск Claude Code из неверного каталога. Относительные пути проекта в .mcp.json, файлах исключений и конфигурации Graphify разрешаются относительно рабочего каталога процесса сервера, который не обязательно совпадает с каталогом, который вы имели в виду.

Связи, важные на практике

Граф наиболее полезен, когда показывает связи, которые трудно восстановить по тексту.

Связи между кодом и происхождением данных

Предположим, миграция переименовывает accounts.status на accounts.lifecycle_state. Текстовый поиск может выявить ссылки, а граф — систематизировать затрагиваемые компоненты:

table accounts
  -> column lifecycle_state
  -> migration 2025_04_rename_status
  -> model Account
  -> repository AccountRepository
  -> API response AccountSummary
  -> dashboard query active_accounts

Это даёт Claude Code более надёжную отправную точку для проверки миграции. После того как граф выявит вероятные зависимые компоненты, агент сможет изучить сами файлы.

Топология сервисов и инфраструктуры

Инфраструктурные связи особенно полезны в монорепозиториях, где код приложения и код развёртывания хранятся вместе:

service payments-api
  -> container image payments-api
  -> Kubernetes deployment payments
  -> reads secret PAYMENTS_DATABASE_URL
  -> writes queue payment-events
  -> consumed by reconciliation-worker

Это помогает отвечать на такие вопросы:

• Какое развёртывание нужно изменить при изменении порта?
• Кто читает сообщения из этой очереди?
• Какие сервисы используют эту базу данных совместно?
• Какая конфигурация зависит от среды?
• Какой ресурс Terraform создаёт эту зависимость?

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

Связи между документацией и реализацией

Документация часто остаётся вне поиска по коду, поскольку связь носит семантический, а не синтаксический характер. Инструкция по эксплуатации может упоминать «обработчик расчётов», тогда как в репозитории он называется reconciliation-worker.

Если Graphify связывает упоминания в документации с сущностями кода или инфраструктуры, Claude Code может отвечать на вопросы эксплуатации с меньшим объёмом ручного просмотра:

"Where is the rollback procedure for the component that consumes payment-events?"

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

Graphify, навыки и MCP — разные уровни

Graphify должен дополнять существующие механизмы расширения Claude Code, а не заменять их.

Полезная архитектура выглядит так:

1. Graphify находит потенциально значимые сущности и зависимости.
2. Claude Code использует эти результаты для выбора файлов.
3. Встроенные инструменты работы с файлами проверяют текущую реализацию.
4. Навык применяет принятую в команде процедуру проверки или внесения изменений.
5. Тесты, линтеры и проверки развёртывания дают окончательное подтверждение.

Например, навык проверки миграций может находиться в .claude/skills/review-migration/SKILL.md:

# Review Database Migration

When reviewing a migration:

1. Identify renamed, removed, or changed columns.
2. Query Graphify for code, schema, event, and infrastructure dependents.
3. Read each high-confidence dependent from the working tree.
4. Check backward compatibility for deployed application versions.
5. Run the repository migration and contract tests.
6. Report uncertain graph relationships separately from verified findings.

Навык определяет рабочий процесс. Graphify предоставляет контекст связей. MCP служит транспортом и задаёт границу взаимодействия с инструментами.

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

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

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

Начните с исключений:

# .graphifyignore
.git/
node_modules/
vendor/
dist/
build/
coverage/
tmp/
*.min.js
*.map
.env
*.pem

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

Используйте поэтапную политику индексирования:

• Индексируйте исходный код приложения, схемы, инфраструктуру и поддерживаемую документацию.
• Исключайте генерируемые результаты, если они не являются основным достоверным артефактом.
• Создавайте полный индекс в CI или в задании по расписанию.
• Обновляйте индекс ветки инкрементально, если это поддерживается.
• Сохраняйте исходный коммит рядом с метаданными графа.
• Перестраивайте индекс после изменений парсера или конфигурации.

Агент должен видеть ревизию исходного кода. Такой формат ответа гораздо безопаснее списка без уточнений:

{
  "query": "dependents of table accounts",
  "indexed_revision": "9f31a7c",
  "generated_at": "2025-05-14T10:22:11Z",
  "results": [
    {
      "entity": "AccountRepository",
      "relationship": "reads_from",
      "target": "accounts",
      "confidence": "high",
      "path": "src/accounts/repository.py"
    }
  ]
}

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

Точность, конфиденциальность и границы использования в продакшене

Граф может придать неполной информации вид достоверной. Стоит предусмотреть несколько сценариев ошибок:

• Динамические импорты и рефлексия остаются незамеченными.
• Скрипты оболочки скрывают связи за подстановкой переменных.
• Сгенерированные клиенты скрывают исходную схему.
• Ссылки в документации используют псевдонимы, которые парсер не распознаёт.
• Удалённые файлы остаются в индексе до очистки или перестроения.
• Запрос выполняется к индексу одной ветки, пока агент работает в другой.
• Инфраструктурные модули интерпретируются без значений, специфичных для среды.

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

Конфиденциальность требует не меньшего внимания. Графы репозитория могут раскрывать:

• Названия внутренних сервисов
• Модели данных клиентов и платежей
• Топологию сети
• Секреты через имена файлов или ссылки в конфигурации
• Зависимости, сведения о которых могут раскрыть уязвимости
• Закрытую документацию

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

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

• Выявляет ли он известные импорты и зависимости сервисов?
• Удаляет ли он исчезнувшие связи?
• Даёт ли инкрементальное индексирование в итоге тот же результат, что и полное перестроение с нуля?
• Могут ли пользователи отличить устаревшие результаты и результаты с низкой уверенностью?
• Сообщает ли сервер MCP понятную ошибку, когда индекс недоступен?
• Достаточно ли быстры запросы для интерактивной работы агента?
• Можно ли воспроизвести индекс в CI?

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

Практический подход к внедрению

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

Измеряйте полезные результаты, а не размер графа:

• Время выявления затронутых компонентов
• Количество зависимых компонентов, пропущенных при проверке
• Доля устаревших или неверных связей
• Время индексирования после типичных коммитов
• Сбои запросов и частота перехода к резервному режиму
• Дополнительные данные, раскрываемые модели

Используйте Sonnet 4.6 для масштабного исследования репозитория, когда важна глубина рассуждений, Haiku 4.5 — для простой классификации или повторяющихся задач поиска, а Fable 5 с более широким контекстом — когда рабочий процесс проекта с контекстом 1M действительно выигрывает от включения большого объёма подтверждающих данных. Выбор модели не исправит плохой граф. Меньшая модель с точными и актуальными связями может быть полезнее большой модели, получающей нефильтрованную выгрузку индекса.

Практический шаблон промпта — явное указание происхождения данных:

Use Graphify to identify likely dependents of the `accounts.lifecycle_state`
column. For every result, include its path, indexed revision, relationship,
and confidence. Then read the current files and discard relationships that
do not exist in the working tree. Do not treat graph results as proof.

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

Практические рекомендации

• Основная ценность Graphify — поиск связей между кодом, схемами, инфраструктурой и документацией.
• Установите инструмент с фиксированной версией, изучите его фактические команды CLI и MCP и проверьте его на тестовом примере перед индексированием монорепозитория.
• Поручите Graphify предоставление контекста репозитория, а для воспроизводимых инженерных процедур используйте навыки Claude Code.
• Включайте в ответы графа ревизию индекса, происхождение данных и степень уверенности.
• Исключайте секреты, шум от генерируемых файлов и ненужные материалы сторонних поставщиков.
• Рассматривайте результаты графа как зацепки, которые необходимо проверять по текущему рабочему дереву.
• До внедрения в продакшен проверьте инкрементальное индексирование, обработку удалений, изоляцию веток и работу в резервном режиме.
• Популярность может быть поводом для оценки, но полагаться на инструмент стоит только на основании точности и поведения при эксплуатации в вашем репозитории.