O que é AGENTS.md e como fazer a IA seguir as regras do seu projeto (com template)
A IA instalou biblioteca que você não pediu? Usou any em tudo? Esqueceu os testes? Ela só não conhecia as regras do projeto.
O AGENTS.md resolve isso. Você escreve as regras uma vez e os agentes leem sozinhos.
- Formato aberto: Markdown puro, sem campo obrigatório. Mantido pela Agentic AI Foundation (Linux Foundation).
- Menos retrabalho: você para de repetir as mesmas instruções em todo prompt.
- Verificação: se você lista os comandos de teste, o agente roda e tenta corrigir as falhas.
README é pra pessoas. AGENTS.md é pro agente.
Quais ferramentas leem o AGENTS.md?
- OpenAI Codex: lê antes de começar qualquer tarefa.
- Cursor: lê na raiz e em subpastas.
- Claude Code: lê a partir da versão 2.1.277, se não houver um CLAUDE.md no projeto.
- Outras: GitHub Copilot, Gemini CLI, Jules, Windsurf, Aider e mais, segundo o site oficial.
Usa Next.js? O create-next-app já cria o arquivo de agente em projetos novos. Adicione suas regras sem apagar o bloco gerado pelo Next.
Qual a diferença entre AGENTS.md, CLAUDE.md e .cursor/rules?
| AGENTS.md | CLAUDE.md | .cursor/rules | |
|---|---|---|---|
| Quem lê | Várias ferramentas | Claude Code | Cursor |
| Formato | Markdown puro | Markdown com imports @arquivo | .mdc com frontmatter |
| Melhor pra | Regras gerais, qualquer agente | Recursos do Claude Code | Regras por tipo de arquivo |
Atenção: se o projeto tem os dois arquivos, o Claude Code lê só o CLAUDE.md. A solução é deixar as regras no AGENTS.md e colocar no CLAUDE.md apenas:
@AGENTS.md
Como criar o seu AGENTS.md?
- Crie
AGENTS.mdna raiz, ao lado dopackage.json. - Escreva comandos, stack, padrões e o que é proibido. Seja específico.
- Teste: pergunte ao agente “quais são as regras deste projeto?”.
- Faça commit. O arquivo é parte do projeto.
Template para Next.js com TypeScript. Copie e ajuste:
# AGENTS.md
## Projeto
App de estudo em Next.js (App Router) + TypeScript + Tailwind.
Prefira código simples e legível.
## Comandos
- Instalar: `npm install`
- Dev: `npm run dev`
- Lint: `npm run lint`
- Tipos: `npx tsc --noEmit`
- Testes: `npm test`
## Stack e pastas
- Node 22+, TypeScript `strict`, Tailwind
- `src/app/` rotas e páginas · `src/components/` componentes · `src/lib/` utilitários
## Padrões
- Server Components por padrão; `"use client"` só com estado ou eventos.
- Tipar props e retornos. Nada de `any` (use `unknown`).
- Estilo só com Tailwind. Textos da interface em pt-BR.
- Segredos só em `.env.local`, lidos no servidor.
## Não faça
- Instalar dependência sem perguntar.
- Editar `.env*` ou colocar chave de API no código.
- Apagar arquivos, `git push` ou `git reset --hard`.
## Antes de terminar
1. Rode lint, tipos e testes e corrija os erros.
2. Liste os arquivos alterados e o motivo.Erros comuns: arquivo gigante, regra vaga (“escreva código limpo”), chave de API no arquivo (ele vai pro Git) e regras diferentes no AGENTS.md e no CLAUDE.md.
Perguntas frequentes
AGENTS.md é obrigatório? Não. Mas sem ele o agente não conhece as regras do seu projeto.
Posso escrever em português? Sim. É Markdown livre, sem regra de idioma.
Se o meu pedido no chat contradiz o arquivo? O pedido no chat vale mais, segundo o site oficial.
Quer trabalhar com agentes de IA de verdade?
O AGENTS.md é o primeiro passo. Depois vem planejar tarefas, revisar o que o agente entrega e configurar permissões com segurança.
É isso que eu ensino na Formação Claude Code.