Regras Locais de Projetos: Configurando o escopo do AGENTS.md

📚 Navegação da Série: O artigo anterior 10 · Codex em Nuvem (Cloud) explicou a esteira assíncrona do Codex. Esta seção aborda as regras locais configuradas no arquivo AGENTS.md, que atua como o manual de inicialização lido pela IA a cada execução. No próximo artigo 12 · Atalhos Rápidos e Comandos de Barra, detalharemos comandos de barra úteis.

Uma experiência comum ao iniciar o uso do Codex ajuda a ilustrar a importância da clareza das regras:

No início, criei um arquivo AGENTS.md para um repositório Node especificando na primeira linha: "use pnpm para instalar pacotes, o uso de npm é estritamente proibido". Logo depois, o Codex executou npm install. Copiar a regra e usar negrito não funcionou de início.

O arquivo continha mais de cem linhas com introduções conceituais da empresa e detalhes históricos da escolha da arquitetura. A diretriz útil estava na linha 140. A atenção da IA foi diluída por metadados irrelevantes. O problema não era a falta de obediência do agente, mas sim a inclusão de dados supérfluos no manual.

O arquivo AGENTS.md do Codex tem a mesma finalidade do CLAUDE.md no Claude Code. Contudo, as particularidades de carregamento, override e limites de tamanho diferem e exigem atenção para evitar erros.

Ao terminar de ler este artigo, você terá:

• O fluxo de busca e herança do AGENTS.md (regras globais e locais)
• A aplicação do mecanismo de sobreposição temporária via AGENTS.override.md
• Boas práticas sobre o que documentar e o que evitar nas instruções
• Como configurar caminhos personalizados e limites de tamanho em bytes
• Um roteiro prático para validar se o Codex leu as instruções

⚠️ Nota: Este artigo foca exclusivamente na estrutura do arquivo AGENTS.md. A persistência de memória do assistente (que armazena feedbacks em cache local e vem desativada por padrão) foi explicada no Artigo 02. Lembre-se: regras de time fundamentais devem constar no AGENTS.md e não depender da memória volátil.

---

01 O Papel do AGENTS.md na Inicialização

O arquivo AGENTS.md funciona como um conjunto de instruções persistentes lidas pelo Codex no início de cada thread de execução, definindo o escopo do projeto.

Como cada thread do Codex é inicializada sem histórico, as regras e restrições locais declaradas anteriormente são perdidas. O AGENTS.md evita a necessidade de repetir orientações de ambiente ou formatação a cada nova conversa.

Analogia: painel de avisos na troca de turnos. Em um ambiente de fábrica, o operador do turno anterior anota na lousa as instruções críticas do dia: "não utilize o gerador B", "inspecione a matéria-prima do lote C" ou "contate o supervisor em caso de erro". O operador do próximo turno lê o painel e inicia o trabalho sabendo o que fazer. O AGENTS.md atua como esse painel de orientações.

Principais situações para atualizar as instruções:

• Erros recorrentes: Se a IA repetir um equívoco de sintaxe ou comando, documente a regra.
• Prompts redundantes: Evite digitar a mesma instrução de setup a cada nova sessão.
• Padrões de design: Defina regras de nomenclatura ou arquitetura que a IA deve respeitar.
• Onboarding de desenvolvedores: O documento serve como um guia tanto para o agente quanto para novos programadores.

Se o Codex assumir premissas incorretas sobre seu projeto, documente a correção no AGENTS.md em vez de apenas corrigi-lo no chat. Em poucas interações, o arquivo cresce de forma estruturada e reduz falhas repetidas.

💡 Resumo em uma frase: O AGENTS.md reúne as diretrizes de desenvolvimento lidas a cada inicialização para orientar a IA, semelhante ao CLAUDE.md do Claude Code.

---

02 Busca e Herança de Arquivos

Diferentemente de outros assistentes, o Codex permite múltiplos arquivos de regras organizados por diretórios, unificados na inicialização da thread:

A consolidação técnica das diretrizes segue três etapas na inicialização da sessão:

1. Escopo Global: O Codex busca arquivos na pasta ~/.codex/ (ou no diretório apontado pela variável CODEX_HOME). Ele carrega prioritariamente o arquivo AGENTS.override.md; caso não exista, lê o AGENTS.md. Apenas o primeiro arquivo não-vazio encontrado neste escopo é processado.
2. Escopo do Projeto: O Codex varre a árvore a partir do diretório raiz do Git até a subpasta ativa. Em cada nível, he busca por AGENTS.override.md, depois por AGENTS.md e, finalmente, por nomes cadastrados no project_doc_fallback_filenames. Apenas um arquivo é lido por diretório.
3. Mesclagem de Conteúdo: O Codex concatena o conteúdo dos arquivos localizados do topo até a folha ativa, separados por linhas em branco. As regras declaradas nas subpastas mais próximas do diretório ativo possuem maior prioridade e substituem instruções conflitantes anteriores.

Fluxo de carregamento e concatenação:

O arquivo concatenado acumula as regras de cada nível. A proximidade física em relação à pasta ativa do desenvolvedor determina a prioridade de substituição de conflitos.

Detalhamento técnico da herança:

• Concatenação de regras: As diretrizes locais não excluem as globais. Ambas são enviadas para a sessão do LLM, mas cláusulas conflitantes são resolvidas em favor das regras mais específicas.
• Resolução de conflitos: Se o AGENTS.md global define "use aspas simples" e o arquivo na raiz do repositório define "use aspas duplas", a regra do repositório prevalece.

Analogia: níveis de zoom de mapas. O mapa nacional dá as diretrizes gerais do país (escopo global), o mapa municipal indica as vias da cidade (raiz do repositório) e a placa do condomínio orienta sobre o acesso final (subpastas locais). As três fontes de dados coexistem de forma complementar; se houver divergências de direções, a sinalização local prevalece.

Visualização das camadas de conciliação: as subpastas definem as regras mais específicas, que prevalecem sobre as configurações mais gerais da raiz ou do escopo global.

💡 Resumo em uma frase: A hierarquia de regras une o escopo global do sistema, a raiz do repositório e as subpastas locais, aplicando precedência de acordo com a proximidade física.

---

03 Sobreposição de Regras (AGENTS.override.md)

O arquivo AGENTS.override.md permite aplicar regras temporárias ou específicas sem modificar os arquivos versionados principais.

Se você mantém um AGENTS.md global com as práticas comuns da equipe, mas precisa temporariamente adotar outros padrões em uma tarefa específica sem apagar as diretivas originais, use a sobreposição.

Analogia: notas adesivas temporárias. O contrato original permanece na pasta, mas você anexa um bilhete: "para esta semana, considere a regra X". Após a entrega, você descarta o bilhete e o contrato original volta a valer. O AGENTS.override.md funciona assim: sua presença faz o Codex ignorar o AGENTS.md daquele mesmo nível; ao exclui-lo, a regra anterior é reativada.

Cenários comuns de aplicação:

• Modificações temporárias globais: Crie o ~/.codex/AGENTS.override.md para testes rápidos. Apague-o após a tarefa para retomar as diretrizes padrão.
• Regras para subpastas de microsserviços: Em pastas como services/payments/, aplique uma sobreposição específica para gerenciar frameworks ou bancos de dados isolados:

# services/payments/AGENTS.override.md

## Regras do Serviço de Pagamentos

- Use `make test-payments` em vez de `npm test`
- Notifique o canal de segurança antes de alternar chaves de API

Ao processar essa subpasta, o Codex ignora o AGENTS.md desse nível (caso exista) e adota as definições do override.

Comportamento do override na hierarquia:

Nível de ação	Impacto do AGENTS.override.md
Mesmo diretório	Ignora o AGENTS.md local, substituindo-o na concatenação
Outros diretórios	Não afeta a busca de regras nos níveis superiores ou inferiores

A sobreposição substitui apenas o arquivo de diretrizes do seu próprio nível; o restante da concatenação segue as regras de hierarquia normais.

Se notar comportamentos inesperados do agente nas modificações de arquivos, verifique se há arquivos AGENTS.override.md indesejados na árvore de diretórios.

💡 Resumo em uma frase: O AGENTS.override.md desativa apenas o AGENTS.md do mesmo diretório. Use-o para regras temporárias sem interferir no restante da hierarquia.

---

04 Boas Práticas: O que Documentar

Para que o Codex compreenda as diretrizes sem diluir o contexto, mantenha as instruções diretas e focadas.

Recomenda-se registrar fatos e restrições técnicas permanentes:

Categoria	Conteúdo recomendado	Exemplo prático
Resumo do Projeto	Contexto rápido do repositório	"API de pagamentos baseada em FastAPI"
Stack de Tecnologia	Versões de frameworks e ferramentas	"Python 3.11 / PostgreSQL / pytest"
Comandos Frequentes	Como rodar testes, formatadores e lints	pnpm run lint ou pytest tests/
Padrões de Código	Estilos de nomenclatura e restrições	"Todas as funções requerem type annotations explicativas"
Zonas de Restrição	Arquivos ou caminhos protegidos contra escrita	"Não modifique os arquivos dentro de migrations/"

Os comandos frequentes de lints e testes evitam que a IA tente adivinhar os scripts de compilação. As zonas de restrição impedem edições acidentais em pastas críticas, como arquivos de migração ou código legado protegido.

O que evitar nas instruções:

• ❌ Histórico de decisões de arquitetura: Informações corporativas e discussões conceituais consomem tokens desnecessários e diluem a atenção do agente.
• ❌ Informações desatualizadas: Instruções que conflitam com o estado real do projeto (ex: referenciar npm após migrar para pnpm) causam falhas de execução.
• ❌ Mapeamento óbvio de código: Não descreva a estrutura de diretórios ou regras de estilo já configuradas no ESLint/Prettier. O Codex analisa a base de código diretamente.

O Codex limita o tamanho total das diretrizes por bytes:

O Codex ignora arquivos vazios. Se o conteúdo concatenado das regras atingir o limite definido em project_doc_max_bytes (padrão de 32 KiB), o carregamento de novas diretrizes é interrompido.

A conciliação dessas camadas é limitada pelo tamanho em bytes do buffer de entrada. Se o volume de instruções for excessivo, as regras mais específicas do diretório ativo podem não ser carregadas. Mantenha os arquivos enxutos ou distribua-os em subpastas de forma granular.

Evite documentar padrões que o Codex consegue inferir a partir da leitura do código existente. Foque estritamente em restrições físicas de escrita e caminhos de linter.

💡 Resumo em uma frase: Documente apenas regras técnicas, caminhos de linter e zonas de restrição. Mantenha o tamanho total abaixo de 32 KiB para evitar truncamento.

---

05 Configurações Customizadas no config.toml

Para personalizar o comportamento do leitor de diretrizes, edite o arquivo ~/.codex/config.toml:

1. Nomes de arquivos alternativos (project_doc_fallback_filenames)

Se o seu repositório já possui um guia de desenvolvimento consolidado (ex: DEVELOPMENT.md), configure o Codex para lê-lo diretamente, sem duplicar arquivos:

# ~/.codex/config.toml
project_doc_fallback_filenames = ["DEVELOPMENT.md", ".agents.md"]

A ordem de busca passa a incluir os nomes personalizados, selecionando o primeiro arquivo não-vazio que encontrar.

Arquivos com nomes fora desta lista serão ignorados no fluxo de carregamento de diretrizes.

2. Limite de tamanho em bytes (project_doc_max_bytes)

Caso precise carregar instruções volumosas e queira estender o limite de 32 KiB, ajuste o parâmetro:

# ~/.codex/config.toml
project_doc_max_bytes = 65536

Isso eleva o limite de processamento para 64 KiB. Prefira refatorar e enxugar as diretrizes antes de aumentar este valor para evitar o consumo desnecessário de tokens.

Comparativo de configurações:

Cenário técnico	Ação recomendada
Mapear arquivos de regras existentes (ex: TEAM_GUIDE.md)	Adicionar o nome no array project_doc_fallback_filenames
Instruções de regras truncadas por estouro de tamanho	Otimizar regras e, se necessário, elevar project_doc_max_bytes
Isolar perfis de execução (ex: bots e automações)	Configurar o caminho alternativo na variável CODEX_HOME

⚠️ Nota: Alterações no config.toml exigem reiniciar a CLI ou a extensão do editor para entrar em vigor.

💡 Resumo em uma frase: Use o config.toml para definir nomes de arquivos de regras alternativos ou aumentar a tolerância em bytes, reiniciando o serviço após a edição.

---

06 Prática: Criando e Validando o AGENTS.md

Siga o roteiro a seguir para verificar o fluxo de herança do AGENTS.md em um repositório local:

Nota de compatibilidade: Usuários de Windows devem utilizar o PowerShell ou Git Bash para executar comandos equivalentes.

Passo 1: Inicialize o repositório

mkdir agents-md-demo
cd agents-md-demo
git init

Saída esperada: O Codex identifica a pasta como raiz do projeto por meio do diretório .git ativo.

Passo 2: Crie o arquivo AGENTS.md

Crie o arquivo AGENTS.md na raiz do projeto com o seguinte conteúdo:

# agents-md-demo — Projeto de Testes

Repositório experimental para validação de diretrizes locais.

## Comandos Úteis

- `npm test` —— Executa a suíte de testes locais

## Regras de Código

- Todas as funções requerem type annotations explicativas
- Utilize aspas duplas em strings por padrão

## Restrições

- Não instale novas dependências de produção sem autorização

Saída esperada: Criação do arquivo contendo as regras estruturadas básicas.

Passo 3: Valide o carregamento das diretrizes

Rode a seguinte chamada para instruir a IA a listar o contexto ativo:

codex --ask-for-approval never "Summarize the current instructions."

Saída esperada: O Codex retornará o resumo das regras de formatação de código, comandos e restrições descritas no repositório.

Passo 4: Valide a precedência em subpastas (Override)

Crie um subdiretório e adicione um arquivo de sobreposição:

mkdir -p services/payments

Crie o arquivo services/payments/AGENTS.override.md:

# services/payments/AGENTS.override.md

## Regras do Módulo de Pagamentos

- Use `make test-payments` em vez de `npm test`

Execute a CLI apontando para a subpasta ativa:

codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

Saída esperada: O Codex exibirá o carregamento concatenado dos escopos global, raiz e subpasta. A regra de testes do módulo de pagamentos (make test-payments) prevalecerá sobre a da raiz.

Se notar falhas de leitura do arquivo, execute codex status para validar a detecção da raiz do repositório ou remova arquivos temporários vazios.

💡 Resumo em uma frase: Valide a montagem do arquivo usando prompts de sumário e teste a precedência de regras em subpastas com arquivos de override.

---

07 Resumo

O AGENTS.md permite alinhar o comportamento do Codex aos padrões técnicos da equipe de desenvolvimento.

Tópicos essenciais revisados:

Diretriz técnica	Funcionamento e escopo
Conceito básico	Diretrizes persistentes de contexto do projeto, equivalentes ao CLAUDE.md do Claude Code
Busca de arquivos	Escopo global (~/.codex/) unificado com a busca recursiva de pastas até a subpasta ativa
Concatenação	Arquivos concatenados da raiz até a folha. Cláusulas mais específicas de subpastas têm prioridade
Sobreposição	O arquivo AGENTS.override.md desativa o AGENTS.md do mesmo diretório
Boas Práticas	Mantenha as regras enxutas. Documente apenas stacks, comandos úteis e zonas restritas
Configuração	Use o config.toml para caminhos de arquivos (fallback) e limites de tamanho em bytes

Com a estrutura de herança compreendida, você está apto a redigir manuais de regras eficazes, organizando políticas por módulos de pastas e validando as concatenações locais.

---

O próximo artigo 12 · Atalhos Rápidos e Comandos de Barra explorará as ferramentas rápidas de controle no terminal e no chat. Detalharemos os comandos de barra (/status, /compact) e o mapeamento de atalhos operacionais.

---

Leituras Recomendadas

• Boas Práticas de Desenvolvimento com Codex
• Otimização de Contexto e Desempenho
• Guia de Inicialização do Terminal CLI