AGENTS.md: Context Engineering para Agentes de IA

O AGENTS.md é um arquivo de instruções usado para orientar agentes de IA dentro de um projeto.

Ele funciona como uma camada de contexto persistente, descrevendo como o agente deve entender, modificar, testar e respeitar as decisões técnicas daquele repositório.

O que é AGENTS.md

O AGENTS.md é um documento em Markdown criado na raiz do projeto ou em diretórios específicos do codebase.

Ele define instruções para agentes de IA que trabalham naquele escopo.

Na prática, ele funciona como um guia operacional do projeto.

Em vez de explicar as mesmas regras a cada prompt, você registra essas informações em um arquivo versionado junto com o código.

Isso permite que o agente leia as instruções antes de tomar decisões importantes.

Para que Serve o AGENTS.md

O AGENTS.md serve para reduzir ambiguidade.

Ele informa como o projeto deve ser tratado, quais comandos devem ser usados, quais padrões precisam ser respeitados e quais decisões não devem ser alteradas sem necessidade.

Esse arquivo pode conter instruções como:

Use pnpm para instalar dependências.

Rode pnpm test antes de finalizar alterações.

Não altere arquivos gerados manualmente.

Siga os padrões existentes antes de criar novas abstrações.

Essas regras ajudam o agente a trabalhar de forma mais previsível.

O resultado é menos retrabalho e menos decisões fora do contexto real do projeto.

AGENTS.md e Context Engineering

Context engineering é a prática de organizar o contexto entregue ao agente de IA para melhorar a qualidade da resposta.

Não se trata apenas de escrever prompts melhores.

Trata-se de estruturar informações, regras, exemplos, restrições e objetivos de forma que o agente consiga agir com mais precisão.

O AGENTS.md faz parte desse processo.

Ele transforma contexto importante em documentação operacional.

Em vez de depender da memória da conversa, o projeto passa a carregar suas próprias instruções.

Isso é especialmente útil em repositórios grandes, onde existem padrões locais que não são óbvios apenas olhando um arquivo isolado.

Como Estruturar um AGENTS.md de Forma Eficiente

Um bom AGENTS.md deve ser direto, específico e fácil de seguir.

Ele não precisa explicar tudo sobre o projeto.

Ele precisa dizer o que o agente deve fazer para trabalhar corretamente naquele contexto.

Uma estrutura simples pode ser:

# AGENTS.md

## Visão Geral

Descreva rapidamente o tipo de projeto e o objetivo principal.

## Comandos

Liste os comandos usados para instalar, testar, validar e executar o projeto.

## Padrões de Código

Explique convenções importantes que devem ser preservadas.

## Fluxo de Trabalho

Defina como o agente deve pesquisar, planejar, implementar e validar alterações.

## Restrições

Liste arquivos, decisões ou comportamentos que não devem ser alterados sem pedido explícito.

O ideal é escrever instruções observáveis.

Prefira frases que indiquem ações claras.

Por exemplo:

Use `npm run build` para validar alterações de produção.

Adicione testes quando alterar regras de negócio.

Não use `any` em código TypeScript.

Preserve a estrutura atual de pastas.

Evite instruções genéricas demais.

Frases como “faça código limpo” ou “siga boas práticas” ajudam pouco.

O agente precisa saber quais práticas importam naquele projeto.

AGENTS.md na Raiz e em Subdiretórios

O AGENTS.md pode existir na raiz do repositório e também em pastas específicas.

O arquivo da raiz costuma definir regras gerais.

Arquivos em subdiretórios podem especializar o comportamento para uma parte do projeto.

Por exemplo:

AGENTS.md
apps/web/AGENTS.md
packages/ui/AGENTS.md
packages/api/AGENTS.md

Nesse modelo, o agente usa as instruções mais próximas do arquivo que está sendo alterado.

Isso permite aplicar regras diferentes para frontend, backend, design system ou scripts internos.

Diferença entre AGENTS.md e Skills

O AGENTS.md descreve como trabalhar dentro de um projeto.

Skills descrevem como executar uma capacidade reutilizável.

Uma skill pode ensinar o agente a escrever artigos, revisar pull requests, gerar testes, criar apresentações ou executar um fluxo técnico específico.

O AGENTS.md, por outro lado, orienta o agente sobre o contexto local daquele repositório.

Em resumo:

Recurso	Foco Principal	Escopo
AGENTS.md	Instruções do projeto	Repositório ou diretório
Skills	Capacidades reutilizáveis	Tarefa ou fluxo de trabalho

Uma skill pode ser usada em vários projetos.

Um AGENTS.md normalmente pertence a um projeto específico.

Diferença entre AGENTS.md e Rules

Rules são regras mais gerais de comportamento do agente.

Elas podem vir da ferramenta, do ambiente, da organização ou de uma configuração global.

O AGENTS.md é mais próximo do projeto.

Ele registra instruções versionadas junto com o código.

Na prática, rules costumam responder à pergunta:

Como o agente deve se comportar em geral?

O AGENTS.md responde à pergunta:

Como o agente deve trabalhar neste projeto?

Essa diferença é importante.

Rules definem limites e preferências gerais.

O AGENTS.md conecta essas regras ao contexto real do codebase.

Quando Usar AGENTS.md, Skills e Rules

Use AGENTS.md quando a instrução depende do projeto.

Use skills quando a instrução descreve uma tarefa reutilizável.

Use rules quando a instrução deve valer de forma mais ampla.

Por exemplo:

Situação	Melhor Opção
Definir comandos de build do repositório	AGENTS.md
Ensinar o agente a escrever artigos	Skill
Proibir comandos destrutivos sem confirmação	Rule
Explicar padrões de uma pasta específica	AGENTS.md
Criar um fluxo repetível de revisão de código	Skill

Essa separação evita arquivos enormes e confusos.

Cada tipo de instrução fica no lugar onde faz mais sentido.

Boas Práticas para AGENTS.md

Mantenha o arquivo curto.

Atualize o AGENTS.md quando o fluxo do projeto mudar.

Inclua comandos reais, não comandos aproximados.

Explique decisões específicas do projeto.

Remova instruções antigas.

Evite duplicar documentação que já existe em outro lugar.

O AGENTS.md deve ajudar o agente a agir melhor, não virar uma enciclopédia do repositório.

Conclusão

O AGENTS.md é uma peça importante para trabalhar com agentes de IA em projetos reais.

Ele aproxima o agente do contexto do repositório e reduz a chance de decisões desalinhadas com o projeto.

Quando combinado com context engineering, skills e rules, o AGENTS.md ajuda a criar um ambiente mais previsível para colaboração com IA.

Cada recurso tem um papel diferente, e entender essa separação torna o uso de agentes muito mais eficiente.