AGENTS.md: o padrão que uniu Cursor, Claude Code e Codex

Você abre o agente, explica que o projeto usa TypeScript com Prisma, que snake_case vale só nas colunas do banco, que commits seguem conventional commits. O agente escreve. Na próxima sessão, repete tudo do zero.

Esse loop tem nome: re-onboarding infinito. E tem solução desde dezembro de 2025.

O que é AGENTS.md?

AGENTS.md é um arquivo de texto simples que fica na raiz do repositório. Todo agente de programação compatível lê esse arquivo automaticamente antes de trabalhar, como um onboarding para o agente, não para o dev humano.

O formato foi criado pela OpenAI para o Codex CLI e, em dezembro de 2025, migrou para a Agentic AI Foundation, projeto da Linux Foundation, o mesmo guarda-chuva que abriga o MCP (Model Context Protocol). Não é iniciativa de uma empresa: é padrão aberto.

Hoje, 11 ferramentas leem AGENTS.md nativamente: Codex CLI, GitHub Copilot, Cursor, Windsurf, Claude Code, Amp, Devin, Aider, Zed, Jules e JetBrains Junie. Escreva uma vez. Todos os agentes que entram no repo entendem o projeto.

O que colocar em um AGENTS.md?

Quatro seções resolvem 90% dos problemas de contexto:

1. Visão do projeto

Stack, linguagem, framework, versão. O que o projeto faz em 2-3 frases. O que o agente nunca deve tocar.

2. Comandos de build e teste

Exatos, com flags. npm run test -- --watch=false é melhor que "rode os testes". O agente vai copiar o comando literal.

3. Convenções de código

Só o que diverge do padrão da linguagem. snake_case em variáveis de banco, PascalCase em componentes, commits em português. O que um dev novo erraria sem ler.

4. Contexto de domínio

Terminologia específica do negócio. "customer" no código é sempre o assinante pagante, nunca o usuário final. Isso evita confusão em sessões longas quando o agente começa a misturar os dois.

Template mínimo para qualquer projeto:

# AGENTS.md

## Stack
- TypeScript 5.x + Node.js 22
- Prisma ORM + PostgreSQL
- Vitest para testes unitários e de integração

## Comandos
- Build: `npm run build`
- Testes: `npm run test`
- Lint: `npm run lint`
- Migrate: `npx prisma migrate dev`

## Convenções
- snake_case em colunas de banco e variáveis Prisma
- camelCase em variáveis JavaScript/TypeScript
- Comentários em português
- Commits: conventional commits (feat/fix/chore/refactor)
- Proibido usar `any`; use `unknown` ou o tipo correto

## Proibido
- Nunca modifique arquivos em /generated/
- Nunca commite .env ou .env.local
- O módulo /legacy/ usa código síncrono; não converta para async

## Contexto de domínio
- "customer" = assinante pagante (tem subscription no Stripe)
- "user" = qualquer pessoa logada

Regra da spec oficial: arquivo com mais de 500 linhas começa a ser ignorado. Um AGENTS.md focado de 50 linhas supera um documento de 1.000. Se o arquivo crescer, divida em subdiretórios: /src/payments/AGENTS.md para contexto específico do módulo.

AGENTS.md vs CLAUDE.md vs .cursorrules: qual usar?

Cada ferramenta tem seu formato nativo. Claude Code lê CLAUDE.md. Cursor tem .cursorrules. Copilot tem suas próprias instruções. AGENTS.md é a camada universal que todos leem.

Arquivo	Lido por	Quando usar
`AGENTS.md`	11 ferramentas	Time com devs usando agentes diferentes
`CLAUDE.md`	Claude Code	Time usa Claude Code exclusivamente
`.cursorrules`	Cursor	Time usa Cursor exclusivamente

Se o time tem devs usando Cursor, Claude Code e Verboo Code ao mesmo tempo, AGENTS.md é o único arquivo que todos vão ler. Os específicos funcionam como camadas extras para quem usa aquela ferramenta.

Por que tokens ilimitados importam para o AGENTS.md?

AGENTS.md reduz repetição, mas não elimina o consumo de contexto. Em repos maiores, uma sessão típica carrega:

AGENTS.md completo: ~2.000 tokens
Arquivos abertos na sessão: 5 a 15 arquivos (~8.000 tokens)
Histórico da conversa: cresce a cada mensagem
Output de comandos: logs, resultado de testes, erros

Com um modelo de 100k de contexto e cap de mensagens a cada 5 horas, você passa parte da sessão gerenciando o que cabe na janela, o que derrota o propósito do AGENTS.md.

O Verboo Code roda o deepseek-v4-flash com 1 milhão de tokens de contexto. AGENTS.md completo, arquivos relevantes abertos, histórico longo: o agente lê tudo sem truncar e sem você precisar reiniciar a sessão no meio do refactor. Veja como devs com 57 bilhões de tokens consumidos usam isso na prática.

O que vem depois do AGENTS.md?

AGENTS.md define o contexto estático do projeto, o que não muda entre sessões. O MCP (Model Context Protocol), também na Linux Foundation, resolve o dinâmico: acesso a banco de dados, APIs externas, ferramentas em tempo real.

Os dois se complementam:

AGENTS.md diz: "esse projeto usa Stripe para pagamentos, modelo de dados em /prisma/schema.prisma"
MCP conecta o agente ao Stripe real para consultar dados e executar ações durante a sessão

O padrão foi para a Linux Foundation. Isso não é feature: é infraestrutura de longo prazo.

A convergência de Cursor, Claude Code, Codex e outros em torno de padrões abertos é boa notícia para qualquer dev. Você configura uma vez, todos os agentes entendem. O que ainda muda é quem cobra por token para ler esse contexto, e quem não cobra.

Como criar o seu AGENTS.md em 15 minutos

Crie AGENTS.md na raiz do repositório
Adicione as 4 seções do template adaptadas ao seu projeto
Mantenha abaixo de 200 linhas na primeira versão
Commite com docs: add AGENTS.md
Abra uma nova sessão com seu agente de programação. Ele lê o arquivo automaticamente.

Se o agente ainda pedir contexto que já está no arquivo, o problema está no arquivo: está longo demais ou as instruções são ambíguas demais. Simplifique.

Para referência completa da spec, veja agents.md.

Quer rodar isso sem cap de tokens? Conheça o Verboo Code — agente de programação com tokens ilimitados.