AGENTS.md enxuto é um arquivo de contexto escrito para orientar agentes de código, não para resumir todo o repositório. Ele deve dizer ao Codex, ao Claude Code e a ferramentas parecidas quais comandos importam, quais riscos não podem passar e quando a tarefa está pronta para revisão.

Em 2026, o site oficial do formato AGENTS.md afirma que ele já aparece em mais de 60 mil projetos open-source (AGENTS.md, "A simple, open format for guiding coding agents", 2026). A adoção explica a urgência: se o arquivo vira lixo de contexto, o agente passa a obedecer instruções que atrapalham.

Resumo prático

  • Escreva só regras que mudam uma decisão do agente.
  • Coloque comandos de teste perto do pacote certo.
  • Transforme feedback repetido de PR em regra curta.
  • Valide o arquivo com tarefas reais antes de expandi-lo.

Composição abstrata mostra camadas de contexto conectadas a agentes de código sem texto visível.

Por que AGENTS.md virou disputa de contexto?

Em 2026, o artigo "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?" encontrou custo médio de inferência acima de 20% quando arquivos de contexto eram adicionados sem melhorar a taxa geral de sucesso (arXiv, "Evaluating AGENTS.md", 2026). A disputa existe porque o agente segue instruções, mesmo quando elas criam trabalho desnecessário.

O ponto não é abandonar AGENTS.md. O ponto é parar de usar esse arquivo como enciclopédia. O estudo observou que agentes obedecem instruções, mas visões gerais do repositório não ajudam muito quando apenas repetem o que a árvore de arquivos, os testes e a busca já revelam.

Na prática, um AGENTS.md bom se parece mais com contrato de operação do que com documentação de produto. Ele diz como instalar dependências, qual teste prova a mudança, qual diretório tem regra especial e que tipo de alteração exige revisão humana.

Esse recorte continua a conversa sobre context engineering para agentes de código. Lá, o foco era orçamento de prompt. Aqui, o foco é o arquivo que entra no começo da sessão e influencia cada decisão posterior.

Cápsula citável: Em 2026, AGENTS.md deixou de ser dica de prompt e virou superfície de engenharia. A pesquisa da arXiv sobre "Evaluating AGENTS.md" mediu custo acima de 20% com arquivos de contexto, então o arquivo deve registrar só regras que alteram execução, teste ou revisão.

O que entra no arquivo e o que fica fora?

Em 2026, a documentação de personalização do Codex recomenda manter AGENTS.md pequeno e começar apenas com instruções que importam (OpenAI Developers, "Customization", 2026). Entra no arquivo o que evita erro repetido; fica fora o que o agente consegue descobrir com leitura normal do repositório.

Inclua comandos que não são óbvios. Se npm test falha sem Redis local, diga isso. Se o pacote de pagamentos usa outro comando, crie instrução no diretório desse pacote. Se todo PR precisa de teste de contrato, escreva o critério de pronto.

Deixe fora árvore de pastas, explicação longa da arquitetura e opinião genérica sobre qualidade. O agente pode usar rg, ler package.json, abrir workflows e consultar testes. Repetir essas pistas no contexto inicial só aumenta ruído.

Quando a tarefa atravessa várias sessões, eu trato o RemoteCode como uma extensão de contexto para Claude Code e Codex em fluxos agentic longos, especialmente quando quero manter continuidade sem despejar todo o histórico no prompt principal. É uma ferramenta minha, então a menção aqui é editorial e contextual.

Uma regra simples funciona bem: se a instrução não muda comando, limite, risco, estilo de patch ou critério de aceite, ela provavelmente pertence a outro documento. O AGENTS.md deve apontar para esse documento apenas quando ele for necessário.

Como escrever um AGENTS.md mínimo?

Em 2026, a documentação do Codex informa que ele lê AGENTS.md por escopo global, raiz do projeto e diretórios até a pasta atual, com limite padrão combinado de 32 KiB definido por project_doc_max_bytes (OpenAI Developers, "Custom instructions with AGENTS.md", 2026). Isso favorece instruções curtas e próximas do código afetado.

Comece com um arquivo raiz que tenha poucas seções. Depois mova regras específicas para diretórios. O serviço de pagamentos não deve forçar o agente de frontend a carregar detalhes de webhook. O pacote de design system não deve herdar regra de migração de banco.

Um exemplo suficiente:

# AGENTS.md

## Ambiente
- Use `npm ci` para instalar dependências.
- Antes de editar, rode `npm run typecheck` se a mudança tocar TypeScript.

## Critérios de pronto
- Rode o teste mais próximo do arquivo alterado.
- Se mudar contrato de API, atualize teste de integração.
- Se não conseguir rodar um teste, explique o bloqueio no resumo final.

## Limites
- Não altere migrações aplicadas sem pedir revisão humana.
- Não adicione dependência de produção sem justificar impacto.

Perceba a ausência de mapa de pastas. O arquivo diz como trabalhar, não tenta narrar o repositório. Se o agente precisa conhecer uma convenção de arquitetura, o melhor caminho é apontar para um documento curto, não copiar o documento inteiro.

Loop abstrato mostra agentes passando por comandos, testes e correções sem texto visível.

Cápsula citável: Um AGENTS.md mínimo ajuda Codex e Claude Code quando registra comandos, critérios de pronto e limites de permissão. A documentação do Codex cita 32 KiB como limite padrão combinado para instruções de projeto, o que torna escopo por diretório mais seguro que arquivo raiz inchado.

Quando CLAUDE.md, MEMORY.md e skills entram?

Em 2026, a documentação do Claude Code diz que MEMORY.md carrega as primeiras 200 linhas ou 25 KB no início da conversa, enquanto arquivos CLAUDE.md são carregados por completo e funcionam melhor quando ficam abaixo de 200 linhas (Claude Code Docs, "How Claude remembers your project", 2026). Isso muda a arquitetura do contexto.

Use CLAUDE.md para instruções persistentes que o Claude Code deve ver sempre. Use AGENTS.md quando o objetivo é interoperabilidade com Codex, Cursor, Gemini CLI e outros agentes. Se o time usa mais de uma ferramenta, mantenha uma fonte canônica e use ponte ou link simbólico quando fizer sentido.

Use memória para aprendizado operacional, não para política permanente. Um erro descoberto durante depuração pode virar memória temporária. Se ele vira feedback repetido de PR, promova a regra para AGENTS.md ou CLAUDE.md no diretório certo.

Use skills quando a instrução é grande, rara ou procedural. Em 2026, a documentação de skills do Codex diz que a lista inicial usa no máximo 2% da janela de contexto, ou 8.000 caracteres quando a janela é desconhecida, e só carrega o SKILL.md completo quando a skill é escolhida (OpenAI Developers, "Agent Skills", 2026). Isso é progressive disclosure aplicado ao agente.

Essa separação combina com MCP de codebase RAG para agentes. AGENTS.md define como trabalhar. MCP e skills entregam contexto sob demanda. Memória registra aprendizado que ainda não virou regra estável.

Como validar se o arquivo ajuda ou atrapalha?

Em 2026, o artigo "On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents" analisou 10 repositórios e 124 pull requests; com AGENTS.md, observou mediana de runtime 28,64% menor e tokens de saída 16,58% menores, com comportamento de conclusão comparável (arXiv, "On the Impact of AGENTS.md Files", 2026). O resultado oposto ao outro estudo mostra que o conteúdo do arquivo importa.

Valide com tarefas reais do seu repositório. Pegue correções pequenas, refactors de risco médio e mudanças que exigem teste. Rode com e sem AGENTS.md. Compare tempo, tokens, arquivos lidos, testes executados, regressões e qualidade do resumo final.

O critério mais importante é negativo: o arquivo não deve fazer o agente explorar mais do que a tarefa pede. Se ele lê documentação ampla antes de alterar uma linha simples, há excesso. Se ele roda teste irrelevante por obrigação genérica, há excesso.

Crie uma rubrica curta para PRs de agente:

Sinal observado Interpretação Ação no AGENTS.md
O mesmo teste faltou de novo. Regra útil ausente. Adicionar comando perto do pacote.
O agente leu documentos demais. Roteamento fraco. Apontar só para fontes prioritárias.
O patch alterou camada errada. Fronteira de módulo fraca. Registrar limite do diretório.
O resumo final omitiu risco. Critério de pronto vago. Exigir evidência e risco residual.

Essa validação conversa com evals de PR para agentes no CI. O AGENTS.md orienta o comportamento. O eval mede se esse comportamento entregou prova suficiente para o revisor.

Cápsula citável: Dois estudos de 2026 sobre AGENTS.md chegaram a sinais diferentes: um mediu custo acima de 20% sem ganho geral de sucesso, outro mediu runtime 28,64% menor em 124 PRs. A conclusão prática é testar o arquivo no próprio repositório antes de expandi-lo.

Como manter o AGENTS.md vivo sem virar depósito?

Em 2026, o Codex recomenda tratar AGENTS.md como loop de feedback: quando o agente faz uma suposição errada, corrija e peça atualização do arquivo para que sessões futuras herdem a regra (OpenAI Developers, "Customization", 2026). A manutenção deve nascer de erro repetido, não de ansiedade documental.

Revise o arquivo como código. Toda nova regra deve responder a uma falha observada: teste esquecido, comando errado, estilo de diff incompatível, risco de segurança ou feedback repetido no PR. Se ninguém consegue apontar a falha, a regra não entra.

Também remova regras. Quando um comando muda para o padrão do repositório, a instrução especial perde valor. Quando um pacote morre, apague o bloco. Quando uma skill ou MCP cobre melhor um procedimento, deixe o AGENTS.md apontar para a ferramenta.

Matriz abstrata mostra decisões sobre contexto, testes e limites de agentes sem texto visível.

Para times com fan-out de subagentes, mantenha a regra no menor escopo possível. Um agente de revisão precisa de critérios de risco. Um agente de patch precisa de comando de teste. Um agente de inventário precisa saber onde procurar. Isso aprofunda o padrão de fan-out de subagentes para migrações.

Perguntas frequentes sobre AGENTS.md enxuto

AGENTS.md deve explicar a arquitetura inteira?

Não. Em 2026, a pesquisa "Evaluating AGENTS.md" indicou custo médio acima de 20% quando arquivos de contexto eram adicionados sem ganho geral de sucesso. Explique só exceções, limites e comandos. Para arquitetura completa, aponte para documentos que o agente lê sob demanda.

Codex e Claude Code podem compartilhar o mesmo arquivo?

Sim, mas com cuidado. Em 2026, o formato AGENTS.md declara compatibilidade com um ecossistema amplo e mais de 60 mil projetos open-source. Para Claude Code, você pode manter ponte com CLAUDE.md, mas evite duplicar regras divergentes entre ferramentas.

Qual é o tamanho ideal de um AGENTS.md?

Não há tamanho universal. Em 2026, o Claude Code recomenda mirar abaixo de 200 linhas para CLAUDE.md, enquanto o Codex cita 32 KiB como limite padrão combinado de instruções de projeto. Use esses limites como alerta: quanto maior o arquivo, mais forte precisa ser a evidência.

Quando devo criar AGENTS.md por diretório?

Crie quando o subdiretório tem comando, risco ou regra diferente. Em 2026, a documentação do Codex diz que arquivos mais próximos da pasta atual aparecem depois na cadeia e podem sobrescrever orientação anterior. Isso evita carregar regra de backend em tarefa de frontend.

Como sei que meu AGENTS.md melhorou o agente?

Meça em tarefas reais. Em 2026, um estudo com 10 repositórios e 124 pull requests associou AGENTS.md a runtime 28,64% menor e 16,58% menos tokens de saída. Se seu arquivo não reduz erro, leitura inútil ou retrabalho, ele ainda não está pronto.

Fechamento

AGENTS.md não é um lugar para despejar contexto. É um contrato pequeno para decisões repetidas: como instalar, testar, revisar, limitar ferramentas e registrar exceções. Em agentes de código, contexto bom não é contexto grande. É contexto que muda a próxima ação.

Comece pequeno, avalie no CI e promova só regras que nasceram de erro real. Depois conecte isso ao seu harness de agentes para PRs confiáveis, aos seus evals de PR e às ferramentas MCP que já entregam contexto sob demanda. Assim o agente gasta menos atenção em ruído e mais atenção no patch.

Fontes consultadas

  • AGENTS.md, "A simple, open format for guiding coding agents", recuperado em 2026-07-04, https://agents.md/
  • arXiv, "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?", recuperado em 2026-07-04, https://arxiv.org/abs/2602.11988
  • arXiv, "On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents", recuperado em 2026-07-04, https://arxiv.org/abs/2601.20404
  • OpenAI Developers, "Custom instructions with AGENTS.md", recuperado em 2026-07-04, https://developers.openai.com/codex/guides/agents-md
  • OpenAI Developers, "Customization", recuperado em 2026-07-04, https://developers.openai.com/codex/concepts/customization
  • OpenAI Developers, "Agent Skills", recuperado em 2026-07-04, https://developers.openai.com/codex/skills
  • Claude Code Docs, "How Claude remembers your project", recuperado em 2026-07-04, https://code.claude.com/docs/en/memory
  • OpenAI Developers, "Best practices", recuperado em 2026-07-04, https://developers.openai.com/codex/learn/best-practices