# GEMINI.md przekazuje Gemini Twoje reguły. Nie Twój kod.

Canonical source: https://maguyva.ai/pl/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 ustala kontekst roboczy. MCP pozwala Gemini sięgać po narzędzia. Maguyva to serwer MCP, który daje Gemini przeszukiwalną mapę Twojego repo, więc pierwsza edycja nie jest zgadywaniem struktury plików.

> GEMINI.md to kontekst. MCP to kanał. Maguyva to mapa.

## Warstwowy stos

Cztery idee. Każda pełni jedną funkcję.

### GEMINI.md

Jak Gemini powinien się zachowywać w tym repo.

### MCP

Jak Gemini sięga po zewnętrzne narzędzia i kontekst.

### Maguyva

Serwer MCP, który zwraca fakty potwierdzone w kodzie repo.

### Workspace'y, nie użytkownicy

Bez osobnych opłat za każdego agenta. [Zobacz cennik](https://maguyva.ai/pl/pricing)

## GEMINI.md to kontekst roboczy. Korzystaj z niego.

Trwałe instrukcje należą do `GEMINI.md`. To dobre miejsce na:

- Komendy budowania, testów i lintowania, które powinien uruchamiać Gemini.
- Zabezpieczenia typu “zawsze rób X / nigdy nie rób Y” ograniczone do katalogu.
- Konwencje nazewnictwa i preferencje refaktoryzacji.
- Odnośniki do kanonicznych logów decyzji i notatek architektonicznych.

Trzymaj to zwięźle. Ogranicz zakres. Commituj.

Ale `GEMINI.md` nigdy nie miał być przeszukiwalnym indeksem każdego symbolu, pliku i miejsca wywołania w Twoim repo.

## Gdzie sam GEMINI.md się wyczerpuje

Cztery tryby awarii, po jednym na kartę.

### // kontekst to nie indeks

Powiedzenie Gemini *jak pracować* nie mówi mu, *co istnieje*. Pierwsza edycja w nieznanym pakiecie to zgadywanie ścieżek plików i nazw funkcji. GEMINI.md nie może wymienić każdego symbolu i wcale byś tego nie chciał.

### // dokument odbiega od kodu

Blok GEMINI.md opisujący topologię Twojej kolejki jest poprawny, dopóki ktoś nie wprowadzi nowego konsumenta. Kod jest teraz źródłem prawdy, a dokument jest pewny siebie i nieaktualny. Gemini czyta ten zły.

### // zmiana nazwy to problem grafowy

Na pytanie „Co odwołuje się do tej klasy?” nie da się odpowiedzieć na podstawie pliku markdown. Gemini albo grep-uje i się modli po całym monorepo, albo prosi Cię o wklejenie miejsc wywołań do czatu.

### // okna kontekstu nie są darmowe

Duże okno to nie to samo co przeszukiwalny indeks. Ładowanie GEMINI.md, aż Gemini „wie wystarczająco dużo”, i tak zamienia budżet na wnioskowanie na objętość statycznego kontekstu.

## Jak te trzy warstwy się łączą

Użytkownicy Gemini już myślą w tych kategoriach. Strona powinna to uwidocznić.

- **GEMINI.md**: kontekst (jak zachowuje się Gemini)
- **MCP**: kanał (jak sięga)
- **Maguyva**: fakty o kodzie (co widzi)

- **GEMINI.md**: jak Gemini zachowuje się w tym repo.
- **MCP**: jak Gemini sięga po narzędzia i kontekst. [(specyfikacja)](https://modelcontextprotocol.io/docs/getting-started/intro)
- **Maguyva**: co widzi Gemini, gdy zadaje bazie kodu pytanie. Wyszukiwanie semantyczne, AST, grafowe i tekstowe zwracane ze ścieżkami plików i numerami linii.

> GEMINI.md mówi Gemini *jak pracować*.
> Maguyva daje Gemini *coś, od czego może zacząć*.

## Trzy przepływy pracy

Specyficzne dla Gemini. Ugruntowane na rzeczywistym grafie wywołań, a nie na grep Gemini.

### 01. Zmień nazwę współdzielonej klasy, najpierw znajdź wszystkie zależne elementy

```text
gemini> zmień nazwę PaymentClient → BillingClient

graph::callers(PaymentClient)            12 odwołań w 7 pakietach
graph::importers(src/payments/client.ts)  9 plików importujących ten kod
graph::extends(PaymentClient)             2 podklasy (RetryClient, MockClient)

→ Gemini proponuje migrację z 21 edycjami wraz z listą plików od razu.
[exit 0]
```

Gemini pyta Maguyva o elementy zależne od tej klasy *zanim* zacznie edytować. Lista migracji wraca ugruntowana w rzeczywistym grafie, a nie w pamięci Gemini.

### 02. Znajdź prawdziwą implementację, nie atrapę testową

```text
gemini> jak normalizePhoneNumber obsługuje E.164?

semantic::query("normalize phone E.164")
  src/util/phone.ts:88   normalizePhoneNumber()   ← prawdziwa impl.
  test/util/phone.spec.ts:14  jest.mock(...)      ← atrapa
[exit 0]
```

Nazwy kłamią. Atrapy przesłaniają prawdziwy kod. Maguyva stawia prawdziwą implementację wyżej niż atrapę testową.

### 03. Sprawdź zasięg wpływu przed refaktoryzacją

```text
gemini> co wywołuje QueueDispatcher.publish?

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

Miejsca wywołań między pakietami pojawiają się od razu. Diff opiera się na rzeczywistych elementach importujących ten kod, a nie na wynikach grepa w Gemini.

## Konfiguracja w Gemini CLI

Trzy kroki. Plan Free: 3 repozytoria, Do 50 tys. zindeksowanych linii repo, bez karty kredytowej.

### 01. Zaindeksuj repo na maguyva.ai

Wybierz repo, które dobrze znasz, żeby móc zweryfikować odpowiedzi.

### 02. Dodaj Maguyva jako serwer MCP w ustawieniach Gemini CLI

`~/.gemini/settings.json`

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

### 03. Zadaj jedno pytanie, na które już znasz odpowiedź

Nie zaczynaj od całej firmy. Zacznij od jednego repo i jednego sprawdzalnego pytania.

## Zaindeksuj jedno repo, które już znasz.

Podłącz Gemini przez MCP. Zadaj jedno pytanie, którego odpowiedź możesz zweryfikować.