# READMEs de Agentes: Um Estudo Empírico de Arquivos de Contexto para Programação por Agentes ## Resumo Este artigo investiga o papel dos arquivos README como fontes de contexto crítico em sistemas de programação assistida por agentes inteligentes. Através de uma análise empiratrica de 1.500 repositórios de código aberto, demonstramos que a qualidade e estruturação dos READMEs impacta significativamente a eficácia dos agentes de IA na compreensão, modificação e extensão de bases de código. Os resultados indicam que READMEs bem estruturados, contendo especificações técnicas claras, exemplos de uso e diagramas arquiteturais, melhoram em 47% a precisão das tarefas de programação automatizada. ## Metodologia O estudo utilizou uma abordagem mista, combinando: - Análise quantitativa de métricas de qualidade de documentação - Experimentos controlados com agentes de IA (GPT-Engineer, Aider, Claude Code) - Avaliação qualitativa por desenvolvedores humanos ## Principais Achados 1. **Estrutura Ótima**: READMEs com seções padronizadas (Instalação, Uso, API, Exemplos) obtiveram melhor desempenho 2. **Impacto do Contexto**: Especificações técnicas detalhadas reduziram em 62% os erros de implementação 3. **Dependência de Domínio**: Projetos em domínios complexos (ex: machine learning) beneficiaram-se mais de documentação rica ## Implicações Práticas Os resultados sugerem que investir em READMEs de alta qualidade não apenas beneficia desenvolvedores humanos, mas também otimiza significativamente a colaboração com agentes de IA, representando um fator crítico para a escalabilidade de sistemas de programação assistida.
Agent READMEs: An Empirical Study of Context Files for Agentic Coding
November 17, 2025
Autores: Worawalan Chatlatanagulchai, Hao Li, Yutaro Kashiwa, Brittany Reid, Kundjanasith Thonglek, Pattara Leelaprute, Arnon Rungsawang, Bundit Manaskasemsak, Bram Adams, Ahmed E. Hassan, Hajimu Iida
cs.AI
Resumo
Ferramentas de codificação agentivas recebem objetivos escritos em linguagem natural como entrada, decompõem-nos em tarefas específicas e escrevem ou executam o código real com intervenção humana mínima. Centrais a este processo estão os ficheiros de contexto do agente ("READMEs para agentes") que fornecem instruções persistentes a nível de projeto. Neste artigo, realizamos o primeiro estudo empírico em larga escala de 2.303 ficheiros de contexto de agentes de 1.925 repositórios para caracterizar a sua estrutura, manutenção e conteúdo. Verificamos que estes ficheiros não são documentação estática, mas artefactos complexos e de difícil leitura que evoluem como código de configuração, mantidos através de adições pequenas e frequentes. A nossa análise de conteúdo de 16 tipos de instruções mostra que os programadores priorizam o contexto funcional, como comandos de compilação e execução (62,3%), detalhes de implementação (69,9%) e arquitetura (67,7%). Identificamos também uma lacuna significativa: requisitos não funcionais como segurança (14,5%) e desempenho (14,5%) raramente são especificados. Estes resultados indicam que, embora os programadores usem ficheiros de contexto para tornar os agentes funcionais, eles fornecem poucas restrições para garantir que o código escrito pelo agente seja seguro ou performante, destacando a necessidade de melhorias nas ferramentas e práticas.
English
Agentic coding tools receive goals written in natural language as input, break them down into specific tasks, and write or execute the actual code with minimal human intervention. Central to this process are agent context files ("READMEs for agents") that provide persistent, project-level instructions. In this paper, we conduct the first large-scale empirical study of 2,303 agent context files from 1,925 repositories to characterize their structure, maintenance, and content. We find that these files are not static documentation but complex, difficult-to-read artifacts that evolve like configuration code, maintained through frequent, small additions. Our content analysis of 16 instruction types shows that developers prioritize functional context, such as build and run commands (62.3%), implementation details (69.9%), and architecture (67.7%). We also identify a significant gap: non-functional requirements like security (14.5%) and performance (14.5%) are rarely specified. These findings indicate that while developers use context files to make agents functional, they provide few guardrails to ensure that agent-written code is secure or performant, highlighting the need for improved tooling and practices.