TLDR;

Porque arquivos de configuração como o agents.md estão excessivamente grandes e mal organizados, enviando informação irrelevante a cada requisição e “envenenando” a IA. O agents.md (ou cloud MD) é o arquivo mais crítico, pois ele é incluído em todas as chamadas; se contiver dados desnecessários, desperdiça tokens e compromete a qualidade do código gerado. Reduza o agents.md ao essencial, mova detalhes como estilos ou documentação para arquivos externos ou skills, e carregue apenas o que realmente precisa para cada tarefa.

Resumo

Neste vídeo Kyle, do WebDev Simplified, demonstra como configurar corretamente a IA para evitar erros recorrentes, focando principalmente no arquivo agents.md (ou cloud.md, claude.md, gemini.md), que é incluído em todas as solicitações ao modelo. Ele explica que o system prompt, geralmente fixo, não requer ajustes, enquanto o agents.md deve conter apenas informações essenciais, pois seu tamanho impacta diretamente no consumo de tokens e na qualidade das respostas. Kyle detalha ainda a função dos skills – conjuntos de arquivos markdown que a IA carrega quando precisa executar tarefas específicas, como gerar código TypeScript – e como a documentação externa pode ser referenciada ao invés de ser inserida integralmente no agents.md, reduzindo a sobrecarga. O apresentador mostra exemplos reais de agents.md inflados em projetos como Codeex, Airflow e VS Code, apontando que listas extensas de bullet points sobre revisão de código, mudanças de API e estilos de UI desperdiçam recursos e poluem o contexto. Ele recomenda manter o arquivo enxuto, vinculando guias detalhados a documentos externos e evitando duplicações. Assim, cada prompt enviado à IA traz apenas o que é necessário, garantindo respostas mais precisas, econômicas e alinhadas às necessidades do desenvolvedor. Essa prática otimiza performance, reduz custos e melhora a experiência do usuário.