Um repositório começa simples quando o README explica o que o projeto faz, como rodar a aplicação e onde encontrar as referências principais. Depois entram agentes de IA, comandos de validação, regras de estilo, limites de edição e preferências recorrentes, e a comparação GEMINI.md vs README começa a afetar a manutenção da documentação.

O erro comum é colocar tudo no mesmo lugar, porque a documentação de entrada fica pesada para uma pessoa nova enquanto o agente recebe um texto público demais para orientar execução. A consequência aparece na revisão quando alguém precisa explicar de novo aquilo que deveria estar escrito no arquivo certo, com função clara e leitura adequada ao público.

Direto ao ponto

Use README para orientar pessoas e use GEMINI.md para orientar o Gemini CLI com regras persistentes de execução. Essa separação reduz ambiguidade, melhora a revisão e evita que instruções de agente poluam a documentação de entrada do repositório.

Eu trato esse tema como uma decisão de manutenção, pois cada arquivo precisa responder a uma pergunta diferente dentro do mesmo projeto. README atende quem quer entender propósito, instalação e caminhos de leitura, enquanto GEMINI.md atende o agente que precisa respeitar padrões, limites, comandos e fontes de verdade antes de editar.

Na Formação IA Makers, essa separação aparece quando o aluno começa a usar Gemini CLI, Claude Code, Codex ou outro agente de código no mesmo repositório. A ferramenta muda, mas o risco continua parecido quando a referência errada gera revisão mais cara, regra duplicada e comportamento inconsistente.

README continua sendo a porta de entrada

README deve funcionar como a primeira orientação para uma pessoa que chegou ao repositório e precisa entender o que existe ali. Ele precisa explicar o propósito do projeto, a forma básica de execução, os comandos principais, a estrutura geral e os caminhos para documentação mais detalhada.

Quando esse arquivo recebe regras internas demais para agente, a leitura humana perde clareza e a documentação deixa de cumprir sua função inicial. A pessoa que só quer rodar o projeto precisa atravessar preferências de copy, limites de edição, comandos de lint e detalhes que pertencem melhor a uma sessão de IA.

Isso permite uma seção curta sobre agentes no README, desde que ela funcione como sinalização e direcione para o arquivo correto. O problema começa quando o documento principal tenta carregar toda a regra persistente, como se fosse o único lugar autorizado para qualquer referência do repositório.

O artigo sobre documentação Markdown para IA legível aprofunda a escrita do documento em si. Aqui o recorte é mais específico, porque a decisão principal é escolher qual arquivo recebe cada tipo de referência.

GEMINI.md existe para referência persistente do agente

Na documentação oficial do Gemini CLI, GEMINI.md aparece ligado à memória hierárquica e aos comandos /memory, o que muda a função do arquivo dentro do fluxo de trabalho. Ele participa da referência instrucional que o agente pode carregar antes de agir, em vez de ser apenas mais um Markdown explicativo para leitura humana.

Por isso, eu escreveria GEMINI.md de forma mais direta do que um README, com regras verificáveis e pouca tentativa de apresentação. O arquivo deve dizer quais fontes consultar, que comandos rodar, quais limites respeitar, como tratar mudanças sensíveis e quais padrões sustentam a revisão.

Um bom arquivo de instrução para agente precisa reduzir escolha ambígua durante a execução. Se a regra exige validação antes de remover uma origem, se o repositório usa uma fonte de verdade para SEO ou se uma pasta tem limite de edição, essa orientação precisa aparecer com linguagem operacional.

Esse raciocínio conversa com instruções de agente no onboarding técnico, porque a pessoa nova e a ferramenta precisam de entradas diferentes para trabalhar bem. Onboarding explica como alguém começa, enquanto referência de agente define como a ferramenta deve se comportar durante a execução.

GEMINI.md vs README na prática

A comparação fica mais útil quando você separa função, público e risco, porque a discussão ganha base no uso real da informação dentro do repositório. A pergunta correta é quem consulta aquela referência no momento de uso, qual decisão ela orienta e qual custo aparece quando ela fica no lugar errado.

Critério	README	GEMINI.md
Público principal	Pessoa chegando ao repositório	Agente do Gemini CLI
Função	Explicar propósito, uso e referências	Declarar regras persistentes de execução
Tom	Didático e legível	Direto, verificável e restritivo
Risco de excesso	Onboarding humano confuso	Agente com regra vaga ou duplicada
Boa saída	Linkar documentos específicos	Apontar fontes de verdade e validações

Se a pessoa vai ler para entender o projeto, README é o destino natural da explicação. Se o agente precisa ler para decidir como editar, testar ou revisar, GEMINI.md faz mais sentido como referência persistente da ferramenta.

Essa separação também ajuda a revisar pull requests e mudanças feitas com IA, pois o revisor consegue cobrar aderência a um arquivo com função definida. Quando tudo fica misturado, a discussão vira interpretação de intenção e a revisão perde objetividade.

O que eu colocaria em cada arquivo

No README, eu manteria visão geral, instalação, comandos básicos, estrutura de pastas, links para documentação e orientações de contribuição. Também incluiria uma referência curta ao arquivo usado por agentes, sem duplicar as regras que pertencem à camada instrucional.

No GEMINI.md, eu colocaria padrões de edição, comandos de validação, regras de segurança, fontes de verdade, limites de autonomia e cuidados com arquivos sensíveis. Se o projeto tiver subpastas com regras muito diferentes, faz sentido estudar hierarquia de referência em vez de concentrar tudo em um arquivo enorme.

O post sobre referência de agentes no código complementa essa ideia, porque mostra como instrução mal posicionada muda a qualidade da revisão. Para agente de IA, uma referência boa precisa ser acionável, verificável e próxima da tarefa que ela pretende orientar.

Também vale conectar esse tema com Vibe Coding, porque gerar código com IA fica mais previsível quando o repositório declara padrões antes da geração. A revisão ainda precisa confirmar se o resultado respeitou as regras, mas a ferramenta trabalha com menos ambiguidade desde o início.

Cuidado com duplicidade de regra

O maior risco aparece quando a mesma regra existe em dois arquivos com versões diferentes, porque uma instrução manda rodar um comando e outra aponta outro caminho. A pessoa revisora então precisa descobrir qual versão vale, e o agente pode escolher a orientação mais próxima em vez da fonte correta.

Eu prefiro escolher uma fonte de verdade para cada assunto e fazer os outros documentos apontarem para ela. README pode indicar onde estão as instruções de agente, GEMINI.md pode apontar para guias técnicos, mas a regra inteira deve morar em um único lugar canônico.

Aqui na Promovaweb, Luiz costuma reforçar esse cuidado no Co-work quando alguém tenta corrigir comportamento de IA apenas com prompt de conversa. Se a instrução vai valer de novo em outra sessão, ela precisa morar em um arquivo que o agente consiga recuperar e que a pessoa revisora consiga cobrar.

O Co-work é o encontro ao vivo de trabalho acompanhado da Promovaweb, usado para tirar dúvidas, revisar problemas reais com a tela aberta e comparar decisões práticas entre projetos. Essa dinâmica ajuda a perceber quais orientações pertencem ao README, quais devem virar regra de agente e quais fazem mais sentido em uma fonte técnica própria.

O artigo sobre hierarquia de referência no Gemini entra bem nesse ponto, porque a comparação GEMINI.md vs README define a função principal de cada camada. A hierarquia resolve onde regras específicas devem morar quando o repositório tem áreas com padrões, comandos ou riscos diferentes.

Perguntas frequentes sobre GEMINI.md vs README

O GEMINI.md substitui o README?

GEMINI.md orienta o agente e README orienta pessoas, portanto cada arquivo preserva uma função própria dentro do repositório. Eles podem se referenciar, mas a documentação humana e a referência persistente da ferramenta precisam permanecer separadas para evitar leitura confusa.

Posso colocar regras de IA no README?

Uma seção curta no README pode indicar onde ficam as instruções de agente e quais arquivos sustentam a execução com IA. Regra persistente, comando de validação e limite de edição ficam mais claros em arquivo próprio, porque o agente precisa recuperar essa orientação durante o trabalho.

O que deveria ficar fora do GEMINI.md?

Texto de apresentação, histórico comercial, explicação longa para pessoa iniciante e instruções sem efeito sobre comportamento do agente tendem a funcionar melhor no README ou em documentação técnica. GEMINI.md deve privilegiar regra acionável, fonte de verdade, comando de validação e limite de edição.

Como evitar conflito entre arquivos?

Escolha uma fonte de verdade para cada tipo de regra e use links para apontar documentos relacionados. Quando uma regra mudar, atualize o arquivo canônico e mantenha os outros documentos apenas como orientação de caminho.

Essa lógica vale fora do Gemini CLI?

Essa lógica vale como critério geral para repositórios que usam agentes de código, mesmo quando cada ferramenta tem seu próprio mecanismo de instrução. A separação entre documentação humana e referência persistente continua útil porque público, momento de uso e risco de interpretação mudam de um arquivo para outro.

Quando revisar essa separação?

Revise quando o README ficar pesado, quando o agente repetir erro já previsto ou quando a pessoa revisora precisar explicar a mesma regra em várias tarefas. Esses sinais indicam que a documentação perdeu função clara e que alguma instrução precisa mudar de camada.

Separar arquivos melhora a revisão

Separar GEMINI.md e README dá função clara para cada camada de referência, porque uma pessoa precisa entender o projeto enquanto o agente precisa executar com limites explícitos. O próximo passo é revisar o repositório e classificar cada instrução como entrada humana, referência técnica ou regra persistente de agente.

Se uma instrução aparece toda semana na conversa com a IA, ela provavelmente merece sair do prompt solto e entrar no arquivo certo. Essa mudança reduz repetição na revisão, torna a regra recuperável em sessões futuras e deixa mais claro quem deve ler cada parte da documentação.