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:

Markdown · AGENTS.md
# 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.