Um arquivo AGENTS.md informa a um agente de programação como trabalhar em um repositório. Ele é carregado no contexto em todas as sessões. Portanto, cada linha adicionada tem um custo em todas as tarefas e disputa a atenção do agente com a solicitação real.

Esse único fato explica quase tudo o que vem a seguir.

Escreva apenas o que não pode ser descoberto

Se o agente consegue aprender algo examinando o repositório, não escreva. A estrutura de diretórios, o framework usado e a convenção de nomes dos arquivos de teste estão visíveis no repositório e não precisam ser repetidos.

O que não pode ser descoberto são a intenção e as restrições:

  • O comando que executa os testes, quando ele não for óbvio
  • Convenções que o código ainda não segue de forma consistente
  • Coisas que parecem bugs, mas são intencionais
  • Diretórios que não devem ser editados e o motivo

Mantenha-o curto o bastante para ser lido por inteiro

Um arquivo com mais de aproximadamente cem linhas começa a se comportar como um documento que ninguém lê. Instruções escondidas na linha 180 não mudam o comportamento de forma confiável porque disputam a atenção com todo o restante do contexto.

Se o seu arquivo já cresceu demais, a pergunta útil não é “como faço o agente seguir isso?”, mas “quais destas linhas já mudaram algum resultado?”.

Seja específico sobre os comandos

Orientações vagas produzem comportamentos vagos. Compare:

Run the tests before committing.

com:

Run `pnpm test -- --run` before committing. It takes about 40 seconds.
Do not run `pnpm test` without `--run`; it starts watch mode and hangs.

A segunda versão evita uma falha específica e recorrente. A primeira apenas expressa uma intenção.

Explique o motivo, não apenas a regra

Uma regra acompanhada do motivo funciona mesmo diante de uma situação desconhecida; uma simples proibição não. “Não edite src/generated/” convida a uma exceção na primeira vez em que editar diretamente parecer conveniente. “Não edite src/generated/: pnpm codegen sobrescreve o diretório e sua alteração desaparecerá” não deixa essa dúvida.

Revise-o quando parar de funcionar

Trate o arquivo como algo que se deteriora com o tempo. Quando o agente faz repetidamente algo que você não queria, isso revela algo sobre o arquivo, não apenas sobre o modelo. Ou falta uma instrução, ou a instrução existente está sendo soterrada por trezentas linhas que já não importam.