Manter AGENTS.md com base em evidências do repositório

Visão Geral

Crie ou melhore instruções para agentes que ajudem um agente de codificação a alterar o repositório corretamente sem redescobrir seu fluxo de trabalho. Baseie cada comando, caminho e regra específicos do repositório em evidências no checkout atual.

Prefira um diff focado em vez de uma reescrita completa. Não há um limite universal de linhas, lista de seções obrigatórias, layout de links simbólicos ou política de atribuição de commit; siga as necessidades do próprio repositório e a intenção do mantenedor.

Quando Usar

• O usuário pede para criar, atualizar, encurtar ou auditar AGENTS.md.
• Um monorepo precisa de instruções raiz mais substituições mais específicas em nível de pacote.
• Instruções de agente existentes contêm comandos desatualizados, políticas duplicadas ou afirmações não suportadas.
• O usuário deseja reconciliar AGENTS.md com CLAUDE.md, .github/copilot-instructions.md ou outros arquivos de instrução do repositório.

Use @agents-generator em vez disso quando a tarefa solicitar especificamente seus modos de geração de pacotes, ativos ou fluxo de trabalho de backup. Use esta habilidade quando uma edição legível pelo mantenedor e com base em evidências for o objetivo principal.

Como Funciona

1. Preservar a intenção existente

Antes de escrever, leia todos os arquivos de instrução que se aplicam ao caminho de destino, incluindo arquivos AGENTS.md existentes e arquivos relevantes específicos de ferramentas, como CLAUDE.md, GEMINI.md, .github/copilot-instructions.md e .github/instructions/*.instructions.md.

• Melhore um AGENTS.md existente no local, quando possível.
• Preserve regras precisas escritas pelo mantenedor e políticas específicas do repositório.
• Não substitua o arquivo de instrução de outra ferramenta por um link simbólico, a menos que o usuário solicite e as evidências do repositório mostrem que conteúdo idêntico é desejado.
• Não escolha silenciosamente entre instruções conflitantes. Siga a regra aplicável de maior prioridade, ou pergunte quando a política pretendida não puder ser estabelecida a partir do repositório.

2. Construir um mapa de evidências delimitado

Inspecione apenas o suficiente do repositório para estabelecer como o trabalho é realmente feito:

1. Leia a visão geral do projeto e as orientações de contribuição, como README*, CONTRIBUTING* e documentação relevante.
2. Leia manifestos, arquivos de lock, arquivos de workspace, executores de tarefas e configuração de build para identificar ferramentas suportadas e comandos exatos.
3. Leia fluxos de trabalho de CI para aprender as verificações necessárias. Não presuma que todos os trabalhos de CI ou implantação são seguros ou apropriados para serem executados localmente.
4. Inspecione arquivos de origem e teste representativos para convenções de nomenclatura, layout e teste.
5. Identifique arquivos gerados, migrações, código "vendored", grandes fixtures, limites de segredos e operações apenas de produção.

Prefira rg --files e rg para descoberta quando disponíveis. Rastreie a origem de cada comando ou regra não óbvia para que afirmações não suportadas não entrem no arquivo final.

3. Escolher o escopo da instrução

Use o AGENTS.md raiz para orientação em todo o repositório. Adicione ou revise um AGENTS.md aninhado apenas quando um subdiretório tiver comandos, arquitetura, convenções ou limites de segurança materialmente diferentes.

Mantenha regras compartilhadas na raiz e apenas diferenças em arquivos aninhados. Para ferramentas que implementam a convenção pública AGENTS.md, aplique orientação raiz/ancestral e instruções de subdiretório mais estreitas de acordo com a precedência do host de destino. O arquivo mais próximo não apaga silenciosamente regras ancestrais não relacionadas. Não copie o arquivo raiz completo em cada pacote.

4. Escrever orientação de alto sinal

Escolha títulos que se encaixem no repositório em vez de forçar um modelo fixo. Inclua o seguinte apenas quando suportado por evidências:

• Mapa do repositório: os poucos diretórios e limites que um agente precisa conhecer.
• Configuração e comandos: comandos exatos de instalação, desenvolvimento, build, lint, verificação de tipos e teste, com o diretório de trabalho quando não for óbvio.
• Validação focada: verificações direcionadas para uma pequena alteração e verificações mais amplas necessárias antes da entrega.
• Regras de alteração: propriedade de arquivo gerado, migrações, esquemas, APIs, dependências e coordenação entre pacotes.
• Limites de segurança: segredos, dados de produção, comandos destrutivos, implantações e operações que exigem autorização explícita.
• Regras de contribuição: requisitos específicos do repositório de nomenclatura, formatação, commit ou pull-request que afetam a implementação ou a entrega.

Escreva declarações diretas e testáveis. Prefira:

- From the repository root, run `npm test -- path/to/file.test.ts` for a focused test.

em vez de:

- Make sure tests pass and follow best practices.