// contexto
GEMINI.md
Como o Gemini deve se comportar nesse repositório.
Para usuários do Gemini CLI
O GEMINI.md diz ao Gemini as suas regras.
Não o seu código.
O GEMINI.md define o contexto de trabalho. O MCP permite que o Gemini acesse ferramentas. O Maguyva é o servidor MCP que dá ao Gemini um mapa consultável do seu repositório, para que a primeira edição não seja um chute sobre a estrutura de arquivos.
Plano Free: 3 repositórios, Até 50 mil linhas de repositório indexadas, sem cartão.
O GEMINI.md é o contexto. O MCP é o canal. O Maguyva é o mapa.A stack em camadas
Quatro ideias. Cada uma com uma função.
// transporte
MCP
Como o Gemini acessa ferramentas externas e contexto.
// codebase
Maguyva
O servidor MCP que retorna fatos fundamentados do repositório.
// quem paga
Workspaces, não assentos
Agentes não pagam assento. Ver preços
O GEMINI.md é um contexto de trabalho. Use-o.
Instruções persistentes pertencem ao GEMINI.md. É o lugar certo para:
- Comandos de build, test e lint que o Gemini deve rodar.
- Guardrails do tipo “sempre faça X / nunca faça Y” restritos a um diretório.
- Convenções de nomenclatura e preferências de refatoração.
- Referências para os registros de decisão canônicos e notas de arquitetura.
Mantenha conciso. Delimite o escopo. Faça commit.
Mas o GEMINI.md nunca foi feito para ser um índice consultável de cada símbolo, arquivo e call site do seu repositório.
Onde o GEMINI.md sozinho se esgota
Quatro modos de falha, um por card.
// contexto não é um índice
Dizer ao Gemini como trabalhar não diz a ele o que existe. A primeira edição num pacote desconhecido é um chute sobre caminhos de arquivo e nomes de função. O GEMINI.md não consegue listar cada símbolo, e você nem ia querer isso.
// o doc se desatualiza em relação ao código
Um bloco do GEMINI.md descrevendo a topologia da sua fila está certo até alguém introduzir um novo consumidor. Agora o código é a fonte da verdade e o doc está confiantemente desatualizado. O Gemini lê o errado.
// renomear é um problema de grafo
“O que referencia essa classe?” não tem resposta num arquivo markdown. O Gemini ou faz grep-and-pray no monorepo inteiro ou pede para você colar os call sites no chat.
// janelas de contexto não são de graça
Uma janela grande não é o mesmo que um índice consultável. Carregar o GEMINI.md até o Gemini “saber o suficiente” ainda assim troca orçamento de raciocínio por volume de contexto estático.
Como as três camadas se encaixam
Usuários do Gemini já pensam nesse formato. A página deveria deixar isso óbvio.
GEMINI.md
contexto
como o Gemini se comporta
MCP
o canal
como ele acessa
Maguyva
fatos do codebase
o que ele enxerga
- GEMINI.md como o Gemini se comporta nesse repositório.
- MCP como o Gemini acessa ferramentas e contexto. (especificação)
- Maguyva o que o Gemini enxerga quando faz uma pergunta ao codebase. Busca semântica, AST, de grafo e de texto retornada com caminhos de arquivo e números de linha.
O GEMINI.md diz ao Gemini como trabalhar.
O Maguyva dá ao Gemini algo para trabalhar a partir daí.
Três fluxos de trabalho
Específico para o Gemini. Fundamentado no grafo de chamadas real, não no grep do Gemini.
// workflow 01
Renomeie uma classe compartilhada, encontre cada dependente primeiro
gemini> renomear PaymentClient → BillingClient graph::callers(PaymentClient) 12 referências em 7 pacotes graph::importers(src/payments/client.ts) 9 importadores graph::extends(PaymentClient) 2 subclasses (RetryClient, MockClient) → O Gemini propõe uma migração de 21 edições com a lista de arquivos inline. [exit 0]
O Gemini pergunta ao Maguyva pelos dependentes antes de começar a editar. A lista de migração volta fundamentada no grafo real, não na lembrança do Gemini.
// workflow 02
Encontre a implementação real, não o stub de teste
gemini> como o normalizePhoneNumber trata o 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]
Nomes mentem. Mocks fazem sombra no código real. O Maguyva ranqueia a implementação real acima do mock de teste.
// workflow 03
Confira o raio de impacto antes de uma refatoração
gemini> o que chama QueueDispatcher.publish? graph::callers(QueueDispatcher.publish) 3 em src/billing/* 1 em src/audit/* 1 em src/notifications/* [exit 0]
Call-sites entre pacotes aparecem inline. O diff é fundamentado em importadores reais, não no grep do Gemini.
Configuração no Gemini CLI
Três passos. Plano Free: 3 repositórios, Até 50 mil linhas de repositório indexadas, sem cartão.
// step 01
Indexe um repositório em maguyva.ai
Escolha um que você conheça bem, para conseguir verificar as respostas.
// step 02
Adicione o Maguyva como servidor MCP nas suas configurações do Gemini CLI
// ~/.gemini/settings.json { "mcpServers": { "maguyva": { "httpUrl": "https://maguyva.tools/mcp", "headers": { "Authorization": "Bearer <your-key>" } } } }// step 03
Faça uma pergunta cuja resposta você já saiba
Não comece com a empresa inteira. Comece com um repositório e uma pergunta verificável.