- 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
Ainda não há comentários.