# GEMINI.md spiega a Gemini le tue regole. Non il tuo codice.

Canonical source: https://maguyva.ai/it/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 stabilisce il contesto di lavoro. MCP permette a Gemini di accedere agli strumenti. Maguyva è il server MCP che dà a Gemini una mappa consultabile del tuo repo, così la prima modifica non è un'ipotesi sulla struttura dei file.

> GEMINI.md è il contesto. MCP è il canale. Maguyva è la mappa.

## Lo stack a livelli

Quattro idee. Ognuna ha un compito.

### GEMINI.md

Come Gemini dovrebbe comportarsi in questo repo.

### MCP

Come Gemini accede a strumenti e contesto esterni.

### Maguyva

Il server MCP che restituisce fatti fondati sul repo.

### Workspace, non utenti

Gli agenti non comportano costi per utente. [Vedi i prezzi](https://maguyva.ai/it/pricing)

## GEMINI.md è un contesto di lavoro. Usalo.

Le istruzioni persistenti vanno in `GEMINI.md`. È il posto giusto per:

- Comandi di build, test e lint che Gemini dovrebbe eseguire.
- Regole del tipo “fai sempre X / non fare mai Y” valide per una specifica directory.
- Convenzioni di denominazione e preferenze di refactoring.
- Riferimenti ai log delle decisioni canoniche e alle note di architettura.

Tienilo conciso. Delimitane l'ambito. Salvalo in un commit.

Ma `GEMINI.md` non è mai stato pensato per essere un indice consultabile di ogni simbolo, file e punto di chiamata nel tuo repo.

## Dove GEMINI.md da solo non basta più

Quattro modalità di fallimento, una per scheda.

### // il contesto non è un indice

Dire a Gemini *come lavorare* non gli dice *cosa esiste*. La prima modifica su un pacchetto sconosciuto è un'ipotesi su percorsi dei file e nomi delle funzioni. GEMINI.md non può elencare ogni simbolo, e non lo vorresti comunque.

### // il documento si allontana dal codice

Un blocco di GEMINI.md che descrive la topologia delle tue code è corretto finché qualcuno non introduce un nuovo consumer. Ora il codice è la fonte di verità e il documento è sicuro di sé ma obsoleto. Gemini legge quello sbagliato.

### // rinominare è un problema di grafo

“Cosa fa riferimento a questa classe?” non ha risposta in un file markdown. Gemini fa grep e prega in tutto il monorepo, oppure ti chiede di incollare i punti di chiamata nella chat.

### // le finestre di contesto non sono gratis

Una finestra grande non equivale a un indice consultabile. Caricare GEMINI.md finché Gemini “ne sa abbastanza” scambia comunque budget di ragionamento con volume di contesto statico.

## Come si incastrano i tre livelli

Gli utenti di Gemini pensano già in questi termini. La pagina dovrebbe renderlo evidente.

- **GEMINI.md**: contesto (come si comporta Gemini)
- **MCP**: il canale (come accede)
- **Maguyva**: fatti sul codebase (cosa vede)

- **GEMINI.md**: come Gemini si comporta in questo repo.
- **MCP**: come Gemini accede a strumenti e contesto. [(specifica)](https://modelcontextprotocol.io/docs/getting-started/intro)
- **Maguyva**: cosa vede Gemini quando fa una domanda al codebase. Ricerca semantica, AST, a grafo e testuale, restituita con percorsi di file e numeri di riga.

> GEMINI.md dice a Gemini *come lavorare*.
> Maguyva dà a Gemini *qualcosa da cui partire*.

## Tre flussi di lavoro

Specifici per Gemini. Basati sul grafo di chiamate reale, non sul grep di Gemini.

### 01. Rinomina una classe condivisa, trova prima tutto ciò che ne dipende

```text
gemini> rinomina PaymentClient → BillingClient

graph::callers(PaymentClient)            12 riferimenti in 7 pacchetti
graph::importers(src/payments/client.ts)  9 moduli che lo importano
graph::extends(PaymentClient)             2 sottoclassi (RetryClient, MockClient)

→ Gemini propone una migrazione di 21 modifiche con l'elenco dei file inline.
[exit 0]
```

Gemini chiede a Maguyva tutto ciò che dipende dalla classe *prima* di iniziare a modificare. L'elenco delle modifiche da apportare si basa sul grafo reale, non sul ricordo di Gemini.

### 02. Trova l'implementazione reale, non lo stub di test

```text
gemini> come gestisce normalizePhoneNumber il formato E.164?

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

I nomi mentono. I mock oscurano il codice reale. Maguyva classifica l'implementazione reale sopra il mock di test.

### 03. Controlla il raggio d'impatto prima di un refactoring

```text
gemini> cosa chiama QueueDispatcher.publish?

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

I punti di chiamata tra pacchetti emergono inline. Il diff si basa sui moduli che effettuano davvero gli import, non sul grep di Gemini.

## Configurazione in Gemini CLI

Tre passaggi. Piano Free: 3 repository, Fino a 50K righe di repository indicizzate, senza carta di credito.

### 01. Indicizza un repo su maguyva.ai

Scegline uno che conosci bene, così puoi verificare le risposte.

### 02. Aggiungi Maguyva come server MCP nelle impostazioni di Gemini CLI

`~/.gemini/settings.json`

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

### 03. Fai una domanda di cui conosci già la risposta

Non iniziare con tutta la tua azienda. Inizia con un repo e una domanda verificabile.

## Indicizza un repo che già conosci.

Collega Gemini via MCP. Fai una domanda di cui puoi verificare la risposta.