Um agente de código pode errar por falta de capacidade, mas também pode errar porque recebeu uma regra vencida, especialmente quando o repositório muda comandos, pastas, padrões de teste ou política de revisão. É nesse cenário que faz sentido perguntar como auditar referência do Gemini CLI, pois a ferramenta pode continuar obedecendo a uma versão antiga do trabalho mesmo quando o código já avançou.

O problema costuma aparecer tarde, porque a resposta do agente parece segura, a alteração soa plausível e a primeira leitura do diff não revela imediatamente a origem do desvio. Só na revisão alguém percebe que a IA não inventou uma regra ruim, mas seguiu uma instrução persistente que já não representa o projeto atual.

Eu olho para esse tipo de arquivo como contrato de trabalho do agente, porque ele define o que a ferramenta deve consultar, respeitar, validar e evitar durante uma sessão. Quando esse contrato fica errado, a IA não precisa criar uma resposta absurda para atrapalhar; basta cumprir com disciplina uma orientação escrita em outro momento.

Direto ao ponto

Auditar a referência persistente do Gemini CLI é revisar se o arquivo que orienta o agente ainda descreve as regras reais do repositório, incluindo fonte de verdade, comandos válidos, hierarquia de memória, limites de edição e instruções temporárias que deveriam estar em issue, PR ou plano de execução. A revisão fica mais útil quando nasce de evidência concreta, como mudança de fluxo, comando abandonado, regra duplicada, falha repetida em PR ou divergência entre o que o agente recebeu e o que o projeto exige hoje.

O que é drift na referência do Gemini CLI

Drift de referência é o desalinhamento entre a regra que o agente lê e a prática atual do projeto, o que torna o arquivo persistente uma fonte de erro silenciosa. No caso do Gemini CLI, isso importa porque a documentação oficial descreve esses arquivos como referência persistente para instruções de projeto, persona e guia de estilo.

A própria documentação explica que a CLI carrega referência de forma hierárquica, passando por arquivo global, raiz do projeto, diretórios ancestrais e subdiretórios. Esse desenho ajuda a adaptar o agente ao repositório, mas também aumenta a responsabilidade editorial quando a mesma regra aparece em mais de uma camada.

Eu considero drift perigoso porque ele costuma parecer disciplina, já que o agente “respeita” uma instrução e entrega um comportamento coerente com aquilo que recebeu. O problema é que a instrução perdeu vínculo com o código, com os testes ou com a forma de revisar, então a pessoa responsável paga a conta em diffs maiores, correções repetidas e explicação tardia.

O artigo sobre referência de IA e README ajuda a separar a documentação humana da referência enviada ao agente. Este post entra na etapa seguinte, que é manter essa referência útil depois que o repositório mudou e a primeira versão do arquivo ficou limitada.

Quando revisar a referência persistente

Eu revisaria o arquivo de referência quando a regra persistente do projeto muda, como troca de comando de teste, alteração de pasta pública, novo padrão de branch, ajuste de permissão, mudança de ferramenta de build ou revisão em política de segurança. Também revisaria quando a mesma correção aparece em várias PRs geradas por IA, porque repetição de erro costuma indicar que a instrução recebida pelo agente já ficou antiga.

O sinal mais forte aparece quando o agente insiste em criar arquivo no lugar errado, usar link antigo, ignorar teste obrigatório ou repetir uma estrutura de código que o projeto abandonou. Nessa situação, a auditoria precisa procurar a regra que sustenta o comportamento, corrigindo o diff atual e também a instrução que pode repetir o erro na próxima sessão.

No Gemini CLI, o comando /memory show ajuda nessa conferência porque exibe a referência concatenada que foi carregada antes da resposta do modelo. A documentação também registra /memory refresh, usado para forçar nova leitura dos arquivos, mas eu trataria esses comandos como evidência do que o agente recebeu e não como ritual fixo de checklist.

O post sobre atualizar referência em tarefas longas com IA aprofunda essa lógica quando o trabalho dura várias sessões. O nome do arquivo muda conforme a ferramenta, mas a decisão central continua parecida: separar memória persistente, plano temporário e registro de execução.

O que procurar na auditoria

A primeira revisão é função, porque uma boa referência persistente não tenta vender o projeto, contar toda a história nem guardar detalhe temporário. Ela deve orientar o comportamento do agente com clareza, mostrando o que consultar, o que respeitar, o que validar e onde não mexer sem autorização.

A segunda revisão é duplicação, já que o mesmo parágrafo copiado em README, referência de agente, documentação de arquitetura e checklist de PR cria uma sensação falsa de organização. Na primeira mudança, uma versão fica desatualizada, por isso eu prefiro manter a regra em uma fonte de verdade e fazer os demais arquivos apontarem para ela.

A terceira revisão é comando, porque uma instrução de validação vencida estraga o fluxo de IA de um jeito pouco visível. O agente tenta obedecer, falha, improvisa ou ignora a validação, e nenhuma dessas saídas ajuda a pessoa revisora a confiar no resultado.

A quarta revisão é limite de edição, pois agente com permissão ampla demais tende a transformar tarefa pequena em diff difícil de revisar. A referência precisa dizer quando ler antes, quando pedir confirmação, quando parar e quais arquivos exigem cuidado extra.

Como evitar duplicação entre arquivos de referência

O jeito mais confiável é separar regra global, explicação longa e procedimento recorrente, pois cada tipo de informação precisa morar no lugar em que será revisado com menos perda. Regra global fica no arquivo que orienta o agente naquele projeto, explicação longa fica em documentação própria e procedimento recorrente pode virar skill, comando ou checklist revisável.

No ecossistema da Promovaweb, essa distinção é importante porque cada repositório precisa ter uma fonte operacional clara. Em projetos públicos que usam Gemini CLI, o arquivo padrão da ferramenta pode cumprir esse papel; em um projeto orientado por Codex, a boa regra é saber qual arquivo manda naquele fluxo, sem espalhar a mesma instrução por lugares paralelos.

Quando eu reviso esse tipo de referência, procuro frases que deveriam funcionar como link para uma fonte, não como cópia integral de outra documentação. Se uma regra de SEO mora em um guia específico, o arquivo do agente pode mandar ler esse guia antes de editar conteúdo, sem colar o guia inteiro dentro da memória persistente.

Essa separação diminui manutenção porque, quando o guia muda, a fonte muda uma vez e o agente continua sabendo onde procurar. A pessoa revisora também consegue explicar a decisão com um caminho claro, sem comparar versões paralelas da mesma regra em arquivos diferentes.

O post sobre quando criar skill para agente de código aprofunda esse critério de separação. Skill faz sentido quando existe tarefa recorrente com entrada, fonte, validação e saída, enquanto arquivo global faz sentido quando a regra vale para qualquer alteração do repositório.

Como usar a hierarquia sem criar conflito

A hierarquia do Gemini CLI permite referência global, referência de projeto e referência por subdiretório. A documentação de configuração também registra que o nome padrão do arquivo pode ser configurado via context.fileName, inclusive com lista de nomes.

Esse recurso exige critério porque cada camada deveria carregar uma função diferente. Uma referência global pode guardar preferências pessoais, uma referência de projeto deve guardar regras daquele repositório e uma instrução local deve cobrir diferenças reais de módulo, pacote, app ou área técnica.

Eu evitaria usar instrução local para repetir regra global, porque duplicação local cria conflito quando a regra da raiz muda. Usaria esse nível para exceção específica, como uma pasta de documentação com regra editorial própria, uma pasta de testes com padrão de nomenclatura particular ou uma pasta de infraestrutura com comandos mais sensíveis.

O teste editorial é separar escopo, recência e permanência antes de salvar a instrução. Se a regra vale para o projeto inteiro, ela não pertence a uma subpasta; se vale só para um módulo, ela não deveria poluir a raiz; se é temporária, deve ficar no plano de execução, no PR ou na issue.

Essa leitura conversa com Vibe Coding, porque delegar código para IA com referência vencida é parecido com entregar uma especificação antiga para alguém executar. A ferramenta pode até produzir algo funcional, mas a revisão vira negociação com instruções que o projeto já deveria ter removido.

Como conectar isso com IA Makers

Na Formação IA Makers, esse tema aparece quando o aluno começa a usar agente de código em projeto real e precisa sustentar o trabalho por mais de uma sessão. O desafio inclui preparar referência, revisar diffs, rodar testes, documentar decisão e manter o repositório legível para a próxima pessoa ou para a próxima execução do agente.

Eu conecto auditoria de referência do Gemini CLI a três hábitos: Git como fonte de revisão, PR com motivo e validação que realmente roda. Mudança de referência precisa aparecer em diff pequeno, a regra nova precisa explicar que problema corrige e todo comando citado no arquivo precisa existir no repositório.

Ferramentas como Codex CLI, Claude Code e Gemini CLI ajudam quando o projeto já tem contrato claro. Sem esse contrato, cada sessão começa tentando adivinhar o que a pessoa responsável queria preservar, e a revisão humana gasta energia separando erro de execução, regra vencida e instrução duplicada.

Se você já usa referência persistente no Gemini CLI, revise se ela ainda representa o projeto atual antes de delegar outra tarefa relevante. A página de formações da Promovaweb ajuda a escolher a trilha certa, e a Formação IA Makers aprofunda esse trabalho com Vibe Coding, agentes, Git e revisão humana.