# GEMINI.md каже Gemini ваші правила. Але не ваш код.

Canonical source: https://maguyva.ai/uk/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/uk/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 in src/billing/*    1 in src/audit/*    1 in src/notifications/*
[exit 0]
```

Місця виклику з різних пакетів з'являються прямо в результаті. Diff обґрунтований реальними імпортерами, а не 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. Поставте одне запитання, відповідь на яке можна підтвердити.