Por que agentes de IA ignoram suas regras .md — e como fazer CLAUDE.md, Cursor Rules e AGENTS.md realmente colarem

Você pergunta para o Claude Code: "Você leu o CLAUDE.md?" Ele responde animado: "Sim, li". Algumas interações depois, nenhuma das regras daquele arquivo está sendo seguida — seus comandos específicos do projeto, convenções de mensagem de commit, passos de deploy. Tudo evaporou em silêncio.

Esse não é um problema exclusivo do Claude Code. O mesmo desvio aparece no .cursor/rules do Cursor, no .github/copilot-instructions.md do GitHub Copilot e no AGENTS.md do Codex CLI depois que você usa por tempo suficiente.

Este artigo expõe as cinco causas raiz pelas quais agentes de IA ignoram seus arquivos de regra .md, depois passa por técnicas rápidas de reescrita e sistematização de longo prazo com Hooks e sub-agents, tudo com exemplos concretos.

1. Por que a IA ignora suas regras — 5 causas raiz

1. Limites estruturais da janela de contexto

Um LLM não dá atenção igual a cada token de entrada. Instruções enterradas no meio de um documento longo se perdem — o conhecido efeito "lost in the middle". Quando seu CLAUDE.md passa de cerca de 200 linhas, o que está no meio basicamente desaparece.

2. Auto-compact em sessões longas

O Claude Code tem o recurso /compact que comprime o histórico da conversa. Quando ele dispara automaticamente, instruções no nível do system prompt sobrevivem, mas os detalhes operacionais do CLAUDE.md são resumidos ou descartados por completo. Por isso, violações de regra se concentram na segunda metade de sessões longas.

3. Instruções diretas do usuário têm prioridade

Para a IA, "o que o usuário acabou de dizer" pesa mais do que "uma regra que ela leu 300 turnos atrás". No momento em que o usuário diz "manda ver" ou "pode commitar", sua regra "sempre confirme antes de commitar" no CLAUDE.md é atropelada.

4. Regras vagas ou contraditórias

Diretrizes subjetivas como "escreva com educação" ou "trate isso de forma adequada" deixam a interpretação por conta da IA, o que raramente bate com o que você queria. Reescreva como restrições verificáveis: "respostas com no máximo 3 linhas", "use chat.postMessage para a API do Slack", e assim por diante.

5. Arquivos de regra inchados e espalhados

CLAUDE.md mais SPEC.md mais README.md mais um monte de outros .md — quando estão espalhados e cada um é longo, a IA não lê todos com o mesmo peso. Quando a mesma regra aparece em vários arquivos com diferenças sutis, a IA tende a escolher a versão que parece mais segura.

2. Como diagnosticar se suas regras estão realmente sendo seguidas

Comece checando o estado atual. Dispare as perguntas abaixo para a IA e observe a resposta:

A IA dizer "li" ou "entendi" não significa nada. Se ela realmente aplica as regras é outra história — julgue pelo comportamento após a execução, não pelo que ela afirma.

3. Correções rápidas que você implanta em 5 minutos

1. Comprima seu arquivo de regras para menos de 150 linhas

Na prática, o Claude Code segue de forma confiável um CLAUDE.md de aproximadamente 100 a 150 linhas. Acima disso, divida:

• Regras inegociáveis (10 a 20 linhas) — topo do CLAUDE.md
• Specs específicos de serviço — separe em SPEC-xxx.md
• Histórico e contexto — mova para um diretório docs/

Mantenha no CLAUDE.md apenas "coisas catastróficas se forem esquecidas". O detalhe pode viver em arquivos linkados.

2. Adicione marcadores explícitos de prioridade

Use palavras-chave de prioridade barulhentas para forçar a atenção da IA:

• CRITICAL — violação causa um incidente em produção
• MUST — sempre seguir
• SHOULD — seguir por padrão
• NICE TO HAVE — só se sobrar espaço

Uma linha como "CRITICAL: queries destrutivas no banco de produção exigem aprovação explícita" é muito mais difícil de passar despercebida, mesmo enterrada num arquivo longo.

3. Reforce no próprio chat

No início de uma sessão, jogue um one-liner como "Antes de começar, declare as três regras mais importantes do CLAUDE.md". Isso traz essas regras para o contexto recente e faz com que grudem pelo resto da sessão.

4. Registre operações perigosas no TodoWrite

Use a ferramenta TodoWrite de um agente de IA (ou o equivalente de tracking de tarefas da sua ferramenta) para incluir "checagem de regra" como passo explícito. Visibilidade torna o "esqueci" muito mais raro.

4. Sistematização de longo prazo — Hooks, sub-agents, slash commands

Regras baseadas em prosa só vão até certo ponto. Migrar de "pedir para a IA seguir regras" para "fazer o ambiente forçar o cumprimento" é muito mais confiável.

1. Force mecanicamente com Claude Code Hooks

O recurso Hooks do Claude Code permite rodar scripts arbitrários antes ou depois de chamadas de ferramentas específicas. Você pode montar um setup onde o sistema barra a IA mesmo quando ela própria esquece a regra.

Por exemplo, com um hook PreToolUse:

• Detectar comandos perigosos (rm -rf, git push --force) antes do Bash rodar e bloqueá-los
• Verificar permissões de arquivo ou estado de lock antes do Edit tocar no alvo
• Rodar testes específicos do projeto antes do commit e abortar em caso de falha

Pedir gentilmente em prosa não tem chance contra cumprimento mecânico via Hooks.

2. Separe responsabilidades com sub-agents

Use os recursos de sub-agent do Claude Agent SDK ou do Cursor para construir um "agente de auditoria de regras" dedicado. Um fluxo em duas etapas onde o agente principal escreve código e o agente de auditoria revisa pega violações de regra mesmo quando o principal esquece.

O sub-agent precisa só de um prompt curto focado em auditoria, então sua taxa de reconhecimento das regras se mantém alta. Esse é o pulo do gato.

3. Codifique rotinas como slash commands customizados

Workflows repetidos como "rode estas 3 checagens antes de cada commit" são caso ideal para um slash command (/precommit, etc.). Quando o usuário digita /precommit, a IA executa uma sequência fixa. Sem precisar reler o arquivo de regras toda vez.

4. Detecte violações com scripts automatizados

Rode detecção baseada em grep para padrões proibidos no CI ou como pre-commit hook. Exemplos:

• console.log esquecido em código de produção
• Chaves de API hardcoded
• Cabeçalhos de copyright ausentes

Não dependa da IA — deixe as máquinas encontrarem. Essa é sua última linha de defesa.

5. Boas práticas por ferramenta

A regra universal é "curto, específico, priorizado". Nomes de arquivo e localizações variam por ferramenta, mas os princípios de redação são os mesmos.

6. Três anti-padrões no design de regras

1. "Por favor, siga as boas práticas."

Boas práticas de quem? A IA cai na média dos dados de treinamento, ou seja, você recebe o menor denominador comum. Peculiaridades específicas do projeto nunca entram. Escreva do's e don'ts concretos.

2. A mesma regra duplicada em vários arquivos

Se suas "convenções de commit" vivem em CLAUDE.md, SPEC.md e README.md, as três cópias vão divergir sutilmente e confundir a IA. Escolha uma fonte única da verdade e linke para ela de todos os outros lugares.

3. Carimbar "ABSOLUTAMENTE OBRIGATÓRIO" em tudo

Se tudo é "absoluto", a IA perde a capacidade de priorizar. Reserve "CRITICAL" para o que é genuinamente catastrófico; deixe o resto em prosa normal. Ênfase sofre inflação — use com parcimônia.

Resumo

Quando agentes de IA ignoram suas regras .md, quase sempre é por causa de restrições estruturais e problemas no design das regras, não preguiça da IA. A maioria dos casos se resolve com correções rápidas — comprimir para menos de 150 linhas, adicionar marcadores de prioridade, reforçar no chat. Para as regras realmente críticas que sobrarem, parta para o cumprimento mecânico: Hooks, sub-agents, slash commands e scripts de detecção automatizados.

"Se as regras não estão sendo seguidas, construa um sistema que force" — o novo senso comum na operação de agentes de IA.

FAQ

Q1. Qual o tamanho ideal para o CLAUDE.md?

Na prática, 100 a 150 linhas. Passou de 200, divida em SPEC-xxx.md ou similar. Colocar um resumo "top 5 regras críticas" logo no topo é um bom seguro contra esquecimento.

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

Para setups novos, .cursor/rules/*.mdc. Uma regra por arquivo, com glob patterns para definir onde cada regra se aplica. O legado .cursorrules de arquivo único costuma inchar com o tempo.

Q3. Regras mais longas deixam a IA mais rigorosa?

O contrário. Quanto mais longo o arquivo, mais o meio se dilui. Regras curtas e essenciais colocadas em destaque (no topo) são seguidas com taxa maior.

Q4. E se eu uso várias ferramentas de IA (Claude Code + Cursor) no mesmo projeto?

A resposta pragmática é colocar o mesmo resumo no arquivo de config de cada ferramenta e centralizar os detalhes em um SPEC.md compartilhado. Não existe ainda solução totalmente unificada (em maio de 2026).

Q5. Quando a IA diz "li", ela realmente não está lendo?

A afirmação "li" e o comportamento real em runtime são coisas diferentes. Use os métodos de diagnóstico da seção 2 para verificar o reconhecimento no nível de execução.