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

Meu primeiro AGENTS.md era uma colagem de 200 linhas do guia de estilo da nossa equipe. Incluía convenções de nomenclatura, checklists de revisão de código, procedimentos de deploy e princípios arquiteturais. O agente ignorou a maior parte. Não porque as instruções estavam erradas — porque eram documentação, não operações.

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

TL;DR

A maioria dos problemas com AGENTS.md vem de escrever documentação para humanos em vez de operações para agentes. Arquivos eficazes são orientados a comandos (invocações exatas, não descrições), organizados por tarefa (seções de codificação, revisão, release) e com definição de conclusão (critérios explícitos de “concluído”). Anti-padrões que são ignorados de forma consistente: parágrafos em prosa, diretivas ambíguas (“tenha cuidado”) e prioridades contraditórias. AGENTS.md é um padrão aberto adotado por mais de 60.000 projetos ¹ e funciona com Codex, Cursor, Copilot, Amp, Windsurf e outros ².

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

O que é ignorado

Esses padrões consistentemente 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 depois comparando a precisão de conclusão das tarefas em mais de 10 execuções por padrão. A análise do GitHub de mais de 2.500 repositórios com arquivos AGENTS.md chegou à mesma conclusão: “A maioria dos arquivos de agentes falha porque são vagos demais — não por limitações técnicas” ¹¹. Os padrões abaixo não conseguiram melhorar a precisão de nenhuma forma mensurável.

Parágrafos em 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, representa como uma preferência vaga e prossegue escrevendo código sem testes. Não há instrução acionável — nenhum comando para executar, nenhum limite a atingir, nenhuma definição de “devidamente testado”.

Diretivas 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. “Onde possível” não é uma condição de disparo. “Graciosamente” não é uma especificação de comportamento. Essas instruções soam como orientação entre humanos, não instruções para agentes. Compare com o que funciona: “Execute alembic check antes de aplicar migrations. 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 todas as quatro simultaneamente. Quando as instruções conflitam sem ordenação explícita de prioridade, o modelo pula etapas de verificação e corre para a geração de código. Uma pesquisa do ICLR 2026 (AMBIG-SWE) descobriu que agentes “adotam comportamento não interativo por padrão sem encorajamento explícito” — prosseguindo silenciosamente em vez de fazer perguntas de esclarecimento, o que reduziu as taxas de resolução de 48,8% para 28% ¹². Corrija instruções conflitantes numerando prioridades: “Prioridade 1: Testes passam. Prioridade 2: Menos de 5 minutos. Prioridade 3: Entregue 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 exato de linting que aplica o estilo (ruff check --select D ou pylint --rcfile=.pylintrc), o agente não tem mecanismo para verificar sua 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 orientadas a comandos

## 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 pode verificar o sucesso checando o código de saída. Cada instrução no seu AGENTS.md deve responder à pergunta: “Qual comando prova que isso foi feito corretamente?”

Definições de conclusão

## 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 conclusão eliminam o modo de falha mais comum: o agente reporta “concluído” sem verificar. Quando “concluído” é definido como códigos de saída específicos, o agente executa cada verificação antes de reportar a conclusão. Sem essa definição, “concluído” significa “eu acho que terminei” — uma fonte comum 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 instruções relevantes com base no que está fazendo no momento. Listas planas forçam o agente a analisar cada instrução independentemente do contexto. O prefixo “When…” mapeia diretamente para como o agente raciocina sobre o contexto da tarefa.

Regras de escalação

## 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 escalação, os agentes recorrem a soluções alternativas cada vez mais criativas quando ficam bloqueados — deletando arquivos de lock, ignorando verificações ou falhando silenciosamente. A lista “Never” é tão importante quanto os caminhos de escalação. Proibir explicitamente padrões destrutivos de recuperação previne os piores modos de falha.

Escopo por diretório para monorepos

AGENTS.md suporta 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

Instruções do nível raiz são concatenadas com arquivos mais profundos. As ferramentas percorrem da raiz do projeto até o diretório de trabalho atual, combinando cada AGENTS.md encontrado no caminho ⁴. O próprio repositório do Codex da OpenAI usa 88 arquivos AGENTS.md separados para seu monorepo — um por serviço e pacote ⁴.

No Codex, você também pode usar AGENTS.override.md em qualquer nível para substituir (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 override: congelamentos de release, modo de incidente ou qualquer serviço com restrições de segurança que substituem os padrões do projeto inteiro.

Compatibilidade entre ferramentas

AGENTS.md é adotado por mais de 60.000 projetos ¹ e reconhecido por todas as principais ferramentas de codificação com IA. Veja como o mesmo arquivo se comporta em diferentes ecossistemas:

Se sua equipe usa várias ferramentas: Escreva AGENTS.md como a fonte canônica. Adicione arquivos específicos por ferramenta (CLAUDE.md, .cursorrules) que importem ou espelhem as seções relevantes. Não mantenha conjuntos paralelos de instruções que divergem com o tempo.

Ordem de escrita: o que adicionar primeiro

Se você está escrevendo um AGENTS.md do zero, adicione as seções nesta ordem de prioridade. Cada camada se baseia na anterior:

1. Comandos de build e teste — o agente precisa deles antes de poder fazer qualquer coisa útil
2. Definição de concluído — previne falsos positivos de “acho que terminei”
3. Regras de escalação — previne soluções destrutivas quando o agente fica travado
4. Seções organizadas por tarefa — reduz a análise de instruções irrelevantes por tarefa
5. Escopo por diretório (apenas monorepos) — mantém instruções de serviço isoladas

Pule preferências de estilo até que os quatro primeiros estejam funcionando. A maioria dos arquivos AGENTS.md falha porque começa com orientações de estilo e nunca chega aos comandos.

Testando seu AGENTS.md

Verifique se o agente realmente lê e segue 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 definitivo: Peça ao agente para explicar 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 reter na janela de contexto. Arquivos AGENTS.md longos são truncados pelas janelas de contexto — mantenha cada seção com menos de 50 linhas e coloque as instruções mais críticas no início.

FAQ

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

Mantenha cada seção com menos de 50 linhas e o arquivo total com menos de 150 linhas ¹³. O Codex impõe um limite padrão de 32 KiB (project_doc_max_bytes) ⁴. Arquivos longos são truncados pelas janelas de contexto, então coloque as instruções mais críticas no início — comandos e definições de conclusão antes de preferências de estilo.

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

Não. AGENTS.md funciona junto com CLAUDE.md, .cursor/rules e outros arquivos específicos por ferramenta. Escreva AGENTS.md como a fonte canônica e depois espelhe as seções relevantes nos arquivos específicos por ferramenta. Os padrões do AGENTS.md (orientado a comandos, com definição de conclusão) funcionam em qualquer arquivo de instrução independentemente da ferramenta.

E se o agente ignorar meu AGENTS.md?

Teste pedindo ao agente para explicar seus comandos de build. Se ele não conseguir reproduzi-los literalmente, o arquivo é muito verboso (conteúdo empurrado para fora do contexto), muito vago (o agente não consegue extrair instruções acionáveis) ou não está sendo descoberto (verifique a localização do arquivo e a documentação da ferramenta). A análise do GitHub de 2.500 repositórios descobriu que a falta de clareza — não limitações técnicas — causa a maioria das falhas ¹¹.

Principais conclusões

Para desenvolvedores individuais:

• Substitua prosa por comandos. Cada instrução deve ser verificável executando algo.
• Defina a conclusão explicitamente. “Concluído” significa códigos de saída específicos, não sensações.
• Teste seu AGENTS.md pedindo ao agente para recitá-lo. O que ele não consegue recitar, ele não vai seguir.

Para equipes:

• Use AGENTS.md como a fonte única da verdade. Espelhe para arquivos específicos por ferramenta, não mantenha cópias paralelas.
• Organize por tarefa (codificação, revisão, release), não por categoria (estilo, testes, deploy).
• Inclua regras de escalação. Sem elas, agentes bloqueados improvisam de formas que você não vai gostar.
• Defina escopo por diretório em monorepos. Regras específicas de serviço não devem poluir as instruções globais.

Referências