O que é AGENTS.md?
AGENTS.md é um arquivo Markdown aberto e simples, dentro do repositório, que explica aos agentes de programação com IA como trabalhar no projeto: como compilar e testar, quais convenções seguir e o que evitar. Pense nele como um README para agentes, lido por muitas ferramentas diferentes.
Quais agentes leem
O formato é descrito em agents.md, que lista mais de 20 ferramentas compatíveis. O suporte varia nos detalhes, então confira também a documentação do seu agente.
- Codex, Cursor, o agente de programação do GitHub Copilot, opencode, Amp, Aider, goose, Zed, Warp, Junie e Jules, entre outros, leem o arquivo.
- O Gemini CLI lê GEMINI.md por padrão; adicione AGENTS.md à configuração context.fileName no settings.json e ele lê esse também.
- O Claude Code lê CLAUDE.md e, desde a versão 2.1.277, lê AGENTS.md quando o repositório não tem CLAUDE.md. Você também pode importá-lo no CLAUDE.md com @AGENTS.md.
AGENTS.md, CLAUDE.md e GEMINI.md
CLAUDE.md e GEMINI.md são os arquivos próprios do Claude Code e do Gemini CLI; AGENTS.md é o compartilhado. Os três guardam o mesmo tipo de conteúdo. Uma configuração comum mantém as regras compartilhadas no AGENTS.md e faz os arquivos de cada ferramenta apontarem para ele, acrescentando só o que é específico, para que as instruções não se desencontrem. Se os dois existem, o Claude Code lê por padrão só o CLAUDE.md, então importe o AGENTS.md a partir dele ou mude a configuração Project instructions.
O que colocar nele
Escreva o que um colega novo precisaria saber no primeiro dia e o que, de outro modo, você repetiria em todo prompt. Mantenha curto: os agentes carregam o arquivo no contexto no início de cada sessão.
- Comandos de instalação, build e testes, exatamente como são executados.
- Estilo de código e convenções que o linter não verifica.
- Estrutura do projeto: onde fica cada coisa e quais pastas são geradas.
- Regras para commits e pull requests.
- O que nunca fazer, como editar arquivos gerados ou commitar segredos.
Um exemplo curto
Um AGENTS.md mínimo para um projeto TypeScript poderia ser assim. Num monorepo, cada pacote pode ter o próprio AGENTS.md, e os agentes usam o mais próximo do arquivo que estão editando.
- ## Comandos: pnpm install; rode pnpm test antes de cada commit e pnpm lint depois de mover arquivos.
- ## Estilo: TypeScript em modo strict, aspas simples, sem ponto e vírgula.
- ## Estrutura: código do app em src/; o cliente da API em src/gen/ é gerado, nunca edite à mão.
- ## Pull requests: título como “[pacote] Resumo curto”; lint e testes precisam passar.
Onde o AgentVera se encaixa
O AgentVera inicia a própria CLI de cada agente na pasta do projeto, então o AGENTS.md e os arquivos de cada ferramenta valem como sempre; o campo de papel e instruções de um agente acrescenta instruções permanentes por cima, e CLIs sem uma opção para instruções extras (como Cursor, Gemini CLI e Amp) se apoiam no AGENTS.md ou nos arquivos de regras do projeto.
Perguntas frequentes
AGENTS.md é um padrão formal?
É um formato aberto sem campos obrigatórios nem esquema: Markdown simples com os títulos que ajudarem. O site dele é agents.md.
Preciso de CLAUDE.md e AGENTS.md ao mesmo tempo?
Não necessariamente. Versões recentes do Claude Code leem AGENTS.md quando não há CLAUDE.md. Se quiser regras só para o Claude, mantenha um CLAUDE.md curto que importe o AGENTS.md com @AGENTS.md.
Onde fica o arquivo?
Na raiz do repositório. Repositórios grandes podem ter outros em subpastas; vale o mais próximo do código editado, e uma instrução direta no chat passa na frente de todos.
Qual deve ser o tamanho?
O mais curto possível sem deixar de ser útil. Ele ocupa contexto em toda sessão, e uma regra enterrada num arquivo longo escapa mais fácil a um agente.