Suporte a AGENTS.md no Claude Code: como usar com o CLAUDE.md

Claude Code AGENTS.md chegou na versão v2.1.277: em um projeto sem CLAUDE.md, o Claude Code agora lê o seu AGENTS.md como instruções do projeto. Você não precisa de um import, de um symlink nem de nenhuma configuração. Se o seu repositório tiver os dois arquivos, o Claude lê apenas o CLAUDE.md, a menos que você altere a configuração Project instructions em /config para carregar os dois.

Se a sua equipe usa vários agentes de codificação, o mesmo AGENTS.md que o Codex e o Cursor já leem agora também orienta o Claude Code. Este guia aborda precedência, migração e como criar um AGENTS.md que ensina qualquer agente a testar suas APIs com a Apidog CLI.

O que é AGENTS.md no Claude Code?

AGENTS.md é um arquivo Markdown simples com instruções para agentes de codificação: comandos de build, comandos de teste, estilo de código e regras do projeto. Desde a v2.1.277, o Claude Code o lê por meio de um plugin integrado, então um repositório configurado para outros agentes funciona com o Claude Code sem arquivos extras. Ele não exige campos obrigatórios nem sintaxe especial.

O formato em si é aberto. O site do AGENTS.md o descreve como “um formato simples e aberto para orientar agentes de codificação”, usado por mais de 60.000 projetos open-source e hoje mantido pela Agentic AI Foundation sob a Linux Foundation. Tanto o OpenAI Codex quanto o Cursor documentam o suporte ao AGENTS.md, e o Claude Code era o grande ausente até esta versão.

Novo no formato? Comece com como escrever arquivos AGENTS.md para equipes de desenvolvimento de APIs.

Aqui está o histórico de versões do changelog oficial do Claude Code:

Execute claude --version antes de depender de qualquer um desses recursos. Em versões anteriores à 2.1.277, o Claude Code lê apenas arquivos CLAUDE.md.

CLAUDE.md vs AGENTS.md: qual vence?

Por padrão, o CLAUDE.md vence. O Claude Code lê o AGENTS.md apenas quando não existe nenhum CLAUDE.md no seu diretório de trabalho ou em nenhum diretório acima dele. A documentação de memória do Claude Code detalha três casos:

Nem todo arquivo entra nessa verificação. Estes três bloqueiam o AGENTS.md:

• CLAUDE.md no diretório de trabalho ou acima dele
• .claude/CLAUDE.md no diretório de trabalho ou acima dele
• CLAUDE.local.md no diretório de trabalho ou acima dele

Estes não bloqueiam e continuam sendo carregados junto com o AGENTS.md: o seu arquivo de usuário em ~/.claude/CLAUDE.md, o CLAUDE.md gerenciado da sua organização e os arquivos em .claude/rules/.

Cuidado com a armadilha do CLAUDE.local.md: se você criar um pessoal para anotações não versionadas, o Claude para de ler o AGENTS.md da equipe para você.

O que o Claude Code carrega, e quando

Quando nada bloqueia, o Claude Code lê:

1. No início da sessão: todo AGENTS.md e .claude/AGENTS.md no diretório de trabalho e nos diretórios acima dele. Sessões interativas exibem uma linha como no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md.
2. Em subdiretórios: o AGENTS.md de um subdiretório, assim que o Claude abrir um arquivo lá com a ferramenta Read e essa pasta não tiver um CLAUDE.md próprio.
3. Imports: imports @path dentro do AGENTS.md são expandidos, e os padrões de claudeMdExcludes são aplicados.

O Claude Code não lê AGENTS.local.md, AGENTS.override.md nem nada dentro de .agents/. Se você compartilha um repositório com o Codex, que documenta o AGENTS.override.md, tenha isso em mente.

Como alterar quais arquivos de instruções o Claude Code carrega

Digite /config em uma sessão e defina Project instructions com um destes quatro valores:

Para a maioria das equipes mistas, claude-md-and-agents-md é a configuração ideal. Ela mantém o seu CLAUDE.local.md pessoal e ainda carrega o AGENTS.md compartilhado.

Você também pode defini-la em um arquivo de configurações. O Claude Code lê essa entrada do ~/.claude/settings.json, de um arquivo --settings ou das configurações gerenciadas, e a ignora em arquivos de configurações de projeto e locais:

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

Antes da v2.1.285, o ID do plugin era agents-md@builtin. Versões a partir da 2.1.285 leem qualquer um dos IDs, então use o antigo se instalações mais antigas compartilharem o arquivo. A mudança vale a partir da sua próxima mensagem.

Se a opção Project instructions não aparece no /config, sua sessão não consegue carregar o AGENTS.md: você está em uma versão anterior à 2.1.277, desativou o plugin integrado via /plugin, ou é a sua primeira sessão após a atualização (funciona a partir da próxima).

Como migrar uma solução alternativa antiga com AGENTS.md

Muitas equipes integravam o AGENTS.md ao Claude Code manualmente antes desta versão. A documentação recomenda:

Mantenha o import @AGENTS.md se alguém da sua equipe ainda usar uma versão anterior à 2.1.277. É a única configuração que funciona em todas as versões.

Import ou symlink?

Se você precisa de regras específicas do Claude além do arquivo compartilhado, use um import. O Claude lê o arquivo importado primeiro, depois o restante:

@AGENTS.md

## Claude Code

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

Se você não precisa de nada específico do Claude, um symlink funciona:

ln -s AGENTS.md CLAUDE.md

Dois detalhes: as ferramentas Edit e Write do Claude não escrevem através de um symlink, e o Git no Windows faz checkout de um symlink versionado como um arquivo de texto de uma linha, a menos que core.symlinks esteja ativado. Se alguém da sua equipe usa Windows, escolha o import.

De qualquer forma, execute /context all na sua próxima sessão e confirme que o CLAUDE.md aparece em Memory files.

Um único AGENTS.md para Codex, Cursor e Claude Code

A grande vantagem é ter uma única fonte da verdade. Coloque seus comandos de build, comandos de teste e convenções no AGENTS.md na raiz do repositório. Codex, Cursor e Claude Code o leem todos.

Uma estrutura que funciona na prática:

• AGENTS.md na raiz: tudo o que todo agente precisa. Comandos, mapa de pastas, regras de estilo, o que não tocar.
• AGENTS.md em subpastas grandes: regras que valem apenas ali, como services/payments/AGENTS.md. O Claude Code carrega esses arquivos sob demanda ao ler um arquivo naquela pasta.
• CLAUDE.md opcional: apenas se você precisar de comportamento exclusivo do Claude, como plan mode ou hooks. Comece com @AGENTS.md.

Uma ressalva: um AGENTS.md carregado pela configuração não dispara hooks InstructionsLoaded e não é carregado de diretórios --add-dir. Se você depende de qualquer um desses, use o caminho do import @AGENTS.md.

Ensine seu agente a testar APIs com a Apidog CLI no AGENTS.md

Escreva suas regras de teste de API uma única vez, e qualquer agente que abrir o repositório executará os testes da mesma forma. A Apidog CLI fornece ao agente uma saída JSON estruturada que ele consegue ler, então o ciclo continua no terminal.

Configure uma vez por máquina:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install

Um atalho: diga ao seu agente “Read https://apidog.com/apidog-cli-installation-guide.md and set up Apidog CLI”. Esse guia foi escrito para agentes e cobre instalação, login e a skill.

Depois, adicione uma seção como esta ao seu AGENTS.md:

## API testing (Apidog CLI)

- Apidog project ID: 123456. Staging environment ID: 7890.
- Never build Apidog JSON payloads from memory. Run
  `apidog cli-schema get <key>` first, then
  `apidog cli-schema validate <key> --file <path>`, and write only after it passes.
- After changing any handler under `src/routes/`, find its endpoint with
  `apidog endpoint list --project 123456` and its cases with
  `apidog test-case list --project 123456 --endpoint <endpointId>`.
- If a route has no test case, create one with
  `apidog test-case create --project 123456 --file case.json`.
- Run cases with
  `apidog run --test-case <caseId> --project 123456 -e 7890 -r cli,json`
  and summarize every failure before you say the task is done.
- Do not edit or delete endpoints in Apidog unless the task asks for it.

Agora um único prompt faz o trabalho no Claude Code, no Codex ou no Cursor:

I changed POST /orders to require a currency field. Update the Apidog test
case for it and run it against staging, following AGENTS.md.

O agente segue suas regras e executa comandos como estes:

apidog endpoint list --project 123456
apidog test-case list --project 123456 --endpoint <endpointId>
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project 123456 --file case.json
apidog run --test-case <caseId> --project 123456 -e 7890 -r cli,json

Cada flag acima vem de apidog <cmd> --help na Apidog CLI 2.2.12. A mesma linha do apidog run com -r junit se encaixa no CI, e --upload-report envia o resumo da execução para o app, para que sua equipe possa vê-lo. Para detalhes sobre o lado do Claude Code, veja como usar a Apidog CLI no Claude Code; usuários do Codex podem seguir a Apidog CLI no Codex. O Apidog Free cobre até 4 usuários, então uma equipe pequena pode experimentar isso hoje mesmo.

Solução de problemas: meu AGENTS.md não está carregando

1. Procure um CLAUDE.md no caminho. Um CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md no seu diretório de trabalho ou acima dele vence por padrão. O seu ~/.claude/CLAUDE.md não conta.
2. Verifique sua versão. Execute claude --version. Você precisa da 2.1.277 ou posterior, e da 2.1.281 ou posterior no Bedrock, Vertex AI, Foundry, gateways ou com telemetria desativada.
3. Verifique a configuração. Abra o /config e garanta que Project instructions não esteja definida como claude-md ou managed-only.
4. Confirme que ele carregou. Execute /memory e procure o caminho do AGENTS.md na lista.

Perguntas frequentes

O Claude Code lê o AGENTS.md agora? Sim, a partir da v2.1.277. Sem nenhum CLAUDE.md no seu diretório de trabalho ou acima dele, o Claude Code lê o AGENTS.md como instruções do projeto automaticamente.

Se eu tiver CLAUDE.md e AGENTS.md, qual o Claude Code usa? Apenas o CLAUDE.md, por padrão. Defina Project instructions como claude-md-and-agents-md no /config para carregar ambos, com o CLAUDE.md primeiro.

Devo apagar meu CLAUDE.md que importa @AGENTS.md? Não precisa. O import nunca carrega o AGENTS.md duas vezes, e continua funcionando para colegas em versões anteriores à 2.1.277. Apague-o apenas se ele não tiver mais nada e todos já tiverem atualizado.

O Claude Code lê o AGENTS.override.md como o Codex? Não. O Claude Code ignora o AGENTS.override.md, o AGENTS.local.md e tudo dentro de .agents/.

O AGENTS.md funciona no Amazon Bedrock ou no Google Vertex AI? Sim, a partir da v2.1.281. Versões anteriores no Bedrock, Vertex AI, Foundry, gateways ou com telemetria desativada leem apenas o CLAUDE.md; use um import @AGENTS.md nesses casos.