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.

O mesmo vale para .cursor/rules do Cursor, .github/copilot-instructions.md do GitHub Copilot e AGENTS.md do Codex CLI: o local de carregamento e as condições de aplicação variam de ferramenta para ferramenta. Um arquivo ser carregado e o modelo seguir suas instruções são questões distintas.

Em resumo, o processo tem três etapas. Primeiro, veja se as instruções estão sendo carregadas. Regras carregadas que não são seguidas devem ser reescritas como frases cujo cumprimento possa ser verificado depois. O que ainda assim precisar ser executado sempre deve ir para Hooks ou CI. A documentação oficial do Claude Code também explica que o CLAUDE.md é “contexto, não uma configuração imposta” e recomenda usar hooks quando for preciso bloquear uma ação independentemente do que o Claude decidir.

Este artigo apresenta, nesta ordem, cinco pontos a verificar, incluindo carregamento, restauração após compactação e conflitos de instruções, as etapas de diagnóstico e exemplos de regras reescritas.

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

1. Arquivos longos, em que as regras se perdem

A documentação do Claude Code recomenda manter cada arquivo CLAUDE.md com menos de 200 linhas e explica o motivo: “arquivos mais longos consomem mais contexto e reduzem o cumprimento”. As 200 linhas não são o ponto em que o carregamento é interrompido: um CLAUDE.md de até 4 MiB é carregado por inteiro (arquivos acima de 4 MiB são ignorados). O que acontece com um arquivo longo não é deixar de ser lido a partir de certo ponto, e sim ser lido e ter cada regra seguida com menos consistência.

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. Segundo a documentação oficial, uma instrução que desapareceu após a compactação foi (1) dada apenas na conversa, (2) está num CLAUDE.md de subdiretório que ainda não foi recarregado ou (3) está numa regra específica de caminhos que ainda não correspondeu a nenhum arquivo lido. Para preservar o que foi decidido na conversa, acrescente-o ao CLAUDE.md.

3. Instruções conflitantes e escopo

Se “teste antes de fazer commit” e “pule os testes desta vez” coexistirem, a escolha de qual instrução aplicar fica a critério do modelo. A documentação oficial do Claude Code explica que, quando duas regras se contradizem, o Claude pode escolher uma delas arbitrariamente. Compare periodicamente as instruções do projeto, pessoais e específicas de diretórios para eliminar contradições e, se houver exceções, escreva “quem pode autorizá-las e de que forma”. Para bloquear a própria operação, use configurações de permissão ou Hooks, não o CLAUDE.md. Para que o Claude encontre por você instruções conflitantes ou desatualizadas, use /doctor prompt-audit (como funciona e o que encontrou neste site).

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. Escreva o requisito de forma que o cumprimento possa ser verificado: “escreva no máximo três linhas” ou “ao usar a API do Slack, utilize chat.postMessage”, por exemplo (veja exemplos de reescrita na seção 3).

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.

Quando os arquivos CLAUDE.md e AGENTS.md colocados em subdiretórios são carregados (o Claude Code e o Codex diferem nisso) e como fazer a IA seguir as regras em um monorepo com verificações automáticas são explicados em detalhes no artigo sobre CLAUDE.md e AGENTS.md em subdiretórios.

As especificações do Claude Code descritas até aqui seguem a documentação oficial de memória do Claude Code (em 21 de setembro de 2026).

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:

Uma resposta como “eu li” ou “entendi” não é evidência de carregamento nem de aplicação. As evidências são a exibição de carregamento e os resultados da execução.

Quatro etapas para identificar a causa

1. Verifique o ponto de entrada. No Claude Code, veja se o CLAUDE.md e as regras relevantes aparecem em Memory files, em /context. Se não aparecerem, examine o local do arquivo e as configurações de exclusão (claudeMdExcludes). Um AGENTS.md carregado diretamente não aparece nessa lista. Com a configuração padrão, veja se aparece a linha no CLAUDE.md found; AGENTS.md loaded: …, exibida no início da sessão (um AGENTS.md importado a partir do CLAUDE.md aparece na lista).
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, essa regra não foi recarregada. Para registrar o que foi carregado e quando, use o hook InstructionsLoaded, que grava em log o carregamento do CLAUDE.md e das regras (ele não é acionado para um AGENTS.md carregado diretamente).
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 testar com uma frase secreta, escreva-a apenas no arquivo de instruções e não a inclua na pergunta.
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. Registre as configurações, a versão da ferramenta e os arquivos de destino usados no teste e repita-o quando qualquer um deles mudar.

Por exemplo, se a instrução “teste antes de fazer commit” foi carregada, mas os testes não foram executados, mudar o arquivo de lugar não resolverá. O que precisa ser corrigido é a forma como a regra está escrita (veja os exemplos de reescrita na próxima seção) e o mecanismo de verificação. Exigir verificações de CI antes do merge fornece evidências independentes 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. Reescreva as regras como frases cujo cumprimento possa ser verificado

Para uma regra carregada que não é seguida, veja primeiro se ela diz “o que conta como cumpri-la”. A documentação oficial do Claude Code também recomenda escrever instruções específicas o suficiente para serem verificadas e dá como exemplo “execute npm test antes de fazer commit” em vez de “teste suas alterações”. Dando mais um passo e descrevendo também o que fazer em caso de falha e as condições para exceções, o resultado fica assim:

Com as frases reescritas, é possível avaliar o cumprimento pelo diff, pelo histórico de comandos e pelos códigos de saída. Uma regra escrita de forma avaliável também serve diretamente como condição de verificação quando for transferida para Hooks ou CI (seção 4).

3. 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.

4. 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.” A declaração faz o agente relembrar as regras; se elas foram seguidas, veja nos resultados depois do trabalho.

5. Inclua condições de conclusã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”. Se uma etapa tiver marca de conclusão com o campo de evidências vazio, não a trate como concluída.

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
• Executar testes específicos do projeto antes de um commit e bloqueá-lo 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 a verificar, o diff e as evidências esperadas (nomes de testes e códigos de saída). Confira os apontamentos recebidos nos arquivos reais ou nos resultados dos testes e trate 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 confira os resultados ao final.

Os locais dos arquivos e as formas de invocação estão na documentação oficial de skills. Inclua na skill o procedimento e os critérios de aprovaçã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, e quais recursos as leem varia de recurso para 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 (exemplos de reescrita na seção 3).

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 também é reinserido após a compactação; portanto, uma instrução que desapareceu depois dela foi dada apenas na conversa ou está num CLAUDE.md aninhado ou numa regra específica de caminhos que ainda não foi recarregada.

• Não está sendo carregada: corrija o local do arquivo, as configurações de exclusão e as condições de carregamento do AGENTS.md
• É carregada, mas não é seguida: reescreva a regra como uma frase cujo cumprimento possa ser verificado depois
• Precisa ser executada sempre: verifique com 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, 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, com a explicação de que arquivos mais longos consomem mais contexto e reduzem o cumprimento. Passar de 200 linhas não interrompe o carregamento no meio (até 4 MiB, o arquivo é carregado por inteiro). Mantenha apenas as regras necessárias em todas as sessões e mova as usadas só com determinados arquivos para regras específicas de caminhos. Arquivos separados por meio de importações @path também são carregados na inicialização, então isso não reduz o contexto.

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. A documentação oficial também explica que arquivos longos reduzem o cumprimento. Se for acrescentar algo, acrescente condições verificáveis e exemplos concretos, e remova duplicações e contradições.

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

Reúna as regras compartilhadas num AGENTS.md como fonte oficial e deixe as configurações específicas no ponto de entrada de cada ferramenta. Codex e Cursor aceitam AGENTS.md. O Claude Code, a partir da v2.1.277, também carrega o AGENTS.md diretamente se não houver CLAUDE.md, .claude/CLAUDE.md nem CLAUDE.local.md no diretório de trabalho ou acima dele. Se houver algum deles, por padrão apenas esse arquivo é lido; basta criar um CLAUDE.local.md pessoal para que o AGENTS.md deixe de ser lido. Em projetos que também usam CLAUDE.md, escreva no CLAUDE.md a linha @AGENTS.md para importá-lo (também é possível definir Project instructions como claude-md-and-agents-md em /config para carregar os dois). O carregamento direto não funciona em sessões por provedores externos, como o Amazon Bedrock, ou com a telemetria desativada, na primeira sessão após instalar ou atualizar e em ambientes em que os hooks foram desativados, por exemplo com disableAllHooks; nesses casos, use a importação. Para saber por qual caminho o arquivo está sendo lido, use a etapa 1 da seção 2.

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

A resposta não é evidência de que o arquivo foi lido nem de que não foi. Use as etapas de diagnóstico da seção 2 para ver a exibição de carregamento e compará-la com diffs, resultados de testes e histórico de execução.