Por que o teste é importante

Assistentes de código baseados em IA frequentemente permitem que as equipes coloquem um arquivo de "regras" no repositório e esperam que o modelo obedeça às suas diretrizes em cada solicitação. Na prática, o modelo pode nunca ver o arquivo, ou pode vê-lo, mas ignorar o conteúdo. Um experimento recente com o Claude Code mostrou ambos os problemas. A ferramenta ignorou silenciosamente um arquivo AGENTS.md de 72 KB; quando o mesmo arquivo foi renomeado para CLAUDE.md, o assistente o carregou e aumentou a contagem de tokens para cada solicitação. Esse orçamento extra de tokens inflaciona a latência, o custo e pode fazer com que uma solicitação ultrapasse o limite do modelo.

Desenvolvedores que assumem que "o arquivo existe" é o mesmo que "o modelo segue as regras" correm o risco de ineficiências ocultas e resultados imprevisíveis. O teste de três etapas exige evidências concretas em cada estágio: configuração, carregamento e utilidade.

As três perguntas a serem feitas

  1. Configurado – O arquivo está no local onde o assistente o procura? Diferentes ferramentas utilizam caminhos ou convenções de nomes de arquivos hard-coded; uma incompatibilidade significa que o arquivo nunca entra no pipeline do prompt.
  2. Carregado – O assistente apresenta alguma prova de que recebeu o arquivo? Um hash pode confirmar a identidade do arquivo no disco, mas apenas um rastreamento de entrega (por exemplo, uma linha de log ou contagem de tokens) prova que o modelo realmente o observou.
  3. Útil – A presença do arquivo melhora o resultado da tarefa? Um arquivo carregado que adiciona tokens, mas deixa o resultado inalterado, é uma perda líquida.

Executando o teste

O procedimento é deliberadamente minimalista para que possa ser repetido em qualquer plataforma.

  1. Crie uma regra visível – Escreva uma instrução simples e observável. Por exemplo: “Liste exatamente dois arquivos antes de editar”. O efeito da regra pode ser verificado na resposta do assistente.

  2. Verifique a versão da ferramenta e o modelo – Abra uma nova sessão, anote a string de versão e o identificador do modelo. Diferentes versões podem alterar o nome do arquivo que reconhecem.

  3. Execute duas execuções Execução A: Use um nome de arquivo que a ferramenta não reconheça (ex: AGENTS.md). Execução B: Use o nome de arquivo nativo da ferramenta (ex: CLAUDE.md).

    Registre:

    • O hash de origem do arquivo (para provar que o conteúdo no disco não mudou).
    • O caminho exato utilizado.
    • Qualquer evidência que o assistente registrou sobre o carregamento do arquivo (aumento na contagem de tokens, mensagem explícita “loaded X.md”, etc.).
    • A contagem de tokens para cada solicitação.
    • O resultado da tarefa (o assistente listou exatamente dois arquivos?).

Se a Execução B mostrar que a regra está sendo obedecida e a contagem de tokens aumentar na quantidade esperada, o arquivo foi carregado e é útil. Se a regra for ignorada, apesar do aumento de tokens, o arquivo está sendo lido, mas o processamento do prompt do modelo descarta a instrução. Nesse caso, adicionar mais texto ao arquivo não ajudará; em vez disso, mova a regra para um gate de política hard-coded ou para um ambiente de teste (test harness).

O que os dados revelam

O caso do Claude Code demonstrou uma lacuna gritante entre configuração e carregamento. O arquivo de 72 KB existia, tinha o hash correto e estava sincronizado com o repositório, mas o assistente nunca o mencionou. Renomear o arquivo para o nativo CLAUDE.md acionou o carregamento, mas também adicionou um overhead substancial de tokens. Cada token extra consome ciclos de computação e pode fazer com que a solicitação ultrapasse os limites de taxa (rate limits).

O teste de três etapas traz à tona esses custos ocultos antes que eles se tornem bloqueadores de produção. Ao capturar o delta de tokens, as equipes podem decidir se o benefício da regra compensa seu custo.

Lição principal

Nunca assuma que um arquivo de regras está funcionando apenas porque ele está no repositório. Use o teste de três etapas — configurar, carregar, provar utilidade — para transformar essa suposição em evidência mensurável. Quando a prova mostrar que um arquivo é apenas um consumidor de tokens, mova a lógica para fora do prompt e para um gate determinístico. O resultado é um fluxo de trabalho de codificação com IA mais enxuto, rápido e previsível.