// contexto
GEMINI.md
Cómo debe comportarse Gemini en este repo.
Para usuarios de Gemini CLI
GEMINI.md le dice a Gemini tus reglas.
No tu código.
GEMINI.md establece el contexto de trabajo. MCP le permite a Gemini alcanzar herramientas. Maguyva es el servidor MCP que le da a Gemini un mapa consultable de tu repo, para que la primera edición no sea una adivinanza sobre la estructura de archivos.
Nivel Free: 3 repositorios, Hasta 50 mil líneas de repo indexadas, sin tarjeta.
GEMINI.md es el contexto. MCP es el canal. Maguyva es el mapa.El stack en capas
Cuatro ideas. Cada una cumple una función.
// transporte
MCP
Cómo alcanza Gemini herramientas y contexto externos.
// codebase
Maguyva
El servidor MCP que devuelve hechos fundamentados del repo.
// quién paga
Workspaces, no asientos
Los agentes no pagan asientos. Ver precios
GEMINI.md es un contexto de trabajo. Úsalo.
Las instrucciones persistentes van en GEMINI.md. Es el lugar correcto para:
- Comandos de build, test y lint que Gemini debería ejecutar.
- Guardrails de “siempre haz X / nunca hagas Y” acotados a un directorio.
- Convenciones de nomenclatura y preferencias de refactor.
- Referencias a los registros de decisiones canónicos y notas de arquitectura.
Mantenlo conciso. Acótalo. Commitealo.
Pero GEMINI.md nunca fue pensado para ser un índice consultable de cada símbolo, archivo y punto de llamada en tu repo.
Dónde GEMINI.md solo se queda corto
Cuatro modos de falla, uno por tarjeta.
// el contexto no es un índice
Decirle a Gemini cómo trabajar no le dice qué existe. La primera edición en un paquete desconocido es una adivinanza sobre rutas de archivo y nombres de función. GEMINI.md no puede listar cada símbolo, y tampoco querrías que lo hiciera.
// el doc se desalinea del código
Un bloque de GEMINI.md que describe la topología de tus colas está bien hasta que alguien introduce un nuevo consumer. El código es ahora la fuente de verdad y el doc está confiadamente desactualizado. Gemini lee el equivocado.
// renombrar es un problema de grafo
“¿Qué referencia esta clase?” no se puede responder desde un archivo markdown. Gemini hace grep-y-reza en todo el monorepo, o te pide que pegues los puntos de llamada en el chat.
// las ventanas de contexto no son gratis
Una ventana grande no es lo mismo que un índice consultable. Cargar GEMINI.md hasta que Gemini “sepa lo suficiente” igual cambia presupuesto de razonamiento por volumen de contexto estático.
Cómo encajan las tres capas
Los usuarios de Gemini ya piensan en esta forma. La página solo debería hacerlo evidente.
GEMINI.md
contexto
cómo se comporta Gemini
MCP
el canal
cómo alcanza
Maguyva
hechos del codebase
qué ve
- GEMINI.md cómo se comporta Gemini en este repo.
- MCP cómo alcanza Gemini herramientas y contexto. (especificación)
- Maguyva qué ve Gemini cuando le hace una pregunta al codebase. Búsqueda semántica, de AST, de grafo y de texto, devuelta con rutas de archivo y números de línea.
GEMINI.md le dice a Gemini cómo trabajar.
Maguyva le da a Gemini algo desde dónde trabajar.
Tres flujos de trabajo
Específico de Gemini. Fundamentado en el grafo de llamadas real, no en el grep de Gemini.
// workflow 01
Renombra una clase compartida, encuentra primero cada dependiente
gemini> renombrar PaymentClient → BillingClient graph::callers(PaymentClient) 12 referencias en 7 paquetes graph::importers(src/payments/client.ts) 9 importadores graph::extends(PaymentClient) 2 subclases (RetryClient, MockClient) → Gemini propone una migración de 21 ediciones con la lista de archivos inline. [exit 0]
Gemini le pregunta a Maguyva por los dependientes antes de empezar a editar. La lista de migración vuelve fundamentada en el grafo real, no en el recuerdo de Gemini.
// workflow 02
Encuentra la implementación real, no el stub de prueba
gemini> ¿cómo maneja normalizePhoneNumber el formato E.164? semantic::query("normalize phone E.164") src/util/phone.ts:88 normalizePhoneNumber() ← impl real test/util/phone.spec.ts:14 jest.mock(...) ← stub [exit 0]
Los nombres mienten. Los mocks tapan el código real. Maguyva ubica la implementación real por encima del mock de prueba.
// workflow 03
Revisa el radio de impacto antes de un refactor
gemini> ¿qué llama a QueueDispatcher.publish? graph::callers(QueueDispatcher.publish) 3 en src/billing/* 1 en src/audit/* 1 en src/notifications/* [exit 0]
Los puntos de llamada entre paquetes aparecen inline. El diff está fundamentado en importadores reales, no en el grep de Gemini.
Configuración en Gemini CLI
Tres pasos. Nivel Free: 3 repositorios, Hasta 50 mil líneas de repo indexadas, sin tarjeta.
// step 01
Indexa un repo en maguyva.ai
Elige uno que conozcas bien, para poder verificar las respuestas.
// step 02
Agrega Maguyva como servidor MCP en la configuración de Gemini CLI
// ~/.gemini/settings.json { "mcpServers": { "maguyva": { "httpUrl": "https://maguyva.tools/mcp", "headers": { "Authorization": "Bearer <your-key>" } } } }// step 03
Haz una pregunta cuya respuesta ya conozcas
No empieces con toda tu empresa. Empieza con un repo y una pregunta verificable.