AGENTS.md: o arquivo que orienta agentes de código

Toda sessão nova com um agente de código começa do mesmo jeito. Alguém explica de novo que os testes rodam com pnpm test, que a pasta legacy/ fica intocada e que o commit segue o padrão do time.

Na terceira vez, a explicação vira um texto colado no começo do prompt. Na décima, cada pessoa do time tem a sua versão desse texto, e nenhuma bate com a outra.

O AGENTS.md acaba com essa repetição. Ele é um arquivo Markdown na raiz do repositório com as instruções que um agente precisa para trabalhar ali: como instalar, como testar, que convenções seguir e o que deixar quieto.

O agente segue o que está escrito no repositório. O arquivo de instruções é onde o time decide essas regras uma vez, em vez de repetir tudo no prompt de cada sessão.

O que é o AGENTS.md e quem mantém o formato

O site oficial do formato define o arquivo como um README para agentes. A ideia é dar ao agente um lugar previsível para achar o contexto do projeto, sem encher o README humano de detalhe operacional.

O formato nasceu de uma colaboração entre equipes de OpenAI Codex, Amp, Jules (Google), Cursor e Factory. Hoje quem cuida dele é a Agentic AI Foundation, sob a Linux Foundation. O mesmo site informa que mais de 60 mil projetos open source já usam o arquivo.

Não existe esquema. O site diz que o arquivo é Markdown padrão, aceita qualquer heading e o agente interpreta o texto que encontrar. Isso baixa a barreira: quem sabe escrever um README sabe escrever esse arquivo.

A lista de ferramentas compatíveis publicada no site inclui Codex, Jules, Cursor, Gemini CLI, GitHub Copilot coding agent, Aider, Zed, Warp, VS Code, Devin, Junie e Windsurf, entre outras. Algumas pedem um ajuste: no Aider, por exemplo, você aponta o arquivo no .aider.conf.yml.

Quem já tem instruções num arquivo com outro nome não precisa reescrever nada. O site sugere renomear o arquivo e criar um link simbólico com o nome antigo, para as ferramentas que ainda procuram por ele.

README, CLAUDE.md e o arquivo dos agentes

Os três arquivos podem morar no mesmo repositório, cada um com um leitor diferente.

O CLAUDE.md é o arquivo específico do Claude Code. A documentação de memória do Claude Code diz que ele lê o arquivo dos agentes como instrução de projeto a partir da versão 2.1.277. Por padrão, ele só usa esse arquivo quando não acha CLAUDE.md nem CLAUDE.local.md no diretório de trabalho ou acima dele.

Se o repositório tem os dois, o Claude lê só o CLAUDE.md. A saída que a própria documentação indica é um CLAUDE.md curto que importa o arquivo comum na primeira linha:

@AGENTS.md

## Claude Code

Use o modo de plano para mudanças em `src/billing/`.

Assim o time mantém um texto só para todas as ferramentas e deixa no CLAUDE.md apenas o que vale para o Claude. Outra opção é mudar a configuração Project instructions, no /config, para ler os dois arquivos.

O que escrever no arquivo

O site do formato sugere visão geral do projeto, comandos de build e teste, estilo de código, instruções de teste, cuidados de segurança e regras de commit e pull request. A documentação do Claude Code dá o critério para cada linha: a regra precisa ser concreta a ponto de alguém conseguir verificar.

"Rode npm test antes do commit" funciona. "Teste suas mudanças" não diz nada que o agente consiga conferir. O mesmo vale para estilo: indentação de dois espaços é verificável, "formate bem o código" não é.

A mesma documentação diz quando acrescentar uma linha: quando o agente comete o mesmo erro pela segunda vez, quando a revisão pega algo que ele deveria saber ou quando você digita no chat a correção da sessão anterior.

Um exemplo curto, para um projeto Node com pnpm:

# Instruções para agentes

## Ambiente
- Instale as dependências com `pnpm install`.
- Suba o projeto local com `pnpm dev`.

## Testes
- Rode `pnpm lint` e `pnpm test` antes de cada commit.
- Todo código alterado em `src/` ganha teste novo.

## Estrutura
- API em `src/api/`, interface em `src/web/`.
- A pasta `legacy/` está congelada. Não altere sem pedido explícito.

## Segurança
- Nunca grave chave ou token em arquivo. Use as variáveis do `.env.example`.
- Não rode migração contra o banco de produção.

## Pull request
- Título no formato `[pacote] descrição curta`.
- Descreva o que mudou e como você testou.

O site do formato descreve um efeito direto dos comandos de teste. Quando eles estão no arquivo, o agente tenta rodar as verificações e corrigir as falhas antes de dar a tarefa por encerrada.

O que deixar fora do AGENTS.md

Segredo não entra. O arquivo fica versionado, vai para cada clone e passa por todas as ferramentas que o time usa. Escreva o nome da variável e onde ela é configurada, nunca o valor.

Instrução vaga também sai: "Escreva código limpo" ocupa espaço e não muda o comportamento do agente.

Tamanho pesa. A documentação do Claude Code recomenda menos de 200 linhas por CLAUDE.md, porque arquivo longo consome contexto e reduz a aderência. O guia do Codex informa que ele para de juntar instruções quando a soma passa do limite configurado, de 32 KiB por padrão.

E o arquivo só orienta. A documentação do Claude Code trata esses arquivos como contexto, sem força de configuração, e manda usar um hook quando a ação precisa ser bloqueada. Regra de segurança que não pode falhar fica em permissão e em revisão de código com agente, com um humano no fim.

Monorepo: um arquivo por pacote

Em monorepo, o site do formato recomenda um AGENTS.md dentro de cada subprojeto. O agente lê o mais próximo na árvore de diretórios, e esse vence quando há conflito. Uma instrução explícita no chat fica acima de todos.

O próprio site cita o repositório principal da OpenAI, que tinha 88 desses arquivos quando a página foi escrita.

Cada ferramenta implementa a busca do seu jeito. O Codex começa na raiz do projeto, desce até o diretório atual e junta no máximo um arquivo por pasta, da raiz para baixo. O arquivo mais próximo aparece por último e por isso prevalece. Se a pasta tiver um AGENTS.override.md, o Codex lê esse no lugar do arquivo normal. O Claude Code carrega o arquivo de um subdiretório quando abre um arquivo daquela pasta, desde que ela não tenha CLAUDE.md próprio.

Essa divisão ajuda quando o agente trabalha em paralelo. Com subagentes, cada um recebe as regras do pacote onde está mexendo, sem carregar as dos outros.

Outros arquivos que ajudam o agente

O arquivo principal fica melhor curto, com ponteiros para o resto. Alguns documentos complementam bem:

• ARCHITECTURE.md: como os módulos se conversam e por que o projeto foi dividido daquele jeito
• SECURITY.md: como reportar falha e quais dados o código trata
• PRD: o que a funcionalidade precisa entregar, para o agente comparar a tarefa com o objetivo

No Claude Code, um @caminho dentro do arquivo importa o documento junto. Em outras ferramentas, basta citar o caminho e o agente abre quando precisar.

Procedimento de vários passos, como publicar uma versão, rende mais como Agent Skill, que só entra no contexto quando a tarefa pede. Preferência pessoal de cada desenvolvedor vai para a memória da ferramenta ou para um arquivo local fora do controle de versão.

Como escrever o primeiro AGENTS.md

1. Junte os comandos que você digita. Instalação, servidor local, lint, teste e build, exatamente como rodam hoje.
2. Dê uma tarefa pequena ao agente sem o arquivo. Anote cada ponto em que ele errou ou perguntou algo óbvio para o time.
3. Transforme cada erro numa regra verificável. Uma linha por regra, com caminho de pasta ou comando sempre que der.
4. Escreva o que não pode ser tocado. Pasta congelada, banco de produção, arquivo gerado por script.
5. Resolva a convivência com o CLAUDE.md. Se ele já existe, coloque @AGENTS.md na primeira linha dele. O comando /init do Claude Code gera um ponto de partida para quem não tem nenhum.
6. Revise o arquivo no pull request, como código. Quando o agente repetir um erro, a correção entra no arquivo e passa a valer para todo o time.

Num repositório sem CLAUDE.md, a sessão interativa do Claude Code mostra se o arquivo carregou. Segundo a documentação, aparece na conversa uma linha com o caminho do arquivo carregado, no formato no CLAUDE.md found; AGENTS.md loaded.