CLAUDE.md é um arquivo de texto no seu repositório com as regras do projeto que um agente de código como o Claude Code lê no começo de cada sessão. O AGENTS.md cumpre o mesmo papel em muitas outras ferramentas. Ali vai o que o código não diz: convenções, comandos úteis e o que não mexer. Costuma ser carregado inteiro toda vez, então vale deixá-lo curto.
Uma pergunta do app. Escolha uma resposta.
Seu arquivo de instruções diz "rode os testes antes de terminar". O que você ganha?
É uma orientação: o agente pode pular. Por isso você ainda confere se há resultados.
São coisas diferentes. O arquivo diz como trabalhar; as permissões, quais ações são permitidas.
Se a ferramenta lê esse arquivo, ele orienta o trabalho. Ajuda muito, mas não substitui conferir o resultado.
O que um agente de código não consegue adivinhar lendo os arquivos. Uma convenção: "valores são guardados em centavos, como número inteiro; nunca com decimais". Um limite: "a pasta de emissão de nota fiscal é de outra equipe: não edite". Um comando que não é óbvio, como o que monta o app para testar.
O que sobra: o que o agente vê sozinho (quais bibliotecas o projeto usa já está nos arquivos), manuais longos e regras para uma tarefa feita uma vez por mês. E nunca chaves nem senhas: o arquivo costuma ficar no repo e qualquer pessoa com acesso pode ler.
O arquivo entra na janela de contexto antes de você escrever o primeiro pedido, e fica ali a sessão toda. Com números de exemplo: um CLAUDE.md de 400 linhas pode chegar a uns 5.000 tokens que vão junto em cada sessão, sendo usados ou não. Além disso, entre tantas regras, as importantes pesam menos.
Um teste útil para cada linha: se você apagar, o agente erraria? Se não, sobra. Instruções longas para uma tarefa pontual, como publicar uma versão nova, costumam ficar melhor numa skill, que só é carregada quando precisa.
O que o arquivo diz orienta o agente, mas não o prende. Numa sessão longa, com muito texto em cima, ele pode deixar passar uma regra que seguiu no começo. Escrever em maiúsculas ou repetir três vezes não a torna automática.
Se algo tem que acontecer sempre, que não dependa da memória dele: muitas ferramentas permitem configurar scripts que rodam sozinhos diante de um evento (em algumas se chamam hooks) e permissões que bloqueiam ações. E o que ele fez de verdade você vê no diff, não no arquivo de regras.
"Escrevo uma vez e pronto." Se você muda um comando e o arquivo não, o agente continua usando o antigo. "Todas as ferramentas leem o mesmo arquivo." Não: qual cada uma lê depende da ferramenta e da configuração. Se sua equipe usa várias, confira que não existam duas versões que se contradizem: em AGENTS.md você vê como compartilhar um só.