AGENTS.md e os agentes de código: o novo ferramental do desenvolvedor
Em 2026, os agentes de código passam do autocompletar ao colega de equipe. O arquivo AGENTS.md se impôs como o padrão aberto para lhes dar o contexto de um projeto. Por que isso importa.
Do autocompletar ao agente
Em poucos anos, a assistência ao código mudou de natureza: da sugestão linha a linha, passamos a agentes capazes de ler uma base inteira, rodar testes, abrir uma pull request. O problema já não é «gerar código», mas dar ao agente o contexto certo — comandos de build, convenções, arquitetura.
AGENTS.md: um padrão aberto, em Markdown
É exatamente o que o AGENTS.md resolve: um simples arquivo Markdown, na raiz do projeto, que explica a qualquer agente como trabalhar aqui — comandos de build e de teste, estilo de código, frameworks, decisões de arquitetura. Sem esquema imposto, sem ferramenta a instalar: todo agente que o lê se beneficia de imediato.
O formato foi formalizado em agosto de 2025, depois doado à Agentic AI Foundation da Linux Foundation em dezembro de 2025. No fim de 2025, mais de 60 000 projetos open source o haviam adotado, e mais de vinte ferramentas o suportam — GitHub Copilot (suporte nativo desde agosto de 2025), OpenAI Codex, Cursor, Gemini e Jules, Windsurf, Zed, e outras. Sinal dos tempos: o Next.js 16.2 agora gera um AGENTS.md no create-next-app.
Por que é mais do que modismo
Um agente sem contexto redescobre o projeto a cada vez: adivinha os comandos, ignora suas convenções, produz código que é preciso retrabalhar. Um AGENTS.md bem escrito elimina essa fase de descoberta: o código gerado respeita seus padrões desde o início, e as idas e vindas de revisão diminuem.
É, no fundo, a mesma ideia de uma boa documentação de onboarding — só que aqui o recém-chegado é uma máquina que lê rápido e não esquece nada.
Minha posição
Digo com frequência: a IA faz parte das minhas ferramentas, não das minhas fundações. Um agente bem equipado acelera a pesquisa, a prototipagem, as tarefas mecânicas. Mas é o desenvolvedor que escreve o AGENTS.md, que decide a arquitetura, que revisa e valida. A ferramenta não substitui o julgamento: ela o amplifica.
Um agente vale o que vale o contexto que você lhe dá. AGENTS.md é esse contexto, versionado com o código.