AGENTS.md é um arquivo de texto no seu repositório com as instruções para os agentes de código: como instalar, como rodar os testes e quais convenções seguir. É um formato aberto que muitas ferramentas leem, como Codex, Cursor e GitHub Copilot. A ideia é ter um arquivo só de regras, não importa qual agente abra o projeto.
Uma pergunta do app. Escolha uma resposta.
Você usa dois agentes e cada um lê outro arquivo de regras. Como evitar contradições?
Funciona no primeiro dia. Depois você muda uma regra num arquivo e esquece do outro.
Fica uma fonte só: o segundo arquivo importa ou aponta para o primeiro, e o que você muda vale para os dois.
Ocupam espaço em cada mensagem e dependem de você lembrar. O arquivo existe para não repetir.
O README explica o projeto para uma pessoa; o AGENTS.md explica para um agente de código. Ali vai o que o agente não consegue adivinhar: o comando que roda os testes, a convenção de nomes, a pasta que ninguém mexe. Não tem campos obrigatórios: é Markdown comum, com os títulos que você quiser.
Num repo com várias partes, cada pasta pode ter o seu, e o agente usa o mais próximo do arquivo em que está trabalhando. O que o arquivo diz entra no prompt do modelo e ocupa espaço na janela de contexto em cada sessão, então vale deixá-lo curto. Em outubro de 2026, quem cuida do formato é a Agentic AI Foundation, dentro da Linux Foundation.
Em outubro de 2026, Codex, Cursor, GitHub Copilot, Gemini CLI e muitos outros leem AGENTS.md. O Claude Code nasceu lendo o próprio CLAUDE.md, e as versões recentes também leem AGENTS.md, mas com uma condição: por padrão, só se o projeto não tiver um CLAUDE.md. Se os dois estiverem lá, ele lê o CLAUDE.md e deixa o AGENTS.md de fora, a menos que você mude essa opção na configuração.
O contrário é parecido: o Codex não lê CLAUDE.md a menos que você configure. Por isso, se sua equipe usa várias ferramentas, não basta ter os dois arquivos: é preciso decidir qual manda.
O mais simples: as regras ficam no AGENTS.md e o CLAUDE.md só o importa com uma única linha: @AGENTS.md. O Claude Code lê primeiro o importado e depois o que você colocar embaixo, que fica para o que é só do Claude. Assim você muda uma regra num lugar e vale para todos.
Outra opção é o CLAUDE.md ser um link simbólico para o AGENTS.md. Funciona, mas se alguém da equipe usa Windows o link pode chegar como um arquivo de uma linha. E se uma instrução longa serve só para uma tarefa, como publicar uma versão, costuma ficar melhor numa skill, que é carregada quando precisa.
@AGENTS.md
## Claude Code
Use plan mode for changes under src/billing/."Se tenho os dois arquivos, o Claude lê os dois." Por padrão, não: ele lê o CLAUDE.md. "Escrevo no CLAUDE.md 'leia também o AGENTS.md' e pronto." Assim o agente só abre se decidir; a importação com @ carrega sempre. "Copio as regras nos dois." Funciona até o dia em que você muda uma e esquece a outra.