AGENTS.md para o Codex: o guia completo de configuração (2026)
O AGENTS.md é o arquivo de instruções persistentes do Codex (OpenAI Codex CLI), lido automaticamente antes de ele trabalhar em um repositório. O Codex o procura em uma ordem de busca fixa (global e, depois, da raiz do git até o seu diretório atual), concatena tudo o que encontra e limita o tamanho combinado a 32 KiB — passou disso, o resto é descartado silenciosamente. Uma coisa que vale lembrar: o Codex não lê o CLAUDE.md. Neste guia eu explico a mecânica: a ordem de busca, como os arquivos se combinam, o limite de tamanho e um AGENTS.md de verdade que você pode copiar.
- A mecânica do AGENTS.md no Codex muda rápido; os detalhes abaixo foram conferidos com a documentação oficial na data em que escrevi (ago/2026) — confira a documentação atual antes de depender dela.
O que o AGENTS.md faz no Codex (e a questão do CLAUDE.md)
O AGENTS.md é o arquivo de instruções persistentes que o Codex carrega no contexto toda vez que você abre uma sessão — convenções do projeto, comandos de teste/build e regras que ele não pode quebrar, para você não precisar repetir tudo isso a cada prompt. Segundo a documentação oficial em learn.chatgpt.com/codex/agent-configuration/agents-md, o Codex encontra e carrega os arquivos AGENTS.md por um mecanismo fixo — mas essa mesma página não menciona o CLAUDE.md nem uma vez. Sendo direta: por ora, o Codex não lê o CLAUDE.md, mesmo que o CLAUDE.md e o AGENTS.md representem exatamente a mesma ideia.
Uma frase para evitar confusão: o AGENTS.md (arquivo de configuração do Codex) é diferente do AgentKit (o kit que roda dentro do Codex/Claude Code, agentkit.best) e do OpenAI AgentKit (o Agent Builder/ChatKit da OpenAI).
Se você também usa o Claude Code e quer saber se um arquivo de contexto longo realmente ajuda, veja AGENTS.md vs CLAUDE.md — e se arquivos longos ajudam mesmo — aquele texto cobre a pesquisa; este aqui é sobre a mecânica de configuração do próprio Codex.
Onde o Codex procura o AGENTS.md — a ordem de busca exata
O Codex não lê um único arquivo AGENTS.md — ele percorre vários níveis, nesta ordem exata (segundo a documentação oficial):
- Nível global: o Codex verifica primeiro
~/.codex/AGENTS.override.md; se existir, ele o usa em vez de~/.codex/AGENTS.md. Sem override, ele lê~/.codex/AGENTS.md. - Nível de diretório (percorrendo da raiz do git até o seu diretório atual): o Codex encontra a raiz do repositório git e, então, desce por cada nível de diretório até o
cwd(de onde quer que você esteja rodando o Codex). Em cada nível, ele aplica a mesma regra de override: umAGENTS.override.mdnaquele nível vence; caso contrário, ele usaAGENTS.md.
Exemplo: você está em ~/projects/shop/apps/web e a raiz do git é ~/projects/shop. O Codex verifica, nesta ordem: global (~/.codex/) → ~/projects/shop/AGENTS.md (raiz do git) → ~/projects/shop/apps/AGENTS.md (se existir) → ~/projects/shop/apps/web/AGENTS.md (cwd). O que não existe é simplesmente ignorado — sem erro.
Para que o arquivo de override serve de fato: manter um AGENTS.md compartilhado commitado no git para o time inteiro, enquanto você joga ajustes pessoais ou específicos da máquina em um .override.md no mesmo nível — sem mexer no arquivo que todo mundo compartilha.
Vale lembrar: isto não é 'o arquivo mais próximo vence e o resto é ignorado' — todo arquivo encontrado é combinado junto (próxima seção), e não apenas um escolhido.
Como os arquivos se combinam — concatenação da raiz para baixo, o arquivo mais próximo vence
Depois que os encontra, o Codex não escolhe um arquivo — ele concatena tudo o que achou em um único bloco de contexto, na mesma ordem da busca: primeiro o global, depois a raiz do git e, então, cada subdiretório, separados por linhas em branco. Como um arquivo mais próximo do cwd é anexado por último, ele fica no fim do contexto — e, quando duas instruções entram em conflito, a que aparece depois (mais perto do cwd) costuma ser a que o agente segue.
Um exemplo com 3 arquivos, e qual vence no conflito:
~/.codex/AGENTS.md(global): 'Sempre rode a suíte de testes completa antes de commitar.'~/projects/shop/AGENTS.md(raiz do git): 'Use pnpm, não npm.'~/projects/shop/apps/web/AGENTS.md(cwd): 'Rode apenas os testes unitários (pnpm test:unit) ao editar este diretório — a suíte completa é lenta demais para iterar.'
Esses três não se contradizem totalmente, mas a regra 3 conflita de verdade com a regra 1. Como a regra 3 é anexada por último, o Codex tende a segui-la enquanto trabalha dentro de apps/web. É exatamente por isso que o arquivo mais próximo de você deve carregar instruções específicas e locais, enquanto o arquivo global/raiz deve ficar com convenções amplas e estáveis. Na prática, isso também significa que um AGENTS.md de subdiretório não consegue 'desfazer' completamente uma regra global — ele só pode adicionar uma instrução posterior e mais específica, que o agente tende a pesar mais naquele contexto.
O limite de 32 KiB — project_doc_max_bytes
O tamanho combinado de todos os arquivos AGENTS.md encontrados (não de cada arquivo individualmente) é limitado por project_doc_max_bytes, cujo padrão é 32 KiB. Segundo a documentação config-advanced, o Codex ignora arquivos vazios e para de adicionar conteúdo no momento em que o tamanho combinado atinge o limite — o que passa disso nunca entra no contexto, sem erro nem aviso no TUI.
Para aumentar o limite, adicione isto ao ~/.codex/config.toml:
project_doc_max_bytes = 65536(65536 bytes = 64 KiB é só um exemplo — defina o valor de que você realmente precisa. Não aumente 'por via das dúvidas': quanto mais longo o arquivo, mais o agente tende a exagerar em cada linha — veja o exemplo enxuto abaixo.)
| Configuração | Valor |
|---|---|
| Padrão | 32 KiB (aplica-se a todos os arquivos AGENTS.md combinados) |
| Configurado via | project_doc_max_bytes no ~/.codex/config.toml |
| Acima do limite | Para de adicionar conteúdo — sem erro, sem aviso |
| Arquivos vazios | Ignorados, não contam para o total |
A pegadinha do truncamento silencioso (um relato de bug real)
Esta é a parte que a maioria dos outros guias pula. A GitHub Issue #7138 (aberta em 22/11/2025, fechada como 'not planned') documenta exatamente isto: o AGENTS.md combinado de um usuário chegou a cerca de 40 KB, e o Codex o cortou silenciosamente para 32 KB — sem aviso no TUI, nem no /stats. A issue contrasta isso explicitamente com o Claude Code, que avisa quando um arquivo de contexto passa do orçamento.
Observação: na data em que escrevo, esta issue está fechada como 'not planned' — ou seja, o time do Codex não tem planos de adicionar um aviso. Confira o status da issue antes de citá-la; os trackers mudam.
A solução prática: não enfie toda convenção em um único AGENTS.md raiz gigante. Divida por diretório — deixe o arquivo global para as convenções amplas e faça cada subdiretório carregar só o que é relevante para ele — o que mantém você abaixo do limite de 32 KiB e combina com o que a pesquisa sobre AGENTS.md/CLAUDE.md já concluiu: arquivos longos não ajudam, só custam mais.
project_doc_fallback_filenames e CODEX_HOME
Duas configurações menores que vale conhecer se você personaliza a fundo:
project_doc_fallback_filenames: um array de nomes de arquivo alternativos que o Codex aceita em um nível de diretório quando não existe AGENTS.md ali — útil se o seu time já tem umTEAM_GUIDE.mde não está pronto para renomeá-lo. Defina no~/.codex/config.toml:project_doc_fallback_filenames = ["TEAM_GUIDE.md"].CODEX_HOME: a variável de ambiente que aponta para o diretório de configuração do Codex, padrão~/.codex. Ele guardaconfig.toml,auth.jsonehistory.jsonl— mude-a se quiser separar a configuração do Codex por perfil ou máquina (por exemplo, umCODEX_HOMEseparado por runner de CI, para que sessões automatizadas nunca toquem no seuauth.jsonpessoal).
Um AGENTS.md de verdade e enxuto que você pode usar
Aqui está o AGENTS.md raiz que eu mesma uso em um repositório Node/TypeScript — de propósito curto, porque um arquivo mais longo não faz o Codex ter um desempenho melhor (veja a pegadinha acima e a pesquisa sobre arquivos de contexto):
# Build & test
- Install: `pnpm install`
- Unit tests: `pnpm test` - e2e: `pnpm test:e2e` (Playwright, slow, run only when needed)
- Build: `pnpm build`
- Before committing: `pnpm lint && pnpm typecheck`
# Must not break
- Don't change the public API in `src/sdk/` without a major version bump.
- Never commit `.env*` files.
- Don't touch `infra/` (Terraform) outside a reviewed PR.
# Key paths
- API routes: `src/api/`
- Shared types: `src/types/`
- DB migrations: `db/migrations/` (never edit an applied migration, always add a new one)15 linhas. Nenhuma 'visão geral do projeto', nenhum texto explicativo. Cada linha é ou um comando executável ou uma regra específica de 'não pode quebrar' — exatamente a parte que a pesquisa sobre AGENTS.md vs CLAUDE.md descobriu que os agentes de fato seguem.
O AGENTS.md define as regras — o AgentKit acrescenta as skills
O AGENTS.md é uma configuração gratuita que o Codex lê nativamente — nada a instalar. Ele responde 'o que fazer / o que não fazer'. O que ele não traz são skills ou fluxos de trabalho empacotados — é isso que o AgentKit (agentkit.best, a CLI ak) acrescenta, rodando por cima do Codex, sem substituir o AGENTS.md.
Instalando o kit para o Codex: ak kit init engineer --target codex --global (adicione --global para usá-lo em todos os repositórios); depois, dentro de uma nova sessão do Codex, rode $ak:cook ... (repare na sintaxe $ak: no Codex, contra /ak: no Claude Code — a entrega no Codex é, por enquanto, apenas nativa: skills, regras, dispatch de agentes, hooks parciais; os comandos do kit ainda não estão ativos ali, e não há status line).
Sendo franca sobre a linha gratuito/pago: o AGENTS.md não custa nada. O AgentKit é um add-on pago (o Engineer Kit em torno de $99, e a loja costuma rodar -20%, caindo para cerca de $79.20 na data em que escrevo — confira o preço atual). Novo no Codex? Veja primeiro o que é o OpenAI Codex; quer saber o que o SKILL.md realmente é (diferente do AGENTS.md — uma capacidade sob demanda, não um contexto sempre carregado), veja Codex Skills explicado; quer o passo a passo de rodar o AgentKit dentro do Codex, veja AgentKit no Codex.
Quer skills empacotadas rodando por cima de um AGENTS.md enxuto? O AgentKit Engineer Kit acrescenta fluxos de trabalho/skills prontos para o Codex e o Claude Code — o seu AGENTS.md continua fazendo o trabalho básico de definir as regras.
Conheça o AgentKit Engineer Kit — 20% de desconto, agora $79.20 →
Perguntas frequentes (FAQ)
O Codex lê o CLAUDE.md?
Não. Segundo a documentação oficial, o Codex só procura e carrega arquivos AGENTS.md (e AGENTS.override.md) — não há mecanismo que leia o CLAUDE.md. Se você usa o Claude Code e o Codex no mesmo repositório, mantenha os dois arquivos (ou crie um symlink de um para o outro).
Qual é o limite de tamanho do AGENTS.md no Codex?
32 KiB por padrão, aplicado ao total combinado de todos os arquivos AGENTS.md encontrados (não a cada arquivo individualmente), via project_doc_max_bytes. Qualquer coisa acima do limite é descartada silenciosamente — sem erro, sem aviso. Você pode aumentar o limite no ~/.codex/config.toml.
Qual arquivo vence se eu tiver AGENTS.md global, na raiz do repositório e em subdiretório?
Nenhum deles 'vence' de forma absoluta — o Codex combina todos, na ordem do global até a raiz do git e descendo até o seu diretório atual. Como o arquivo mais próximo do seu diretório atual é anexado por último, geralmente são as instruções dele que prevalecem quando algo entra em conflito.
Para que serve o AGENTS.override.md?
Quando presente em um nível (global ou um diretório), o AGENTS.override.md é usado em vez do AGENTS.md naquele mesmo nível. É útil para manter um AGENTS.md compartilhado pelo time no git enquanto você adiciona overrides pessoais sem tocar no arquivo compartilhado.
O Codex me avisa se o meu arquivo for longo demais?
Não, pelo menos até a data em que escrevo. A GitHub Issue #7138 documenta um arquivo de 40 KB sendo cortado silenciosamente para 32 KB sem aviso no TUI, e está fechada como not planned. O Claude Code, em contraste, avisa quando um arquivo de contexto passa do orçamento — uma diferença que vale lembrar.
Onde o Codex guarda a sua configuração?
Dentro do diretório CODEX_HOME, padrão ~/.codex — guardando config.toml, auth.json e history.jsonl. Você pode apontar o CODEX_HOME para outro diretório pela variável de ambiente.
Conclusão
A mecânica do AGENTS.md no Codex se resume a três coisas: uma ordem de busca fixa (global e, depois, da raiz do git até o cwd), a concatenação da raiz para baixo em que o arquivo mais próximo de você vence no conflito, e um limite de 32 KiB que descarta silenciosamente o excedente — e nada disso jamais toca no CLAUDE.md. Escreva enxuto, divida por diretório em vez de empilhar um único arquivo raiz gigante, e você escapa tanto da pegadinha quanto do custo desperdiçado. Para entender por que arquivos longos não ajudam, para começar, veja AGENTS.md vs CLAUDE.md — e se arquivos longos ajudam mesmo.