Por que a IA ignora regras: verificando CLAUDE.md, Cursor Rules e AGENTS.md

Você pergunta ao Claude Code se ele leu CLAUDE.md. Ele diz que sim, mas ainda pula os testes que você especificou. Quando isso acontecer, diferencie instruções que nunca chegaram ao modelo de instruções que chegaram, mas não foram seguidas. A resposta “eu li” não comprova nenhuma das duas situações.

Para .cursor/rules do Cursor, .github/copilot-instructions.md do GitHub Copilot e AGENTS.md do Codex CLI, também é preciso verificar de onde os arquivos são carregados e quando se aplicam. Como uma ferramenta carrega instruções e se o modelo as segue são questões distintas.

Este artigo apresenta cinco pontos a verificar, incluindo carregamento, restauração após compactação e conflitos de instruções, com uma sequência de diagnóstico e melhorias práticas. Encurtar o texto, por si só, não garante o cumprimento. Transfira condições verificáveis automaticamente para Hooks ou CI e deixe as questões que exigem julgamento humano para a revisão.

1. Por que a IA ignora regras: cinco pontos a verificar

1. Confundir recomendações de tamanho com limites de carregamento

Instruções longas consomem contexto e dificultam encontrar condições importantes. A documentação do Claude Code recomenda manter cada arquivo CLAUDE.md com menos de 200 linhas, mas isso não significa que o carregamento pare na linha 200. Diferencie um limite de carregamento do cumprimento das instruções carregadas. A documentação não estabelece fronteiras como “150 linhas garantem o cumprimento” ou “o meio desaparece acima de 200 linhas”.

2. Auto-compact em sessões longas

O comando /compact do Claude Code compacta a conversa, mas o CLAUDE.md da raiz do projeto é relido do disco e reinserido no contexto após a compactação. Já os arquivos CLAUDE.md de subdiretórios e as regras específicas de caminhos são recarregados quando os arquivos correspondentes são lidos. Diferencie decisões tomadas apenas na conversa, instruções de subdiretórios ainda não recarregadas e instruções carregadas que não foram seguidas.

3. Instruções conflitantes e escopo

Se “teste antes de fazer commit” e “pule os testes desta vez” coexistirem, o agente precisa determinar qual instrução se aplica. A cronologia, sozinha, não explica a prioridade: uma instrução mais recente não tem necessariamente prioridade maior. Compare instruções do projeto, pessoais e específicas de diretórios, e defina quem pode autorizar exceções. Escrever uma proibição em CLAUDE.md não remove, por si só, a permissão para executar a operação.

4. Regras vagas ou contraditórias

Com instruções subjetivas ou abstratas, como “escreva com educação” ou “trate isso de forma adequada”, a IA cria sua própria interpretação, que pode divergir das suas expectativas. Torne o requisito verificável: “escreva no máximo três linhas” ou “ao usar a API do Slack, utilize chat.postMessage”, por exemplo.

5. Arquivos de regras extensos ou dispersos

Um link comum de CLAUDE.md para SPEC.md não carrega necessariamente todo o arquivo vinculado na inicialização. O Claude Code expande importações @path na inicialização, mas o conteúdo também consome contexto. Separar arquivos para organizar é diferente de carregá-los somente quando necessário. Se regras duplicadas divergirem, esclareça qual é a fonte oficial e qual o escopo de cada uma.

Essas distinções seguem a documentação oficial de memória do Claude Code, conferida no original em 21 de setembro de 2026. Leia as recomendações de tamanho separadamente da explicação sobre o que retorna após a compactação para evitar um diagnóstico incorreto.

2. Como verificar se as regras estão sendo seguidas

Comece verificando a situação atual. Faça estas perguntas à IA e examine as respostas:

Mesmo que a IA diga “eu li” ou “entendi”, aplicar as instruções é outra questão. Verifique tanto as evidências de carregamento quanto os resultados da execução.

Quatro etapas para identificar a causa

1. Verifique o ponto de entrada. No Claude Code, consulte Memory files em /context para verificar o carregamento de CLAUDE.md e das regras. Confirme também se o arquivo está no diretório relevante e não foi excluído pelas configurações. O carregamento direto de AGENTS.md é uma exceção que pode não aparecer nessa lista; portanto, sua ausência ali não prova que o arquivo não foi lido.
2. Acione as condições da regra. Para regras específicas de caminhos, peça ao agente que leia um arquivo correspondente. Se ele ainda não leu esse arquivo após a compactação, as regras talvez não tenham sido recarregadas. Registre as instruções de inicialização separadamente daquelas carregadas para tarefas específicas.
3. Teste com uma tarefa pequena e inofensiva. Peça ao agente que edite uma amostra descartável sob regras como “informe o arquivo de destino antes de alterá-lo” e “depois, informe o comando de teste e seu código de saída”. Não use exclusão de dados de produção nem publicação como teste. Se você incluir uma frase secreta de teste na própria pergunta, o agente poderá responder sem ler o arquivo de instruções; isso não testa o carregamento.
4. Verifique o resultado de forma independente. Procure alterações inesperadas no diff, confirme se os testes relatados realmente foram executados e avalie se a quantidade de itens verificados foi suficiente. Um teste bem-sucedido não garante todas as operações futuras. Registre as configurações alteradas, a versão da ferramenta e os arquivos de destino, e repita a verificação quando as condições mudarem.

Por exemplo, se o agente carregou “teste antes de fazer commit”, mas não executou os testes, apenas mover o arquivo não resolverá a causa. Especifique quais testes executar e não marque a etapa de commit como concluída sem os resultados. Exigir verificações de CI antes do merge também fornece evidências além do relato da própria IA.

Se o CLAUDE.md relevante não aparecer na exibição de carregamento, corrija o local de inicialização e as configurações antes de dar mais ênfase ao texto. Reveja a precisão das instruções e o processo de verificação se as violações persistirem após confirmar o carregamento. Essa sequência evita atribuir toda falha a “a IA esqueceu”.

3. Ajustes rápidos para testar em cinco minutos

1. Separe regras sempre necessárias de detalhes lidos sob demanda

Use a recomendação oficial do Claude Code de menos de 200 linhas como ponto de partida, mas reduza duplicações e explicações desnecessárias em vez de perseguir um número de linhas. Por exemplo:

• Regras essenciais (10–20 linhas) → início de CLAUDE.md
• Especificações detalhadas dos serviços → arquivos SPEC-xxx.md separados
• Histórico e contexto → diretório docs/

Após mover detalhes para outro arquivo, indique no arquivo de entrada o que ler antes de cada tipo de tarefa. Se você importar tudo o que é necessário em todas as sessões, separar os arquivos não reduzirá o contexto inicial. Use regras específicas de caminhos ou skills quando quiser carregar instruções condicionais apenas conforme a necessidade.

2. Adicione marcadores de prioridade

Rótulos de importância ajudam pessoas e IA a entender a intenção. Os rótulos, por si só, não impõem a execução. Por exemplo, defina-os assim:

• CRITICAL: uma violação pode causar um incidente em produção
• MUST: sempre obrigatório
• SHOULD: esperado normalmente
• NICE TO HAVE: opcional quando houver tempo

“CRITICAL: consultas destrutivas ao banco de produção exigem aprovação prévia” define a operação e a condição que exige aprovação. Bloquear efetivamente operações não autorizadas também requer configurações de permissão ou verificações antes da execução.

3. Reforce as regras na conversa

No início de uma sessão, acrescente “Informe as três regras mais importantes antes de começar o trabalho.” Isso cria uma oportunidade de verificar o entendimento, mas não garante que os testes sejam executados. Verifique os resultados depois também.

4. Inclua condições de verificação no plano

Inclua “verificar as regras” no acompanhamento de tarefas do seu agente de IA e torne visíveis as condições de conclusão de cada etapa. Peça o comando, o código de saída e o escopo não testado, em vez de apenas “testado”. Uma marca de conclusão sem evidências ainda deixa o trabalho sem verificação.

4. Proteções de longo prazo: Hooks, revisões e skills

Transforme condições avaliáveis em scripts e controle as permissões de operação nas configurações. Hooks, CI, revisão por IA e skills têm finalidades diferentes. Chamar tudo isso de “aplicação automática” oculta o que cada mecanismo deixa de verificar.

1. Imponha verificações com Claude Code Hooks

O recurso Hooks do Claude Code pode executar scripts antes ou depois de chamadas específicas de ferramentas. Ele permite criar um mecanismo em que o sistema interrompe uma operação mesmo que a IA esqueça a regra.

Por exemplo, um hook PreToolUse pode:

• Detectar comandos perigosos (rm -rf, git push --force) antes da execução da ferramenta Bash e bloqueá-los
• Verificar as permissões ou o bloqueio do arquivo de destino antes da execução da ferramenta Edit
• Execute testes específicos do projeto antes de um commit e bloqueie-o se falharem

Quando um hook PreToolUse precisar bloquear uma operação, faça-o retornar o código de saída 2 ou o JSON de negação adequado. Se um teste falhar e retornar 1 apenas com saída de texto comum, isso será um erro não bloqueante e a operação continuará. PostToolUse é executado depois, portanto não é um mecanismo para desfazer uma operação já concluída.

Um hook só pode bloquear aquilo que seu script avalia no evento configurado. Monitorar apenas Edit não cobre gravações feitas pelo shell. A simples busca por strings perigosas também não é abrangente. Combine hooks com permissões, sandbox e CI, e teste tanto entradas que devem passar quanto entradas que devem ser bloqueadas.

2. Separe responsabilidades com subagentes

Use os recursos de subagentes do Claude Agent SDK ou do Cursor para criar um agente dedicado à auditoria de regras. Pedir a um agente auditor que revise o código escrito pelo agente principal pode revelar omissões sob outra perspectiva. Porém, ambos ainda podem cometer o mesmo erro ou deixar passar o mesmo problema.

Forneça ao revisor as regras relevantes, o diff e as evidências esperadas. Um prompt curto não garante uma alta taxa de reconhecimento das regras. Confira cada apontamento nos arquivos reais ou nos resultados dos testes e mantenha como não verificadas as áreas fora do escopo do revisor.

3. Acione procedimentos repetíveis por meio de skills

No Claude Code, você pode colocar um procedimento repetível em .claude/skills/precommit/SKILL.md e acioná-lo como seu próprio /precommit. Esse é um exemplo que você cria, não um comando nativo. Os arquivos no diretório antigo .claude/commands/ continuam funcionando, mas a documentação atual os incorpora às skills. Acionar um procedimento é diferente de passar em todas as verificações, portanto examine os resultados ao final.

Consulte a documentação oficial de skills para os locais dos arquivos e as formas de invocação. Inclua na skill tanto o procedimento quanto suas condições de verificação e peça evidências de que as etapas foram executadas.

4. Detecte violações com scripts automatizados

Use grep na CI ou em um hook de pré-commit para detectar padrões proibidos. Alguns exemplos:

• console.log deixado no código de produção
• Chaves de API escritas diretamente no código
• Ausência de comentários de direitos autorais no início dos arquivos

Scripts não verificam regras que não implementam nem arquivos fora de seu escopo. Teste exemplos válidos, violações e falhas de obtenção de dados, e mostre quantos itens foram verificados ou ignorados. Por exemplo, se dois de dez arquivos não puderem ser lidos, a aprovação dos outros oito não significa “todos os arquivos passaram”.

5. Boas práticas por ferramenta

Consulte a documentação de regras do Cursor, as instruções personalizadas do GitHub Copilot e o guia de AGENTS.md da OpenAI para as condições específicas de cada ferramenta. As instruções do Copilot específicas de caminhos usam *.instructions.md; verifique o suporte em cada recurso. O limite de 32 KiB do Codex é um limite padrão combinado em bytes, não em caracteres ou linhas.

O princípio comum é “concisão, especificidade e prioridades claras”. Os nomes e locais dos arquivos variam por ferramenta, mas os princípios de escrita permanecem os mesmos.

6. Três erros no projeto das regras

1. “Siga as boas práticas”

O pedido, sozinho, não define “boas práticas”. Especifique os métodos usados no projeto e como verificá-los. Para “teste de forma adequada”, indique os comandos de teste obrigatórios e a etapa do fluxo que deve parar se eles falharem.

2. Duplicar a mesma regra em vários arquivos

Se as mesmas convenções de commit aparecem em CLAUDE.md, SPEC.md e README.md, atualizações podem deixar as três cópias inconsistentes. Escolha uma única fonte oficial e crie links para ela nos demais arquivos.

3. Escrever “absolutamente obrigatório” em todo lugar

Dar a mesma ênfase a todas as condições dificulta comunicar prioridades. Reserve “CRITICAL” para condições com consequências realmente graves e use linguagem comum nas demais. Lembre-se de que a ênfase perde seu valor quando usada em excesso.

Resumo

Quando as regras não forem seguidas, investigue nesta ordem: condições de carregamento → escopo → instruções conflitantes → resultados da execução. O CLAUDE.md da raiz é reinserido após a compactação, portanto não atribua o problema apenas a ela. Texto conciso, ênfase e revisão por IA oferecem apoio. Coloque condições testáveis de forma confiável em Hooks ou CI e defina as operações permitidas nas configurações de permissão.

A comprovação da conclusão vem dos resultados de execução e dos artefatos que cobrem o escopo necessário, não da resposta “eu li”.

Perguntas frequentes

P1. Qual é o tamanho ideal de CLAUDE.md?

A orientação oficial é menos de 200 linhas por arquivo. Isso não é um limite de carregamento nem uma garantia de cumprimento. Mantenha as regras necessárias em todas as sessões e separe os detalhes, com condições explícitas para sua leitura. Importar todos esses detalhes de volta não reduz o contexto inicial.

P2. Devo usar .cursorrules ou .cursor/rules/*.mdc do Cursor?

Para uma configuração nova, use .cursor/rules/*.mdc. Mantenha uma regra por arquivo, com padrões glob para definir onde ela se aplica. O antigo .cursorrules é um único arquivo que pode ficar difícil de gerenciar.

P3. Regras mais longas tornam a aplicação mais rigorosa?

O tamanho, por si só, não torna as regras mais rigorosas. Adicionar condições ou exemplos necessários pode ajudar, mas evite criar duplicações ou contradições. Verifique o que é carregado e quais condições podem ser realmente verificadas.

P4. E se eu usar várias ferramentas de IA, como Claude Code e Cursor, no mesmo projeto?

Mantenha uma única fonte oficial para regras compartilhadas, com pontos de entrada e configurações próprios para cada ferramenta. Codex e Cursor aceitam AGENTS.md. No Claude Code, outra opção é importar @AGENTS.md a partir de um CLAUDE.md que seja carregado. Porém, o escopo de descoberta de arquivos e as configurações de exclusão diferem. Colocar um arquivo compartilhado no projeto não comprova que todas as ferramentas o receberam.

P5. Se a IA diz “eu li”, o arquivo pode não ter sido lido?

A resposta, sozinha, não prova que o arquivo deixou de ser lido nem comprova que foi lido. Use as etapas de diagnóstico deste artigo para verificar a exibição de carregamento e compará-la com diffs, resultados de testes e histórico de execução.