# Como partilhar instruções entre Claude Code, Codex e Cursor com AGENTS.md e CLAUDE.md em 2026
> Uma única fonte de instruções para Claude Code, Codex e Cursor: AGENTS.md, importação @AGENTS.md em CLAUDE.md, ligações simbólicas e /init.
Source: https://ailoot.ai/blog/pt-pt/agents-md-claude-md-one-instruction-file/
Canonical: https://ailoot.ai/blog/pt-pt/agents-md-claude-md-one-instruction-file/
Language: pt-PT
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-004
Revision: sha256-c9320f01e2743cf30599a949896244f6016d102a3270d9a056b2e75952f25171
Para obter informações sobre o serviço, consulte a [documentação da Ailoot](https://ailoot.ai/docs/).
## O que muda quando utiliza Claude Code, Codex e Cursor em conjunto?
Conclusão principal
Em 2026, a configuração típica de um vibe coder não inclui uma ferramenta, mas sim 3–5. Claude Code como ferramenta principal, Codex para tarefas autónomas longas, Cursor para edições rápidas no IDE. Cada um tem o seu próprio ficheiro de instruções: `CLAUDE.md`, `AGENTS.md`, `.cursorrules`. Se os mantiver sincronizados manualmente, edita uma linha em cinco sítios, esquece-se de atualizar o Cursor e, uma semana depois, Claude e Codex dão resultados diferentes para o mesmo pedido.
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](https://ailoot.ai/blog/pt-pt/claude-code-codex-together/).
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?
Conclusão principal
Sim, a partir da versão 2.1.277, lançada em 18 de setembro de 2026, mas apenas se não existir `CLAUDE.md`, `.claude/CLAUDE.md` ou `CLAUDE.local.md` no diretório de trabalho ou em qualquer diretório acima dele. Se existir `CLAUDE.md`, por predefinição o Claude Code lê apenas esse ficheiro, e `AGENTS.md` é incluído com a linha `@AGENTS.md` dentro de `CLAUDE.md` ou através de uma ligação simbólica. O comportamento muda em `/config`, na secção Project instructions. Antes de setembro, o Claude Code não lia `AGENTS.md` de todo, e importá-lo era a única forma.
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 Claude Code consegue ler AGENTS.md como instruções do projeto, pelo que um repositório já preparado para outros agentes funciona sem CLAUDE.md, importação ou configuração.
— Anthropic, https://code.claude.com/docs/en/memory#agents-md
O que o Claude Code lê depende exatamente dos ficheiros existentes no projeto:
| Ficheiros no projeto | O que o Claude Code lê |
|----|----|
| `AGENTS.md`, sem `CLAUDE.md` ou `CLAUDE.local.md` no diretório de trabalho ou acima dele | `AGENTS.md` |
| `AGENTS.md` e `CLAUDE.md` (ou `CLAUDE.local.md`) no diretório de trabalho ou acima dele | Apenas `CLAUDE.md` |
| `CLAUDE.md` com a linha `@AGENTS.md` | `CLAUDE.md` e `AGENTS.md` dentro dele através da importação |
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:
| Definição | O que o Claude Code lê |
|----|----|
| `claude-md-or-agents-md` (predefinição) | `CLAUDE.md` ou, se nem este nem `CLAUDE.local.md` existirem, `AGENTS.md` |
| `claude-md-and-agents-md` | Ambos os ficheiros: em cada diretório, primeiro `CLAUDE.md` e depois `AGENTS.md` |
| `claude-md` | Apenas `CLAUDE.md` |
| `managed-only` | Apenas o `CLAUDE.md` empresarial gerido e a memória automática |
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?
Conclusão principal
É necessária uma importação quando o projeto tem um `CLAUDE.md`: com esse ficheiro presente, por predefinição o Claude Code não lê `AGENTS.md` por si só. Para a configurar, escreva a linha `@AGENTS.md` no início do ficheiro `CLAUDE.md`. Quando o Claude Code inicia uma sessão, insere o conteúdo de `AGENTS.md` no lugar dessa linha e lê o resultado como um único texto. Abaixo da importação, pode acrescentar uma secção «Claude Code» com regras aplicáveis apenas ao Claude. As importações funcionam com caminhos relativos e absolutos e podem ter até quatro níveis de profundidade.
Um exemplo mínimo funcional da documentação oficial:
```markdown
@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:
Os ficheiros CLAUDE.md podem importar ficheiros adicionais utilizando a sintaxe @path/to/import. Os ficheiros importados são expandidos e carregados para o contexto no início da sessão, juntamente com o CLAUDE.md que os referencia.
— Anthropic, https://code.claude.com/docs/en/memory
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?
Conclusão principal
A Anthropic oferece dois mecanismos: uma importação através de `@AGENTS.md` ou uma ligação simbólica, `ln -s AGENTS.md CLAUDE.md`. Uma ligação simbólica é mais simples — é apenas um alias e não exige alterações a ficheiros. Mas tem três desvantagens: o Windows exige privilégios de administrador, não pode acrescentar regras específicas do Claude a `CLAUDE.md` e, por vezes, o Git mostra a ligação como lixo no diff. A importação é a abordagem universal. Se não tiver regras apenas para o Claude, a partir da versão 2.1.277 não precisa de nenhum dos dois: o Claude Code lerá o próprio `AGENTS.md`.
A documentação apresenta a opção da ligação simbólica desta forma:
```bash
ln -s AGENTS.md CLAUDE.md
```
E logo a seguir deixa um aviso franco sobre o Windows:
Se você ou alguém que clona o repositório trabalha no Windows, use a importação @AGENTS.md. Criar uma ligação simbólica nesse sistema exige privilégios de administrador ou o Developer Mode, e o Git sem core.symlinks ativado faz checkout de uma ligação submetida como um ficheiro de texto normal, deixando um CLAUDE.md de uma só linha em vez das instruções nessa cópia.
— Anthropic, https://code.claude.com/docs/en/memory
Tabela comparativa:
| Critério | Importação `@AGENTS.md` | Ligação simbólica `ln -s` |
|----|----|----|
| **Funciona no Windows sem privilégios de administrador** | sim | não (requer Developer Mode) |
| **Permite acrescentar regras apenas para o Claude** | sim, abaixo da importação | não, o ficheiro é idêntico |
| **Aparece no Git como markdown normal** | sim | como ligação (depende de `core.symlinks`) |
| **Permite importar vários ficheiros** | sim, até quatro níveis | não, relação de um para um |
| **Cache/invalidação no Claude Code** | padrão para CLAUDE.md | funciona, mas as ligações simbólicas têm armadilhas de metadados |
| **Opção predefinida** | adequada para todos | apenas se a utilização multiplataforma não for importante |
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](https://ailoot.ai/blog/pt-pt/claude-code-safe-mode-recovery/).
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?
Conclusão principal
Cada ferramenta lê o seu próprio ficheiro, por vezes mais do que um. O Claude Code lê `CLAUDE.md` e, desde setembro de 2026, também lê `AGENTS.md` se o projeto não tiver `CLAUDE.md`. O Codex CLI lê `AGENTS.md` e `AGENTS.override.md`. O Cursor lê o formato antigo `.cursorrules` ou o mais recente `.cursor/rules/*.mdc` e, desde o verão de 2026, também lê `AGENTS.md`. O Copilot lê `.github/copilot-instructions.md` ou `.github/instructions/*.instructions.md`. O Windsurf lê o antigo `.windsurfrules` ou o mais recente `.windsurf/rules/`. O Gemini CLI lê `GEMINI.md`. O Aider e o Cline já adotaram `AGENTS.md`.
Um mapa das sete principais ferramentas (com base na documentação oficial de cada ferramenta):
| Ferramenta | Ficheiro principal de instruções | Alternativas | Lê AGENTS.md? |
|----|----|----|----|
| **Claude Code** | `CLAUDE.md` | `~/.claude/CLAUDE.md`, `./.claude/CLAUDE.md`, política gerida | sim, se o projeto não tiver `CLAUDE.md` (desde 2.1.277); caso contrário, através de uma importação |
| **Codex CLI** (OpenAI) | `AGENTS.md` | `AGENTS.override.md` | sim (nativamente) |
| **Cursor** | `.cursor/rules/*.mdc` | `.cursorrules` (obsoleto) | sim |
| **GitHub Copilot** | `.github/copilot-instructions.md` | `.github/instructions/*.instructions.md` | através de extensões |
| **Windsurf** | `.windsurf/rules/` | `.windsurfrules` (obsoleto) | sim |
| **Gemini CLI** | `GEMINI.md` | \- | não |
| **Aider, Cline, opencode** | `AGENTS.md` | \- | sim (nativamente) |
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?
Conclusão principal
`/init` cria um `CLAUDE.md` com base no que já existe no repositório e poupa 20–30 minutos de trabalho manual. Por predefinição, deteta regras do Cursor (`.cursor/rules/`, `.cursorrules`) e do Copilot (`.github/copilot-instructions.md`), enquanto lê `AGENTS.md`, `.windsurfrules` e `.clinerules` no modo `CLAUDE_CODE_NEW_INIT=1`. Este mesmo modo inicia um fluxo interativo com várias fases: faz perguntas, explora o código através de um subagent e propõe um plano antes de escrever. Desde setembro de 2026, `/init` tem uma desvantagem num projeto com `AGENTS.md`: um novo `CLAUDE.md` desativa a leitura direta de `AGENTS.md`, e as regras acabam em dois ficheiros.
A Anthropic descreve `/init` da seguinte forma na sua documentação:
Executar /init lê ficheiros de instruções de outras ferramentas e transfere as partes relevantes para o CLAUDE.md gerado: regras do Cursor de `.cursor/rules/` ou `.cursorrules`, regras do Copilot de `.github/copilot-instructions.md` e, com CLAUDE_CODE_NEW_INIT=1, também `AGENTS.md`, `.devin/rules/`, `.windsurf/rules/` ou `.windsurfrules` e `.clinerules`.
— Anthropic, https://code.claude.com/docs/en/memory
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:
```bash
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](https://ailoot.ai/blog/pt-pt/spec-kit-claude-code-spec-driven-development/).
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?
Conclusão principal
Coloque em `AGENTS.md` as regras que qualquer agente de IA consegue compreender: no que não tocar, como dar nome às branches, que `.env` contém um segredo e que comandos utilizar para os testes. Coloque em `CLAUDE.md` (abaixo da importação) as regras específicas do Claude Code: plan mode, skills, hooks, referências a skills e nomes de modelos por versão. A distinção é simples: se uma regra começa por «O Claude deve», pertence a `CLAUDE.md`. Se começa por «A ferramenta deve», pertence a `AGENTS.md`.
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](https://ailoot.ai/blog/pt-pt/claude-memory-claude-md-auto-memory/).
- **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?
Conclusão principal
Num projeto grande, um único `AGENTS.md` não chega — cresce demasiado e cada agente inclui material desnecessário no contexto. A solução é um diretório `.claude/rules/` com ficheiros separados por tema e YAML frontmatter `paths:` para acionadores baseados no caminho. Por exemplo, uma regra de API só se aplica quando Claude trabalha em `src/api/`. Isto poupa muito espaço na janela de contexto. O equivalente para o Cursor é `.cursor/rules/`, e para o Windsurf é `.windsurf/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:
```markdown
---
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):
| Nível | Localização | Objetivo |
|----|----|----|
| **Política gerida** | `/Library/Application Support/ClaudeCode/CLAUDE.md` (Mac), `/etc/claude-code/CLAUDE.md` (Linux) | Regras empresariais, IT/DevOps |
| **Utilizador** | `~/.claude/CLAUDE.md` | Preferências pessoais em todos os projetos |
| **Projeto** | `./CLAUDE.md` ou `./.claude/CLAUDE.md` | Regras da equipa do projeto |
| **Local** | `./CLAUDE.local.md` (em `.gitignore`) | Preferências pessoais para um projeto específico |
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?
Conclusão principal
Se `AGENTS.md` foi compilado em 2025 para o Codex ou o Aider e não foi editado desde então, abra o projeto no Claude Code e peça a Claude que edite o ficheiro. AGENTS.md é um documento vivo; a especificação da Linux Foundation é atualizada. A regra principal para o manter atualizado: cada regra tem de responder à pergunta «O que estou farto de repetir ao Claude/Codex?» Se não responder, arquive-a.
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?
Conclusão principal
Importar `@AGENTS.md` não faz com que ferramentas diferentes se comportem como uma só. Cada uma tem as suas particularidades: o Codex CLI não conhece `.claude/rules/` nem hooks. O Cursor tem o seu próprio motor de preenchimento automático, que não lê CLAUDE.md enquanto completa texto. O Copilot segue `.github/copilot-instructions.md`, e as regras apenas em AGENTS.md não lhe chegam. Não se trata de «um ficheiro = um comportamento», mas de «uma fonte para as regras de base e, depois, os acrescentos próprios de cada ferramenta».
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](https://github.com/marketplace?type=apps&category=copilot-extensions) 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ó.
### Fontes
- [Documentação Claude Code Memory — secção AGENTS.md](https://code.claude.com/docs/en/memory#agents-md) — quando o Claude Code lê o próprio AGENTS.md, definições de Project instructions, importações e ligações simbólicas e comportamento de `/init`.
- [Documentação Claude Code Memory — importar ficheiros adicionais](https://code.claude.com/docs/en/memory#import-additional-files) — sintaxe `@path/to/file`, profundidade de quatro níveis, caminhos relativos e absolutos.
- [agents.md — norma da Linux Foundation](https://agents.md/) — norma oficial AGENTS.md e lista de ferramentas compatíveis.
- [Documentação das regras do Cursor](https://docs.cursor.com/context/rules-for-ai) — o que o Cursor lê (`.cursor/rules/*.mdc`, AGENTS.md).
- [Instruções personalizadas do GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) — formato `.github/copilot-instructions.md`.
- [Especificação de AGENTS.md na Linux Foundation](https://aaif.io/projects/agents-md/) — especificação em constante atualização.
A configuração completa de vibe coding para uma noite: **clone de IA + Second Brain + engenharia de contexto**.
Conheça a [Ailoot](https://ailoot.ai/).
## Perguntas frequentes
### Quando uso uma importação em vez de ligação simbólica?
Use `@AGENTS.md` em `CLAUDE.md` quando precisar de acrescentos específicos Claude ou colegas usarem Windows. Uma ligação faz ambos os nomes apontarem para o mesmo conteúdo e não admite uma secção Claude separada.
### Como verifico o carregamento das instruções comuns?
Execute `/memory` e consulte os ficheiros listados. Se `CLAUDE.md` ou `CLAUDE.local.md` suprimir AGENTS.md direto na configuração, adicione a importação ou selecione a definição que carrega ambos e abra uma sessão nova.
## Ailoot · A empresa e a sua carteira de projetos
A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI.
A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões.
A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.