Intensivo Grátis 21–22/11Intensivo gratuito de 2 dias em Vibecoding (21–22/11 às 16:00 MSK) · Turma 3 começa 23/11Inscrever-se grátis →Turma 3 (23/11)
LançamentoAnálise · No radarHabr AI→ original

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
AGENTS.md ajudou o Codex a seguir as regras do projeto: 0 violações em 13 contra 5 em 13
Fonte: Habr AI. Colagem: Hamidun News.
Ouvir artigo
Ficha técnica e números-chave
ParâmetroDados
Fonte originalHabr AI ↗
Editor-chefe
Dado-chave #1O skill não trouxe vantagem sobre o AGENTS.md: o arquivo raiz apenas ficou mais curto
Vercelsem uma referência explícita no AGENTS.md, o skill não foi acionado em 56% dos casos
ETH Zuricharquivos escritos pelo próprio modelo encareceram as tarefas em 20–23%

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.

História

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.

ZK
Zhemal Khamidun — CPO da Alpina Digital, gerente de produto do AlpinaGPT. Cria produtos de IA desde 2019. O Hamidun News é um projeto pessoal que virou um agregador em produção com mais de 6.000 leitores.
✦ Hands-On AI Engineering · Hamidun Academy

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.

Start 72h Free Trial →Vibe-Coding Intensive
O que você acha?
Carregando comentários…