CLAUDE.md vs .cursorrules vs AGENTS.md
Três formatos para orientar agentes e IDEs. A diferença não é só nome: é quem lê o arquivo e em qual ferramenta ele tem prioridade.
CLAUDE.md
Melhor para: Fluxo Anthropic / Claude Code; instruções globais do repo.
Atenção: Outras IAs podem ignorar se o produto não integrar.
.cursorrules
Melhor para: Cursor: regras injetadas no contexto do projeto.
Atenção: Específico do ecossistema Cursor; duplicar regra se o time usa várias IDEs.
AGENTS.md
Melhor para: Documentação para humanos + agentes em monorepos e padrões de comunidade.
Atenção: Menos “mágico” que rules automáticas; depende de você apontar o arquivo.
Veredito
Use um arquivo canônico de verdade (AGENTS.md ou README de contribuição) e espelhe o mínimo em CLAUDE.md e .cursorrules onde a ferramenta exige. Evite três versões divergentes.
Artigos relacionados
Perguntas frequentes
Qual é melhor: CLAUDE.md ou .cursorrules?
Depende da IDE. No Cursor, .cursorrules costuma ter efeito direto. No Claude Code, CLAUDE.md. Para equipe mista, mantenha AGENTS.md como fonte única e sincronize trechos.
Posso ter os três arquivos no mesmo repositório?
Sim, desde que não contradizam. Documente qual arquivo manda em caso de conflito e revise quando mudar stack.
AGENTS.md substitui documentação humana?
Não. Ele resume expectativas para devs e agentes. Documentação de produto e ADRs continuam valendo para decisões arquiteturais.