Meu agent.md para melhorar a qualidade de código assistida por LLM
Desenvolvedores estão debatendo o quão úteis são arquivos dedicados “AGENTS.md” para orientar modelos de linguagem grandes na geração de código, em comparação com linters, documentos CONTRIBUTING/CODING_STANDARDS existentes e diretrizes mais simples e de alto nível. Muitos reclamam que os modelos produzem comentários de baixo valor e correções de estilo verbosas em excesso, argumentando que verificações mecânicas e regras concisas, formuladas de forma positiva, funcionam melhor do que arquivos longos e detalhados de instruções para agentes, que podem diluir o contexto ou ficar obsoletos à medida que os modelos melhoram. Outros ainda veem valor em prompts mínimos para agentes que codificam normas de fluxo de trabalho (como TDD ou limitar edições não relacionadas) e restrições de voz/estilo, mas consideram configurações por projeto e em evolução mais eficazes do que conjuntos de regras universais.
Função e Design de AGENTS.md
- Muitos veem AGENTS.md como útil, mas altamente pessoal: pessoas, projetos e modelos diferentes têm modos de falha diferentes, então um template compartilhado é apenas um ponto de partida.
- Alguns argumentam que grande parte do conteúdo do artigo é CS genérico ou já é “conhecido” por modelos modernos, então regras extras podem acrescentar pouco ou até prejudicar.
- Outros acham que AGENTS.md é um “remendo feio” que fica desatualizado com novos modelos, muitas vezes é ignorado e pode envenenar o raciocínio quando as regras são mal interpretadas.
- Alternativa: manter regras do projeto em CONTRIBUTING/CODING_STANDARDS e deixar o harness ou skills descobrirem-nas conforme necessário.
Linters vs Instruções para Agentes
- Tema forte: impor regras mecânicas/de estilo com linters, hooks de pre-commit e CI, não com agentes não determinísticos.
- Exemplos: chaves em
ifde uma linha, sem ternários aninhados, sem comentários, formatação, números mágicos. - Alguns usam um LLM como CI/revisor para detectar padrões/comentários proibidos, fazendo “robôs lutarem com robôs”.
Comentários e Documentação
- Frustração generalizada com excesso de comentários: agentes geram comentários verbosos de “o que isso faz”, muitas vezes maiores que o código.
- Muitos tentam proibir comentários por completo ou permitir apenas comentários de “por que/contexto”; o “o que” deveria ser autoevidente pelo código.
- Preocupações: comentários ficam desatualizados, enganam humanos e agentes futuros, e poluem o contexto.
- Uma minoria defende comentários como resumos para funções grandes/feias ou lugares com complexidade oculta; alguns ocultam comentários via folding do editor.
Seguimento de Instruções e Estratégia de Prompt
- Usuários relatam sucesso misto com regras como “nunca adicione comentários”; modelos maiores e mais novos obedecem melhor, outros ignoram.
- Discussão sobre formulação “faça” vs “não faça”: instruções positivas podem persistir melhor do que proibições, mas algumas restrições (por exemplo, “sem comentários jamais”) são difíceis de expressar sem “não”.
- AGENTS.md longo e denso pode sofrer com diluição de contexto “lost in the middle”; vários preferem regras centrais curtas, ou arquivos de regras modulares que o agente seleciona por tarefa.
Preferências de Estilo, Arquitetura e Fluxo de Trabalho
- Fortes divergências sobre mandatos de estilo: nomes de função curtos vs longos, sempre usar chaves vs minimalismo, enums vs booleanos, funções pequenas extraídas vs funções maiores.
- Alguns enfatizam contexto arquitetural e de “por quê” em AGENTS.md em vez de regras no nível de linha.
- Fluxos de trabalho mencionados: geração em múltiplas passagens com auto-revisão, regras no estilo convergência (sucesso/progresso/parar honestamente), prompts centrados em TDD e limites rígidos para agentes tocarem código não relacionado.