AGENTS.md - um formato aberto para agentes de codificação com IA

 (agents.md)
35 pontos por GN⁺ 2025-08-21 | 1 comentários | Compartilhar no WhatsApp
  • AGENTS.md complementa o README e funciona como um arquivo dedicado a contexto e instruções necessários quando agentes de codificação com IA trabalham em um projeto
  • Já é usado em mais de 20 mil projetos de código aberto, organizando informações como build/testes/estilo de código que são desnecessárias para humanos, mas importantes para agentes
  • Fornece instruções dedicadas a agentes em um local claro e previsível, mantendo o README conciso e ao mesmo tempo aumentando a eficiência da colaboração
  • Um único AGENTS.md é compatível com vários agentes e ferramentas, e em monorepos grandes é possível usar AGENTS.md separados por subprojeto
  • Um padrão aberto criado em colaboração entre vários ecossistemas, como OpenAI Codex, Cursor e Google Jules

Why AGENTS.md?

  • README.md é documentação para humanos, oferecendo início rápido, descrição do projeto e diretrizes de contribuição
  • AGENTS.md é um documento auxiliar para agentes, contendo contexto detalhado como regras de build/testes/código sem tornar o README complexo
  • Motivos para mantê-lo em um arquivo separado
    • Oferece aos agentes um local previsível para consultar instruções
    • Mantém o README enxuto e focado em contribuidores humanos
    • Fornece instruções precisas dedicadas a agentes que complementam a documentação existente
  • Adota um nome de padrão aberto que qualquer pessoa pode usar, em vez de um formato proprietário
  • Um AGENTS.md pode ser compatível com vários agentes de codificação com IA e ferramentas

How to use AGENTS.md?

  • 1. Criar o arquivo AGENTS.md
    • Coloque-o na raiz do repositório (muitos agentes oferecem suporte à criação automática)
  • 2. Escrever os itens principais
    • Visão geral do projeto
    • Comandos de build e teste
    • Diretrizes de estilo de código
    • Como testar
    • Considerações de segurança
  • 3. Incluir instruções adicionais
    • Regras de commit/PR, cuidados de segurança, grandes conjuntos de dados, etapas de deploy e outros pontos a transmitir à equipe
  • 4. Suporte a monorepo
    • É possível colocar um AGENTS.md para cada pacote
    • Os agentes leem o arquivo mais próximo e seguem as instruções adequadas para aquele subprojeto
    • Exemplo: o repositório da OpenAI contém 88 arquivos AGENTS.md

FAQ

  • Itens obrigatórios: nenhum; use livremente o formato padrão de Markdown
  • Em caso de conflito: o AGENTS.md mais próximo tem prioridade; prompts explícitos do usuário prevalecem por último
  • Execução automática: os comandos de teste especificados no arquivo podem ser executados pelo agente para tentar corrigir erros
  • Possibilidade de atualização: pode ser alterado a qualquer momento, sendo gerenciado como um documento vivo
  • Migração de documentação existente: renomeie o arquivo e mantenha compatibilidade com um link simbólico
    • mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

Leituras relacionadas

1 comentários

 
GN⁺ 2025-08-21
Comentários do Hacker News

  • Em projetos pequenos, um único arquivo .md já basta, mas em projetos complexos percebi que uma estrutura hierárquica de pastas com index.md é muito mais eficaz
    Uma estrutura composta por index.md e arquivos abaixo dele como auth.md e performance.md é fácil de manter, e permite que um LLM ou agente extraia apenas o contexto relevante sem gastar tokens desnecessariamente
    Os arquivos .docs acabam ficando adequados tanto para humanos quanto para LLMs, e o index.md também pode incluir uma orientação breve sobre cada arquivo e diretrizes de organização
    Dito isso, acho que um nome mais intuitivo do que .agents seria melhor, como .codebots ou .context

    • Acho que não há necessidade de esconder arquivos e diretórios importantes
      Especialmente no caso de documentação, escondê-la só a torna mais opaca; talvez seja tradição, mas esse não parece um bom padrão
      Fiquei pensando se um nome como robot_docs não seria melhor

    • Na verdade, como esse tipo de informação coincide com o que os contribuidores querem saber, acho que o lugar certo para isso originalmente seria o CONTRIBUTING.md

    • Essa estrutura parece um documento de design de software/guia de estilo de código para humanos e robôs ao mesmo tempo
      Eu coloco esses arquivos .md na pasta docs/, e o Claude Code os escreve diretamente
      AGENTS.md e CLAUDE.md deveriam ser usados apenas para robôs, e tanto dividir um grande arquivo em seções com cabeçalhos h2 quanto separá-lo em vários arquivos têm seus prós e contras
      Também existem formatos de documentação de arquitetura, como o Arc42, que suportam os dois casos
      Em vez de referenciar uma seção específica dentro de um Markdown grande, é mais fácil e menos sujeito a erros criar um arquivo separado e mencioná-lo com @
      Quando é preciso focar em uma parte específica, quebrar em arquivos pequenos também é melhor para agentes de código
      Arquivos menores também são mais práticos para revisar diff/PRs

    • Também é possível ter vários arquivos AGENTS.md dentro da codebase
      Se o tooling ler tanto o AGENTS.md do diretório atual quanto o da raiz, a informação pode ficar perto do código, o que combina com a forma como eu gostaria de trabalhar

    • Eu também uso uma estrutura parecida, e tenho obtido resultados bem bons adicionando ao index.md uma breve orientação sobre cada arquivo
      Também estou experimentando uma abordagem de colocar arquivos de regras por diretório, como rules.md, com o comportamento desejado
      Por exemplo, em um diretório que reúne serviços variados como realtime-service.ts e queue-service.ts, eu deixaria um rules.md ao lado deles
      Dá para indicar esse arquivo de regras no prompt e criar coisas novas com facilidade; o nome ainda precisa de mais reflexão

  • No momento, estamos em uma fase de transição em que é preciso escrever guias especiais, além do que os humanos precisam, para ajudar o agente a entender a codebase
    Acho que em breve isso não será mais necessário
    Se a documentação do projeto já fosse suficientemente completa desde o início, tudo o que está em AGENTS.md também poderia estar incluído nela
    Devemos sempre escrever documentação pensando em humanos, e a vantagem dos LLMs é justamente conseguirem ler o que foi escrito por humanos
    Acho que esse é o jeito certo de pensar o design

    • Isso é útil não só para entender a codebase, mas também para explicitar regras de um estilo específico, como qual biblioteca de assert usar nos testes, proibição de comentários, uso de logging estruturado etc.
      Na verdade, pode ser até mais útil em projetos novos, onde quase não há código ainda

    • Imagino que regras legíveis por máquina serão adotadas cada vez mais em vários lugares da sociedade
      Um exemplo são os carros autônomos e as leis de trânsito: placas cujo contexto já é difícil para humanos entenderem, como “proibido virar à direita no sinal vermelho, em dias letivos, das 7 às 9”, são ainda mais difíceis para máquinas
      No fim, os órgãos públicos vão precisar reduzir a exigência de contexto ou trocar isso por sinais com legibilidade para máquinas, como QR codes
      Sem esse tipo de mudança, as máquinas vão acabar infringindo regras com frequência

    • Em áreas como lógica de negócio, acho que instruções especiais para agentes continuarão sendo indispensáveis
      O que está sendo construído, qual é a intenção e qual é o objetivo final do projeto são coisas que a máquina não consegue inferir sem que alguém as explique de forma concreta
      O mesmo vale para arquitetura: cada pessoa tem um critério diferente, e ter essa estrutura mental ajuda a entender mudanças reais; no fim, esse é o verdadeiro gargalo

    • Concordo no geral, mas às vezes surge a vontade de forçar a inclusão de certas informações em um arquivo separado, por exemplo algo que você quer garantir que esteja sempre no contexto

    • Se não documentarmos as regras e premissas que temos implicitamente em mente, o LLM não tem como saber
      Talvez ele consiga inferir parte disso a partir do código, mas nunca 100%, então é importante deixar os requisitos explícitos

  • No fim das contas, AGENTS.md faz o mesmo papel que README.md, só que com hype suficiente para fazer as pessoas realmente preencherem o conteúdo, e isso é curioso
    As pessoas têm preguiça de escrever documentação para outras pessoas, mas para robôs estão escrevendo com empenho, o que é interessante
    Esse fenômeno é parecido com projetar algo ergonomicamente para uma minoria e acabar criando um design de alça melhor para todo mundo

    • Na verdade, é o contrário: como as pessoas não liam a documentação, ninguém se sentia motivado a escrevê-la
      Um CLAUDE.md para agentes, uma vez escrito, logo será lido por mil agentes, então dá mais vontade de escrever

    • No fim, não daria para simplesmente colocar o mínimo necessário no README.md?

    • Na prática, até os próprios agentes acabam não lendo esse documento ou esquecendo tudo depois de mais algumas instruções

    • A situação atual existe porque as pessoas estão tentando ativamente tirar desenvolvedores humanos — inclusive elas mesmas — do processo de desenvolvimento, e por isso os agentes precisam necessariamente ter instruções adequadas
      Isso vem de um desejo crescente de eliminar toda participação humana no desenvolvimento de software

build steps, tests, and conventions that might clutter a README or aren’t relevant to human contributors. Separar esse tipo de coisa à parte realmente dá uma sensação de não entender mais como o mundo está funcionando

  • Comentando em tom de brincadeira, hoje em dia o clima todo é de vibe coding
    Acho que já apareceu antes a opinião de que escrever documentação para bots no fundo não é tão diferente de escrever boa documentação

  • No fim, passa a impressão de “crie um arquivo AGENTS.md e preencha com magia”, e então mandar o usuário para o site de verdade

  • No meu caso, estou desenvolvendo um agente de programação que gerencia mais de 5.000 repositórios
    O estado do agente é salvo dentro de um diretório oculto .agent, que inclui pastas de configuração por papel do agente e instruções claras para cada papel
    No diretório do projeto, eu mantenho uma pasta agents, dividindo vários arquivos por papel no formato <Role> <instruction>
    O agente lê apenas os arquivos do papel definido, e o estado fica guardado em uma pasta dot<coding agent name>
    A inicialização é feita com /init e, em vez de simplesmente indexar todo o código do repositório, ele gera um high-level summary de toda a arquitetura e lógica
    Esse resumo é fornecido no editor como “ghost comments” alternáveis, metadados que não são commitados no código real
    Cada resumo é ligado com precisão às linhas de código por meio de um sistema sofisticado de mapeamento
    No começo, quando usei RAG diretamente sobre o código, não obtive o resultado que queria, então adotei essa estrutura atual
    Hoje uso um modelo híbrido de busca que combina pesquisa sintática rápida baseada em AST com exploração semântica baseada em resumo (RAG)
    Por exemplo, se você perguntar “como funciona a autenticação deste app?”, a busca sintática encontrará apenas funções com palavras como login, enquanto a busca semântica, por meio dos resumos, reconstrói narrativamente todo o fluxo de autenticação e conecta conteúdos espalhados por diferentes arquivos — e isso funciona quase como mágica

    • Além disso, dá para criar uma hierarquia de resumos, em forma de árvore B ou árvore comum
      Ou seja, haveria um summary por método/classe/módulo, com cada nível apontando para os níveis inferiores
      O RAG poderia explorar na profundidade necessária conforme a consulta semântica, e cada etapa resumiria o conteúdo abaixo, reduzindo o volume de informação, mas preservando o significado essencial
      Essa abordagem é especialmente eficaz quando o código tem uma boa abstração
      Por exemplo, em uma função como add(n1, n2), o nome por si só já transmite o significado, então não é necessário conhecer a implementação real; mas em funções do mundo real, que também fazem logging, cache etc., talvez seja necessário incluir o código real no contexto dependendo da situação

    • Gostaria de ouvir uma explicação mais detalhada

  • Parece que os humanos estão sendo lentamente condicionados a finalmente escrever a documentação do projeto direito

    • É brincadeira, mas na verdade tenho usado exatamente esse argumento com a equipe
      Mesmo que os LLMs não aumentem tanto assim a produtividade na prática, o efeito colateral é que a documentação acaba ficando muito melhor

    • "Mission. Fucking. Accomplished." xkcd 810

  • Ainda não tenho certeza se faz sentido separar README.md e AGENTS.md

  1. estilo de escrita (ênfase em CAIXA ALTA em documentos para agentes é desconfortável em documentos para humanos)
  2. concisão versus completude (documentos para agentes devem levar apenas a informação essencial, enquanto os para humanos devem documentar tudo o máximo possível)
  3. diferença nas necessidades de informação (o que um LLM precisa e o que é importante para um humano não são a mesma coisa)
    O motivo para não separar é:
  4. manutenção duplicada (o peso de escrever a mesma coisa essencialmente em dois lugares)

  • O README.md hoje parece mais uma página de marketing/landing page, enquanto AGENTS.md e CLAUDE.md viraram o lugar para buscar o conteúdo real sobre código, arquitetura e uso

  • Ao ler os exemplos, pensei a mesma coisa: talvez um único README.md realmente bem feito já bastasse

  • O README é para humanos; AGENTS.md e afins são para LLMs
    Como usar e instalar vai no readme; como compilar e testar, decisões de arquitetura, padrões de código, estrutura do repositório etc. ficam nos documentos para agentes

  • Também é preciso pensar na limitação de capacidade de contexto dos LLMs
    README.md costuma ser longo demais para ser enviado inteiro no contexto
    No AGENT.md, você coloca de forma concisa apenas os comandos essenciais de teste, build etc. que o LLM realmente precisa
    Pode haver sobreposição com o README, mas a ideia é evitar retransmitir contexto desnecessário

  • A promessa da IA não era justamente que não precisaríamos ficar obcecados com formatos exatos, porque a máquina se adaptaria ao jeito como escrevemos?

    • Na prática, o que foi padronizado foi só o nome do arquivo, e não o conteúdo; isso faz sentido, porque cada um pode escrever do jeito que quiser sem impor um formato rígido
      AGENTS.md é Markdown padrão, então você pode usar os títulos que quiser, e o agente faz o parsing do texto

    • Ainda assim, algum nível de estrutura e formato continua sendo importante
      Não no nível de sintaxe exata de código, claro, mas ainda importa

    • No fim, a conclusão é que o conteúdo precisa ser escrito com clareza
      Quanto maior a documentação, mais uma abordagem estruturada favorece a manutenção do ponto de vista humano

  • Cada agente que eu uso — Claude Code, Gemini, Aider — usa um nome de arquivo diferente
    Seria ótimo se houvesse padronização, mas por enquanto aceito o trabalho de gerar vários formatos automaticamente com o ruler
    Especialmente porque cada agente também consome arquivos de configuração MCP de maneira diferente, então não acho que a padronização vá acontecer tão cedo
    ruler

    • Vendo de forma um pouco cínica, isso parece um movimento para criar vendor lock-in
      Talvez as empresas evitem padronização porque padronizar pode levar à comoditização

    • O Jules usa AGENTS.md, o que mostra que o Google está aderindo a esse padrão
      Se o Gemini Code Assist continuar existindo, imagino que também passe a oferecer suporte a AGENTS.md
      A documentação do Aider não menciona um nome de arquivo específico; se alguém tiver um link, eu gostaria de ver
      A Anthropic parece ser a única que ainda não oferece suporte a um nome de arquivo padrão

    • É uma pena que uma ferramenta como o ruler realmente seja necessária

  • É um site que passa uma sensação estranha
    Fiquei com a impressão de que, por ter sido feito pela OpenAI, o objetivo seria atrair visitantes e se posicionar em marketing
    Na prática, na verdade ele não define um formato, só um nome de arquivo
    Também chama a atenção a ausência de Anthropic/Claude; embora dê para usar o truque de link simbólico e apontar CLAUDE.md para AGENTS.md

    • Na verdade, foi feito pela Sourcegraph e existe desde maio
      Antes era agent.md, e agora redireciona com 301 para agents.md
      Veja o link antigo
      Também existe um anúncio oficial
      Parece que recentemente firmaram uma parceria com a OpenAI
      Curiosamente, no começo era agent.md, mas agora mudou para agents.md

    • O motivo de o Claude não estar na lista é que só ele ainda não oferece suporte a uma convenção padrão de nome de arquivo