Um agente de código pode conhecer a linguagem, mas ainda assim ignorar a regra específica do repositório. Ele pode sugerir um padrão antigo, criar arquivo no lugar errado ou rodar um comando que já não representa a validação do projeto. Essa diferença entre capacidade geral e instrução local é o motivo de tanta gente procurar como usar referência do Gemini CLI.

No Gemini CLI, esse arquivo existe para reduzir repetição de instruções. Em vez de explicar a cada prompt qual stack o projeto usa, quais padrões de estilo importam e quais limites o agente deve respeitar, a referência persistente fica escrito em um lugar que a CLI consegue carregar.

Eu vejo valor nesse tipo de arquivo quando ele funciona como orientação de trabalho, não como manual enciclopédico. O agente precisa saber o que consultar, o que evitar e como confirmar que a alteração está pronta para revisão.

Direto ao ponto

Use o arquivo de referência do Gemini CLI para registrar instruções persistentes do projeto para o agente: padrão de código, fontes de verdade, comandos de validação, limites de edição e cuidados com arquivos sensíveis. O arquivo deve ser curto o bastante para ser revisado e específico o bastante para orientar uma sessão real. Detalhe temporário de tarefa pertence a issue, PR ou plano de execução.

O que o arquivo de referência faz no Gemini CLI?

A documentação oficial do Gemini CLI descreve o arquivo padrão de referência como recurso para instruções de projeto, persona e guia de estilo. O objetivo é dar ao modelo uma base persistente para responder com mais aderência ao repositório.

Essa referência não substitui leitura de código, Git, teste nem revisão humana. Ele ajuda a orientar a primeira decisão do agente. Se o projeto usa TypeScript com uma regra de estilo específica, se a pasta pública tem convenção própria ou se há comando obrigatório antes de fechar a tarefa, isso pode ficar explícito.

Eu gosto de pensar nesse arquivo como a conversa inicial que você não quer repetir em toda sessão. Ele não deve carregar a história inteira do projeto. Deve carregar aquilo que o agente precisa lembrar antes de propor uma mudança.

O post sobre referência do Gemini CLI vs README para referência de IA aprofunda essa separação. README orienta pessoas. O arquivo de referência orienta o agente. Os dois podem conversar, mas cada um tem função editorial diferente.

O que escrever em uma referência útil para agentes?

Um bom arquivo de referência começa com regra que afeta decisão. Vale registrar stack principal, padrão de pastas, comando de teste, comando de build, política de permissão, arquivos que exigem cuidado, fonte de verdade para copy, design ou arquitetura e critério de revisão.

O arquivo também deve dizer como o agente deve se comportar quando faltar informação. Em projetos reais, isso importa mais do que parece. Agente que inventa caminho para terminar uma tarefa cria retrabalho. Agente instruído a perguntar, parar ou registrar pendência fica mais previsível.

Eu evitaria transformar o arquivo em apostila. Se uma regra mora em um guia maior, a referência do Gemini CLI pode mandar ler esse guia antes de editar aquele assunto. Aqui na Promovaweb, eu prefiro que contexto de agente aponte para fontes de verdade em vez de repetir o guia inteiro dentro do arquivo.

Também vale evitar meta-instrução vaga. Frases como “seja profissional” ou “entregue código excelente” dizem pouco. Melhor escrever: “antes de alterar componente visual, consulte o guia de design”; “antes de fechar tarefa, rode o comando de teste indicado”; “não edite arquivo de credenciais”.

Como separar referência do Gemini CLI de README e documentação longa?

A separação mais limpa vem pela pergunta: quem precisa ler isso primeiro? Se a resposta for uma pessoa entrando no projeto, o lugar natural é o README ou uma documentação humana. Se a resposta for o agente antes de alterar código, o lugar pode ser o arquivo de referência.

Documentação longa continua tendo valor. Arquitetura, decisões de domínio, design system, padrões de deploy e regras editoriais podem viver em arquivos próprios. A referência do Gemini CLI aponta para essas fontes e resume o comportamento esperado do agente.

Essa decisão reduz conflito. Quando cada regra tem uma fonte clara, a manutenção fica mais simples. Se o padrão de teste mudou, você altera o documento certo e confere se o arquivo de referência aponta para ele corretamente.

O artigo sobre como auditar referência do Gemini CLI sem quebrar contexto do agente entra na etapa seguinte. Primeiro você estrutura o arquivo. Depois você revisa se ele continua representando o projeto.

Como usar referência por diretório sem criar ruído?

O Gemini CLI trabalha com referência hierárquico. A documentação explica que a CLI pode carregar arquivo global, arquivo da raiz do projeto, arquivos de diretórios ancestrais e arquivos em subdiretórios abaixo do ponto atual. Isso permite instrução mais específica por módulo, componente ou área.

Esse recurso ajuda quando há diferença real de referência. Uma pasta de documentação pode ter regra editorial própria. Uma pasta de testes pode ter padrão de nomenclatura específico. Uma área de infraestrutura pode exigir limite de edição mais restrito.

Eu não usaria instrução local para repetir regra global. Usaria para exceção bem definida. Se a mesma instrução aparece em vários arquivos, alguém vai esquecer uma versão na próxima mudança. A duplicação começa pequena e termina como disputa silenciosa entre regras.

A documentação de configuração também registra que o nome padrão do arquivo de referência pode ser configurado via context.fileName. Esse dado importa porque mostra que o conceito é mais amplo que o nome padrão: o ponto é o arquivo carregado como referência, com escopo claro.

Como verificar a referência que o agente recebeu?

Antes de culpar o modelo, vale conferir a referência carregada. No Gemini CLI, /memory show exibe a memória hierárquica concatenada, e /memory refresh força nova leitura dos arquivos. Esses comandos ajudam a ver se o agente recebeu a regra certa.

Essa checagem é útil em revisão. Se o agente ignorou uma convenção, talvez o arquivo esteja ausente, duplicado, desatualizado ou em uma camada que não foi carregada para aquela sessão. A pergunta ganha evidência: qual instrução chegou ao modelo?

Eu também usaria essa conferência depois de alterar o arquivo. Mudou regra persistente, confira o que a CLI carregou. Mudou nome de arquivo via configuração, confira de novo. O objetivo não é ritual; é reduzir dúvida antes de executar uma tarefa mais sensível.

Essa lógica se aproxima do post sobre quando atualizar referência do Claude Code em tarefas longas com IA. Ferramentas diferentes usam arquivos e comandos diferentes, mas o critério permanece: referência persistente precisa representar o trabalho atual.

Como conectar isso com Vibe Coding e IA Makers?

referência bem escrito muda a qualidade da conversa com o agente em Vibe Coding. O desenvolvedor deixa de pedir código em cima de instrução solta e passa a trabalhar com escopo, regra e validação mais visíveis.

Na Formação IA Makers, eu conecto esse tema a três hábitos. O primeiro é Git como registro da mudança. O segundo é revisão humana como etapa obrigatória. O terceiro é arquivo de referência como apoio, não como autorização para o agente sair alterando tudo.

Ferramentas como Gemini CLI, Codex CLI e Claude Code funcionam melhor quando o projeto já tem regra persistente e limite claro. Sem isso, a sessão começa com uma negociação improvisada sobre o que o agente pode ou não pode fazer.

O post sobre quando criar skill para agente de código ajuda a decidir o que deve sair da referência global e virar procedimento próprio. Se a tarefa tem entrada, etapas, validação e saída recorrente, talvez ela mereça uma skill. Se a regra vale para qualquer alteração, o arquivo de referência pode ser suficiente.

Se você usa Gemini CLI, revise o arquivo de referência como parte do repositório, não como anotação lateral. Se usa outro agente, procure o arquivo equivalente e aplique o mesmo critério. A página de formações da Promovaweb ajuda a escolher a trilha certa, e a Formação IA Makers aprofunda esse trabalho com agentes, Git, revisão e referência persistente.