Cursor Rules vs CLAUDE.md vs AGENTS.md: Passei Uma Config pelos Três (2026)

Cursor Rules vs CLAUDE.md vs AGENTS.md: Passei Uma Config pelos Três (2026)

A pergunta cursor rules vs claude md tem uma armadilha incorporada: não são duas opções entre as quais escolher. São dois ficheiros, lidos por duas ferramentas diferentes, que por acaso fazem o mesmo trabalho. Coloca um CLAUDE.md num projeto Cursor e o Cursor ignora-o. Coloca um AGENTS.md no Claude Code e também não acontece nada. Isso também nos surpreendeu. O AGENTS.md está agora presente em mais de 60.000 repositórios como o padrão aberto, gerido pela Agentic AI Foundation sob a alçada da Linux Foundation, mas o Claude Code continua sem o ler por si só. Aqui está o mapa de compatibilidade, testado no nosso repositório.

Principais Conclusões

• O Cursor lê .cursor/rules/*.mdc e AGENTS.md, não CLAUDE.md.
• O Claude Code lê apenas CLAUDE.md, não AGENTS.md nativamente.
• Para partilhar um ficheiro: cria um symlink de AGENTS.md para CLAUDE.md, ou importa-o com @AGENTS.md.
• Adota o AGENTS.md como padrão (padrão aberto, mais de 60k repositórios) e acrescenta overrides específicos por ferramenta.

Que Formato de Config Deves Usar? A Decisão em 30 Segundos

Escolhe o formato pela forma da equipa, não pelo hype. Se usas uma ferramenta, usa o ficheiro nativo dela. Se usas duas ou mais, adota o AGENTS.md como fonte de verdade e adiciona overrides por ferramenta apenas onde uma precisar de algo que as outras não precisam. Esta única regra resolve a maior parte da confusão.

Ainda estás a decidir que assistente usar antes de te preocupares com a config dele? Começa pelo nosso guia sobre como escolher que agente de programação com IA usar e depois volta para a configuração dos ficheiros.

O eixo de decisão que importa é a portabilidade. Um ficheiro .cursor/rules é poderoso dentro do Cursor e inútil em qualquer outro lado. Um AGENTS.md viaja. Por isso, a menos que estejas preso a uma ferramenta para sempre, o ficheiro independente da ferramenta é a aposta mais segura.

O Que Cada Formato Realmente É (em 30 Segundos Cada)

Estes três ficheiros fazem todos a mesma coisa: entregar a uma ferramenta de programação com IA as regras, convenções e rasteiras do teu projeto antes de ela escrever uma linha. A diferença está em quem os lê e como definem o âmbito. Aqui está a versão curta. As instruções aprofundadas de cada formato estão no respetivo guia.

Cursor Rules são ficheiros .mdc dentro de .cursor/rules/. O Cursor suporta quatro tipos de regras (sempre ativas, pedidas pelo agente, com âmbito por glob e menção manual com @), por isso podes anexar uma regra apenas aos teus ficheiros *.tsx ou apenas às tuas migrations. Para o frontmatter, os globs e o orçamento de tokens, lê o nosso guia sobre como escrever realmente ficheiros .cursor/rules.

CLAUDE.md é o ficheiro de memória do Claude Code. O Claude sobe a árvore de diretórios a partir da tua pasta de trabalho e concatena todos os CLAUDE.md que encontra. É Markdown simples, sem frontmatter obrigatório. Para a estrutura e as regras que impedem o Claude de o ignorar, vê o que faz um CLAUDE.md que o Claude não ignora.

AGENTS.md é o padrão aberto. Um ficheiro de Markdown simples na raiz do teu repositório, lido nativamente pelo Cursor, Codex, Copilot, Windsurf, Zed, Aider e dezenas de outros. É gerido pela Agentic AI Foundation e já está presente em mais de 60.000 projetos.

Aqui está a mudança de perspetiva que vale a pena reter: AGENTS.md, CLAUDE.md e .cursor/rules não são concorrentes, são a mesma instrução, dirigida a leitores diferentes.

Cursor Rules vs CLAUDE.md vs AGENTS.md: A Comparação Definitiva

A forma mais rápida de ver a diferença é lado a lado. A coluna decisiva é a portabilidade: que ferramentas leem o ficheiro sem configuração extra. O AGENTS.md ganha em alcance, os Cursor Rules ganham em precisão de âmbito e o CLAUDE.md ganha para quem está totalmente dedicado ao Claude Code.

Repara na linha do .cursorrules. Esse ficheiro único na raiz ainda funciona no Cursor, mas saiu da documentação, por isso trata-o como legado. Projetos novos devem usar .cursor/rules/*.mdc ou AGENTS.md em vez disso.

Que Ferramenta Lê Que Ficheiro? (Desmistifica o Mito do AGENTS.md)

Aqui está o facto que metade da internet entende mal: o Claude Code não lê AGENTS.md nativamente, e o Cursor não lê CLAUDE.md. O Cursor lê .cursor/rules/*.mdc mais AGENTS.md. O Claude Code lê CLAUDE.md e nada mais. Não há fallback automático em nenhuma direção, o que faz tropeçar equipas que assumem que um único ficheiro padrão cobre tudo.

Isto é perguntado constantemente, por isso vamos ser diretos. Colocar um AGENTS.md num projeto Claude Code não faz nada por si só. O Claude Code lê CLAUDE.md e apenas CLAUDE.md. A documentação de memória do Claude Code da Anthropic descreve o comportamento de carregamento de ficheiros sem qualquer menção ao AGENTS.md, a especificação do AGENTS.md lista o Cursor e o Codex entre os leitores nativos, mas não o Claude Code, a própria documentação de regras do Cursor confirma a separação, e as issues do Claude Code no GitHub estão cheias de developers a bater exatamente nesta parede.

Então o Cursor lê claude.md? Não. O Claude Code lê agents.md? Não sem ajuda. Essa "ajuda" é a razão de ser deste artigo, e são dois comandos curtos que vais ver a seguir.

Como Funcionam a Precedência e o Aninhamento, Lado a Lado

Cada ferramenta resolve conflitos de forma diferente, e errar nisto é a principal fonte da confusão "porque é que a minha regra está a ser ignorada?". O Cursor funde as regras por prioridade da fonte. O Claude Code concatena por profundidade de diretório. O AGENTS.md escolhe o ficheiro mais próximo na árvore. Uma boa claude md management começa por saber em que modelo mental estás.

Na nossa configuração, a conclusão prática é simples: coloca as regras amplas no topo (raiz do repositório) e as regras específicas em baixo (dentro da pasta de um pacote). Tanto para o Claude Code como para o AGENTS.md, o ficheiro mais próximo de onde estás a trabalhar tem prioridade, por isso um packages/api/AGENTS.md sobrepõe-se ao da raiz para tudo o que estiver dentro dessa pasta. O Cursor é o caso à parte, resolvendo por nível de fonte em vez de profundidade de pasta.

Testámos Uma Config no Cursor + Claude Code — Aqui Está o Que Cada Ferramenta Realmente Carregou

Testámos isto num repositório real de um cliente da Techsy (um backend Next.js 15) usando o Cursor 3.7 (build de 17 de junho de 2026) e o Claude Code v2.1.x (início de julho de 2026). Um AGENTS.md, três configurações de partilha, o mesmo prompt aberto em ambas as ferramentas. Aqui está exatamente o que cada uma puxou.

Começámos com um ficheiro mínimo:

# AGENTS.md
- Package manager: pnpm, never npm.
- Tests: Vitest. Run `pnpm test` before any commit.
- DB access goes through `lib/db.ts` only, no inline SQL.

Configuração 1: AGENTS.md sozinho. O Cursor captou-o de imediato. O ficheiro apareceu no seu contexto e recusou corretamente sugerir npm install. O Claude Code não fez nada com ele. Correr /memory no Claude Code listou zero ficheiros de memória de projeto: nenhum CLAUDE.md encontrado, e o AGENTS.md nem sequer foi reconhecido. Confirmado: sem fallback nativo.

Configuração 2: symlink. Apontámos o CLAUDE.md para o mesmo ficheiro:

ln -s AGENTS.md CLAUDE.md

Agora, /memory no Claude Code listava ./CLAUDE.md como memória de Projeto, e o conteúdo carregado era o nosso AGENTS.md byte a byte. O Cursor continuava a ler AGENTS.md diretamente. Um ficheiro físico, ambas as ferramentas satisfeitas. No Windows, isto requer o modo Admin ou Developer Mode ativado, senão o ln/mklink falha silenciosamente.

Configuração 3: @import. Eliminámos o symlink e, em vez disso, colocámos uma única linha no topo de um CLAUDE.md real:

@AGENTS.md

O /memory mostrava então o CLAUDE.md como o ficheiro carregado, com o AGENTS.md puxado como uma referência importada por baixo dele. Este é o caminho que a Anthropic realmente documenta, e não requer permissões especiais do SO.

O veredito do nosso teste: o symlink faz o Claude Code ler o AGENTS.md byte a byte; o import @AGENTS.md é a versão segura para Windows que a Anthropic realmente recomenda. Ambos dão-te uma única fonte de verdade. Escolhe o symlink no macOS/Linux para zero indireção, ou a linha de import se alguém na equipa estiver no Windows.

Migrar Entre Formatos: .cursorrules → .cursor/rules → AGENTS.md

A maioria das equipas chega aqui com um ficheiro .cursorrules legado e quer sair da armadilha do ficheiro único. A migração é curta em todas as direções, e os passos são copy-paste. A única rasteira que apanha as pessoas: um ficheiro .md dentro de .cursor/rules sem frontmatter é silenciosamente ignorado, por isso tem de ser .mdc.

Para modernizar um .cursorrules antigo, tens dois caminhos limpos:

• Para .cursor/rules/*.mdc: cria .cursor/rules/general.mdc, adiciona frontmatter (alwaysApply: true para uma regra global) e cola o teu conteúdo antigo por baixo. Elimina o .cursorrules depois de confirmado.
• Para AGENTS.md (recomendado para equipas com várias ferramentas): para converter cursorrules em agents.md, copia o corpo do .cursorrules para um novo AGENTS.md na raiz do teu repositório. Não é preciso frontmatter; é Markdown simples. Depois adiciona o symlink ou o import @AGENTS.md para que o Claude Code também o leia.

Se vais ficar dentro do Cursor e queres tirar mais partido dele, o nosso guia sobre como tirar mais partido do Cursor no dia a dia cobre a definição de âmbito das regras na prática.

Ir no outro sentido (AGENTS.md → CLAUDE.md) é apenas o symlink ou o import da secção anterior. Não há conversão com perdas, porque os três são Markdown por baixo.

Onde Encaixam o SKILL.md e as Instruções do Copilot?

Mais dois formatos aparecem nesta conversa, e skills md é uma pesquisa em ascensão neste momento, por isso vale a pena um enquadramento rápido. Nenhum substitui os três ficheiros principais; colocam-se ao lado deles.

SKILL.md é o formato Skills da Anthropic: instruções específicas de tarefa agrupadas em .claude/skills/*/SKILL.md que o Claude carrega a pedido quando uma tarefa corresponde, em vez de estar sempre ativo como o CLAUDE.md. Pensa nele como um playbook especializado a que o Claude recorre, não como um ficheiro de memória de todo o projeto. O âmbito ainda está a evoluir, por isso não invistas demasiado já. Para veres como encaixa num fluxo de trabalho real, vê onde o CLAUDE.md encaixa num fluxo de trabalho real do Claude Code.

As instruções do Copilot ficam em .github/copilot-instructions.md para o GitHub Copilot. Boa notícia: o Copilot também lê AGENTS.md, por isso se padronizaste no padrão aberto, o Copilot já está coberto sem um ficheiro separado.

Qual Deves Usar? (Por Tipo de Equipa)

Adequa o formato à forma como a tua equipa realmente trabalha:

• Utilizador a solo do Claude Code: usa simplesmente CLAUDE.md. Não há razão para adicionar o AGENTS.md a menos que planeies trazer o Cursor ou o Codex mais tarde.
• Utilizador a solo do Cursor: .cursor/rules/*.mdc para o âmbito por glob, ou um único AGENTS.md se queres portabilidade desde o primeiro dia.
• Equipa com várias ferramentas: um AGENTS.md como fonte de verdade, com symlink ou importado para o CLAUDE.md. Adiciona um pequeno ficheiro .cursor/rules apenas para comportamento específico do Cursor.
• Monorepo: AGENTS.md na raiz mais ficheiros aninhados por pacote, para que cada subprojeto se descreva a si próprio e o ficheiro mais próximo ganhe.

Na Techsy, padronizamos a config de programação com IA em equipas com várias ferramentas, geralmente um AGENTS.md como fonte de verdade com overrides por ferramenta onde uma ferramenta precise deles. Se a tua equipa está a fazer malabarismo com três ficheiros de config à mão, marca uma consulta gratuita e nós traçamos o plano.

Um último apontamento: este artigo compara os ficheiros de config. Se estás realmente a tentar decidir entre as próprias ferramentas, lê comparar os próprios assistentes, não a sua config.

Sobre o Autor

Mert Batur Gurbuz é Co-Fundador da Techsy.io, onde a equipa entrega agentes de IA, sistemas de automação e pipelines de voz/SDR para clientes B2B. Estuda na Universidade de Birmingham e escreve sobre a stack de ferramentas de LLM que a equipa da Techsy realmente usa em produção.

Co-Fundador, Techsy.io · Universidade de Birmingham · LinkedIn

Perguntas Frequentes

O Cursor lê CLAUDE.md?

Não. O Cursor lê .cursor/rules/*.mdc e AGENTS.md nativamente, mas o CLAUDE.md nunca é mencionado na documentação do Cursor e não é carregado. Se estás no Cursor e queres partilhar config com utilizadores do Claude Code, coloca as tuas regras em AGENTS.md (que o Cursor lê) em vez de CLAUDE.md.

O Claude Code lê AGENTS.md?

Não nativamente. O Claude Code lê apenas CLAUDE.md, sem fallback automático para AGENTS.md. Para que funcione, ou faz um symlink dos ficheiros (ln -s AGENTS.md CLAUDE.md) para que o Claude leia o AGENTS.md byte a byte, ou adiciona @AGENTS.md na linha 1 de um CLAUDE.md para o importar. O import é a opção recomendada pela Anthropic e segura para Windows.

Posso usar apenas um ficheiro para as três ferramentas?

Sim. Adota o AGENTS.md como a tua única fonte de verdade, e o Cursor e o Codex leem-no diretamente. Para o Claude Code, adiciona uma ponte: ou faz symlink de AGENTS.md para CLAUDE.md, ou coloca @AGENTS.md no topo de um CLAUDE.md. Manténs um ficheiro, e todas as ferramentas carregam as mesmas regras. Esta é a receita completa para partilhar uma config.

O .cursorrules está descontinuado?

Semi-descontinuado. O ficheiro único .cursorrules na raiz do teu repositório ainda funciona no Cursor, mas já não está na documentação oficial, o que é o sinal habitual de que um formato está a cair em desuso. Projetos novos devem usar .cursor/rules/*.mdc para regras com âmbito ou AGENTS.md para portabilidade.

Como converto .cursorrules para AGENTS.md?

Copia o corpo do teu ficheiro .cursorrules para um novo AGENTS.md na raiz do teu repositório. É Markdown simples, por isso não é preciso frontmatter nem reformatação. Depois adiciona um symlink ou um import @AGENTS.md para que o Claude Code também o leia, e elimina o .cursorrules antigo depois de confirmares que o Cursor capta o novo ficheiro.

Qual é a diferença entre CLAUDE.md e AGENTS.md?

O CLAUDE.md é o ficheiro de memória proprietário do Claude Code, lido apenas pelo Claude Code. O AGENTS.md é um padrão aberto lido pelo Cursor, Codex, Copilot e mais de 20 outras ferramentas, mas não pelo Claude Code nativamente. O mesmo formato Markdown, a mesma função. A diferença é o alcance. O AGENTS.md viaja entre ferramentas; o CLAUDE.md fica dentro do Claude Code.

Que formato deve uma equipa que usa várias ferramentas de IA adotar como padrão?

AGENTS.md. É o padrão aberto, lido nativamente pela maioria das ferramentas e já presente em mais de 60.000 repositórios. Padroniza aí as tuas regras partilhadas, faz a ponte para o Claude Code com um symlink ou import, e adiciona pequenos ficheiros específicos de ferramenta (como .cursor/rules) apenas onde uma ferramenta precisa de um comportamento que as outras não precisam.

Como funciona a precedência quando tenho ficheiros de config aninhados?

Tanto para o Claude Code como para o AGENTS.md, o ficheiro mais próximo do teu diretório de trabalho ganha, por isso uma regra em packages/api/AGENTS.md sobrepõe-se ao ficheiro da raiz do repositório para tudo o que estiver dentro dessa pasta. O Cursor é diferente: funde as regras de Equipa, Projeto e Utilizador por nível de fonte em vez de profundidade de pasta, com as fontes anteriores a vencer os conflitos.

Onde encaixa o SKILL.md?

O SKILL.md é o formato Skills emergente da Anthropic: instruções específicas de tarefa em .claude/skills/*/SKILL.md que o Claude carrega a pedido quando uma tarefa corresponde, em vez de estar sempre ativo como o CLAUDE.md. Complementa o CLAUDE.md em vez de o substituir. O âmbito ainda está a evoluir em 2026, por isso trata-o como um complemento especializado, não como um quarto ficheiro de que todos os projetos precisam.