# O que é AGENTS.md?

URL: https://agentvera.dev/pt/glossary/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.

- **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.

---

**Sobre o AgentVera.** AgentVera é um app desktop para macOS, Windows e Linux, desenvolvido pela Solviera Teknoloji. Ele roda 18 agentes de programação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) lado a lado, por projeto, em terminais reais com as instalações e logins de CLI do próprio usuário. O plano gratuito tem agentes ilimitados. Baixar: https://agentvera.dev/pt/download/ · Preços: https://agentvera.dev/pt/pricing/