Como escrever um agents.md excelente: um resumo da experiência de mais de 2500 bases de código. A ideia central é que diretrizes vagas como "você é um assistente de programação prestativo" são ineficazes. O que realmente funciona é uma definição de função específica, como declarar explicitamente "você é um engenheiro de testes que escreve testes especificamente para componentes React, segue exemplos específicos e nunca modifica o código-fonte". O arquivo agents.md serve como um manual de trabalho completo para a definição de agentes inteligentes: posicionamento de funções, conhecimento da pilha de tecnologia, estrutura de arquivos do projeto, fluxo de trabalho, comandos executáveis, exemplos de estilo de código e, mais importante, limites operacionais claros. A análise revelou cinco elementos-chave que os arquivos agents.md bem-sucedidos geralmente seguem: 1. Prefixar comandos coloca o comando executável no início do arquivo, incluindo todos os parâmetros e opções do comando, como npm test, pytest -v, em vez de apenas o nome da ferramenta. 2. Use exemplos de código em vez de texto. Um trecho de código real é mais eficaz do que três parágrafos descritivos. Demonstre diretamente o estilo de saída esperado. 3. Defina limites claros e diga explicitamente à IA qual conteúdo ela não pode acessar de forma alguma, como informações confidenciais, diretórios de fornecedores, configurações de produção, etc. "Nunca enviar chaves" é a restrição mais comum e eficaz. 4. A pilha de tecnologias específica deve ser escrita como "React 18 + TypeScript, usando Vite e Tailwind CSS", em vez do genérico "Projeto React", e deve incluir o número da versão e as principais dependências. 5. Abrangência de seis áreas principais: comandos, testes, estrutura do projeto, estilo de código, fluxo de trabalho Git e limites operacionais — abordar essas áreas elevará seus arquivos de configuração a um nível superior. O exemplo prático fornece uma configuração completa de um agente de inteligência de documentos, demonstrando como aplicar os princípios acima a um cenário real. Esta configuração inclui: • Defina sua função: Especialista em documentação técnica, com proficiência em Markdown e TypeScript. • Conhecimento do projeto: Versões específicas da pilha de tecnologias e estrutura de diretórios de arquivos. • Comandos disponíveis: `npm run docs:build` e `npx markdownlint docs/` • Sistema de limites de três níveis: O que fazer sempre, o que perguntar primeiro e o que proibir absolutamente. Vários agentes inteligentes dedicados que valem a pena construir. @docs-agent: Lê o código e gera a documentação, escrevendo apenas no diretório docs/. @test-agent: Ao escrever testes, os casos de teste com falha não devem ser excluídos. @lint-agent: Corrige a formatação do código sem alterar a lógica. @api-agent: Requer consulta antes de criar endpoints de API e modificar o esquema do banco de dados. @dev-deploy-agent: Gerencia compilações e implantações locais, somente em ambiente de desenvolvimento. A recomendação de implementação é começar com tarefas simples e evitar tentar criar uma "função auxiliar genérica". Escolha tarefas específicas, como escrever a documentação da função, adicionar testes unitários ou corrigir erros de código. A configuração mais simplificada requer apenas três elementos: nome do agente, breve descrição e definição específica da função. Você também pode deixar que o Copilot ajude a gerar a configuração inicial e, em seguida, ajustá-la de acordo com o projeto em questão. A principal conclusão é que os melhores arquivos de configuração de agentes são aprimorados iterativamente, em vez de planejados de uma só vez. Comece com configurações simples, teste-as e adicione mais detalhes à medida que o agente encontrar erros. A chave para o sucesso reside em fornecer definições de função específicas e manuais de operação detalhados, em vez de instruções vagas. Endereço do blog:
