AGENTS.mdAGENTS.md: onde fica e como as ferramentas o leem
AGENTS.md é um arquivo Markdown simples com instruções para o projeto, lido pela maioria dos agentes de programação sem configuração adicional. A OpenAI o apresentou à Agentic AI Foundation, da Linux Foundation, e mais de 60k projetos de código aberto o utilizam.
Onde fica
- AGENTS.md na raiz do repositório, para todo o projeto.
- Arquivos AGENTS.md em subdiretórios ou pacotes; os agentes usam o mais próximo na árvore de diretórios.
- OpenAI Codex: um arquivo global ~/.codex/AGENTS.override.md ou, se estiver vazio ou não existir, ~/.codex/AGENTS.md.
- Cline: um arquivo global ~/.agents/AGENTS.md.
- Claude Code também aceita .claude/AGENTS.md.
Formato
Markdown simples, sem frontmatter nem campos obrigatórios; qualquer título de seção é válido. O formato não define um limite de tamanho, mas o OpenAI Codex para de ler ao atingir project_doc_max_bytes, que é 32 KiB por padrão.
# Acme web app
Customer-facing web app with an admin area and a REST API.
## Commands
- Install: `pnpm install`
- Test: `pnpm test`
- Lint and type-check: `pnpm lint && pnpm tsc --noEmit`
## Code style
- TypeScript strict mode; no `any` in new code.
- Keep database access in `src/db/`.
## Never
- Never commit secrets or .env files.
- Never edit files under `src/generated/` by hand.
Precedência e combinação
O AGENTS.md mais próximo do arquivo editado prevalece, e uma instrução explícita no chat substitui qualquer arquivo. O OpenAI Codex concatena um arquivo por diretório, da raiz do projeto até o diretório de trabalho; assim, os arquivos mais próximos ficam no final e têm prioridade. O Claude Code ignora AGENTS.md por padrão sempre que há um CLAUDE.md.
Ferramentas que o leem
| Ferramenta | Suporte |
|---|---|
| OpenAI Codex | Nativo. Lê um arquivo global e, em seguida, no máximo um arquivo por diretório, da raiz até o diretório de trabalho, com limite de 32 KiB por padrão. |
| Claude Code | Nativo a partir da v2.1.277, mas somente quando não existe CLAUDE.md nem CLAUDE.local.md, a menos que esteja definido como claude-md-and-agents-md. |
| Cursor | Nativo, na raiz e em subdiretórios; os arquivos aninhados são combinados com os dos diretórios superiores, e o mais específico prevalece. |
| GitHub Copilot (cloud agent, code review, VS Code) | Nativo em qualquer lugar do repositório; o arquivo mais próximo prevalece. |
| Devin Desktop (formerly Windsurf) | Nativo. O arquivo da raiz está sempre ativo; um arquivo em um subdiretório se aplica ao próprio diretório. |
| Cline | Nativo, além de ~/.agents/AGENTS.md global; ative ou desative no painel Rules. |
| Gemini CLI | Opcional: adicione AGENTS.md a context.fileName em .gemini/settings.json. |
| Aider | Opcional: adicione read: AGENTS.md a .aider.conf.yml. |
| OpenClaw | Nativo, como arquivo obrigatório com instruções de operação no workspace do agente. |
| Listed on agents.md (not individually re-verified) | Uma das 23 ferramentas listadas em agents.md, incluindo Amp, Jules, Zed, Warp, goose, opencode e JetBrains Junie; não verificamos cada uma individualmente. |
Dicas
- Renomeando um arquivo AGENT.md antigo? agents.md sugere mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md para manter os dois nomes funcionando.
- Liste os comandos de teste e lint: os agentes tentam executar as verificações encontradas e corrigir as falhas antes de terminar.
- Em um monorepo, crie um AGENTS.md curto por pacote em vez de aumentar um único arquivo longo na raiz.
- No OpenAI Codex, um AGENTS.override.md tem prioridade sobre o AGENTS.md no mesmo diretório.
Gere um AGENTS.md e arquivos de regras correspondentes para cinco ferramentas a partir de um único formulário. Abrir o gerador de AGENTS.md →