AGENTS.md no Codex: onde fica, em que ordem carrega e o que escrever

Onde o Codex procura o AGENTS.md, em ordem de carregamento

O Codex monta a cadeia de instruções uma única vez ao iniciar (na interface de terminal, uma vez por sessão). Os arquivos são juntados de cima para baixo nesta tabela, então as instruções mais próximas do seu diretório de trabalho vêm depois e prevalecem.

Como configurar o AGENTS.md para o Codex

1. Crie os padrões globais

   Execute mkdir -p ~/.codex e escreva em ~/.codex/AGENTS.md as preferências que você quer em todos os repositórios. Para conferir se foi carregado, peça ao Codex um resumo das instruções dele.

   # ~/.codex/AGENTS.md
   
   ## Working agreements
   
   - Always run `npm test` after modifying JavaScript files.
   - Prefer `pnpm` when installing dependencies.
   - Ask for confirmation before adding new production dependencies.

2. Adicione um arquivo de projeto e overrides onde os times divergem

   Coloque um AGENTS.md na raiz do repositório para a configuração comum. Em uma pasta com regras diferentes, adicione AGENTS.override.md: ele substitui o AGENTS.md dessa pasta, que o Codex passa a ignorar.

   # AGENTS.md (repository root)
   
   ## Repository expectations
   
   - Run `npm run lint` before opening a pull request.
   - Document public utilities in `docs/` when you change behavior.
   
   # services/payments/AGENTS.override.md
   
   ## Payments service rules
   
   - Use `make test-payments` instead of `npm test`.
   - Never rotate API keys without notifying the security channel.

3. Confira o que foi carregado

   Inicie o Codex na pasta que interessa, por exemplo codex --cd services/payments, e peça que ele liste as fontes de instruções que carregou. Ele deve listar o arquivo global, depois o da raiz e depois o da pasta.

4. Reaproveite um nome de arquivo existente ou aumente o limite

   Se o seu repositório já guarda instruções em outro arquivo, adicione-o a project_doc_fallback_filenames em ~/.codex/config.toml. O Codex para de adicionar arquivos quando o tamanho combinado chega a project_doc_max_bytes, 32 KiB por padrão.

   # ~/.codex/config.toml
   project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
   project_doc_max_bytes = 65536

5. Adicione regras para o code review do Codex

   Para o @codex review no GitHub, adicione uma seção ## Code Review Rules ao AGENTS.md mais próximo do código que ela rege. Diga o que deve ser apontado e qual é a alternativa segura; deixe formatação e lint para a CI.

   ## Code Review Rules
   
   ### Experiment cohorts
   
   - Do not filter treatment comparisons on post-exposure behavior.
     Safe path: build cohorts from assignment or exposure.

Fonte: documentação do Codex, Custom instructions with AGENTS.md

Boas práticas para o AGENTS.md

• Fique no que o Codex não consegue descobrir sozinho: os comandos exatos de build, testes e lint (incluindo como rodar um único teste), as armadilhas do código e as decisões que não estão escritas em lugar nenhum.
• Coloque as regras mais específicas perto do código: um AGENTS.md aninhado em services/payments/ é melhor do que um arquivo raiz longo com uma seção de pagamentos.
• Cuidado com o orçamento de 32 KiB: os arquivos são adicionados da raiz para baixo e o resto é cortado, então divida arquivos longos em arquivos aninhados ou aumente project_doc_max_bytes.
• Use AGENTS.override.md para mudanças temporárias, globais ou em uma pasta, e apague-o para voltar ao normal.
• Um AGENTS.md vazio é ignorado, e a busca naquele diretório passa para o próximo nome de arquivo.
• Use um CODEX_HOME separado para usuários de automação, para que as instruções globais deles não se misturem com as suas.

AGENTS.md no Codex vs Claude Code e outros

O AGENTS.md é um formato aberto lido por muitos agentes, o que faz dele o melhor lugar para as instruções que você quer compartilhar. O Claude Code tem o próprio arquivo, o CLAUDE.md; veja o guia do CLAUDE.md para os detalhes.

O AGENTS.md diz ao Codex como. O Crewmark diz o que vem a seguir.

Um bom AGENTS.md faz cada sessão do Codex começar bem informada, mas a sessão continua esperando o seu prompt. O Crewmark transforma uma sessão do Codex, Claude Code, DeepSeek Harness ou OpenCode em um funcionário de IA com um papel, uma meta e um horário de trabalho, e a acorda com um heartbeat para pegar a próxima issue de um quadro.

1. Mantenha o AGENTS.md no repositório

   A sessão do Codex do funcionário lê o arquivo como a sua, então as convenções e os comandos de teste vêm junto.

2. Deixe o heartbeat iniciar o trabalho

   Durante o horário de trabalho, o funcionário acorda a cada 15, 30 ou 60 minutos na mesma conversa; veja como tornar o Codex proativo.

3. Misture agentes em um só quadro

   Um único AGENTS.md pode atender funcionários do Codex e do Claude Code lado a lado; compare os dois em Claude Code vs Codex.

Perguntas frequentes sobre o AGENTS.md no Codex