AGENTS.md ajudou o Codex a seguir as regras do projeto: 0 violações em 13 contra 5 em 13
Uma nova sessão de agente de IA não se lembra dos combinados de ontem: coloca SQL diretamente no serviço, cria uma coluna extra cancelled_at e esquece de registrar a ação no log de auditoria. Sergei Proshchaev, Tech Lead, rodou 18 sessões do Codex em um pequeno serviço em Python. Sem regras, o agente violou 5 de 13 decisões do projeto; com o arquivo AGENTS.md ou com um skill, nenhuma das 13 foi violada. Por isso, vale registrar no arquivo apenas o que o agente faria de forma diferente sem ser avisado.
Processado por IA de Habr AI; editado por Hamidun News
Você passa uma semana desenvolvendo um projeto junto com um agente de IA e combina: o SQL fica somente em db.py, os erros passam por AppError, e o cancelamento de uma assinatura altera o campo status e grava um registro no log de auditoria. A sessão é encerrada.
No dia seguinte, uma nova sessão adiciona um relatório de receita, coloca conn.execute diretamente no serviço, cria a coluna cancelled_at e esquece a auditoria. Os testes estão verdes, o relatório calcula corretamente, mas as decisões da equipe ficaram no chat de ontem.
Sergei Proshchaev, Tech Lead, verificou em 18 sessões do Codex se o arquivo AGENTS.md resolve isso. Trata-se de um arquivo de texto comum com as regras do projeto, que o agente lê no início de cada sessão.
O resultado: sem regras, o agente violou 5 de 13 decisões verificáveis; com AGENTS.md ou com um skill, ou seja, um diretório separado com instruções, nenhuma das 13 foi violada.
O que mostrou o experimento
O autor executou o Codex CLI 0.166.0 em um pequeno serviço em Python. A tarefa envolvia assinaturas com preço em rublos, cancelamento e relatório de receita. Cada sessão começava do zero, em um diretório isolado e sem histórico de conversas. Foram comparadas três variantes: sem regras, com AGENTS.md e com um skill separado. Cada variante foi executada três vezes.
Na primeira rodada, houve oito verificações. Sem regras, o agente violou duas em cada sessão: nomeou a coluna de valor monetário como price_kopecks em vez do nome adotado e colocou SQL no serviço, embora o users.py vizinho acesse o banco por meio de db.py. O restante ele deduziu sozinho pelo código: guardou o dinheiro em centavos, obteve o tempo pelo clock e lançou AppError.
Na segunda rodada, o autor acrescentou cinco decisões que contrariam os hábitos do modelo. Sem regras, em todas as três sessões o agente criou cancelled_at em vez de status, não chamou db.add_audit, embora a função existisse no projeto, e escreveu os códigos de erro no estilo antigo bad_price. São as mesmas 5 violações em 13 verificações. Com AGENTS.md e com o skill, não houve nenhuma violação. Os testes de aceitação passaram em todas as variantes, inclusive na "sem regras". Os testes comuns não capturam esse tipo de acordo, por isso foi necessário um script separado, check.py, que analisa o código com ast.
Dois indicadores o autor retirou honestamente da contagem. O UUID o agente escolheu mesmo sem regras, porque a assinatura exigia um id em forma de string. O formato dos logs não foi violado porque, simplesmente, não havia logs no novo módulo.
Como escrever as regras
Passo 1: para cada decisão, pergunte se o agente faria aquilo por conta própria. A resposta deve vir de uma sessão sem regras, não de um palpite. Passo 2: cada regra precisa de um motivo e de um sinal observável de violação, e o que é proibido deve ser nomeado explicitamente (cancelled_at, execute). Se o código antigo não cumpre a regra, escreva isso na própria regra; caso contrário, o agente tomará como modelo aquilo que vê ao lado.
Passo 3: no AGENTS.md da raiz, coloque as decisões que valem para qualquer alteração. O Codex lê o arquivo global e, depois, um arquivo por diretório, percorrendo o caminho até o diretório de trabalho. O limite total project_doc_max_bytes é de 32 KiB por padrão. As regras de um módulo específico é melhor manter no AGENTS.md do diretório desse módulo.
Passo 4: o conteúdo extenso vai para um skill, mas o AGENTS.md deve fazer referência a ele. O agente enxerga apenas o cabeçalho do skill e decide sozinho se carrega o restante. No teste da Vercel com a documentação do Next.js 16, o skill não foi acionado em 56% dos casos, e a taxa de tarefas resolvidas ficou em 53%, igual à de quando não havia documentação. Uma frase explícita no AGENTS.md elevou esse número para 79%, e um índice compacto diretamente no arquivo chegou a 100%. No experimento de Proshchaev a referência estava sempre presente, e o skill foi aberto em seis das seis sessões.
Passo 5: teste as regras em um ambiente limpo. O autor tem um AGENTS.md global com 62 KB de regras pessoais e cerca de cem skills, de modo que a variante "sem regras" não seria realmente sem regras sem isolamento. Para a verificação, HOME e CODEX_HOME apontam para um diretório temporário.
Passo 6: transforme as decisões em verificações automáticas e teste as próprias verificações em código deliberadamente quebrado.
Limitações e custo
O experimento é pequeno: um modelo, uma tarefa, três sessões por variante. A taxa de violações para outros agentes não pode ser extrapolada a partir dele. O skill não trouxe ganho mensurável em relação ao AGENTS.md; a vantagem foi apenas organizacional. O script check.py detecta apenas formas de violação previstas de antemão: SQL passado por outro helper ele não captura.
O arquivo de contexto custa dinheiro. Segundo o estudo "Evaluating AGENTS.md", da ETH Zurich, os arquivos gerados pelo modelo não aumentaram a taxa de tarefas resolvidas, mas o custo subiu 20–23%. Já os arquivos escritos por desenvolvedores elevaram as tarefas resolvidas em 2,4%, um resultado estatisticamente insignificante, com aumento de custo de até 19%. Os agentes passam a investigar e testar mais, e isso também consome tokens.
A conclusão prática: pegue as três últimas correções que você fez à mão depois do agente, escreva-as como regras com um sinal de violação e rode uma sessão em ambiente limpo. As regras que o agente viola sem o arquivo e cumpre com ele formam o seu AGENTS.md. O restante só acrescenta custo. O suporte aos formatos depende da ferramenta: o Claude Code lê o CLAUDE.md, e o Gemini CLI, por padrão, lê o GEMINI.md, então vale conferir a documentação do seu agente.
- 30 de abr. de 2026Como transformar o OpenAI Codex em um agente de IA completo para desenvolvimento real: 5 práticas
- 12 de out. de 2026T-Bank ensinou um agente de IA a escrever testes unitários de iOS com AGENTS.md e SKILL.md
- 30 de abr. de 2026Anthropic e ETH Zurich: um CLAUDE.md longo piora o trabalho do agente e aumenta os custos
- 19 de jul. de 2026Agentes com GPT-4o-mini e GPT-5.2 violam regras silenciosamente em testes do τ²-bench
Perguntas frequentes sobre a notícia
O que mostrou o experimento?
O autor executou o Codex CLI 0.166.0 em um pequeno serviço em Python. A tarefa envolvia assinaturas com preço em rublos, cancelamento e relatório de receita. Cada sessão começava do zero, em um diretório isolado e sem histórico de conversas. Foram comparadas três variantes: sem regras, com AGENTS.md e com um skill separado. Cada variante foi executada três vezes. Na primeira rodada, houve oito verificações.
Como escrever as regras?
Passo 1: para cada decisão, pergunte se o agente faria aquilo por conta própria. A resposta deve vir de uma sessão sem regras, não de um palpite. Passo 2: cada regra precisa de um motivo e de um sinal observável de violação, e o que é proibido deve ser nomeado explicitamente (cancelled_at, execute). Se o código antigo não cumpre a regra, escreva isso na própria regra; caso contrário, o agente tomará como modelo aquilo que vê ao lado.
O que se sabe sobre Limitações e custo?
O experimento é pequeno: um modelo, uma tarefa, três sessões por variante. A taxa de violações para outros agentes não pode ser extrapolada a partir dele. O skill não trouxe ganho mensurável em relação ao AGENTS.md; a vantagem foi apenas organizacional. O script check.py detecta apenas formas de violação previstas de antemão: SQL passado por outro helper ele não captura. O arquivo de contexto custa dinheiro.
Build & Ship Production AI Agents Without Boilerplate Code
Start your free 72-hour trial at Hamidun Academy (academy.hamidun.com) — interactive lessons on Claude Code & Cursor, live Tech Radar, and production agent templates.
O essencial da IA — uma vez por semana
Sete histórias que realmente importaram, escolhidas a dedo. Sem ruído nem releases.
Pronto! Verifique seu e-mail para a confirmação.