Padrões de AGENTS.md: o que realmente muda o comportamento do agente

Meu primeiro AGENTS.md era o guia de estilo do nosso time colado em 200 linhas. Tinha convenções de nomenclatura, checklists de revisão de código, procedimentos de deploy e princípios de arquitetura. O agente ignorou quase tudo. Não porque as instruções estivessem erradas, mas porque eram documentação, e não operação.

O AGENTS.md deve conter instruções que começam pelo comando, com as invocações exatas, seções organizadas por tarefa (código, revisão, release) e critérios explícitos de “pronto” que o agente consiga verificar. Escreva política operacional, não documentação para humanos. Inclua os comandos de shell específicos, as configurações de linter e os comandos de teste que o agente precisa executar. Evite parágrafos de prosa, diretrizes ambíguas como “tenha cuidado” e prioridades contraditórias sem uma ordem explícita. O AGENTS.md é um padrão aberto adotado por mais de 60.000 projetos e funciona em Codex, Cursor, Copilot e outras ferramentas de agente.

Essa distinção importa mais do que qualquer padrão específico deste post. O AGENTS.md é política operacional para um agente de IA, não um README para pessoas. O agente não precisa entender por que você usa conventional commits. Ele precisa saber o comando exato a executar e como é o “pronto”.

TL;DR

A maior parte dos problemas com AGENTS.md vem de escrever documentação para humanos em vez de operação para agentes. Arquivos eficazes começam pelo comando (invocações exatas, não descrições), são organizados por tarefa (seções de código, revisão e release) e definem o encerramento (critérios explícitos de “pronto”). Antipadrões que são ignorados de forma previsível: parágrafos de prosa, diretrizes ambíguas (“tenha cuidado”) e prioridades contraditórias. O AGENTS.md é um padrão aberto adotado por mais de 60.000 projetos ¹ e funciona em Codex, Cursor, Copilot, Amp, Devin Desktop e outras ferramentas ².

Contexto: o AGENTS.md é mantido pela Agentic AI Foundation, sob a Linux Foundation ³, com membros platina como Anthropic, Google, Microsoft e OpenAI. Este post trata de padrões práticos. Para a configuração específica do Codex, veja o guia do Codex. Para o equivalente no Claude Code (CLAUDE.md), veja o guia do Claude Code.

O que é ignorado

Esses padrões não produzem nenhuma mudança observável no comportamento do agente. Identifiquei cada um executando tarefas idênticas com e sem a instrução presente e comparando a precisão de conclusão em mais de 10 execuções por padrão. A análise do GitHub sobre mais de 2.500 repositórios com arquivos AGENTS.md chegou à mesma conclusão: “a maioria dos arquivos de agente falha porque é vaga demais” ¹¹. Os padrões abaixo não melhoraram a precisão de nenhuma forma mensurável.

Parágrafos de prosa sem comandos

<!-- BAD: Agent skips this -->
We value clean, well-tested code. Our team follows TDD principles
and believes in comprehensive test coverage. Please ensure all
changes are properly tested before submitting.

O agente lê isso, guarda como uma preferência vaga e segue escrevendo código sem testes. Não há instrução acionável, nem comando a executar, nem limiar a atingir, nem definição do que é “devidamente testado”.

Diretrizes ambíguas

<!-- BAD: "Careful" means nothing to an agent -->
- Be careful with database migrations
- Optimize queries where possible
- Handle errors gracefully

“Cuidado” não é uma restrição. “Quando possível” não é uma condição de disparo. “De forma elegante” não é uma especificação de comportamento. Isso soa como orientação de pessoa para pessoa, não como instrução para um agente. Compare com o que funciona: “Execute alembic check antes de aplicar migrações. Aborte se o caminho de downgrade estiver ausente”.

Prioridades contraditórias

<!-- BAD: Which one wins? -->
- Move fast and ship quickly
- Ensure comprehensive test coverage
- Keep the runtime budget under 5 minutes
- Run the full integration test suite before every commit

O agente não consegue satisfazer as quatro ao mesmo tempo. Quando as instruções entram em conflito sem uma ordem explícita de prioridade, o modelo pula etapas de verificação e corre para gerar código. Uma pesquisa apresentada na ICLR 2026 (Ambig-SWE) constatou que “sem um estímulo explícito, os modelos quase nunca interagem, mesmo diante de entradas gravemente subespecificadas” – os agentes seguem em silêncio em vez de fazer perguntas de esclarecimento – enquanto estimulá-los a interagir melhora o desempenho em até 74% em tarefas subespecificadas ¹². Corrija instruções conflitantes numerando as prioridades: “Prioridade 1: os testes passam. Prioridade 2: abaixo de 5 minutos. Prioridade 3: entregar rápido”.

Guias de estilo sem aplicação

<!-- BAD: No way to verify compliance -->
Follow the Google Python Style Guide for all code.
Use numpy-style docstrings for public functions.

A menos que você inclua o comando de lint exato que aplica o estilo (ruff check --select D ou pylint --rcfile=.pylintrc), o agente não tem como verificar a própria conformidade. O padrão aqui é universal: instruções sem comandos de verificação são sugestões, não regras.

O que funciona

Esses padrões produzem mudanças consistentes e mensuráveis no comportamento do agente.

Instruções que começam pelo comando

## Build and Test Commands
- Install: `pip install -r requirements.txt`
- Lint: `ruff check . --fix`
- Format: `ruff format .`
- Test: `pytest -v --tb=short`
- Type check: `mypy app/ --strict`
- Full verify: `ruff check . && ruff format --check . && pytest -v`

Comandos são inequívocos. O agente sabe exatamente o que executar, quais argumentos passar, e consegue confirmar o sucesso pelo código de saída. Cada instrução do seu AGENTS.md deveria responder à pergunta: “qual comando prova que isso foi feito corretamente?”.

Definições de encerramento

## Definition of Done
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
4. Changed files have been staged and committed
5. Commit message follows conventional format: `type(scope): description`

Definições explícitas de encerramento eliminam o modo de falha mais comum: o agente reportar “pronto” sem verificar. Quando “pronto” é definido como códigos de saída específicos, o agente roda cada checagem antes de reportar a conclusão. Sem essa definição, “pronto” significa “acho que terminei”, uma fonte frequente de bugs introduzidos por agentes.

Seções organizadas por tarefa

## When Writing Code
- Run `ruff check .` after every file change
- Add type hints to all new functions
- Test command: `pytest tests/ -v -k "test_<module>"`

## When Reviewing Code
- Check for security issues: `bandit -r app/`
- Verify test coverage: `pytest --cov=app --cov-fail-under=80`
- List changed files: `git diff --name-only HEAD~1`

## When Releasing
- Update version in `pyproject.toml`
- Run full suite: `pytest -v && ruff check . && mypy app/`
- Tag: `git tag -a v<version> -m "Release v<version>"`

Arquivos organizados por tarefa permitem que o agente selecione as instruções relevantes com base no que está fazendo naquele momento. Listas planas obrigam o agente a processar cada instrução independentemente do contexto. O prefixo “When…” mapeia diretamente a forma como o agente raciocina sobre o contexto da tarefa.

Regras de escalonamento

## When Blocked
- If tests fail after 3 attempts: stop and report the failing test with full output
- If a dependency is missing: check `requirements.txt` first, then ask
- If you encounter merge conflicts: stop and show the conflicting files
- Never: delete files to resolve errors, force push, or skip tests

Sem regras de escalonamento, agentes bloqueados partem para contornos cada vez mais criativos: apagam arquivos de lock, burlam checagens ou ignoram falhas em silêncio. A lista de “nunca” é tão importante quanto os caminhos de escalonamento. Proibir explicitamente padrões destrutivos de recuperação evita os piores modos de falha.

Escopo por diretório em monorepos

O AGENTS.md oferece escopo hierárquico como recurso central da especificação ². Arquivos mais próximos do diretório de trabalho têm precedência:

/repo/AGENTS.md                        ← Project-wide rules
  └─ /repo/services/AGENTS.md          ← Service defaults
      ├─ /repo/services/api/AGENTS.md  ← API-specific rules
      └─ /repo/services/web/AGENTS.md  ← Frontend-specific rules

As instruções do nível raiz se concatenam com os arquivos mais profundos. O Codex percorre da raiz do projeto até o diretório de trabalho atual, combinando cada AGENTS.md encontrado no caminho ⁴; a própria especificação define a precedência do arquivo mais próximo, então outras ferramentas podem resolver a hierarquia de outro jeito ². O próprio repositório codex da OpenAI faz isso na prática: ele traz um AGENTS.md aninhado abaixo do arquivo da raiz ⁴.

No Codex, você também pode usar AGENTS.override.md em qualquer nível para substituir (e não estender) as instruções do nível superior ⁴. O mecanismo de override é específico do Codex, outras ferramentas não o implementam.

<!-- /repo/services/payments/AGENTS.override.md (Codex only) -->
# Payment Service Rules (OVERRIDE)

This service has additional security requirements.
All changes require: `bandit -r . -ll` passing with zero findings.
No dependency updates without explicit approval.
Test with: `pytest -v --tb=long -x` (fail fast, full tracebacks)

Quando usar o override: congelamento de release, modo de incidente ou qualquer serviço com restrições de segurança que se sobrepõem aos padrões do projeto inteiro.

Compatibilidade entre ferramentas

O AGENTS.md foi adotado por mais de 60.000 projetos ¹ e é reconhecido por todas as principais ferramentas de programação com IA. Veja como o mesmo arquivo se comporta em cada ecossistema (tabela verificada em agosto de 2026):

Se o seu time usa várias ferramentas: escreva o AGENTS.md como fonte canônica. Adicione arquivos específicos de cada ferramenta (CLAUDE.md, .cursorrules) que importem ou espelhem as seções relevantes. Não mantenha conjuntos paralelos de instruções que acabam divergindo.

Ordem de escrita: o que adicionar primeiro

Se você vai escrever um AGENTS.md do zero, acrescente as seções nesta ordem de prioridade. Cada camada se apoia na anterior:

1. Comandos de build e teste, o agente precisa deles antes de fazer qualquer coisa útil
2. Definição de pronto, evita falsas conclusões do tipo “acho que terminei”
3. Regras de escalonamento, evita contornos destrutivos quando o agente trava
4. Seções organizadas por tarefa, reduz o processamento de instruções irrelevantes por tarefa
5. Escopo por diretório (só em monorepos), mantém isoladas as instruções de cada serviço

Deixe as preferências de estilo para depois que os quatro primeiros itens estiverem funcionando. A maioria dos arquivos AGENTS.md falha porque começa pela orientação de estilo e nunca chega aos comandos.

Testando o seu AGENTS.md

Confirme que o agente de fato lê e segue as suas instruções:

# Codex: Show the full instruction chain
codex --ask-for-approval never "Summarize your current instructions"

# Codex: Generate a scaffold (slash command inside an active session)
# Type /init at the Codex prompt, not as a shell command
codex  # then type: /init

# Claude Code: Check active instructions
claude --print "What instructions are you following for this project?"

# Verify specific rules are active
codex --ask-for-approval never "What is your definition of done?"

O teste decisivo: peça ao agente que explique os seus comandos de build. Se ele não conseguir reproduzi-los literalmente, as instruções não estão sendo lidas ou são verbosas demais para caber no contexto. Arquivos AGENTS.md longos são truncados pela janela de contexto, então mantenha cada seção abaixo de 50 linhas e coloque as instruções mais críticas no início.

Perguntas frequentes

Qual deve ser o tamanho de um arquivo AGENTS.md?

Minha regra prática: cada seção abaixo de 50 linhas e o arquivo inteiro abaixo de 150. O princípio por trás disso vem da orientação de agent experience da Marmelab – o arquivo deve permanecer “curto e direto ao ponto”, porque os agentes o leem no início de toda sessão ¹³; os números de linhas são meus, não deles. O Codex aplica um limite padrão de 32 KiB (project_doc_max_bytes) ⁴. Arquivos longos são truncados pela janela de contexto, então coloque no início as instruções mais críticas, os comandos e as definições de encerramento, antes das preferências de estilo.

O AGENTS.md substitui os arquivos de instrução específicos de cada ferramenta?

Não. O AGENTS.md funciona lado a lado com CLAUDE.md, .cursor/rules e outros arquivos específicos de ferramenta. Escreva o AGENTS.md como fonte canônica e depois espelhe as seções relevantes nos arquivos de cada ferramenta. Os padrões do AGENTS.md (começar pelo comando, definir o encerramento) funcionam em qualquer arquivo de instrução, seja qual for a ferramenta.

E se o agente ignorar o meu AGENTS.md?

Teste pedindo ao agente que explique os seus comandos de build. Se ele não conseguir reproduzi-los literalmente, o arquivo é verboso demais (o conteúdo foi empurrado para fora do contexto), vago demais (o agente não extrai instruções acionáveis) ou não está sendo descoberto (confira a localização do arquivo e a documentação da ferramenta). A análise do GitHub sobre mais de 2.500 repositórios concluiu que a maioria dos arquivos de agente falha por ser vaga demais ¹¹.

Principais conclusões

Para desenvolvedores individuais:

• Troque prosa por comandos. Toda instrução deveria ser verificável executando alguma coisa.
• Defina o encerramento de forma explícita. “Pronto” significa códigos de saída específicos, não sensações.
• Teste o seu AGENTS.md pedindo ao agente que o recite. O que ele não recita, ele não segue.

Para times:

• Use o AGENTS.md como fonte única de verdade. Espelhe nos arquivos de cada ferramenta, não mantenha cópias paralelas.
• Organize por tarefa (código, revisão, release), não por categoria (estilo, testes, deploy).
• Inclua regras de escalonamento. Sem elas, agentes bloqueados improvisam de um jeito que você não vai gostar.
• Defina escopo por diretório em monorepos. Regras de um serviço não deveriam poluir as instruções globais.

Referências