Chega um dia em que o seu projeto tem regras — como se inicia, com qual comando se testa, o que NÃO se toca, como se escrevem os commits — e mais de um cérebro artificial passa por ele: você constrói com um, revisa com outro, e amanhã troca de modelo para gastar menos créditos. O problema é que esse conhecimento vive na sua cabeça, e cada agente novo começa do zero: você explica tudo, fecha a sessão, e uma semana depois repete de novo (ou repete para uma IA diferente). AGENTS.md acaba com esse pedágio. É um padrão aberto — um "README para agentes" — que hoje mais de 25 ferramentas leem (OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, Aider, Zed, Windsurf, Devin, Claude Code…) e mais de 60.000 projetos usam. Um arquivo de Markdown puro, sem configuração estranha, na raiz do seu projeto: você escreve suas regras UMA vez e todos os agentes obedecem, hoje e amanhã. Aqui você vai entender por que precisa dele, o que vai dentro, a nuance entre AGENTS.md e CLAUDE.md sem duplicar nada, e o prompt que o gera perfeito olhando o seu código de verdade. Zero enrolação.
A necessidade aparece no dia em que o seu projeto tem regras e mais de um cérebro artificial passa por ele. Pode ser que você use o Claude Code para construir, outra ferramenta para revisar, e de vez em quando abra o Cursor ou o Copilot para algo pontual. Ou que amanhã troque de agente para economizar créditos. Em todos esses casos há conhecimento que não vive no código: como se inicia o ambiente, com qual comando os testes rodam, quais pastas são sagradas e não se tocam, como você quer que as mensagens de commit sejam escritas. Esse conhecimento hoje vive na sua cabeça — e cada agente novo começa do zero, sem saber nada disso.
A dor é silenciosa e se paga em parcelas. A sessão de hoje com a sua IA sabe perfeitamente como o seu projeto funciona porque você foi explicando durante horas. Mas esse conhecimento não fica guardado em lugar nenhum: quando você fecha a conversa, ele evapora. Amanhã você abre uma sessão nova — ou troca de modelo para gastar menos — e está de novo na estaca zero, repetindo "lembra que os testes rodam com este comando", "não toque na pasta de pagamentos", "os commits vão neste formato".
Por que isso acontece? Porque cada agente começa cego: só vê o seu código, não vê suas regras nem seus costumes. E como cada ferramenta guardava suas instruções à sua maneira — Claude num arquivo, Cursor em outro, Copilot em outro — você tinha que manter o mesmo conhecimento escrito três ou quatro vezes. Um caos que se dessincroniza sozinho: você muda uma regra num arquivo e esquece nos demais.
AGENTS.md é um README para agentes. Assim como o README de sempre conta a um humano do que se trata o seu projeto, AGENTS.md conta a qualquer IA de código como se comportar dentro dele. É um arquivo de texto puro (Markdown) que você coloca na raiz do seu projeto, e pronto. Sem configuração estranha, sem código, sem cerimônias.
O que o torna poderoso não é o formato — é que ele virou um padrão aberto que hoje mais de 25 ferramentas diferentes leem: OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, Google Jules, Aider, Zed, Windsurf, Devin, JetBrains Junie, Warp, goose e mais. Mais de 60.000 projetos de código aberto já o usam. Você escreve suas regras UMA vez, e elas funcionam com a IA que você usa hoje e com a que usar amanhã. Você deixa de estar casado com uma única ferramenta.
O padrão aberto AGENTS.md — o "README para agentes" que hoje mais de 25 ferramentas de código com IA leem. Guia, exemplos e a especificação completa. Administrado pela Agentic AI Foundation (Linux Foundation). ~23k★.
Aqui vem a melhor notícia: não precisa aprender um formato rígido. AGENTS.md é Markdown comum e corrente — títulos com #, listas com traços, texto. Não leva aquele cabeçalho técnico cheio de dois-pontos e chaves (o que os programadores chamam de YAML frontmatter): nada disso é obrigatório. Você escreve em seções com o nome que quiser, e o agente lê o que você colocar. Ponto.
Dito isso, há cinco blocos que quase todo bom AGENTS.md inclui — porque são justamente o conhecimento que evapora entre sessões. Pense neles como as cinco gavetas do manual do cargo:
Este recurso não é daqueles que se aplicam todo dia — é daqueles que se fazem bem uma vez e se ajustam de tempos em tempos. A constância aqui não está na frequência, mas em dois momentos concretos em que você não pode esquecer dele:
Aqui é onde as pessoas se enrolam, então vamos deixar claro. Antes de o padrão existir, cada ferramenta inventou seu próprio arquivo de regras: Claude Code lê um CLAUDE.md, Cursor lia um .cursorrules, e assim por diante. O problema evidente: se você usava três ferramentas, mantinha três arquivos com o mesmo conhecimento, dessincronizando sozinhos. AGENTS.md nasceu justamente para acabar com essa bagunça: uma única fonte de verdade que todas leem.
# CLAUDE.md # Las reglas del proyecto viven en AGENTS.md (fuente única). # Claude Code las carga con esta línea de importación: @AGENTS.md # Debajo, solo lo específico de Claude Code que NO aplica # a los demás agentes (si es que hay algo).
Quando usar qual? Fácil: AGENTS.md para tudo que você quer que qualquer agente obedeça (95% das suas regras). O arquivo próprio de uma ferramenta (CLAUDE.md, .cursorrules) só para o que é exclusivo dessa ferramenta — um comando que só ela entende, um ajuste que só serve para ela. Na dúvida, vai para o AGENTS.md. A regra mental: escreva para todos por padrão; escreva para um só por exceção.
Se você vem da ideia de escrever uma especificação antes de construir (o quê você quer que seja construído), AGENTS.md é a outra metade do par — e eles não se atropelam, se complementam. A spec governa O QUÊ se constrói: a funcionalidade, o objetivo, o resultado. AGENTS.md governa COMO qualquer agente se comporta enquanto constrói: com quais comandos, quais regras, o que não tocar. Uma é a planta do prédio; a outra, as normas de segurança da obra. Você precisa das duas.
Aqui está o atalho. Você não precisa escrever o arquivo à mão nem pensar em cada seção: você dá este prompt ao seu agente de código dentro do seu projeto, e ele redige tudo para você olhando como o seu código está montado de verdade. Você só revisa e ajusta. Copie tal como está, preencha os colchetes com o que você souber, e deixe ele trabalhar:
Quero criar um arquivo AGENTS.md na raiz do meu projeto: o "README para agentes" do padrão aberto (agents.md) que as ferramentas de IA de código leem. É Markdown puro, SEM cabeçalho YAML. Me guie em linguagem simples, assumindo que não sou programador. Primeiro, EXPLORE o meu projeto de verdade (revise a estrutura de pastas, o package.json ou equivalente, e como está organizado) para NÃO inventar nada. Depois redija um AGENTS.md com estas seções, em Markdown limpo: 1. Resumo do projeto — 2 ou 3 frases do que é e quais tecnologias usa (deduza do código). 2. Preparar o ambiente — os comandos reais para instalar e iniciar o projeto do zero. 3. Como se testa — o comando exato dos testes e da checagem de erros/tipos, para que qualquer agente verifique seu trabalho antes de dar por bom. 4. Regras de estilo — o idioma do código e as convenções que você detectar (aspas, nomes, formato). 5. Commits e PRs — este é o meu formato de mensagens de commit: [descreva-o, ou me diga se não tenho um e proponha um bom]. 6. Limites · o que NÃO se toca — marque como INTOCÁVEIS sem permissão explícita estas pastas/arquivos sagrados: [liste aqui o sensível: pagamentos, segredos, configuração, migrações… o que você tiver]. Deixe claro que um agente deve PARAR e perguntar antes de modificá-los. Regras para redigir: - Só afirme coisas que você possa verificar olhando o meu código. Se algo você não souber, coloque um marcador [A CONFIRMAR] em vez de inventar. - Que seja conciso e acionável, não um romance. Um agente lê tudo antes de trabalhar. - Se a minha ferramenta principal já tem seu próprio arquivo de regras (por exemplo CLAUDE.md), NÃO duplique o conteúdo: faça esse arquivo importar o AGENTS.md com uma única linha, e me deixe o AGENTS.md como fonte única de verdade. Ao terminar, me mostre o arquivo completo e me explique em uma frase o que você guardou em cada seção, para eu revisar.
[A CONFIRMAR] quando não estiver certa — nada de enrolação, nada de regras inventadas. Seu trabalho se reduz a ler o rascunho e corrigir o que não bater com o jeito que você trabalha. De especialista a revisor: exatamente o papel que cabe a você.Como em toda a série, há duas formas de fazer isso e nenhuma te obriga a mexer no terminal se você não quiser:
AGENTS.md na pasta raiz do seu projeto, e escreve as cinco seções você mesmo copiando o modelo de baixo. Também vale — é só texto.Se você vai pelo caminho manual, este é o modelo mínimo pronto para copiar e preencher. Mude ao seu gosto: lembre que não há formato obrigatório.
# AGENTS.md ## Resumen del proyecto [Qué es y con qué está hecho. 2-3 frases.] ## Preparar el entorno [Comandos para instalar y arrancar de cero.] ## Cómo se prueba - Pruebas: [comando exacto] - Chequeo de errores/tipos: [comando exacto] > Corre esto y déjalo en verde antes de dar por terminado un cambio. ## Reglas de estilo [Idioma del código, convenciones de nombres/formato.] ## Commits y pull requests [Tu formato de mensajes de commit. Ejemplo de uno bueno.] ## Límites · NO tocar sin permiso - [Carpeta o archivo sagrado 1 — por qué es sensible] - [Carpeta o archivo sagrado 2] > Ante cualquiera de estos: PARA y pregunta antes de modificar.
AGENTS.md, na raiz. Pare de se repetir em cada sessão.Join 4,200+ builders. No credit card. Build your first app with AI in minutes.