# GEMINI.md знакомит Gemini с вашими правилами. Но не с вашим кодом.

Canonical source: https://maguyva.ai/ru/for-gemini

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

GEMINI.md задаёт рабочий контекст. MCP позволяет Gemini обращаться к инструментам. Maguyva — это MCP-сервер, который даёт Gemini карту вашего репозитория с возможностью поиска, так что первая правка — не догадка о структуре файлов.

> GEMINI.md — это контекст. MCP — это канал. Maguyva — это карта.

## Многоуровневый стек

Четыре идеи. У каждой своя задача.

### GEMINI.md

Как Gemini должен вести себя в этом репозитории.

### MCP

Как Gemini обращается к внешним инструментам и контексту.

### Maguyva

MCP-сервер, который возвращает факты о репозитории, подтверждённые кодом.

### За пространство, не за пользователя

За каждого агента не взимается отдельная плата. [Смотреть тарифы](https://maguyva.ai/ru/pricing)

## GEMINI.md — это рабочий контекст. Используйте его.

Постоянные инструкции следует хранить в `GEMINI.md`. Это правильное место для:

- Команд сборки, тестирования и линтинга, которые должен запускать Gemini.
- Ограничений вида “всегда делай X / никогда не делай Y”, привязанных к директории.
- Соглашений об именовании и предпочтений по рефакторингу.
- Ссылок на канонические журналы решений и заметки об архитектуре.

Держите его кратким. Ограничивайте область применения. Коммитьте.

Но `GEMINI.md` никогда не задумывался как индекс с возможностью запроса по каждому символу, файлу и месту вызова в вашем репозитории.

## Где одного GEMINI.md перестаёт хватать

Четыре сценария сбоя, по одному на карточку.

### // контекст — это не индекс

Рассказать Gemini, *как работать*, не значит рассказать, *что существует*. Первая правка в незнакомом пакете — это догадка о путях файлов и именах функций. GEMINI.md не может перечислить каждый символ, да и не должен.

### // документ расходится с кодом

Блок в GEMINI.md, описывающий топологию ваших очередей, верен, пока кто-то не добавит нового потребителя. Теперь источник истины — код, а документ уверенно устарел. Gemini читает не тот источник.

### // переименование — это задача про граф

На вопрос «что ссылается на этот класс?» markdown-файл не ответит. Gemini либо делает grep и надеется на удачу по всему монорепозиторию, либо просит вас вставить места вызова в чат.

### // окно контекста не бесплатно

Большое окно контекста — это не то же самое, что индекс с возможностью запроса. Загрузка GEMINI.md, пока Gemini не «узнает достаточно», всё равно меняет бюджет на рассуждение на объём статичного контекста.

## Как три слоя сочетаются друг с другом

Пользователи Gemini уже мыслят в терминах этой схемы. Страница должна сделать это очевидным.

- **GEMINI.md**: контекст (как ведёт себя Gemini)
- **MCP**: канал (как он обращается)
- **Maguyva**: факты о кодовой базе (что он видит)

- **GEMINI.md**: как Gemini ведёт себя в этом репозитории.
- **MCP**: как Gemini обращается к инструментам и контексту. [(спецификация)](https://modelcontextprotocol.io/docs/getting-started/intro)
- **Maguyva**: что видит Gemini, когда задаёт вопрос кодовой базе. Семантический, AST, графовый и текстовый поиск с путями к файлам и номерами строк.

> GEMINI.md рассказывает Gemini, *как работать*.
> Maguyva даёт Gemini *то, от чего можно оттолкнуться*.

## Три сценария

Сценарии для Gemini. Они опираются на данные реального графа вызовов, а не grep'а Gemini.

### 01. Переименуйте общий класс, сначала найдя все зависимые элементы

```text
gemini> переименовать PaymentClient → BillingClient

graph::callers(PaymentClient)            12 ссылок в 7 пакетах
graph::importers(src/payments/client.ts)  9 импортирующих модулей
graph::extends(PaymentClient)             2 подкласса (RetryClient, MockClient)

→ Gemini предлагает миграцию из 21 правки со списком файлов прямо в выводе.
[exit 0]
```

Gemini спрашивает у Maguyva о зависимых элементах *перед* тем, как начать редактировать. План миграции опирается на реальный граф, а не на воспоминания Gemini.

### 02. Найдите настоящую реализацию, а не тестовую заглушку

```text
gemini> как normalizePhoneNumber обрабатывает E.164?

semantic::query("normalize phone E.164")
  src/util/phone.ts:88   normalizePhoneNumber()   ← реальная реализация
  test/util/phone.spec.ts:14  jest.mock(...)      ← заглушка
[exit 0]
```

Имена лгут. Моки заслоняют настоящий код. Maguyva ранжирует настоящую реализацию выше тестового мока.

### 03. Проверьте радиус влияния перед рефакторингом

```text
gemini> что вызывает QueueDispatcher.publish?

graph::callers(QueueDispatcher.publish)
  3 в src/billing/*    1 в src/audit/*    1 в src/notifications/*
[exit 0]
```

Места вызова между пакетами всплывают прямо в выводе. Дифф опирается на реальные связи импорта, а не на результаты grep, выполненного Gemini.

## Настройка в Gemini CLI

Три шага. Тариф Free: 3 репозитория, До 50 тыс. проиндексированных строк, без банковской карты.

### 01. Проиндексируйте репозиторий на maguyva.ai

Выберите тот, который хорошо знаете, чтобы можно было проверить ответы.

### 02. Добавьте Maguyva как MCP-сервер в настройках Gemini CLI

`~/.gemini/settings.json`

```json
{
  "mcpServers": {
    "maguyva": {
      "httpUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}
```

### 03. Задайте один вопрос, ответ на который вы уже знаете

Не начинайте сразу со всей компании. Начните с одного репозитория и одного проверяемого вопроса.

## Проиндексируйте один репозиторий, который вы уже знаете.

Подключите Gemini через MCP. Задайте один вопрос, ответ на который можно перепроверить.