// contesto
GEMINI.md
Come Gemini dovrebbe comportarsi in questo repo.
Per gli utenti di Gemini CLI
GEMINI.md dice a Gemini le tue regole.
Non il tuo codice.
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.
Piano Free: 3 repository, Fino a 50K righe di repository indicizzate, senza carta.
GEMINI.md è il contesto. MCP è il canale. Maguyva è la mappa.Lo stack a livelli
Quattro idee. Ognuna fa un lavoro.
// trasporto
MCP
Come Gemini accede a strumenti e contesto esterni.
// codebase
Maguyva
Il server MCP che restituisce fatti fondati sul repo.
// chi paga
Workspace, non postazioni
Gli agenti non pagano postazioni. Vedi i prezzi
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” con ambito su una directory.
- Convenzioni di denominazione e preferenze di refactoring.
- Riferimenti ai log delle decisioni canoniche e alle note di architettura.
Tienilo conciso. Delimitane l'ambito. Fanne 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)
- 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
Specifico per Gemini. Fondato sul grafo di chiamate reale, non sul grep di Gemini.
// workflow 01
Rinomina una classe condivisa, trova prima ogni dipendente
gemini> rinomina PaymentClient → BillingClient graph::callers(PaymentClient) 12 riferimenti in 7 pacchetti graph::importers(src/payments/client.ts) 9 importatori 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 i dipendenti prima di iniziare a modificare. L'elenco di migrazione torna fondato sul grafo reale, non sul ricordo di Gemini.
// workflow 02
Trova l'implementazione reale, non lo stub di test
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.
// workflow 03
Controlla il raggio d'impatto prima di un refactoring
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 è fondato su importatori reali, non sul grep di Gemini.
Configurazione in Gemini CLI
Tre passaggi. Piano Free: 3 repository, Fino a 50K righe di repository indicizzate, senza carta.
// step 01
Indicizza un repo su maguyva.ai
Scegline uno che conosci bene, così puoi verificare le risposte.
// step 02
Aggiungi Maguyva come server MCP nelle impostazioni di Gemini CLI
// ~/.gemini/settings.json { "mcpServers": { "maguyva": { "httpUrl": "https://maguyva.tools/mcp", "headers": { "Authorization": "Bearer <your-key>" } } } }// step 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.