---
title: "Use AGENTS.md no Claude Code e no Codex"
description: "O Codex lê AGENTS.md por padrão. O Claude Code 2.1.277 ou mais novo lê esse arquivo quando o projeto não tem CLAUDE.md. Para manter os 2, coloque @AGENTS.md no seu CLAUDE.md."
canonical: "https://logbrew.co/pt-BR/guides/agents-md"
last_updated: "2026-11-10"
---

# Use AGENTS.md no Claude Code e no Codex

O Codex lê `AGENTS.md` por padrão. O Claude Code 2.1.277 ou mais novo lê esse arquivo quando o projeto não tem `CLAUDE.md`. Para manter os 2, coloque `@AGENTS.md` no seu `CLAUDE.md`.

Testado em 10 de novembro de 2026 com Claude Code 2.1.319 e Codex CLI 0.167.0

Por [Furkan Erday](https://github.com/furkanerday). Furkan Erday é o fundador do LogBrew. Ele desenvolve o LogBrew com Claude Code e Codex todos os dias.

Canonical: https://logbrew.co/pt-BR/guides/agents-md

## Quando cada agente carrega `AGENTS.md`

| Seu projeto tem | Claude Code | Codex |
| --- | --- | --- |
| Só `AGENTS.md` | Carregado | Carregado |
| `AGENTS.md` e `CLAUDE.md` | Ignorado | Carregado |
| Um `CLAUDE.md` que importa `@AGENTS.md` | Carregado | Carregado |
| Um `CLAUDE.md` que é link simbólico para `AGENTS.md` | Carregado | Carregado |
| `AGENTS.md` e `CLAUDE.local.md` | Ignorado | Carregado |

Lemos as instruções que cada agente enviou na primeira requisição.

## Configure 1 arquivo para os 2 agentes

### Crie o AGENTS.md na raiz do projeto

Coloque os comandos de build, os comandos de teste e as regras de código em 1 arquivo. Os 2 agentes leem esse arquivo da raiz do repositório Git até a pasta atual.

### Atualize o Claude Code

O Claude Code lê `AGENTS.md` sozinho a partir da versão 2.1.277. Versões mais antigas precisam da importação do próximo passo.

```bash
claude update
```

### Importe o AGENTS.md no seu CLAUDE.md

Um `CLAUDE.md`, `.claude/CLAUDE.md` ou `CLAUDE.local.md` na sua pasta ou acima dela faz o Claude Code deixar de ler `AGENTS.md`. Adicione esta linha ao seu `CLAUDE.md` para carregar os 2.

```bash
@AGENTS.md
```

### Ou crie um link do CLAUDE.md para o AGENTS.md

Se o seu `CLAUDE.md` teria só a importação, transforme ele em um link simbólico.

```bash
ln -s AGENTS.md CLAUDE.md
```

### Ou carregue os 2 com uma configuração

Para manter um `CLAUDE.local.md` e ainda carregar `AGENTS.md`, adicione isto a `~/.claude/settings.json`. Em uma sessão, a opção Instruções do projeto em `/config` define o mesmo valor.

```bash
{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}
```

### Veja o que o Codex carregou

Execute isto na pasta em que você trabalha. A documentação do Codex dá este comando para fazer o Codex repetir as instruções que carregou.

```bash
codex --ask-for-approval never "Summarize the current instructions."
```

## O que vimos no teste

Apontamos os 2 agentes para um servidor de teste local e lemos as instruções que cada um enviou na primeira requisição. Assim dá para ver exatamente quais arquivos cada agente carrega.

O Claude Code carregou `AGENTS.md` quando o projeto não tinha `CLAUDE.md`, e o log de debug dele mostrou `no CLAUDE.md found; AGENTS.md loaded`. Com um `CLAUDE.md` ao lado, o Claude Code deixou `AGENTS.md` de fora. Com a importação `@AGENTS.md` ou com o link simbólico, o texto do `AGENTS.md` apareceu exatamente 1 vez.

A configuração `pluginConfigs` acima carregou os 2 arquivos, também com um `CLAUDE.local.md` no projeto.

O Codex carregou primeiro `~/.codex/AGENTS.md`, depois o `AGENTS.md` da raiz e depois o arquivo da pasta atual. Um `AGENTS.override.md` substituiu o `AGENTS.md` da mesma pasta. O Codex ignorou um `CLAUDE.md` até o adicionarmos a `project_doc_fallback_filenames`. Quando os 2 arquivos existiam, o Codex carregou só `AGENTS.md`, mesmo com o fallback definido.

## AGENTS.md ou CLAUDE.md

O Codex lê `AGENTS.override.md` ou `AGENTS.md` em cada pasta, além do `~/.codex/AGENTS.md` global, até 32 KiB no total por padrão. Ele só lê `CLAUDE.md` se você o listar em `project_doc_fallback_filenames`.

O Claude Code lê `CLAUDE.md` primeiro. Ele só lê `AGENTS.md` e `.claude/AGENTS.md` quando nenhum `CLAUDE.md` de projeto se aplica. O seu `~/.claude/CLAUDE.md` pessoal não conta, então ele carrega junto com o `AGENTS.md`.

## O que dizem os relatos no GitHub

O #6235, com 409 comentários, pediu suporte a AGENTS.md no Claude Code. Em 17 de agosto de 2026, um engenheiro da Anthropic fechou o pedido com a importação e o link simbólico acima. Hoje o Claude Code lê o arquivo sozinho. O #31005 pede também suporte a `.agents/skills/` e continua aberto.

## Perguntas frequentes

### O Claude Code lê AGENTS.md?

Sim, a partir da versão 2.1.277, quando não existe `CLAUDE.md`, `.claude/CLAUDE.md` nem `CLAUDE.local.md` na sua pasta ou acima dela. Confirmamos isso na 2.1.319.

### Devo usar AGENTS.md ou CLAUDE.md?

Use `AGENTS.md` se alguém da sua equipe usa o Codex ou outro agente. Mantenha um `CLAUDE.md` só para regras que valem apenas para o Claude Code, e importe `@AGENTS.md` nele.

### Posso criar um link simbólico do CLAUDE.md para o AGENTS.md?

Sim. No nosso teste, o Claude Code carregou o arquivo do link 1 vez, igual à importação.

### O Codex lê CLAUDE.md?

Não por padrão. Adicione `project_doc_fallback_filenames = ["CLAUDE.md"]` a `~/.codex/config.toml`.

## Leve os seus erros de produção até o agente

Conecte o servidor MCP do LogBrew e o Claude Code ou o Codex lê os erros, logs e traces dos projetos que você aprovar. Comece no plano gratuito generoso, sem cartão.

[Conectar seu agente](https://logbrew.co/pt-BR/agents)

## Fontes

- [Claude Code docs, How Claude remembers your project](https://code.claude.com/docs/en/memory#agents-md)
- [Codex docs, Custom instructions with AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
- [anthropics/claude-code#6235](https://github.com/anthropics/claude-code/issues/6235)
- [anthropics/claude-code#31005](https://github.com/anthropics/claude-code/issues/31005)

## Mais guias para agentes de programação com IA

- [Adicione um servidor MCP ao Claude Code e ao Codex](https://logbrew.co/pt-BR/guides/mcp-server-claude-code-codex)
- [Corrija o erro 529 overloaded e o erro 429 de rate limit do Claude](https://logbrew.co/pt-BR/guides/claude-overloaded-rate-limit-error)
- [Como corrigir erros no Claude Code, no Codex e no JavaScript do navegador](https://logbrew.co/pt-BR/guides)