CLAUDE.md e AGENTS.md no mesmo projeto: como não manter dois arquivos

Resposta curta: mantenha um arquivo como fonte e o outro como ponteiro para ele. Os dois agentes de IA leem o mesmo conteúdo, você edita num lugar só, e nenhum deles trabalha com uma versão velha das regras. Duplicar o texto funciona por duas semanas e depois vira a origem de erros que parecem aleatórios.

O Claude Code lê CLAUDE.md. O Codex lê AGENTS.md. Se você usa os dois no mesmo projeto, tem dois arquivos dizendo como trabalhar no seu código, e nada obriga os dois a dizerem a mesma coisa.

Por que dois arquivos divergentes custam caro

O problema não é a duplicação em si, é o silêncio dela. Você acrescenta uma regra nova (não mexer nesta pasta, sempre rodar aquele comando antes de commitar) no arquivo que estava aberto, e esquece o outro. Duas semanas depois um agente de IA faz exatamente o que a regra proibia, e a mensagem de erro não diz "eu li a versão antiga do seu arquivo de instruções". Ela diz outra coisa qualquer, e você procura no lugar errado.

Quanto mais específicas as suas regras, pior fica. Regras genéricas convergem sozinhas; regras de projeto, não.

Como manter os dois sem duplicar o texto

Escolha um arquivo para ser a fonte e faça o outro apontar para ele. Um AGENTS.md de três linhas resolve:

# Instruções do projeto\n\nAs regras deste repositório estão em CLAUDE.md. Leia aquele arquivo\nantes de qualquer coisa e siga o que estiver lá.

Funciona porque as duas ferramentas leem arquivo do repositório sob demanda: o agente abre o apontado e segue. Você passa a ter um lugar para editar, e a pergunta "qual dos dois está certo?" deixa de existir.

Link simbólico funciona?

Funciona, e é a solução mais enxuta se o seu time é todo Unix: ln -s CLAUDE.md AGENTS.md e os dois passam a ser o mesmo arquivo. A ressalva é Windows, onde link simbólico depende de permissão e o Git precisa estar configurado para preservá-lo. Se alguém do time clona no Windows sem isso, o arquivo vira um texto de uma linha com o caminho dentro, e o agente de IA lê aquilo como se fossem as instruções.

O ponteiro em texto não tem esse risco e custa três linhas. É o que preferimos.

O que escrever nesse arquivo

A parte que muda o resultado não é o formato, é o conteúdo. O que rende, na nossa experiência com seis agentes de IA no mesmo repositório:

• O que NÃO tocar, com o motivo junto. "Não edite este arquivo" é ignorado; "não edite este arquivo porque ele é gerado por X e sua mudança some no próximo build" é obedecido.
• O comando que prova que está pronto. Um agente sem critério de conclusão entrega quando acha que acabou. Com o comando escrito, ele roda e conserta antes de te chamar.
• Como o trabalho é isolado, se você roda mais de um agente ao mesmo tempo. Sem isso, dois agentes editam o mesmo arquivo e o trabalho de um some.

E se as regras precisarem ser diferentes por ferramenta?

Acontece, e é o único caso em que dois arquivos separados se justificam: quando a instrução é sobre a própria ferramenta, não sobre o projeto. Nesse caso mantenha o ponteiro para as regras comuns e acrescente só o trecho específico embaixo. O que não pode é a regra de projeto viver duplicada nos dois.

Isso vale para outros agentes de IA?

Vale, e a tendência é piorar antes de melhorar: cada ferramenta nova traz o próprio nome de arquivo. A estratégia de um arquivo fonte com ponteiros escala para quantos aparecerem, porque o custo de adicionar mais um é três linhas, e não uma cópia do seu manual inteiro.

Como saber que os dois estão sendo lidos

Pergunte ao agente. Um "quais instruções deste projeto você carregou?" no começo da sessão responde em um segundo, e é mais confiável do que supor. Vale especialmente depois de mexer na estrutura de pastas: arquivo de instrução em subdiretório nem sempre é encontrado de onde a ferramenta foi aberta.