Código / CDG.008Guia

AGENTS.md: o arquivo que ensina agentes de IA a trabalhar no seu projeto

Um README para agentes: o AGENTS.md reúne comandos, regras e testes que um agente de IA precisa conhecer antes de mexer no seu projeto. Veja como escrever um.

Imagine receber uma pessoa nova na equipe sem dizer como rodar o projeto, quais testes executar ou que padrão de código seguir. Então, ela vai adivinhar, e boa parte do primeiro trabalho vai precisar ser refeita. Da mesma forma, agentes de IA de programação vivem essa situação toda vez que abrem um repositório. O AGENTS.md é a resposta mais adotada até agora: um arquivo em Markdown, na raiz do projeto, com as instruções que um agente precisa conhecer antes de mexer em qualquer coisa.

Neste guia, você vai entender de onde veio o formato, o que colocar no arquivo e como escrever um primeiro AGENTS.md.

O que é o AGENTS.md

O AGENTS.md é um formato aberto e simples para dar a agentes instruções e contexto específicos de um projeto. Na prática, ele foi lançado em agosto de 2025 e, segundo o anúncio da OpenAI sobre a Agentic AI Foundation, já tinha sido adotado por mais de 60 mil projetos abertos e frameworks de agentes. Além disso, em dezembro de 2025, o formato passou a fazer parte dessa fundação, ligada à Linux Foundation, ao lado do MCP.

A mesma página lista ferramentas que leem o arquivo, como Codex, Cursor, Devin, Gemini CLI, GitHub Copilot, Jules e VS Code. Ou seja, você escreve as instruções uma vez, e agentes diferentes encontram tudo no mesmo lugar.

Por que não usar só o README

O README é escrito para pessoas. Em geral, ele explica o que o projeto é, como instalar e como contribuir. Já um agente precisa de outro tipo de informação: o comando exato para rodar os testes, a regra de estilo que o linter cobra, o que nunca deve ser alterado.

Porém, colocar tudo isso no README deixaria o arquivo pesado para quem só quer entender o projeto. Por isso, o AGENTS.md fica ao lado dele, com um público diferente. É a mesma lógica de separar o manual do usuário do manual de manutenção.

Comparação entre README e AGENTS.md: o README é escrito para pessoas e explica o que o projeto é, como instalar e como contribuir; o AGENTS.md é escrito para agentes e traz comandos exatos, regras de estilo, testes obrigatórios e limites do que não deve ser alterado.
Os dois arquivos convivem na raiz do projeto, cada um com seu leitor.

O que colocar no AGENTS.md

Por enquanto, não existe um esquema obrigatório. O exemplo mínimo do repositório do formato tem três blocos: dicas do ambiente de desenvolvimento, instruções de teste e regras para pull requests. A partir disso, um bom arquivo costuma responder a cinco perguntas:

  1. Como preparar o ambiente? Comandos de instalação e versões necessárias.
  2. Como rodar e testar? O comando de testes, o de lint e quando executar cada um.
  3. Que padrões seguir? Estilo de código, nomes, estrutura de pastas.
  4. O que não mexer? Arquivos gerados, migrações antigas, configurações de produção.
  5. Como entregar? Formato do título do pull request e checagens antes do commit.

Veja um exemplo curto:

# AGENTS.md

## Ambiente
- Node 22. Instale com `npm ci`.

## Testes
- Rode `npm test` e `npm run lint` antes de cada commit.

## Regras
- Componentes novos ficam em `src/components/`, em TypeScript.
- Nunca edite arquivos em `dist/` nem em `migrations/`.

## Pull requests
- Título no formato `[área] descrição curta`.
Anatomia de um AGENTS.md em cinco blocos: ambiente com versões e instalação, testes com comandos e quando rodar, padrões de código, limites do que não alterar e regras de entrega dos pull requests.
Cinco blocos cobrem a maior parte do que um agente precisa saber.

Boas práticas para o arquivo funcionar

Afinal, escrever para um agente é escrever para um leitor literal. Por isso, algumas escolhas fazem diferença:

  • Prefira comandos exatos a descrições. “Rode npm test” funciona melhor que “teste antes de enviar”.
  • Diga o porquê das proibições. Assim, o agente entende o limite em situações parecidas.
  • Mantenha o arquivo curto. Afinal, instruções demais competem entre si, e as importantes se perdem.
  • Atualize junto com o projeto. Do contrário, um comando que mudou e não foi atualizado ensina o erro.

Inclusive, o efeito aparece nos dados. O Octoverse 2026 do GitHub observou que, entre os repositórios criados em 2026, os que tinham um arquivo de configuração para agentes registraram em média oito vezes mais commits que os demais. Esse número mostra associação, não causa: projetos mais ativos tendem a se organizar melhor. Ainda assim, ele indica onde as equipes que trabalham com agentes estão investindo.

Um arquivo pequeno, uma conversa maior

O AGENTS.md parece um detalhe técnico, mas ele registra decisões que antes ficavam na cabeça de quem conhecia o projeto. Além disso, escrever esse arquivo obriga a equipe a responder perguntas simples, como qual é o comando certo de teste, que muitas vezes ninguém tinha formalizado.

Se você está começando a usar agentes, vale ler também como o MCP conecta agentes a ferramentas. O AGENTS.md diz ao agente como trabalhar; o MCP define o que ele pode alcançar.

/ Conexões

Próximas conexões

Autor

Gledson Dias

Ver todos os artigos

Sistemativo / Brief

Gostou dessa ideia?

A cada duas semanas, ideias, ferramentas, referências e movimentos que valem alguns minutos da sua atenção.

Brief (formulário compacto)

Você poderá sair da lista quando quiser. Sem spam.