AGENTS.md: o que é e como usar com CLAUDE.md e outras ferramentas
Entenda o que é o AGENTS.md, como ele se relaciona com o CLAUDE.md e como manter uma única fonte de instruções para vários assistentes de código.
Quer aplicar isso na sua empresa?
Agendar conversa com o Juan →AGENTS.md: o que é e como usar com CLAUDE.md e outras ferramentas
AGENTS.md é um arquivo Markdown na raiz do repositório que reúne instruções para agentes de código: como instalar dependências, rodar testes, seguir convenções e o que evitar. Funciona como um README escrito para o agente, e várias ferramentas já o leem. O Claude Code lê o CLAUDE.md, então a forma mais simples de manter uma única fonte é escrever tudo no AGENTS.md e fazer o CLAUDE.md apontar para ele.
Principais pontos
- AGENTS.md é um formato aberto e simples: texto em Markdown, sem campos obrigatórios, versionado junto com o código.
- O CLAUDE.md cumpre papel parecido dentro do Claude Code. Os dois não se substituem automaticamente, mas podem compartilhar o mesmo conteúdo.
- Uma fonte única evita instruções que divergem entre ferramentas e reduz o trabalho de manutenção da equipe.
- O arquivo deve conter comandos, convenções e limites verificáveis, não textos genéricos sobre "ser um bom programador".
- Instrução em arquivo orienta o agente, mas não substitui permissões, sandbox e revisão humana.
O que é o AGENTS.md e para que serve?
Todo assistente de código precisa de contexto sobre o projeto antes de agir bem. Qual comando roda os testes? Qual gerenciador de pacotes é usado? Onde ficam as migrações? Que pastas não devem ser editadas? Sem essas respostas, o agente adivinha, e adivinhar custa tempo de revisão.
O AGENTS.md resolve isso com um lugar previsível. A ideia, descrita no site do formato, é que o README continue falando com pessoas e o AGENTS.md fale com agentes, com detalhes que atrapalhariam a leitura humana, como passos exatos de build e regras de estilo.
O formato é deliberadamente leve. Não há esquema rígido: são títulos e listas em Markdown. Em repositórios com várias pastas, também é possível ter arquivos aninhados em subpastas, e a convenção é que o arquivo mais próximo do código editado tenha precedência. Isso ajuda em monorepos, onde o serviço de pagamentos e o aplicativo móvel seguem regras diferentes.
O ponto que mais importa para quem decide: o arquivo vive no repositório. Ele passa por pull request, tem histórico e dono. Instrução que ninguém revisa envelhece e passa a enganar o agente.
Como o AGENTS.md se relaciona com o CLAUDE.md?
O CLAUDE.md é o arquivo de memória do projeto no Claude Code. Ele é carregado no início das sessões e carrega instruções persistentes. A documentação de memória do Claude Code descreve os níveis em que esses arquivos podem existir (projeto, usuário e outros) e a possibilidade de importar outros arquivos com a sintaxe de arroba.
Na prática, a relação é esta: AGENTS.md é um formato compartilhado entre várias ferramentas, e CLAUDE.md é o nome que o Claude Code procura. Se o repositório tem só o AGENTS.md, o Claude Code não depende dele por conta própria. Confirme o comportamento atual na documentação da versão que a sua equipe usa, porque ferramentas mudam.
Há três arranjos comuns:
- Dois arquivos independentes. Simples no começo, mas as instruções divergem em poucas semanas.
- Link simbólico do CLAUDE.md para o AGENTS.md. Funciona bem em Linux e macOS, mas pode dar atrito em equipes com Windows ou em alguns fluxos de CI.
- CLAUDE.md curto que importa o AGENTS.md. É o arranjo mais portátil: o CLAUDE.md contém uma linha de importação e, se necessário, instruções que valem só para o Claude Code.
Para a maioria das equipes, a terceira opção é a mais segura. O conteúdo comum fica no AGENTS.md, e o CLAUDE.md guarda apenas o que é específico da ferramenta, como referência a skills ou a configurações do Claude Code. Para esse segundo grupo, veja Skills no Claude Code.
O que escrever no arquivo e o que deixar de fora?
O arquivo é lido a cada sessão, então ele ocupa espaço na janela de contexto do modelo. Texto demais dilui o que importa. A Anthropic discute isso em seu material sobre engenharia de contexto: o objetivo é dar o menor conjunto de informações que realmente orienta o comportamento. Para entender o limite em termos simples, vale ler sobre janela de contexto.
O que costuma valer a pena incluir:
- Comandos exatos para instalar, compilar, rodar testes e rodar o linter, com o diretório onde executá-los.
- Estrutura do projeto em poucas linhas: o que existe em cada pasta principal.
- Convenções que o linter não pega, como nomes de arquivos, padrão de commits e estilo de mensagens de erro.
- Limites claros: pastas geradas, arquivos que nunca devem ser editados, migrações que exigem aprovação.
- Critério de pronto: quais verificações precisam passar antes de o agente dizer que terminou.
- Como lidar com dados sensíveis: não colar dados reais de clientes em testes, usar massas fictícias, respeitar a LGPD.
O que deixar de fora:
- Segredos, tokens e senhas. O arquivo é versionado e lido por ferramentas diferentes.
- Descrições longas de arquitetura que já existem em documentação própria. Aponte para o documento.
- Regras vagas como "escreva código limpo". Se não dá para verificar, o agente não tem como seguir de forma consistente.
- Instruções que mudam toda semana. Isso pertence a uma tarefa, não ao arquivo permanente.
Uma boa regra de escrita: cada linha deve responder a um erro real que já aconteceu ou a uma dúvida que o agente teria. Se nenhuma das duas, a linha provavelmente pode sair.
Como manter uma única fonte de instruções, passo a passo
Este é um plano de adoção que cabe em uma tarde para um repositório pequeno e em um piloto curto para vários.
- Levante o que existe hoje: procure CLAUDE.md, arquivos de regras de editor, instruções de copiloto e trechos soltos no README. Liste o que cada um diz.
- Consolide em um AGENTS.md na raiz, removendo duplicações e contradições. Quando duas instruções conflitam, decida com o responsável técnico e registre a decisão.
- Crie um CLAUDE.md curto que importe o AGENTS.md e mantenha nele só o que é exclusivo do Claude Code.
- Para as demais ferramentas da equipe, confirme na documentação de cada uma se leem AGENTS.md. Se alguma exigir outro nome de arquivo, prefira uma referência ou um passo de sincronização automatizado, em vez de copiar texto à mão.
- Defina um dono e uma regra de revisão: alterações no AGENTS.md passam por pull request como qualquer código.
- Teste com tarefas reais e pequenas: peça a cada ferramenta que rode os testes e faça uma mudança simples. Veja se todas seguiram os mesmos comandos e convenções.
- Revise depois de algumas semanas: remova o que ninguém usou e acrescente os erros recorrentes que o agente cometeu.
Se a equipe ainda está escolhendo ferramentas, o texto sobre Claude Code, Cursor ou GitHub Copilot ajuda a comparar critérios. Uma fonte única de instruções reduz o custo de trocar ou combinar ferramentas depois.
Cenário ilustrativo: uma equipe com três assistentes
Imagine uma software house pequena que atende varejistas. Uma pessoa desenvolvedora usa o Claude Code, outra prefere um editor com agente integrado e uma terceira usa o assistente do GitHub. Cada uma criou suas próprias instruções. Em um mesmo repositório, um assistente roda os testes com um comando, outro usa um comando antigo, e o terceiro formata o código em um estilo diferente. As revisões de pull request ficam cheias de ajustes de estilo.
A equipe decide consolidar. Cria um AGENTS.md com os comandos corretos, a estrutura das pastas, o padrão de commits e uma lista de arquivos que não devem ser editados. O CLAUDE.md passa a importar esse arquivo. Depois, a equipe pede a cada ferramenta a mesma pequena tarefa e compara o resultado. As divergências que sobram mostram o que ainda falta no arquivo.
Este é um cenário ilustrativo, sem resultados medidos. O que ele mostra é o mecanismo: a mesma instrução, em um só lugar, revisada por pessoas.
Instrução em arquivo não é controle de acesso
Um erro comum é tratar o AGENTS.md como cerca de segurança. Escrever "nunca apague a pasta de produção" é útil, mas é só uma orientação. O modelo pode seguir, esquecer ou ser induzido a ignorar, por exemplo por um texto malicioso em um arquivo ou página que ele leu. O guia da OWASP sobre prevenção de prompt injection explica por que instruções e dados não confiáveis se misturam e por que a defesa precisa de camadas.
Por isso, o que é crítico deve ser imposto fora do texto:
- Permissões da ferramenta configuradas para negar comandos destrutivos e leitura de arquivos de segredos.
- Sandbox ou ambiente isolado para execução.
- Aprovação humana para ações irreversíveis, como deploy, migração e exclusão.
- Credenciais de menor privilégio, nunca as de produção, no ambiente do agente.
O texto Segurança no Claude Code para empresas detalha permissões, sandbox e tratamento de segredos. O AGENTS.md diz o que se espera; a configuração impede o que não pode acontecer.
Há ainda um cuidado de privacidade. Se o repositório lida com dados pessoais de clientes, o arquivo deve deixar claro que dados reais não entram em testes, prompts ou logs. Isso não cumpre a LGPD sozinho, mas registra a regra interna que a equipe pode auditar.
Como o método mapear, limitar, pilotar e transferir se aplica
O mesmo raciocínio que usamos para agentes de atendimento vale para agentes de código. Mapear: entender como a equipe trabalha hoje, quais ferramentas usa e onde as instruções estão espalhadas. Limitar: definir o que o agente pode ler, executar e alterar, com permissões e não só com texto. Pilotar: escolher um repositório e uma tarefa real, com um critério de sucesso combinado, por exemplo que os testes passem sem correção manual de estilo. Transferir: deixar o arquivo com dono, regra de revisão e uma decisão explícita de expandir, ajustar ou parar.
Não há promessa de ganho. O que se busca é previsibilidade: o agente se comportar de forma parecida em qualquer ferramenta e a equipe saber por quê.
Perguntas frequentes
AGENTS.md substitui o README? Não. O README continua sendo a porta de entrada para pessoas, com visão geral e instruções de uso. O AGENTS.md complementa com detalhes operacionais para agentes, como comandos exatos e regras de edição, que seriam excessivos para o leitor humano.
O Claude Code lê o AGENTS.md diretamente? A referência estável do Claude Code é o CLAUDE.md. Por isso, a prática recomendada é criar um CLAUDE.md que importe o AGENTS.md, em vez de supor leitura direta. Como o comportamento das ferramentas muda, confirme na documentação da versão em uso.
Posso ter AGENTS.md em subpastas? Sim, e isso é útil em monorepos. A convenção é que o arquivo mais próximo do código editado prevaleça sobre o da raiz. Mantenha os arquivos aninhados curtos e só com o que for diferente do arquivo principal, para evitar conflitos.
Quem deve manter o AGENTS.md? Defina uma pessoa responsável, normalmente quem cuida da qualidade técnica do repositório, e use pull request para qualquer mudança. Revise o arquivo quando o agente repetir um erro ou quando comandos do projeto mudarem. Instrução desatualizada é pior do que instrução ausente.