Como escrever um arquivo AGENTS.md para que qualquer agente de programação com IA entenda seu projeto

Se você já viu um agente de programação com IA executar o comando de teste errado, formatar o código num estilo que seu projeto proíbe ou reinventar um utilitário que já existe, a correção normalmente não é um modelo mais inteligente — é contexto. O AGENTS.md é a forma padrão de dar esse contexto aos agentes, e funciona em quase todas as ferramentas.

O que o AGENTS.md realmente é

O AGENTS.md é "um README para agentes": um arquivo Markdown simples que você coloca na raiz do seu repositório para dizer às ferramentas de programação com IA como seu projeto funciona (agents.md). Não é uma nova linguagem de configuração — não há campos obrigatórios nem sintaxe especial. Use os cabeçalhos Markdown que quiser.

O formato importa porque é genuinamente compatível entre ferramentas. Em meados de 2026, ele é lido nativamente por OpenAI Codex, GitHub Copilot, Cursor, Windsurf, Devin, Aider, Zed, VS Code, JetBrains Junie e dezenas de outros — mais de 28 ferramentas e mais de 60.000 repositórios de código aberto (agents.md; Codersera). Agora é administrado pela Agentic AI Foundation da Linux Foundation, ao lado do Model Context Protocol da Anthropic. O Claude Code também lê o AGENTS.md, embora seu formato nativo mais rico continue sendo o CLAUDE.md (DeployHQ).

Um arquivo, e a maioria das suas ferramentas se comporta de forma consistente.

Por que um arquivo é melhor do que se repetir no chat

Quando você cola instruções em uma mensagem de chat, elas duram exatamente uma conversa. A próxima sessão — ou o próximo colega de equipe, ou um agente na nuvem executando sua tarefa durante a noite — começa do zero. Um AGENTS.md é carregado automaticamente no início de cada execução, então suas convenções são aplicadas por padrão, em vez de dependerem de você ter lembrado de mencioná-las. É esse o objetivo: tirar o conhecimento do projeto da sua cabeça e de chats descartáveis, e colocá-lo num arquivo que as ferramentas leem toda vez.

O que colocar nele

Pense no que um colega de equipe novo e competente precisaria no primeiro dia — é exatamente disso que um agente precisa. As seções mais úteis são:

• Visão geral do projeto — um parágrafo sobre o que é isto e a stack de tecnologia.
• Comandos de configuração e build — os comandos exatos para instalar, executar e compilar.
• Testes — como executar os testes e a regra de que os testes devem passar antes de uma mudança ser considerada concluída.
• Estilo de código — formatador, linter, convenções de nomenclatura, padrões a preferir ou evitar.
• Diretrizes de commit e PR — formato das mensagens, regras de branch, o que não mexer.
• Armadilhas — qualquer coisa não óbvia que faça as pessoas tropeçarem.

Seja concreto. "Escreva código limpo" não diz nada a um agente. "Use pnpm, não npm; execute pnpm test antes de terminar; nunca edite arquivos em src/generated/" é aplicável.

Um exemplo concreto

Aqui está um AGENTS.md compacto para um aplicativo web típico:

# AGENTS.md

## Project
Next.js 15 + TypeScript storefront. Package manager is pnpm.

## Setup & commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Build: `pnpm build`

## Testing
- Run all tests: `pnpm test`
- All tests must pass before a task is considered done.

## Code style
- TypeScript strict mode; no `any`.
- Format with Prettier (`pnpm format`) — do not hand-format.
- Prefer named exports. Reuse helpers in `src/lib/` before writing new ones.

## Do not touch
- `src/generated/**` is auto-generated. Never edit by hand.
- Never commit `.env` files.

Entregue isso ao Claude Code, ao Cursor ou ao Copilot e cada um deles vai adotar as mesmas regras.

Monorepos: use arquivos aninhados

Em um monorepo você pode colocar um AGENTS.md em cada pacote, além de um na raiz. Quando um agente trabalha dentro de um subdiretório, o arquivo mais próximo vence (agents.md). Mantenha as convenções compartilhadas na raiz e os comandos específicos de cada pacote nos arquivos aninhados, para que um agente que edita packages/api/ receba automaticamente os comandos de build e teste daquele pacote.

AGENTS.md vs CLAUDE.md vs regras do Cursor

Você talvez já tenha arquivos específicos de ferramenta, como CLAUDE.md ou .cursor/rules. Não precisa descartá-los. Na prática, as equipes colocam as convenções compartilhadas e independentes de ferramenta no AGENTS.md — aquilo de que todo agente precisa — e mantêm os extras específicos de cada ferramenta no arquivo nativo da ferramenta que oferece recursos mais ricos (DeployHQ). O Claude Code, por exemplo, lê ambos, com o CLAUDE.md como seu formato mais expressivo. Um padrão comum é manter um único AGENTS.md canônico e, onde uma ferramenta precisar do seu próprio arquivo, fazer esse arquivo apontar para o AGENTS.md, de modo que haja uma única fonte da verdade. Comece com o AGENTS.md; recorra ao arquivo específico da ferramenta apenas quando precisar de um recurso que só ele oferece.

Mantenha-o curto e específico

Mais não é melhor. Um AGENTS.md gigante que reescreve todo o seu guia de estilo disputa a atenção do modelo e sepulta as regras que realmente importam. Mire no punhado de coisas que um agente vai errar sem orientação — o comando não óbvio, o diretório em que não mexer, o padrão que sua base de código prefere. Se uma regra já é óbvia pelo código, você provavelmente não precisa escrevê-la.

Como mantê-lo útil

Um AGENTS.md só compensa se continuar verdadeiro. Trate-o como código: quando um comando ou convenção mudar, atualize o arquivo no mesmo commit. E quando um agente cometer o mesmo erro duas vezes, não se limite a corrigi-lo no chat — anote a regra. Esse único hábito transforma cada tropeço em uma correção permanente, e é a coisa de maior alavancagem que você pode fazer para tornar os agentes de IA confiáveis no seu projeto.