AGENTS.md é um arquivo em Markdown, colocado no repositório, que explica a agentes de código como trabalhar naquele projeto. Ele reúne o que uma pessoa nova no time precisaria saber: como instalar, rodar testes, qual estilo de código seguir.
Pense nele como um README, mas escrito para a IA ler antes de mexer no código.
Como funciona
Quando um agente compatível abre o projeto, ele procura o arquivo e carrega o conteúdo como contexto. Assim você não precisa repetir as mesmas instruções a cada conversa.
O formato é livre, é só Markdown. Um bom arquivo costuma ter:
- comandos para instalar dependências, rodar e testar;
- estrutura de pastas e o papel de cada uma;
- convenções de código e de commits;
- regras do tipo "nunca altere o arquivo X";
- avisos sobre armadilhas conhecidas do projeto.
Quanto mais curto e específico, melhor. Instruções enormes ocupam contexto e podem ser ignoradas.
Exemplo prático
Você tem um projeto Node.js e quer que o agente sempre rode os testes antes de concluir. Crie na raiz:
# Instruções do projeto
## Comandos
- Instalar: npm install
- Testar: npm test
- Lint: npm run lint
## Regras
- Rode npm test antes de finalizar qualquer tarefa.
- Use TypeScript estrito.
- Não edite arquivos em /dist.Pronto. Na próxima tarefa, o agente já sabe como validar o próprio trabalho.
Para que serve
- Consistência: todo agente segue as mesmas regras.
- Menos retrabalho: você não explica o projeto toda vez.
- Onboarding: serve também de documentação rápida para pessoas.
- Segurança: limita o que o agente deve evitar.
Em times que usam vários agentes ao mesmo tempo, como num squad orquestrado no bridgecode, um arquivo comum de instruções ajuda todos a trabalharem do mesmo jeito.
Diferença entre AGENTS.md e CLAUDE.md
O CLAUDE.md é o arquivo equivalente usado pelo Claude Code. A ideia é a mesma: instruções persistentes para o agente. O AGENTS.md busca ser um nome mais neutro, lido por diferentes ferramentas. Verifique na documentação da sua ferramenta qual nome ela lê.
Um bom hábito é revisar o arquivo de tempos em tempos. Se o agente erra sempre a mesma coisa, adicione uma linha explicando o certo. Se uma regra ficou velha, remova.