AGENTS.md e CLAUDE.md: dá para manter um só arquivo de regras para Claude Code e Codex?

Dois agentes no mesmo repositório, dois manuais, e em duas semanas eles já não contam a mesma história

É o cenário mais comum hoje: metade do time roda Claude Code, a outra metade roda Codex, cada ferramenta procura instrução no lugar dela, e ninguém lembra de atualizar os dois arquivos ao mesmo tempo

Aí um agente respeita o padrão de commit e o outro não, um sabe qual comando roda os testes e o outro inventa, e a culpa cai na IA quando o problema era documentação divergente

Neste post eu mostro como eleger UM arquivo como fonte da verdade e fazer o outro agente apontar pra ele, usando só o que a documentação de cada ferramenta descreve

O que você precisa antes de começar

Nada de exótico, mas confere esses pontos antes:

• Um repositório com raiz Git: o Codex procura as instruções partindo da raiz do projeto (tipicamente a raiz do Git) e vai descendo até o diretório de trabalho atual. Sem raiz de projeto, ele olha só o diretório atual
• Claude Code e Codex instalados na máquina, cada um com uma sessão que você consiga abrir e fechar pra testar
• Acesso ao ~/.codex/config.toml, caso você vá pelo caminho alternativo lá do final

Aviso pra quem está no Windows: existe a solução por symlink, ligando um arquivo no outro

Porém criar symlink no Windows exige privilégio de Administrador ou o Modo Desenvolvedor ligado, e a própria documentação recomenda usar a importação @AGENTS.md nesse caso

Então é o caminho da importação que eu sigo aqui 🙂

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Como manter um único arquivo de regras para Claude Code e Codex

Antes do passo a passo, vale entender o PORQUÊ, senão o passo 2 parece burocracia

Cada agente tem um lugar próprio pra buscar instrução, e nenhum dos dois enxerga o arquivo do outro por padrão:

Se liga que o conflito não é filosófico, é de caminho de arquivo

A solução é ter um arquivo com o conteúdo e outro que só aponta pra ele

1. Escreva as regras no AGENTS.md da raiz

O AGENTS.md é Markdown padrão, sem exigência de títulos ou seções específicas, então escreve do jeito que o time entende

# AGENTS.md

## Stack
Next.js, TypeScript, Drizzle, Postgres

## Comandos
- `npm run dev` sobe o ambiente local
- `npm run test` roda a suíte antes de qualquer PR

## Regras
- Nada de `any` em código novo
- Migration nunca é editada depois de aplicada

O erro comum deste passo: procurar um esquema oficial de headings pra seguir. Não existe, o formato é Markdown comum e o que manda é a clareza pro agente

2. Crie o CLAUDE.md na raiz importando esse arquivo

A documentação oficial do Claude Code orienta exatamente isso pra repositório que já usa AGENTS.md: criar um CLAUDE.md com a importação, em vez de duplicar as instruções

# CLAUDE.md

As regras do projeto vivem no AGENTS.md

@AGENTS.md

Pronto, os dois agentes leem o mesmo texto

O erro comum deste passo: assumir que o Codex leria o CLAUDE.md sozinho e pular o AGENTS.md. Ele não lê por padrão, o fallback dele vem como lista vazia

3. Entenda como o caminho da importação é resolvido

A sintaxe é @caminho/do/arquivo, e aceita caminho relativo e absoluto

O detalhe que pega gente: o relativo é resolvido em relação ao ARQUIVO que contém a importação, não ao diretório de trabalho

# .claude/CLAUDE.md

@../AGENTS.md

Ou seja, se você optou por .claude/CLAUDE.md em vez do CLAUDE.md na raiz, o @AGENTS.md sozinho procuraria dentro de .claude/

O erro comum deste passo: escrever o caminho pensando de onde você chamou o terminal. Pensa a partir do arquivo, sempre

4. Valide abrindo uma sessão nova

Os arquivos importados são expandidos e carregados no contexto na abertura da sessão, junto do CLAUDE.md que referencia eles

Então editar o AGENTS.md com a sessão aberta não te dá garantia nenhuma: fecha, abre de novo e pergunta pro agente qual comando roda os testes

O erro comum deste passo: achar que quebrar tudo em importações economiza contexto. Não economiza. Dividir organiza o material, mas o conteúdo importado entra no contexto do mesmo jeito no lançamento

Esse cuidado de validar em sessão nova é o mesmo que vale pra padronizar o agente entre vários devs do repositório: se não abriu sessão limpa, você não testou nada

Alternativa: fazer o Codex ler outro nome de arquivo

E se o teu repositório já tem TUDO escrito no CLAUDE.md e ninguém quer mexer?

Dá pra ir pelo caminho oposto

A opção project_doc_fallback_filenames define nomes alternativos pro Codex quando não existe AGENTS.md naquele diretório, e o padrão dela é lista vazia

1. Abra o ~/.codex/config.toml, que é onde essa configuração mora

2. Declare o nome alternativo

project_doc_fallback_filenames = ["CLAUDE.md"]

3. Reinicie o Codex, porque a configuração atualizada só vale depois disso

O erro comum deste passo: salvar o config, continuar na mesma sessão e concluir que "não funciona"

Duas coisas pra ter na cabeça antes de escolher esse caminho

Em cada diretório do trajeto, o Codex checa AGENTS.override.md, depois AGENTS.md, depois os nomes do fallback, e inclui no máximo um arquivo por diretório

Ou seja: o fallback só entra em cena quando não há AGENTS.md ali. Se você deixar os dois arquivos no mesmo diretório, o CLAUDE.md simplesmente não é lido, e aí você tem a ilusão de fonte única com dois textos vivos

Por que os dois arquivos divergem (e como evitar)

A divergência quase nunca é dramática. Ela é silenciosa, e você só descobre quando um agente faz besteira que o outro não faria

Mapeei as armadilhas mais comuns:

O agente lê um arquivo que ninguém atualiza:

Sintoma: o Claude Code segue um padrão antigo que o time abandonou mês passado

Causa: existem dois documentos de verdade, e a regra nova entrou só em um

Solução: um arquivo canônico com conteúdo, o outro só com o ponteiro @AGENTS.md. Se o segundo arquivo tem parágrafo de regra dentro dele, você já perdeu a fonte única

A regra da subpasta atropela a da raiz:

Sintoma: dentro de packages/api o Codex ignora um padrão que está na raiz

Causa: ele concatena os arquivos da raiz para baixo e, em caso de instruções conflitantes, o arquivo mais próximo do diretório de trabalho prevalece

Solução: hierarquia consciente. Arquivo de subpasta trata do que é específico daquele pacote, e não repete (nem contradiz) o que já está na raiz

O material é cortado no meio:

Sintoma: parte das instruções parece não existir pro Codex

Causa: ele para de somar arquivos quando o tamanho combinado atinge o limite de project_doc_max_bytes, que tem padrão de 32 KiB

Solução: arquivo enxuto. Manual de regras não é documentação de produto, é o essencial que o agente precisa obedecer

O arquivo existe, mas está vazio:

Sintoma: você criou o AGENTS.md na subpasta como "placeholder" e nada acontece

Causa: o Codex ignora arquivos vazios

Solução: ou o arquivo diz alguma coisa, ou ele não precisa existir

A cadeia de importações passa de cinco saltos:

Sintoma: no Claude Code, um trecho lá no fim da corrente some do contexto

Causa: arquivos importados podem importar outros de forma recursiva, mas com profundidade máxima de cinco saltos

Solução: corrente rasa. Um CLAUDE.md que importa o AGENTS.md que importa mais um ou dois arquivos já cobre quase todo caso real. Se você precisou de cinco níveis, o problema virou arquitetura de documento

Tem um caso que é primo desse aqui e vale separar na cabeça: quando o que você quer distribuir não é regra escrita, e sim compartilhar skills com o time, a discussão muda de lugar

Quando vale um arquivo só e quando vale separar

Fonte única é o padrão, não o dogma

Monorepo com regras por pacote: aqui separar é a jogada certa. O Codex varre da raiz do projeto até o diretório atual e o Claude Code monta o contexto por importação, então regra geral fica na raiz e regra de pacote fica no pacote. Só lembra da precedência: no conflito, quem está mais aninhado ganha no Codex

Preferência pessoal que não pertence ao repositório: aquele teu jeito de pedir explicação, teu idioma, teu estilo de commit. Isso não vai pro arquivo versionado. No Claude Code o lugar é o ~/.claude/CLAUDE.md, e no Codex o escopo global fica no diretório home dele (por padrão ~/.codex, ou o que estiver em CODEX_HOME), onde ele usa apenas o primeiro arquivo não vazio daquele nível

Regra específica de um agente só: se a instrução só faz sentido pra uma das ferramentas, ela merece um trecho próprio em vez de poluir o arquivo canônico. Fonte única é sobre a regra do PROJETO, não sobre detalhe de operação de uma ferramenta

O que rodar Codex de verdade mostrou sobre regras de projeto

Eu vivi na prática o motivo de tudo isso importar

No vídeo abaixo eu coloco duas ferramentas de IA lado a lado construindo o MESMO app, com 5 prompts idênticos de cada lado: setup com autenticação, upload de PDF, integração com IA, dashboard, e a landing page com polimento

Antes de disparar o primeiro prompt, eu criei um arquivo de regras em Markdown pra parametrizar o projeto: análise do projeto, stack utilizada, regras que o projeto precisa seguir e os comandos que o projeto deve rodar

E aí veio a parte que interessa pro tema daqui

Pra comparação ficar justa, eu não deixei cada ferramenta gerar o arquivo dela

Eu copiei manualmente o arquivo pra pasta do outro projeto, abri e conferi na tela que os dois eram idênticos, caractere por caractere

Porque prompt igual só é comparação justa quando as instruções de projeto são as mesmas dos dois lados. Se cada agente parte de um manual diferente, você não está comparando ferramenta, está comparando documentação

E tem mais: mesmo achando que a ferramenta leria o arquivo sozinha, eu referenciei o arquivo de regras explicitamente dentro do prompt, usando a marcação de arquivo de cada uma

Desconfiança saudável, e é a mesma desconfiança que eu recomendo aqui: valida em sessão nova, pergunta pro agente qual é o comando dos testes, não confia no "deve estar lendo"

Outro hábito meu que entrou no teste: eu mantenho um bloco fixo no fim de todo prompt delimitando escopo (não criar upload, não criar formulários, nada além do que foi pedido), porque num vídeo anterior as ferramentas extrapolaram feio o pedido

Um comentarista me cutucou dizendo que eu elogiei um tema claro/escuro que eu nem tinha pedido, e ele tem razão: ganhar recurso não solicitado nem sempre é ponto positivo 😅

Sobre consumo, que é a dúvida que sempre aparece: o plano Pro do Codex, entre os testes e a gravação do curso, não chegou a 50% da cota, nem na janela de 4 horas nem no semanal

Um ponto de honestidade: eu tenho muito mais vivência com uma das ferramentas do que com a outra, e isso pesa na minha percepção

No quesito criar o arquivo de regras, inclusive, a vantagem não ficou com o Codex: criar o arquivo direto pelo editor (botão direito, novo arquivo, salvar) foi mais simples do que abrir um editor separado ou pedir pro próprio agente gerar

Por que o AGENTS.md virou o formato comum

Se você vai eleger um arquivo canônico, a pergunta óbvia é: por que o AGENTS.md e não o CLAUDE.md?

O AGENTS.md é um formato aberto pra orientar agentes de código, e é usado por mais de 60 mil projetos de código aberto

Ele também foi uma das contribuições fundadoras da Agentic AI Foundation, formada pela Linux Foundation em dezembro de 2025, ao lado do MCP e do goose

Ou seja: não é convenção de uma ferramenta só, é um formato com governança aberta e adoção larga

Somando com o fato de a própria documentação do Claude Code sugerir o CLAUDE.md importando o AGENTS.md, a conta fecha: conteúdo no AGENTS.md, ponteiro no CLAUDE.md

Conclusão

A decisão é mais simples do que parece: escolhe UM arquivo canônico, faz o outro agente apontar pra ele, e mantém o texto curto o bastante pra caber nos limites

Tudo que você precisa lembrar cabe em quatro linhas:

• Claude Code lê o CLAUDE.md e não lê o AGENTS.md como memória nativa
• Codex não lê o CLAUDE.md por padrão, porque project_doc_fallback_filenames vem vazio
• A ponte oficial é o CLAUDE.md com @AGENTS.md dentro (e no Windows ela evita a dor do symlink)
• Importação organiza, mas não economiza contexto, então arquivo enxuto continua sendo obrigação

Próximo passo prático, pra fazer agora: abre o repositório, consolida as regras no AGENTS.md, cria o CLAUDE.md com a importação e testa em sessão NOVA nos dois agentes, perguntando pra cada um qual comando roda os testes

Se os dois responderem igual, acabou a divergência 😀

até o próximo post!