Source: https://aiprimetech.io/pt/blog/claude-code-agents-md-support/ Set 19, 2026 · 8 min · Guias para desenvolvedores # Claude Code agora lê AGENTS.md: CLAUDE.md vs. AGENTS.md e o diretório .claude A Por [AI Prime Tech](https://aiprimetech.io/pt/) · Com auxílio de IA Se você está perguntando “o que é claude.md”, trata-se de um arquivo Markdown que fornece ao Claude Code instruções persistentes sobre seu projeto e fluxo de trabalho. O Claude Code 2.1.277, lançado em setembro de 18, 2026, adiciona suporte à leitura de AGENTS.md quando nenhum arquivo de instruções do Claude que atenda aos critérios está presente. Este guia explica esse mecanismo alternativo, como carregar ambos os arquivos e onde devem ficar as configurações, os comandos, os subagentes e as habilidades no .claude diretório. ## O que é claude.md e o que você deve colocar nele? CLAUDE.md é um arquivo Markdown de texto simples que contém instruções que o Claude Code lê e incorpora ao contexto da sessão. Ele oferece um lugar para registrar informações que você teria de repetir de outra forma: comandos de compilação e teste, convenções de código, arquitetura do projeto e regras de fluxo de trabalho. Não há um formato obrigatório para o documento. Você pode organizá-lo com títulos e listas comuns do Markdown, escolhendo a estrutura que facilite a compreensão das instruções do seu projeto. Do Claude Code, /init O comando gera um arquivo inicial com base no projeto, conforme descrito na [documentação oficial de boas práticas](https://code.claude.com/docs/en/best-practices). Um bom ponto de partida é abordar quatro áreas: - Comandos de compilação e teste: os comandos que os colaboradores devem usar para compilar o projeto e verificar as alterações. - Convenções de código: nomenclatura, formatação e outras convenções relevantes para o repositório. - Arquitetura do projeto: os principais componentes e como eles se integram. - Regras de fluxo de trabalho: as etapas que você quer que Claude siga ao fazer e verificar alterações. Trate essas instruções como orientações persistentes. Elas entram no contexto de Claude; não são configurações impostas pelo sistema. Se você precisar configurar o próprio Claude Code, use o arquivo de configurações apropriado em vez de esperar que o texto em CLAUDE.md funcione como um valor de configuração. Essa distinção importa ao organizar um repositório: o conhecimento sobre o projeto pertence aos arquivos de instruções, enquanto a configuração da aplicação pertence às configurações. A [central de guias do Claude Code](/pt/claude-code/) oferece um ponto de partida para o fluxo de trabalho mais amplo. ## Onde colocar CLAUDE.md Claude Code oferece suporte a instruções compartilhadas do projeto e instruções pessoais em vários locais. A [documentação sobre arquivos de instruções](https://code.claude.com/docs/en/memory) descreve esses locais estabelecidos e como funciona a descoberta de instruções. | Local | Finalidade | ./CLAUDE.md | Instruções compartilhadas do projeto | ./.claude/CLAUDE.md | Instruções compartilhadas do projeto em .claude | ~/.claude/CLAUDE.md | Instruções pessoais para todos os projetos | ./CLAUDE.local.md | Instruções pessoais para o projeto atual Os arquivos de instruções dos diretórios ancestrais são carregados na inicialização. Os arquivos em subdiretórios são carregados sob demanda, permitindo que as instruções se tornem relevantes à medida que Claude trabalha nessas partes do projeto. Para instruções compartilhadas, escolha um local que faça sentido para sua equipe. Um arquivo CLAUDE.md na raiz coloca as orientações junto aos outros arquivos de nível superior do repositório. .claude/CLAUDE.md as coloca junto aos arquivos do projeto específicos de Claude. ### As instruções pessoais afetam mais do que a organização dos arquivos CLAUDE.local.md tem uma finalidade diferente da do arquivo compartilhado do projeto: ele contém suas instruções pessoais para esse projeto. Na versão 2.1.277, sua presença também afeta se Claude Code recorre a AGENTS.md. Isso significa que adicionar um arquivo de instruções locais pode mudar quais instruções compartilhadas entram no contexto. Antes de criar um em um repositório que depende de AGENTS.md, verifique a configuração Instruções do projeto descrita abaixo. Os locais acima vêm de uma documentação atualizada continuamente, cuja redação exata de setembro de 19 não foi verificada. O comportamento de fallback na próxima seção está documentado especificamente para a versão 2.1.277 identificada por uma tag. ## Claude Code lê AGENTS.md automaticamente? Sim, sob certas condições. As [notas de versão do Claude Code 2.1.277](https://github.com/anthropics/claude-code/releases/tag/v2.1.277) afirmam: “Adicionado suporte a AGENTS.md: em um projeto sem CLAUDE.md, Claude Code lê AGENTS.md em seu lugar”. O comportamento padrão é um fallback, portanto a presença de um AGENTS.md arquivo, por si só, não significa que ele será carregado. Nesta versão, a verificação inclui mais do que um arquivo na raiz CLAUDE.md. ### O que impede o fallback padrão? Qualquer um destes arquivos, em qualquer ponto do caminho entre a raiz do sistema de arquivos e o diretório de trabalho, impede o fallback padrão de AGENTS.md : - CLAUDE.md - .claude/CLAUDE.md - CLAUDE.local.md As instruções gerenciadas, as instruções pessoais em ~/.claude/CLAUDE.md e .claude/rules/ de fato não impedem esse fallback. Por exemplo, considere um repositório com um arquivo compartilhado AGENTS.md e sem nenhum arquivo de instruções de Claude que atenda aos critérios no caminho dos diretórios ancestrais. O modo padrão lê as instruções de AGENTS. Se você então adicionar CLAUDE.local.md, o fallback padrão será impedido, mesmo que o novo arquivo contenha instruções pessoais em vez das orientações compartilhadas da equipe. ### Como funciona a descoberta de AGENTS.md O suporte integrado é fornecido pelo agents-md plugin, na versão 0.1.0. Ele descobre ambos AGENTS.md e .claude/AGENTS.md no caminho dos diretórios ancestrais e anexa instruções aninhadas quando Claude lê arquivos abaixo da raiz do projeto. O conteúdo já carregado por meio de uma importação ou de um link é deduplicado. Isso importa se um arquivo de instruções de Claude já incorpora o mesmo conteúdo de AGENTS. Até a data limite de publicação em setembro de 19, o anúncio da versão informa que esse suporte ainda não está disponível no Bedrock, Vertex ou Foundry. ## Configure Claude Code para ler um arquivo ou ambos Abra /config e altere Instruções do projeto para escolher o comportamento de carregamento das instruções. O [README do plugin com a tag v2.1.277](https://raw.githubusercontent.com/anthropics/claude-code/v2.1.277/mods/agents-md/README.md) documenta quatro valores exatos. | Valor | Comportamento | claude-md-or-agents-md | Padrão: usar arquivos de instruções de Claude, com fallback para AGENTS quando não houver um arquivo de Claude que atenda aos critérios | claude-md-and-agents-md | Carregar arquivos de instruções de Claude e de AGENTS | claude-md | Carregar apenas arquivos de instruções de Claude | managed-only | Manter instruções gerenciadas e a memória do mecanismo; remover instruções do projeto, locais e do usuário do contexto inicial O README inclui uma ressalva importante para managed-only: anexos aninhados de CLAUDE.md ainda podem chegar. Não interprete o valor como uma garantia de que nenhum conteúdo de instruções aninhadas de Claude possa entrar na conversa. ### Configuração exata para a versão 2.1.277 Para carregar ambas as famílias de instruções, use esta configuração: ``` { "pluginConfigs": { "agents-md@builtin": { "options": { "instructionFiles": "claude-md-and-agents-md" } } } } ``` Para esta versão, coloque-a nas configurações do usuário em ~/.claude/settings.json, em um arquivo fornecido por meio de --settings ou nas configurações gerenciadas. O arquivo do projeto .claude/settings.json de fato não fornece essas opções do plugin. As alterações são aplicadas na próxima reconstrução do contexto, como na próxima interação ou em uma nova conversa. Considere esse momento ao verificar se uma configuração mudou as instruções carregadas. ### Importar instruções compartilhadas continua sendo uma opção Você também pode colocar @AGENTS.md dentro de um arquivo vizinho CLAUDE.md. Isso importa explicitamente as instruções compartilhadas por meio do arquivo de instruções de Claude. As importações de arquivos de instruções de Claude usam @path/to/file.md e foram introduzidas na v0.2.107. A versão 2.1.277 deduplica o conteúdo de AGENTS já importado por CLAUDE.md. Isso oferece duas maneiras de organizar as orientações compartilhadas: configurar Claude Code para carregar ambos os arquivos ou usar uma importação para incorporar o conteúdo de AGENTS a um arquivo de instruções de Claude. Escolha a organização que deixe essa relação clara para os colaboradores do repositório. ## O que deve ficar no diretório .claude? O .claude diretório contém vários tipos de arquivos do projeto. Eles têm finalidades diferentes, portanto escolha o local com base no que você está escrevendo: orientações persistentes, configurações, um prompt reutilizável, uma definição de subagente ou um procedimento. | Arquivo ou diretório | Finalidade | .claude/CLAUDE.md | Instruções compartilhadas do projeto | .claude/settings.json | Configurações compartilhadas do projeto que podem ser incluídas em um commit para a equipe | .claude/settings.local.json | Substituições pessoais das configurações do projeto | .claude/commands/.md | Prompts reutilizáveis de comandos de barra personalizados | .claude/agents/.md | Definições de subagentes do projeto | .claude/skills//SKILL.md | Procedimentos reutilizáveis, opcionalmente acompanhados de scripts e arquivos de referência As configurações pessoais para todos os projetos ficam em ~/.claude/settings.json. As definições pessoais de subagentes usam ~/.claude/agents/, e as skills pessoais usam ~/.claude/skills//SKILL.md. ### Comandos, subagentes e skills Um arquivo de comando como .claude/commands/deploy.md cria /deploy. A versão 2.1.3 unificou comandos de barra e skills, e os arquivos de comando existentes continuam funcionando junto com as skills. As definições de subagentes usam Markdown com frontmatter YAML. Os campos obrigatórios são name e description; os campos opcionais relevantes incluem tools, model e permissionMode. Gerencie-os com /agents, e use o [guia de subagentes](/pt/claude-code/subagents/) para essa parte da configuração do seu projeto. As skills empacotam procedimentos reutilizáveis em uma pasta que contém SKILL.md, com scripts e material de referência opcionais. Claude pode selecionar skills relevantes, ou você pode invocar uma com /skill-name; o corpo da skill é carregado quando ela é usada. O [guia de skills](/pt/claude-code/skills/) aborda esse fluxo de trabalho. Essas estruturas são anteriores à versão que introduziu o fallback AGENTS. O [registro de alterações da versão marcada com uma tag](https://raw.githubusercontent.com/anthropics/claude-code/v2.1.277/CHANGELOG.md) confirma que as configurações de projeto, os comandos, os agentes e as skills já existiam na v2.1.277. As descrições detalhadas dos diretórios se baseiam em documentação atualizada continuamente, cuja redação exata na data de corte não foi verificada. ## CLAUDE.md versus memória automática CLAUDE.md e a memória automática diferem em quem escreve o conteúdo. Você escreve arquivos de instruções para definir as orientações do projeto; Claude salva contexto útil na memória automática. O registro de alterações da versão marcada com uma tag registra o salvamento automático e o gerenciamento por meio de /memory na versão 2.1.59. Portanto, a memória automática tem uma função distinta das instruções que você mantém deliberadamente em CLAUDE.md ou AGENTS.md. Ao decidir onde cada informação deve ficar, use essa distinção de autoria. Coloque comandos explícitos de compilação, convenções, notas de arquitetura e regras de fluxo de trabalho nos seus arquivos de instruções. Use /memory para gerenciar o contexto útil que Claude salva automaticamente. ## Principais conclusões - CLAUDE.md contém instruções persistentes em Markdown que Claude Code lê e incorpora ao contexto; ele não impõe configurações. - Claude Code 2.1.277 adiciona fallback condicional para AGENTS.md , com Bedrock, Vertex e Foundry excluídos no lançamento. - Um arquivo ancestral CLAUDE.md, .claude/CLAUDE.md, ou CLAUDE.local.md suprime o fallback padrão. - Defina as instruções do projeto como claude-md-and-agents-md para carregar ambas as famílias de instruções. - Na v2.1.277, as opções do plugin devem ficar nas configurações do usuário, em um arquivo --settings ou nas configurações gerenciadas — não nas configurações de projeto .claude/settings.json. - O .claude também contém configurações, comandos, subagentes e skills; a memória automática contém contexto salvo por Claude. ## Perguntas frequentes ### O que é CLAUDE.md? CLAUDE.md é um arquivo Markdown de texto simples que contém instruções persistentes para Claude Code, como comandos de compilação, convenções de código, notas de arquitetura e regras de fluxo de trabalho. Claude o lê e incorpora ao contexto da sessão, e /init pode gerar um arquivo inicial com base no projeto. ### Qual arquivo é carregado quando CLAUDE.md e AGENTS.md existem? No modo padrão de Claude Code 2.1.277 claude-md-or-agents-md de operação, um arquivo de instruções do Claude que atenda aos critérios impede o uso de AGENTS como alternativa. Selecione claude-md-and-agents-md para carregar ambos, ou importe instruções de AGENTS de um arquivo vizinho usando @AGENTS.md dentro de CLAUDE.md. ### Por que adicionar CLAUDE.local.md interrompe o fallback para AGENTS? A versão 2.1.277 inclui CLAUDE.local.md entre os arquivos que suprimem o fallback padrão quando encontrados no caminho da raiz do sistema de arquivos até o diretório de trabalho. Portanto, sua presença pode alterar se as instruções compartilhadas de AGENTS são carregadas, embora sua finalidade seja fornecer orientações pessoais para o projeto. ### Posso habilitar ambos os arquivos no .claude/settings.json do projeto? Na v2.1.277, o arquivo de projeto .claude/settings.json não fornece as agents-md opções do plugin. Use /config, ou coloque a configuração documentada pluginConfigs nas configurações do usuário, em um arquivo --settings ou nas configurações gerenciadas. [Claude](/pt/blog/tag/claude/)[Programação](/pt/blog/tag/coding/)[Agentes](/pt/blog/tag/agents/) A [AI Prime Tech](https://aiprimetech.io/pt/) A AI Prime Tech publica este blog. Os artigos são redigidos com assistência de IA; confira detalhes específicos de cada versão, como IDs de modelos, preços e limites, na documentação oficial antes de se basear neles. Obtenha acesso mais barato à API do Claude Uma única chave de API para Claude Opus 5.5, Sonnet 5, Haiku 4.5 e Fable 5.1, além de GPT-6 modelos. Pague conforme o uso, sem assinatura. [Obtenha Sua Chave de API →](/register) A AI Prime Tech é um gateway de API independente de terceiros. Claude™ e Anthropic® são marcas comerciais da Anthropic, PBC. Não há afiliação nem endosso implícitos.