---
name: ragraf-core
description: Работа с индексом RAGRAF через плагин Claude Code — графово-векторным индексом кода. Загружать, когда нужен факт о коде проекта вместо чтения файлов (где определено, кто вызывает, что сломается, что в таблице, где запись), когда индекс отвечает устаревшими данными или capability=degraded.
---

# RAGRAF в Claude Code

RAGRAF держит локальный индекс кода: дерево символов, граф вызовов, полнотекстовый
поиск, векторы и схему БД из миграций. Факт приходит со ссылкой `файл:строка` —
в отличие от чтения файлов целиком, которое тратит контекст и не даёт
доказательства. Индекс лежит на машине, код никуда не отправляется.

**Имена инструментов.** Плагин ставит MCP-сервер под своим именем, поэтому
полное имя выглядит так: `mcp__plugin_ragraf_ragraf__ragraf_search`,
`mcp__plugin_ragraf_ragraf__ragraf_ensure`, `mcp__plugin_ragraf_ragraf__ragraf_symbol`
и так далее. Ниже — короткая часть имени (`ensure`, `search`), но вызывать нужно
полное: короткое имя не разрешится.

## 1. Порядок работы

1. **Первый шаг задачи о коде — `mcp__plugin_ragraf_ragraf__ragraf_ensure`.** Он
   сверяет контрольную сумму корпуса с проиндексированной и сам пересобирает
   отставший индекс. `status`: `actual` — актуален, `reindexed` — пересобран
   только что, `created` — корпуса не было, `not_a_project` — каталог не похож
   на проект, `error` — причина в `reason`.
2. **`mcp__plugin_ragraf_ragraf__ragraf_context`** — если непонятно, о каком
   проекте отвечает сервер: он называет корпус, основание выбора, корень,
   ревизию, свежесть и режим.
3. **Факт берётся из индекса, а не из головы:** `search` (несколько запросов
   сразу), `symbol`, `callers`, `impact`, `code` — и в ответе должна быть ссылка
   `файл:строка`. Файловый поиск (`grep`, `rg`, `Grep`) — только после того, как
   индекс не дал ответа, и с указанием причины «индекс не нашёл X».
4. **Перед написанием SQL — `write_check`**, перед правкой прав —
   `policy_trace`, перед правкой стилей — `class_usage`.
5. **После правок кода — снова `ensure`.** `stale: true` означает, что код ушёл
   вперёд индекса: выводы по устаревшим фактам делать нельзя.

## 2. Когда индексу нельзя верить

* `stale=true` или `capability=degraded` — сказать прямо, чего не хватает
  (граф свойств кода, слой документов, живая база), и не выдавать догадку за факт.
* `found=false` — это «не найдено», а не ошибка: переформулировать запрос или
  сказать, что в индексе такого нет.
* Корпус не выбран — `catalog`, затем `use_project` с именем разработки.
* Инструментов `mcp__plugin_ragraf_ragraf__*` нет вовсе — работать чтением файлов
  и сказать, что факты НЕ подтверждены индексом.

## 3. Что делает плагин, кроме сервера

Гейт использования индекса активен по умолчанию в режиме `warn`: перед файловым
поиском и чтением приходит подсказка, а не запрет. Строгие режимы включаются
переменной `RAGRAF_GATE_MODE=ask|deny|off`. Первый запрос сеанса становится
меткой задачи — отчёт по ней даёт `mcp__plugin_ragraf_ragraf__ragraf_task_stats`.

## 4. Секреты и git

Пароль, токен или ключ не печатать и не хардкодить: значение ищется в хранилище
RAGRAF (`secrets list` → `show` → `reveal --reason`), а встреченный секрет
сохраняется копией под новым именем, не перезаписью.

`.ragraf/` — машинно-локальный индекс: строка `.ragraf/` в корневом `.gitignore`,
проверка `git check-ignore -v .ragraf`. Резервные копии файлов — в `.ragraf/` или
вне корпуса: копия рядом с рабочим файлом сдвигает контрольную сумму корпуса.

## 5. Полный справочник

Операции и их параметры — `reference/operations.md`, восстановление сломанного
индекса — `reference/repair.md` (оба файла идут с плагином).