Como partilhar instruções entre Claude Code, Codex e Cursor com AGENTS.md e CLAUDE.md em 2026

Para obter informações sobre o serviço, consulte a documentação da Ailoot.

O que muda quando utiliza Claude Code, Codex e Cursor em conjunto?#

No exemplo descrito, Claude Code é a ferramenta principal, enquanto Codex e Cursor são utilizados para tarefas específicas. O meu CLAUDE.md tem cerca de 250 linhas de instruções: o que ler e por que ordem, no que não se deve tocar, que comandos utilizar para a implementação e as regras de formatação dos commits. Quando experimentei pela primeira vez o Codex CLI no projeto, não conhecia nenhuma das regras: executou git push --force, mexeu no .env e mudou nomes de ficheiros sem cuidado.

Comecei por copiar manualmente o CLAUDE.md para AGENTS.md. Duas semanas depois, descobri que o projeto já tinha quatro versões das mesmas instruções: em CLAUDE.md, AGENTS.md, .cursorrules e .windsurf/rules/. Todas eram ligeiramente diferentes. Isto não é um problema do Claude nem do Cursor; é a armadilha básica de qualquer sistema com várias fontes de verdade. Abordo o problema com mais detalhe no guia sobre trabalho com vários agentes.

Em junho de 2026, a documentação de memória do Claude Code da Anthropic apresentou uma resposta: um ficheiro partilhado mais uma importação. Desde setembro de 2026, o Claude Code lê o próprio AGENTS.md se o projeto não tiver CLAUDE.md; é necessária uma importação quando existem regras específicas para o Claude. Abaixo, explico quando basta um único AGENTS.md, como configurar uma importação e como separar as regras partilhadas das regras específicas do Claude.

O Claude Code lê o próprio AGENTS.md?#

Antes de setembro de 2026, a resposta era «não». O Issue #6235, que pedia suporte para AGENTS.md, estava aberto desde agosto de 2025 e foi encerrado em 17 de agosto de 2026. Durante todo esse tempo, a documentação de memória apontava para uma solução: criar um CLAUDE.md e incluir nele o AGENTS.md como importação. A partir da versão 2.1.277, a documentação diz algo diferente:

O que o Claude Code lê depende exatamente dos ficheiros existentes no projeto:

Para esta verificação, contam CLAUDE.md, .claude/CLAUDE.md e CLAUDE.local.md no diretório de trabalho e em qualquer diretório acima dele. Um ~/.claude/CLAUDE.md pessoal, um ficheiro empresarial gerido e as regras de .claude/rules/ não contam: são carregados juntamente com AGENTS.md.

Quando não existe CLAUDE.md, o Claude Code lê, ao iniciar, todos os ficheiros AGENTS.md e .claude/AGENTS.md no diretório de trabalho e nos diretórios acima dele, e carrega um AGENTS.md num subdiretório quando abre um ficheiro nesse subdiretório. As importações @path dentro de AGENTS.md também funcionam. O Claude Code não lê AGENTS.local.md, AGENTS.override.md nem o conteúdo do diretório .agents/.

A ressalva: também conta um CLAUDE.local.md pessoal. Se criar um para guardar regras não submetidas, o Claude Code deixa silenciosamente de ler AGENTS.md. A configuração abaixo resolve o problema.

O comportamento muda em /config, na secção Project instructions:

Se quiser manter CLAUDE.local.md sem perder AGENTS.md, defina claude-md-and-agents-md. Não haverá leitura duplicada: se AGENTS.md já estiver incluído através da linha @AGENTS.md ou de uma ligação simbólica, o Claude Code não o carrega uma segunda vez, independentemente da definição.

Pode verificar se o ficheiro foi carregado com o comando /memory: a partir da versão 2.1.280, o caminho para AGENTS.md aparece na lista. Nas versões anteriores à 2.1.277 e nas sessões em que o plugin integrado agents-md está desativado, o Claude Code lê apenas CLAUDE.md, e não existe a opção Project instructions em /config. Antes da versão 2.1.281, as sessões através do Amazon Bedrock e as sessões com a telemetria desativada comportavam-se da mesma forma. Na primeira sessão após a atualização de uma versão anterior, AGENTS.md também poderá não ser carregado; funcionará a partir da sessão seguinte.

O que significa isto para uma configuração com um único ficheiro? Se não tiver regras apenas para o Claude, pode dispensar CLAUDE.md: AGENTS.md basta, e o Claude Code, o Codex e o Cursor irão lê-lo. Se tiver essas regras (plan mode para diretórios de risco, skills, hooks), precisa de CLAUDE.md, e o Claude Code deixará de ler AGENTS.md por si só. Nesse caso, inclua AGENTS.md em CLAUDE.md com a linha @AGENTS.md; esta configuração funciona tal como antes de setembro. Também ajuda com versões mais antigas do Claude Code. Explico-a em detalhe abaixo.

Como importar @AGENTS.md dentro de CLAUDE.md?#

Um exemplo mínimo funcional da documentação oficial:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Eis o que acontece. A primeira linha, @AGENTS.md, é uma diretiva de importação. Quando o Claude Code analisa CLAUDE.md no início de uma sessão, encontra esta importação e insere no respetivo lugar todo o conteúdo de AGENTS.md. A seguir surge o título ## Claude Code: é apenas markdown, mas funciona como uma secção de «aditamentos específicos do Claude». Por baixo está uma regra que se aplica apenas ao Claude Code: utilizar plan mode para alterações no diretório billing. O Codex CLI e o Cursor nem sequer abrem este ficheiro; usam o AGENTS.md simples.

Uma citação da documentação sobre o funcionamento das importações:

Alguns detalhes práticos:

• Caminhos relativos e absolutos. @AGENTS.md é relativo ao ficheiro que contém a importação. @/Users/me/shared/rules.md ou @~/.claude/personal.md são absolutos. Uso @~/.claude/personal.md para preferências pessoais que não quero colocar no repositório.
• Profundidade de quatro níveis. AGENTS.md pode importar @docs/coding-style.md, e coding-style.md pode importar outro ficheiro, até quatro níveis. Isto é suficiente para qualquer estrutura real.
• Os backticks impedem importações. Se o texto disser `@README`, trata-se apenas de uma referência ao nome, não de uma importação. É útil ao explicar aos leitores como funcionam as importações sem ativar uma.
• Aprovação para ficheiros fora do projeto. Se uma importação apontar para fora do diretório de trabalho, como @~/.claude/personal.md, o Claude Code apresenta uma caixa de diálogo com a lista desses ficheiros na primeira vez. Se a recusar, as importações externas ficam desativadas e a caixa não volta a aparecer. @AGENTS.md na raiz do projeto não abre uma caixa de diálogo. Isto protege contra o carregamento acidental de um ficheiro não relacionado para o contexto.

Depois de mudar para esta configuração no projeto descrito, o meu CLAUDE.md passou de 250 linhas para 60: @AGENTS.md mais cinco a sete regras aplicáveis apenas ao Claude Code (plan mode para diretórios de risco, o que não fazer na área de administração e como redigir commits). Tudo o que é partilhado fica em AGENTS.md, que o Codex e o Cursor leem.

Quando deve escolher uma ligação simbólica e quando uma importação?#

A documentação apresenta a opção da ligação simbólica desta forma:

ln -s AGENTS.md CLAUDE.md

E logo a seguir deixa um aviso franco sobre o Windows:

Tabela comparativa:

Uso importações no projeto descrito. Eis as razões:

1. A equipa usa sistemas diferentes. Trabalho num Mac; no exemplo, a equipa está dividida aproximadamente em partes iguais entre Windows e Mac. Se houver uma ligação simbólica no repositório, para os utilizadores de Windows sem Developer Mode será feito checkout de um ficheiro de texto normal que contém uma única linha, AGENTS.md. Isto causa erros estranhos: por vezes as regras funcionam, por vezes não, e não se percebe porquê.
2. Quero regras apenas para o Claude. Sob @AGENTS.md, o meu CLAUDE.md tem uma secção «Claude Code» com regras: utilizar --effort high para tarefas de arquitetura, executar npm run build antes de git push e não chamar /api/v1/deploy manualmente. O Codex não compreende estes comandos.
3. É mais fácil depurar. Quando algo corre mal, abro CLAUDE.md e vejo a importação e as minhas substituições. Uma ligação simbólica não indica que «isto foi acrescentado aqui». Para saber mais sobre a depuração das definições do Claude Code, consulte o guia do modo seguro.

Se não tiver regras específicas para o Claude, a partir da versão 2.1.277 já não precisa de uma ligação simbólica: elimine CLAUDE.md, e o Claude Code lerá o próprio AGENTS.md. Mantenha a ligação simbólica apenas se alguém da equipa usar uma versão anterior à 2.1.277 e não puder atualizá-la. Se tiver regras específicas para o Claude, uma importação é mais conveniente em nove casos em dez.

O que leem Codex, Cursor, Copilot, Windsurf e Gemini CLI?#

Um mapa das sete principais ferramentas (com base na documentação oficial de cada ferramenta):

O que se conclui? Se um repositório tiver AGENTS.md (e um CLAUDE.md com uma importação quando forem necessárias regras específicas do Claude), cinco das sete ferramentas recebem automaticamente instruções atualizadas. O Cursor e o Windsurf, que têm ficheiros próprios nativos, podem ser mantidos como estão (AGENTS.md também é lido por eles) ou podem receber uma importação @AGENTS.md — mas a sintaxe é diferente e nem sempre é suportada.

A estratégia mais simples para um projeto novo:

1. Coloque todas as regras partilhadas em AGENTS.md — 95% das regras pertencem a esse ficheiro.
2. Crie CLAUDE.md se precisar de regras apenas para o Claude: coloque @AGENTS.md na primeira linha e, em seguida, acrescente uma secção com regras específicas do Claude. Se não tiver regras desse tipo, CLAUDE.md é desnecessário; o Claude Code lê o próprio AGENTS.md desde a versão 2.1.277.
3. Mantenha .cursor/rules/ para o Cursor nos casos raros em que precisar de algo específico do Cursor (os comandos @Codebase e @Docs).
4. Faça o mesmo para o Windsurf: esqueça o antigo .windsurfrules; utilize o novo .windsurf/rules/ apenas quando precisar de padrões para a respetiva sintaxe.

Esta abordagem proporciona 80% do benefício com 20% do trabalho. Pela minha experiência, ao organizar equipas mistas no «Antigravity», manter mais de duas fontes de verdade (partilhada e apenas para o Claude) torna-se penoso. Se alguém da equipa acrescentar uma regra a .cursorrules e se esquecer de AGENTS.md, uma semana depois o Cursor e o Codex estarão em desacordo.

Como é que /init no Claude Code deteta um AGENTS.md existente?#

A Anthropic descreve /init da seguinte forma na sua documentação:

O que significa isto na prática? O repositório descrito tinha um .cursorrules da altura em que experimentei o Cursor (cerca de 80 linhas) e um AGENTS.md (120 linhas, compiladas manualmente). Quando executei claude /init, o comando utilizou os dois ficheiros, eliminou regras semelhantes e montou um CLAUDE.md limpo num minuto. Depois verifiquei-o e fiz pequenas alterações — removi itens desatualizados e acrescentei uma estrutura com títulos. Foi mais rápido do que reescrever tudo de raiz.

O modo interativo, no qual /init também lê AGENTS.md, é ativado através de uma variável de ambiente:

CLAUDE_CODE_NEW_INIT=1 claude

Depois de /init arrancar, Claude faz várias perguntas de esclarecimento: que elementos configurar (CLAUDE.md, skills, hooks), que stack o projeto utiliza e que comandos usar para os testes. Em seguida, um subagent explora a base de código — lendo package.json, README.md e ficheiros de configuração — e preenche as partes em falta. No fim, apresenta uma proposta que pode editar antes de guardar. Para saber mais sobre como configurar o Claude Code ao iniciar um projeto, consulte o guia separado.

Agora, a desvantagem. Se o projeto já tiver um AGENTS.md ativo, /init criará ao lado dele um CLAUDE.md com uma cópia das suas regras. A partir daí, por predefinição, o Claude Code lê apenas CLAUDE.md, pelo que voltam a existir duas fontes de verdade: atualiza AGENTS.md, enquanto Claude continua a trabalhar a partir da cópia antiga. O comando /import faz algo semelhante: acrescenta uma cópia única de AGENTS.md a CLAUDE.md. Para manter uma única fonte, coloque a importação @AGENTS.md na primeira linha de CLAUDE.md depois de /init e remova de CLAUDE.md tudo o que repete AGENTS.md.

/init é um bom ponto de partida para um projeto novo ou para um projeto que esteja a migrar do Cursor ou do Copilot. Não é necessário procurar online o «melhor modelo de CLAUDE.md» — a Anthropic já tem em conta o que está no repositório. Se o projeto já tiver um AGENTS.md ativo e não existirem regras apenas para o Claude, /init é desnecessário: o Claude Code lerá o próprio AGENTS.md.

Como separar as instruções partilhadas das específicas do Claude?#

Faço a separação de acordo com este princípio. Regras partilhadas que pertencem a AGENTS.md:

• No que não tocar no código. As pastas .env, node_modules, prisma/migrations (apenas através de prisma migrate), .next/, .git/.
• Como dar nomes às coisas. Branches: feat/, fix/, chore/. Commits: prefixos feat:, fix:, docs: seguidos de uma descrição curta. Ficheiros de componentes em kebab-case.
• Comandos de testes e lint. npm run build, npm run lint, npm test. Que comando executar antes de git push.
• Princípios de arquitetura. O que fica em src/lib/, o que fica em src/components/, onde reside a lógica de negócio e onde fica a interface de utilizador.
• Segurança. Nunca submeta segredos. Aceda à base de dados de produção apenas através de prod-psql. Aceda à produção por SSH apenas através do alias prod, não através de root@IP.

Regras específicas do Claude que pertencem a CLAUDE.md (abaixo de @AGENTS.md):

• Plan mode. Utilize plan mode para alterações em diretórios de risco (por exemplo, src/billing/).
• Nível de esforço. Utilize --effort high para tarefas de arquitetura e medium para trabalho de rotina.
• Skills. Que agentes de IA e skills executar em cada situação. Por exemplo: «ao trabalhar num guia, execute o skill build-masterskaya-guide».
• Memória do Claude. O que guardar na memória automática e o que colocar em CLAUDE.local.md. Para saber mais sobre a memória do Claude, consulte o guia sobre Memory e CLAUDE.md.
• Hooks. Se .claude/settings.json tiver hooks configurados, descreva em CLAUDE.md o que fazem (o Codex e o Cursor não os conhecem nem precisam de os conhecer).
• Skills e comandos. Uma lista de comandos com barra que utilizo frequentemente (/init, /cd, /memory, /plan).

A fronteira nem sempre é clara. Por exemplo, «nunca executar git push --force para main» é claramente uma regra partilhada, pelo que pertence a AGENTS.md. Mas «ao executar git push para uma branch hot, utilize primeiro plan mode» é específica do Claude Code e, por isso, pertence a CLAUDE.md. O teste: «Se amanhã removesse o Claude Code e mantivesse apenas o Codex, esta regra continuaria a aplicar-se?» Se sim, coloque-a em AGENTS.md. Se não, coloque-a em CLAUDE.md.

O que pertence a AGENTS.md e o que pertence a CLAUDE.md ou .claude/rules?#

Se as regras ultrapassarem 200 linhas, está na altura de as dividir. A documentação da Anthropic recomenda apontar para 200 linhas por ficheiro, porque ficheiros CLAUDE.md longos fazem com que Claude comece a cumprir menos as instruções silenciosamente: parece lê-los, mas segue-os com menos frequência.

Uma estrutura para um projeto grande que funciona comigo:

my-project/
├── AGENTS.md                    # 100-150 lines, shared
├── CLAUDE.md                    # 30-50 lines: @AGENTS.md + Claude-only
└── .claude/
    ├── CLAUDE.md                # alternative to root file, same file
    └── rules/
        ├── api.md               # with paths: ['src/api/**']
        ├── components.md        # with paths: ['src/components/**']
        ├── testing.md           # without paths, always active
        └── security.md          # without paths, always active

Cada ficheiro em .claude/rules/ pode ter frontmatter:

---
paths:
  - "src/api/**/*.ts"
---

# API rules
- Every endpoint validates input with zod
- Errors use the standard `{error, code}` format
- OpenAPI comments are required

Claude carrega estas regras apenas quando trabalha com ficheiros que correspondem a este padrão. Se alterar src/components/Button.tsx, as regras da API não são adicionadas ao contexto. Assim, a janela de contexto só ocupa espaço com o que é relevante. O diretório .claude/rules/ também funciona sem CLAUDE.md: se o projeto contiver apenas AGENTS.md, as respetivas regras são carregadas juntamente com ele e não desativam a leitura direta de AGENTS.md.

O Cursor e o Windsurf suportam a mesma abordagem através dos diretórios .cursor/rules/ e .windsurf/rules/. A norma AGENTS.md pode referir estes diretórios, mas a sintaxe entre ferramentas ainda não é totalmente estável. É mais seguro manter as regras partilhadas em AGENTS.md e duplicar as regras limitadas a caminhos em .claude/rules/ e .cursor/rules/ — são casos específicos raros, não a maioria das regras.

Localizações úteis para CLAUDE.md (ordenadas da mais abrangente para a mais restrita):

Um exemplo de ~/.claude/CLAUDE.md poderia conter duas regras: «responde no idioma preferido do utilizador» e «escreve Ailoot exatamente desta forma». Estas regras aplicam-se a todos os projetos, pelo que não é necessário duplicá-las em cada repositório.

Destes quatro níveis, apenas CLAUDE.md ao nível do projeto e CLAUDE.local.md desativam a leitura direta de AGENTS.md. Um ~/.claude/CLAUDE.md pessoal e a política gerida não interferem; o Claude Code lê-os juntamente com AGENTS.md.

O que deve fazer se AGENTS.md já estiver desatualizado no seu projeto?#

No projeto descrito, tinha um AGENTS.md de maio de 2025 — 180 linhas, muitas delas desatualizadas (mencionava endpoints da Anthropic API que entretanto tinham mudado; exemplos com a sintaxe claude --tools que já não existe; e regras sobre ~/.claude/projects/ com uma estrutura desatualizada).

O plano que utilizei para o atualizar:

1. Reveja-o com claude em plan mode. Abro o repositório, executo claude --safe-mode e peço: «Lê novamente AGENTS.md e sugere uma lista de itens desatualizados ou repetidos. Não o edites; apresenta apenas a lista.» Em dois minutos, recebi uma lista de 23 itens para rever.
2. Remova os itens claramente obsoletos. Dos 23 itens, 9 estavam claramente desatualizados — sintaxe de comandos, endpoints e nomes de flags. Apaguei essas linhas.
3. Combine as duplicações. Outros 6 itens repetiam a mesma coisa com palavras diferentes («não faças force-push», «nunca uses --force», «evita git push -f»). Combinei-os numa única linha.
4. Acrescente novos itens. Acrescentei aquilo em que tinha reparado que Claude/Codex erravam regularmente no último mês, seguindo a regra «uma linha por padrão de erro». Isso resultou em 8 itens novos.
5. Peça a um subagent uma revisão final. Pedi a Claude uma revisão com a instrução «encontra contradições, ambiguidades e duplicações». Encontrou três formulações que podiam ser mais claras. Corrigi-as.

Ao fim de uma hora, AGENTS.md tinha 110 linhas, estava atualizado e eu conhecia pessoalmente cada linha. Foi fácil criar a partir dele um CLAUDE.md de 30 linhas. Depois disso, o Codex também ficou visivelmente mais cuidadoso com os testes — suspeito que algumas das suas decisões «estranhas» se deviam a instruções desatualizadas que estava a seguir de boa-fé.

Os princípios principais para um AGENTS.md vivo:

• Cada regra responde a um erro recorrente. Se durante o mês não me lembrei de uma regra nem uma vez, não vale a pena mantê-la.
• Escreva as regras como comandos, não como teoria. «Usa dois espaços» é uma regra. «O estilo do código deve ser cuidado» não é.
• A especificidade é melhor do que a generalidade. «Executa npm run build antes de git push» é uma regra. «Testa as alterações» não é.

O que NÃO funciona de todo com esta configuração?#

Aprendi algumas coisas da maneira difícil durante seis meses a trabalhar com esta configuração:

1. O preenchimento automático do Cursor não utiliza AGENTS.md. Quando o Cursor sugere completar uma linha no editor, não lê AGENTS.md em tempo real — há um motor rápido separado a funcionar. As regras em AGENTS.md só importam quando faz um pedido no chat dentro do Cursor. Isto significa que escrever «não uses var, usa const» em AGENTS.md não afeta o preenchimento automático; tem de configurar isso através do ESLint ou da configuração do TypeScript.

2. Os hooks do Claude Code em AGENTS.md não funcionam para o Codex. Se .claude/settings.json tiver um hook PreToolUse configurado para bloquear uma determinada ação, essa informação só é útil para o Claude. O Codex não conhece hooks; para ele, «a ferramenta decide por si». Faz sentido escrever «não faças X» em AGENTS.md e «há um hook que bloqueia fisicamente X» em CLAUDE.md, abaixo da importação.

3. Copilot e .github/copilot-instructions.md. O GitHub Copilot lê o seu próprio ficheiro e continua a não ler muito bem AGENTS.md. Se a sua equipa utilizar ativamente o Copilot, acrescente um .github/copilot-instructions.md separado com uma versão abreviada das regras ou utilize extensões do Copilot que reconheçam AGENTS.md. Isto está a mudar rapidamente, pelo que a situação poderá ser diferente dentro de três a seis meses.

4. O Git não regista uma ligação simbólica como alteração de CLAUDE.md. Se executar ln -s AGENTS.md CLAUDE.md e atualizar AGENTS.md uma semana depois, o Git mostrará um diff apenas para AGENTS.md. Isso é normal, mas um colega que reveja o PR poderá não perceber que CLAUDE.md também foi atualizado (através da ligação simbólica). Solução: escreva explicitamente na descrição do PR: «atualizei AGENTS.md; o Claude Code vê o mesmo ficheiro através da ligação simbólica».

5. As importações profundas são difíceis de depurar. Se AGENTS.md importar @docs/coding-style.md, que importa @docs/typescript.md, e alguma regra entrar em conflito com outra, é difícil depurar. Limito as importações a um nível (CLAUDE.md → AGENTS.md) e não as aninho mais. A Anthropic disponibiliza um hook InstructionsLoaded que regista que ficheiros foram carregados — útil para depurar configurações em camadas. Nota: o hook é acionado para AGENTS.md incluído através de uma importação ou ligação simbólica, mas não para AGENTS.md que o Claude Code tenha lido por si só.

A configuração completa de vibe coding para uma noite: clone de IA + Second Brain + engenharia de contexto.

Conheça a Ailoot.