Um agente de código erra de um jeito curioso quando recebe regra ampla demais, porque tenta aplicar a mesma instrução em documentação, UI, testes, automação e scripts. É nesse cenário que faz sentido entender o uso de referência local no Gemini CLI, especialmente quando cada pasta tem uma exigência diferente.

No Gemini CLI, o arquivo de referência não precisa existir apenas como regra única na raiz do projeto, pois a documentação oficial descreve uma hierarquia com referência global, raiz, diretórios ancestrais e subdiretórios. Essa lógica permite que a regra more perto do trecho que ela orienta, sem obrigar o agente a carregar uma orientação genérica para qualquer edição.

Eu vejo esse recurso como uma forma de reduzir ambiguidade na revisão, não como substituto para Git, teste e pessoa revisora. O ganho aparece quando o agente recebe uma instrução mais próxima da área que está alterando e entrega algo mais coerente para ser conferido.

Direto ao ponto

Use referência local do Gemini CLI quando uma pasta do projeto precisa de regra própria para orientar o agente, como formato, limite de edição, validação, fonte de verdade ou cuidado com arquivos sensíveis. A regra global deve explicar o comportamento geral, enquanto a regra local registra o que muda naquele recorte.

O papel da referência local

No Gemini CLI, o arquivo padrão de referência registra instruções de projeto, persona e guia de estilo. A documentação oficial explica que a CLI descobre e concatena arquivos de referência em uma hierarquia.

Essa hierarquia muda a forma de pensar instruções para agentes, porque separa o que vale para o projeto inteiro daquilo que pertence a uma pasta específica. Uma área de documentação pode ter regra editorial, uma área de UI pode exigir consulta ao design system e uma área de automações pode pedir cuidado maior com credenciais e payloads.

Eu não trataria isso como enfeite organizacional, já que a regra local só faz sentido quando altera o comportamento do agente naquele caminho. Se o arquivo local repete a raiz com outras palavras, ele aumenta manutenção sem melhorar a resposta.

O post sobre como usar referência do Gemini CLI para orientar agentes de código cobre o uso inicial do arquivo. Aqui o recorte é outro: como distribuir a instrução quando o repositório tem áreas com exigências diferentes.

Regra global e regra local

A regra global deve carregar aquilo que vale para qualquer tarefa, como fonte de verdade principal, limites de edição, comandos de validação, política de permissão e comportamento esperado quando faltar informação. Ela funciona como contrato geral do projeto, por isso não deve receber detalhes que pertencem a uma área específica.

A regra local deve existir quando a pasta tem uma diferença real, como frontmatter, linkagem e voz editorial em posts de blog. Em componentes visuais, ela pode exigir acessibilidade, design system e inspeção visual; em scripts, pode reforçar idempotência, logs e cuidado com execução repetida.

Eu uso um teste simples: se a instrução perder sentido fora daquela pasta, ela pode ser local. Se a instrução continua valendo em qualquer parte do repositório, ela pertence à referência global ou a uma fonte de verdade própria.

Esse critério conversa com o artigo sobre referência do Gemini CLI vs README para referência de IA. O README continua sendo entrada humana, o arquivo de referência orienta o agente, a documentação longa guarda explicação completa e a regra local evita que a instrução certa seja aplicada no lugar errado.

Conteúdo de uma instrução por pasta

Um arquivo de instrução local deve ser curto, específico e verificável, com formato esperado, guias obrigatórios, tipos de alteração que pedem cuidado extra e comandos de validação. A regra precisa ajudar o agente a decidir melhor, não virar uma segunda documentação completa.

Também pode registrar limites, como não alterar arquivos gerados manualmente, não mexer em credenciais, não publicar conteúdo sem validação editorial e não criar componente novo quando existe primitivo local equivalente. O valor está em transformar regra implícita em instrução recuperável pelo agente.

Aqui na Promovaweb, eu prefiro que o arquivo local aponte para a fonte correta em vez de copiar um guia inteiro. Se uma pasta depende de um manual de design ou de regra de SEO, a instrução local deve mandar consultar a fonte certa e evitar versões paralelas.

O mesmo raciocínio aparece no post sobre quando criar skill para agente de código. Instrução local serve para regra persistente por recorte, enquanto skill funciona melhor quando existe procedimento recorrente com entrada, etapas, validação e saída.

Conflitos entre arquivos de referência

Conflito aparece quando a mesma regra mora em camadas diferentes com versões divergentes, fazendo a raiz dizer uma coisa e a pasta dizer outra. O problema não está no número de arquivos; está na ausência de precedência clara.

Eu evitaria duplicar instrução, porque o arquivo local deve complementar a raiz, não reescrever a raiz com outras palavras. Se precisa contrariar uma regra geral, a exceção deve ser explícita e limitada ao recorte para que a pessoa revisora não precise descobrir qual regra deveria mandar.

Também vale revisar o tamanho dos arquivos, pois instrução local não deve virar depósito de tarefas pendentes. Instrução temporária pertence a issue, PR ou plano de execução; regra persistente fica no arquivo de referência; explicação longa fica na documentação.

O artigo sobre como auditar referência do Gemini CLI sem quebrar a memória do agente aprofunda essa manutenção. Depois que a instrução local existe, ela precisa ser revisada quando a pasta muda, quando o comando muda ou quando o agente repete erro em uma área específica.

Conferência da referência carregada

A checagem precisa sair da suposição, porque o agente pode responder como se tivesse lido a regra certa sem ter carregado o arquivo esperado. No Gemini CLI, /memory show exibe a memória hierárquica concatenada e /memory refresh força nova leitura dos arquivos.

Eu usaria essa verificação antes de tarefas sensíveis e depois de alterar arquivos de referência. Se o agente recebeu regra antiga, duplicada ou fora do escopo, a revisão já começa com uma pista; se a regra local não aparece, talvez o arquivo esteja no caminho errado ou a sessão precise recarregar memória.

A documentação de configuração também registra context.fileName, que permite configurar o nome do arquivo de referência. Esse detalhe reforça que a prática depende de escopo e carregamento, não do apego ao nome do arquivo.

Ferramentas como Codex CLI, Claude Code e Gemini CLI variam na forma de carregar instruções, mas o critério editorial é parecido. Regra persistente precisa estar em lugar previsível, com limite claro e revisão humana depois da execução.

Relação com Vibe Coding e IA Makers

A qualidade da referência muda a qualidade da entrega em Vibe Coding. O agente pode gerar uma alteração aceitável no arquivo errado, com regra errada, se o repositório não explica a diferença entre áreas.

Na Formação IA Makers, esse tema aparece quando o aluno começa a trabalhar com repositórios maiores. No nosso Co-work, a conversa quase sempre volta para a mesma base: escopo claro, regra persistente, Git, teste e revisão humana.

Instrução local ajuda porque aproxima a orientação do trabalho e reduz a dependência da memória do prompt principal. Isso não elimina revisão, mas melhora a qualidade do que chega para revisão.

Se você já usa Gemini CLI, vale observar onde a regra global ficou grande demais e onde uma pasta precisa de orientação própria. 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, referência persistente e revisão de código.

O post sobre quando atualizar referência do Claude Code em tarefas longas com IA fecha bem essa leitura. O nome do arquivo muda conforme a ferramenta, mas a decisão continua a mesma: separar a instrução que acompanha toda sessão da instrução que deve ficar perto do trecho alterado.