O Manual vs. O Livro de Regras: Um mal-entendido dispendioso
O fato de muitas equipes não entenderem o papel de um arquivo AGENTS.md cria um ponto cego operacional dispendioso. Pesquisas recentes de engenheiros da Coldtea revelam uma realidade nua e crua: apenas 27% dos 1.000 principais repositórios do GitHub possuem um arquivo AGENTS.md, e uma maioria significativa destes está sendo utilizada incorretamente. Esta supervisão generalizada deixa uma lacuna crítica na gestão de contribuições de IA.
O problema central reside em confundir um manual de operação com um 'livro de regras'. A maioria dos arquivos AGENTS.md existentes funciona como manuais, concentrando-se em descrições da arquitetura do projeto ou listando comandos exatos para compilação e teste. Eles dizem à IA como operar, mas, crucialmente, falham em restringir o que ela deve ou não fazer.
Um verdadeiro AGENTS.md atua como um livro de regras, estabelecendo diretrizes rígidas e restrições negativas explícitas para agentes de IA. Sem este livro de regras, os agentes operam sem limites, levando a contribuições inconsistentes, comportamento inesperado e à introdução de potenciais bugs. Repositórios maiores, por exemplo, dedicam quase o dobro do espaço a regras de "não fazer", um sinal claro da sua compreensão desta necessidade. A ausência de diretrizes claras de "deve", "sempre" e "nunca" transforma uma ferramenta potencialmente poderosa numa responsabilidade imprevisível.
O poder do 'Não': Lições da Vercel e Bun
A pesquisa da Coldtea revela um padrão crítico entre os principais repositórios: os arquivos AGENTS.md mais eficazes priorizam restrições negativas explícitas. Os 100 principais repositórios dedicam quase o dobro do espaço a regras sobre o que não fazer, em comparação com projetos menores, com 784 instâncias de frases implícitas de "não fazer" encontradas.
Surpreendentes 90% destes arquivos de alto desempenho utilizam termos definitivos como 'deve', 'sempre' ou 'nunca' para orientar os agentes de IA. Isso não é acidental; é uma estratégia deliberada para evitar ações não intencionais e manter a integridade do código, uma marca registrada de sistemas robustos.
Exemplos específicos sublinham esta precisão. O repositório Next.js da Vercel, por exemplo, proíbe explicitamente rodapés 'gerados com Claude code' nos commits. Este nível de detalhe garante que as contribuições da IA se alinhem perfeitamente aos padrões do projeto e às expectativas humanas.
O repositório do Bun oferece outra ilustração poderosa com o seu aviso em letras maiúsculas: 'NUNCA execute bun test diretamente - ele não incluirá as suas alterações.' Tais proibições diretas eliminam a ambiguidade, impedindo que os agentes executem comandos prejudiciais que poderiam comprometer o ambiente de compilação ou teste.
Limites explícitos são essenciais porque os agentes de IA operam sem contexto humano ou intuição. Eles carecem da compreensão implícita do histórico do projeto, das normas da equipe ou de potenciais efeitos colaterais. Portanto, você deve dizer-lhes precisamente quais arquivos, funções ou padrões evitar meticulosamente, agindo como um guarda-corpo digital. Esta abordagem proativa evita erros sutis e protege a base de código.
De 33 a 14.000 palavras: Encontrando o tamanho certo para o seu arquivo
A enorme variabilidade no comprimento do arquivo AGENTS.md revela uma prática recomendada nascente. Considere os extremos: o arquivo completo do VS Code abrange apenas 33 palavras, atuando como um simples redirecionamento. O do Neovim, pouco maior com 35 palavras, foca-se numa única regra de divulgação para commits gerados por IA. Enquanto isso, o repositório OpenHands apresenta um formidável conjunto de instruções de 14.000 palavras. Este amplo espectro destaca o desafio de definir um modelo ideal.
A pesquisa da Coldtea, no entanto, oferece uma estrela-guia prática: um comprimento mediano de aproximadamente 1.200 palavras. Este número sugere um ponto ideal pragmático para a maioria dos projetos, equilibrando detalhes suficientes para colaboradores de IA com a clareza necessária para a supervisão humana e iteração rápida. É um parâmetro realista para estabelecer limites eficazes para agentes sem verbosidade excessiva.
Em última análise, a complexidade do seu arquivo AGENTS.md deve estar diretamente alinhada com a escala do seu projeto e com os riscos específicos que você pretende mitigar com a assistência de IA. Um utilitário menor e focado pode precisar de diretrizes mínimas, mas um sistema complexo com vários colaboradores exige um manual de regras robusto. Para obter insights mais profundos sobre como os arquivos de contexto realmente ajudam os agentes de codificação, explore trabalhos como Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?.
Gostando do artigo? Receba um assim na sua caixa de entrada toda manhã.
um e-mail por dia · cancele em dois cliques · sem rastreadores de terceiros
Sua lista de verificação de 3 pontos para um repositório à prova de agentes
Após analisar os 1.000 principais repositórios do GitHub, os engenheiros da Coldtea destilaram a essência de arquivos AGENTS.md eficazes em uma lista de verificação crucial de três pontos. Não se trata de sugestões; trata-se de fornecer comandos precisos para seus agentes de IA, transformando seu arquivo em um manual de regras robusto.
Para um repositório à prova de agentes, certifique-se de que seu AGENTS.md inclua:
- Pelo menos uma regra explícita de 'não fazer'. Esta diretriz crítica, presente em 86% dos arquivos eficazes, estabelece limites claros para o comportamento do agente. Sem essas restrições negativas, os agentes frequentemente recorrem a suposições, potencialmente introduzindo alterações indesejadas ou rodapés "gerados", como visto no Next.js da Vercel. Isso inclui definir claramente o que o agente nunca tem permissão para tocar.
- Detalhar meticulosamente como commits e pull requests devem ser formatados. Encontrado em 79% dos arquivos bem-sucedidos, isso garante que o histórico e os padrões do projeto permaneçam consistentes, independentemente de um humano ou um agente de IA enviar o código. A formatação prescritiva evita o caos no sistema de controle de versão.
- Exatamente como executar testes e lint no código. Cerca de três quartos (75%) dos arquivos eficazes fornecem essas instruções precisas. Estes não são passos opcionais; são comandos diretos para o agente executar, garantindo que cada contribuição adira aos portões de qualidade antes da integração.
Perguntas Frequentes
Qual é o principal erro que os projetos cometem com arquivos AGENTS.md?
O erro mais comum é tratar o AGENTS.md como um manual operacional (listando comandos) em vez de um manual de regras estrito que diz a um agente de IA o que ele deve e, mais importante, o que ele não deve fazer.
Quais são os elementos-chave de um bom arquivo AGENTS.md?
Um arquivo eficaz inclui restrições negativas explícitas (regras de 'não fazer'), instruções claras para formatar commits e PRs, e diretrizes precisas sobre como executar testes e lint no código.
Projetos grandes precisam de arquivos AGENTS.md diferentes dos pequenos?
Sim. Pesquisas mostram que projetos maiores e mais complexos possuem arquivos AGENTS.md muito mais rigorosos, dedicando quase o dobro do espaço a restrições negativas (regras de 'não fazer') para proteger a base de código.
Quão comuns são os arquivos AGENTS.md nos principais repositórios do GitHub?
Eles ainda são relativamente raros. Um estudo dos 1.000 principais repositórios do GitHub descobriu que apenas 27% possuíam um arquivo AGENTS.md, indicando uma grande oportunidade de melhoria na orientação de agentes de IA.