Por que agentes de código ignoram suas instruções
A regra diz para parar, mas o agente continua. Entenda contexto, conflito e compactação, e faça um diagnóstico antes de reescrever o arquivo de instruções.
Por que os agentes de programação ignoram as suas instruções
Os agentes de programação ignoram as suas instruções por quatro motivos, e nenhum deles é o facto de ter sido demasiado cordial. A regra nunca esteve na janela de contexto. A regra era demasiado vaga para permitir verificar uma ação. Algo no restante contexto contradizia-a, normalmente o código que o agente tinha acabado de ler. Ou a regra continua carregada, mas ficou muito atrás do turno atual, e o agente está a trabalhar com base no que está mais próximo.
Cada causa tem a sua própria correção, por isso o primeiro trabalho é distingui-las. Usar letras maiúsculas e a palavra IMPORTANT não é um diagnóstico. Os mecanismos abaixo usam Claude Code como exemplo prático, porque o seu comportamento de carregamento e compactação está documentado em detalhe em outubro de 2026. As outras ferramentas diferem nos detalhes, mas comportam-se da mesma forma em termos gerais.
Primeiro, dois termos. A janela de contexto é o bloco de texto que o modelo vê num determinado turno: o prompt do sistema, os ficheiros de instruções, a conversa e todos os ficheiros que o agente leu. O harness é o programa que envolve o modelo, ou seja, o componente que lê os ficheiros do disco e monta esse bloco. Quase todas as queixas neste artigo são, na realidade, queixas sobre o harness, não sobre o modelo.
O seu ficheiro de instruções é uma mensagem, não uma definição
Um ficheiro de instruções não é configuração. Nada no runtime lê CLAUDE.md e aplica essa regra. O harness lê o ficheiro do disco e cola o texto na conversa. No Claude Code, esse conteúdo é enviado como uma mensagem do utilizador colocada depois do system prompt. Isto significa que o modelo vê as suas regras da mesma forma que vê qualquer outro texto introduzido por si.
Isto tem uma consequência desconfortável. As suas regras competem com todas as outras partes do texto apresentado, em condições de igualdade. Uma regra é uma afirmação. O ficheiro que o agente acabou de abrir é evidência. Quando os dois entram em conflito, a evidência muitas vezes prevalece. Não é gerado nenhum erro, porque, do ponto de vista do modelo, nada correu mal.
A documentação oficial afirma isto de forma clara: os ficheiros de instruções são tratados como contexto, não como configuração aplicada. Para bloquear uma ação independentemente da decisão do modelo, precisa de um hook, não de uma frase. Guarde esta ideia. A maioria das correções no final deste artigo aplica-a a um caso específico.
Quais ficheiros de instruções são carregados e quando
O Claude Code percorre a árvore de diretórios para cima, a partir do diretório onde o iniciou. Todos os ficheiros CLAUDE.md e CLAUDE.local.md, desde a raiz do sistema de ficheiros até ao diretório de trabalho, são carregados integralmente no arranque. São concatenados nessa ordem. Assim, o ficheiro mais próximo do diretório onde iniciou o Claude Code é lido por último. Dentro do mesmo diretório, o ficheiro .local é acrescentado depois do ficheiro principal.
Os ficheiros em subdiretórios abaixo do diretório de trabalho comportam-se de forma diferente. Não são carregados no arranque. São carregados quando o agente lê um ficheiro nesse diretório. O mesmo se aplica às regras associadas a caminhos em .claude/rules/ que tenham um campo de frontmatter paths:: entram no contexto quando é lido um ficheiro correspondente, e não em cada turno. Desde a v2.1.309, os ficheiros carregados desta forma também têm um limite de tamanho por ficheiro (40,000 caracteres numa janela de contexto de 200K). O agente recebe apenas o início de um ficheiro maior, pelo que as regras próximas do fim de um ficheiro aninhado grande podem nunca chegar ao contexto.
Esta diferença explica uma grande parte das falhas reportadas. Coloca uma regra em packages/api/CLAUDE.md, faz uma pergunta sobre a API e o agente responde sem abrir um ficheiro em packages/api/. A regra não foi ignorada. Nunca esteve presente. Se o repositório dividir as orientações por ficheiros de instruções por pacote num monorepo, esta é a primeira coisa a verificar, sempre.
Existe ainda outro problema de carregamento que afeta os repositórios que adotaram AGENTS.md. Desde a v2.1.277, o Claude Code lê AGENTS.md como instruções do projeto por predefinição, mas apenas quando não existe CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md no diretório de trabalho nem em qualquer diretório acima dele (o seu ~/.claude/CLAUDE.md pessoal não conta). Adicione qualquer um desses ficheiros, mesmo um CLAUDE.local.md para notas pessoais, e o Claude Code passa a ler os seus ficheiros CLAUDE.md e deixa completamente de carregar AGENTS.md. Para carregar ambos, defina Project instructions como claude-md-and-agents-md em /config. Em versões anteriores à v2.1.277, ou quando pretende manter um CLAUDE.md, a solução é um CLAUDE.md cuja primeira linha seja @AGENTS.md. Essa linha importa o ficheiro no arranque; pode colocar quaisquer notas específicas do Claude abaixo dela. Uma ligação simbólica também funciona quando não tem conteúdo adicional para acrescentar. Decidir o que deve pertencer a esse ficheiro é uma questão separada, abordada em separar as instruções do agente da documentação para humanos.
Confirme que o ficheiro foi carregado antes de o reescrever
Não altere o texto até ter provas de que o agente consegue ver o ficheiro. Há duas verificações, e a mais simples vem primeiro.
Execute /context dentro da sessão. O comando mostra a janela atual organizada por categoria, e a lista Memory files apresenta o nome de todos os ficheiros de instruções carregados no arranque. Se um ficheiro não aparece nessa lista, não foi carregado no arranque. Por isso, nada do que escrever dentro dele terá efeito até que algo o carregue. Um ficheiro aninhado num subdiretório nunca aparece nessa lista, porque é carregado a pedido. Quando isso acontece, uma linha Loaded com o respetivo caminho aparece no terminal. /memory apresenta as localizações dos ficheiros e abre-os para edição, incluindo os que ainda não existem.
Para obter uma confirmação mais detalhada, registe os carregamentos. O evento de hook InstructionsLoaded é acionado sempre que um CLAUDE.md ou um ficheiro de regras entra no contexto. O matcher indica por que motivo o carregamento ocorreu: session_start, nested_traversal, path_glob_match, include ou compact. Coloque isto em .claude/settings.json:
{
"hooks": {
"InstructionsLoaded": [
{
"matcher": "nested_traversal",
"hooks": [
{
"type": "command",
"command": "cat >> /tmp/instructions-loaded.log"
}
]
}
]
}
}O hook recebe os dados como JSON na entrada padrão, por isso cat acrescenta o registo completo. Monitorize-o com tail -f /tmp/instructions-loaded.log enquanto trabalha. O estado de saída deste evento é ignorado. O hook pode apenas observar, nunca bloquear. Se o seu ficheiro aninhado nunca aparecer nesse log durante uma sessão em que esperava que fosse carregado, pare de reescrever o texto. O problema está na localização. Há uma exceção: um AGENTS.md que o Claude Code lê diretamente não aciona este evento. Nesse caso, procure o caminho em /memory. Um AGENTS.md importado de um CLAUDE.md aciona o evento normalmente.
O que uma sessão longa faz às suas regras
Aplicam-se aqui dois efeitos distintos, e cada um exige uma resposta diferente.
Distância. Até ocorrer uma compactação, uma regra indicada no turno 1 continua na janela no turno 90, mas agora compete com 90 turnos de texto mais recente e mais específico para o que está a fazer neste momento. Depois de ocorrer uma compactação, uma regra que escreveu apenas no chat pode já nem estar na janela: a documentação do Claude Code alerta que as instruções do início da conversa podem perder-se, que é o segundo efeito descrito abaixo. Não pode eliminar a distância através de configuração, mas pode medi-la. Execute a mesma tarefa numa sessão nova. Se a regra for respeitada nessa sessão e falhar já numa sessão longa, a causa é a distância ou a compactação.
Compactação. Quando a janela fica cheia, o harness resume a conversa até esse momento e continua a partir desse resumo. O que sobrevive é o que o resumidor considerou importante, o que não é necessariamente o mesmo que considera importante. O Claude Code documenta o resultado para cada mecanismo, e as diferenças são grandes. O diretório raiz do projeto CLAUDE.md e as regras sem escopo são reinjetados a partir do disco depois de uma compactação. A memória automática é reinjetada a partir do disco. As regras com frontmatter paths: perdem-se até um ficheiro correspondente ser lido novamente. Os ficheiros CLAUDE.md aninhados em subdiretórios perdem-se até ser lido novamente um ficheiro desse subdiretório.
Ordene as suas instruções de acordo com essa tabela e a ordem de fragilidade torna-se evidente. Uma regra que escreveu apenas no chat é o elemento mais frágil da sessão: só persiste se o resumo tiver mantido essa informação. Uma regra em packages/api/CLAUDE.md vem a seguir, porque foi carregada uma vez, eliminada pelo resumo e só regressa na leitura seguinte nesse diretório. Uma regra no ficheiro do diretório raiz do projeto é a mais duradoura, porque é lida novamente a partir do disco todas as vezes.
Por isso, se uma instrução tiver de ser respeitada durante toda a sessão, coloque-a no ficheiro do diretório raiz do projeto sem frontmatter paths:. Todas as outras opções são compromissos que deve escolher de forma consciente. Gerir o que permanece na janela de contexto aborda /compact com um argumento de foco e /clear entre tarefas não relacionadas. Ambos alteram a frequência com que o resumidor pode decidir quais eram as suas regras.
Por que o código ao redor prevalece sobre a regra
Esta é a falha que as pessoas descrevem com mais frequência e diagnosticam com menos frequência. O seu ficheiro diz que o acesso à base de dados passa pela camada de repositório. O agente escreve um handler que chama diretamente o ORM (object relational mapper). A regra não foi ignorada por uma questão de estilo. As evidências tiveram mais peso.
Uma regra descreve uma preferência. O código demonstra uma preferência. Quando o agente abre três ficheiros do módulo que está prestes a editar e os três chamam diretamente o ORM, o contexto contém uma frase abstrata de um lado e três exemplos concretos, recentes e correspondentes à tarefa do outro. Copiar o padrão local é normalmente o comportamento correto. Neste caso, isso só está errado porque sabe algo que o contexto não sabe: esses ficheiros são código legado.
Por isso, escreva essa informação na regra. As regras que identificam as próprias evidências em contrário resistem ao contacto com um repositório real. As regras que apenas declaram uma preferência não resistem.
O novo acesso à base de dados passa porapp/repositories/. Os ficheiros emapp/legacy/ainda chamam diretamente o ORM. Esse é código antigo, não o padrão. Não o copie.
A segunda frase é a parte essencial. Informa o agente sobre o que ele está prestes a encontrar e como deve interpretar isso, antes de o encontrar. A mesma correção aplica-se a qualquer regra que o seu repositório contradiga de forma visível: um estilo de commit que o histórico não segue, uma estrutura de testes que metade da suite ignora, uma convenção de import que só existe no código novo. Sempre que o código discordar do ficheiro, identifique essa discordância no ficheiro.
Uma regra vaga não pode ser verificada e, por isso, não pode ser seguida
"Escreva código limpo." "Não faça engenharia excessiva." "Mantenha a simplicidade." "Tenha cuidado com as migrações." Nenhuma destas regras pode ser testada contra uma ação específica, pelo agente ou por si. Um agente que recebe uma regra que não consegue verificar contra o seu próprio resultado está a adivinhar, e você está a avaliar essa adivinhação com base numa impressão.
Este é o teste a aplicar a cada linha do seu ficheiro. Escreva o comando de shell que terminaria com um código diferente de zero quando a regra fosse violada. Se não conseguir escrever esse comando, a regra não é verificável. Compare estes pares:
- Não verificável: "Mantenha as funções pequenas." Verificável: "Uma função com mais de 60 linhas precisa de um comentário acima dela a explicar o motivo."
- Não verificável: "Teste as suas alterações." Verificável: "Execute
npm teste cole a contagem de falhas antes de marcar uma tarefa como concluída." - Não verificável: "Mantenha os ficheiros organizados." Verificável: "Os handlers HTTP ficam em
src/api/handlers/. Não coloque mais nada nesse diretório." - Não verificável: "Formate o código corretamente." Verificável: "Use indentação de 2 espaços nos ficheiros
.ts."
"Não faça engenharia excessiva" é a regra que as pessoas abandonam primeiro, porque a correção não é uma frase mais curta, mas uma frase mais longa: explicar claramente o que significa a menor alteração que resolve o problema fornece ao agente critérios contra os quais pode comparar o seu próprio diff.
O tamanho é o mesmo problema com outra aparência. As orientações do Claude Code recomendam menos de 200 linhas por ficheiro de instruções e afirmam diretamente que ficheiros mais longos reduzem a adesão. Um ficheiro com 700 linhas não é uma instrução mais firme. São 700 linhas de afirmações com mais possibilidades de se contradizerem, e essas linhas são contabilizadas na sua janela em cada turno, o que se reflete diretamente na utilização de tokens. Estruturar o ficheiro para que cada regra fique sob um título que o leitor possa consultar rapidamente é abordado em escrever um ficheiro de instruções que o agente consegue executar. Melhor ainda, elimine as partes que descrevem em vez de instruírem: uma descrição dos diretórios onde ficam os handlers e os models é uma estrutura que o agente pode consultar quando necessário a partir de um mapa analisado do repositório, em vez de a manter na janela em cada turno.
Como diagnosticar o problema em dez minutos
Execute estes passos pela ordem indicada. Saltar diretamente para o último passo é a razão pela qual acabam por existir ficheiros longos com regras escritas em maiúsculas que continuam sem funcionar.
- Confirme se foi carregado. Execute
/contexte consulte a lista Memory files. Para um ficheiro aninhado, procure a linhaLoadedno terminal. Se o ficheiro não estiver presente, corrija a localização e pare. Nada mais nesta lista se aplica ainda. - Reproduza o problema numa sessão nova. Inicie uma sessão nova e forneça a tarefa mais pequena que deve ativar a regra. Se funcionar no início, mas falhar numa sessão longa, isso aponta para a distância ou para a compactação. Se também falhar aqui, o problema está na própria regra.
- Remova a concorrência. Peça a mesma alteração num diretório cujo código existente já siga a regra. Se a conformidade voltar, o código envolvente estava a sobrepor-se à sua instrução.
- Procure um conflito. Dois ficheiros com instruções diferentes para o mesmo comportamento constituem uma falha documentada: o modelo pode escolher um deles arbitrariamente e não lhe dirá que o fez.
- Torne a regra verificável e teste novamente. Reescreva a regra com um caminho concreto e uma condição. Um aumento significativo da conformidade indica que a formulação era a causa.
O passo 4 consiste num comando. Procure o tópico em todas as fontes de instruções, e não apenas no ficheiro que estava a editar:
grep -rni "migration" --include="CLAUDE.md" --include="CLAUDE.local.md" --include="AGENTS.md" .
grep -rni "migration" .claude/rules/ ~/.claude/CLAUDE.md ~/.claude/rules/ 2>/dev/nullUma ocorrência em dois ficheiros com instruções diferentes é o problema. Elimine uma delas. Não tente estabelecer uma prioridade com uma formulação mais forte, porque não existe um mecanismo de prioridades que possa consultar. No Claude Code v2.1.283 ou posterior, /doctor prompt-audit executa uma versão mais abrangente desta pesquisa nos seus ficheiros de instruções, regras e skills. O comando identifica contradições e propõe alterações, sem modificar nada até receber essa instrução.
As correções, por ordem de eficácia
Cada passo abaixo tem mais eficácia do que o anterior e exige mais trabalho de configuração. Comece pelo topo quando for fácil reformular uma regra. Avance assim que a regra for importante o suficiente para que falhas ocasionais deixem de ser aceitáveis.
- Torne a regra concreta. Indique um caminho, um comando ou uma condição. Acrescente as evidências em contrário que o agente encontrará no repositório, como mostrado anteriormente. Isto não tem custo e corrige uma parte surpreendentemente grande dos casos.
- Aproxime a regra do que ela controla. Use um
CLAUDE.mdaninhado, uma regra com escopo de caminho em.claude/rules/ou um comentário no início do próprio ficheiro. A regra é então lida juntamente com o código a que se aplica. Aceite a limitação: tudo o que for carregado dessa forma desaparece na compactação seguinte e regressa na próxima leitura correspondente. - Coloque a aplicação da regra num hook. A prosa pede. Um hook decide. Os hooks são executados como código em eventos fixos do ciclo de vida e aplicam-se independentemente da conclusão do modelo.
- Entregue a regra a uma ferramenta determinística e elimine a prosa. Formatação, ordem dos imports, comprimento das linhas, imports proibidos, formato das mensagens de commit.
ruff format,prettier --write,eslint, um hookpre-commit. O formatter acerta sempre e não consome tokens. A frase está certa na maioria das vezes e consome tokens em cada interação.
O passo 3 em detalhe. Suponha que os ficheiros de migração nunca podem ser editados pelo agente. Coloque isto em .claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-migrations.sh"
}
]
}
]
}
}E isto em .claude/hooks/guard-migrations.sh:
#!/usr/bin/env bash
set -euo pipefail
path=$(jq -r '.tool_input.file_path // empty')
case "$path" in
*/migrations/*)
echo "Files under migrations/ are written by hand. Stop and ask first." >&2
exit 2
;;
esac
exit 0Execute chmod +x .claude/hooks/guard-migrations.sh, inicie uma nova sessão e peça ao agente para editar um ficheiro em migrations/. A edição é recusada e a sua mensagem é devolvida como motivo. O código de saída 2 em PreToolUse bloqueia a chamada da ferramenta antes da execução, e o texto enviado para stderr é entregue ao modelo como mensagem de bloqueio. ${CLAUDE_PROJECT_DIR} resolve-se para a raiz do projeto, pelo que o hook funciona independentemente do diretório onde o agente esteja. O agente não precisa de concordar com a regra, de se lembrar dela nem de ainda a ter no contexto. A edição não acontece.
Para uma proibição simples, sem lógica, permissions.deny nas suas definições faz o mesmo sem exigir a manutenção de um script, e os modos de permissão determinam o que é executado sem lhe perguntarem primeiro. Se uma instrução tiver realmente de ficar ao nível do system prompt, em vez de numa mensagem do utilizador, --append-system-prompt coloca-a nesse nível. No entanto, é uma opção de arranque que tem de ser passada novamente em cada sessão nova, pelo que é mais adequada para scripts do que para trabalho interativo.
O que não é possível impor apenas com instruções
Seja claro sobre qual metade deste problema é sua. Posicionamento, formulação, conflitos entre ficheiros e tamanho do ficheiro são problemas do autor, com correções que cabem ao autor. O resto é comportamento do modelo, e uma redação melhor não o elimina.
Concordar não é cumprir. Um agente pode confirmar uma regra, repeti-la corretamente e violá-la duas chamadas de ferramenta depois. A confirmação não tem custo e não permite prever nada. Não a interprete como uma correção nem a conte como um teste.
Alguns hábitos persistem. Adicionar comentários, acrescentar tratamento defensivo de erros, escrever um resumo final, executar o próximo comando óbvio. Estes comportamentos reaparecem quando existe uma regra que os proíbe, embora com uma frequência menor, não nula. Pode medir a sua própria taxa: execute a mesma tarefa 10 vezes em sessões novas e conte as violações. Quando esse número precisa de ser zero, a regra tem de sair do prompt. Declarar uma tarefa concluída quando ainda falta uma parte tem a mesma origem comportamental, e a correção é estrutural, não verbal: a competência unlazy troca a frase por uma árvore de profundidade e ficheiros de controlo que o agente tem de validar antes de poder declarar a tarefa concluída.
A própria sessão torna-se um exemplo. Se o agente violou a regra na interação 12 e deixou passar, essa violação passa a fazer parte do contexto como demonstração e é muito mais recente do que a regra. Corrija uma violação assim que a detetar. Uma violação não corrigida ensina o resto da sessão.
Um ficheiro de instruções não é um limite de segurança. Molda o comportamento, mas não o impõe. Tudo aquilo em que uma falha tem um custo elevado, como credenciais ou comandos destrutivos, deve ser tratado com permissões ou um hook. Manter os segredos fora do alcance de um agente aplica o mesmo princípio aos dados: não peça a um agente para não ler um ficheiro; faça com que o ficheiro não possa ser lido.
A versão curta. Prove que o ficheiro foi carregado, torne a regra verificável, coloque-a junto do objeto que governa e, quando a taxa de falhas continuar a ser relevante, retire-a da prosa. Uma regra que um agente não pode ignorar é uma regra que nunca lhe foi pedida.
FAQ
Por que o Claude Code ignora o meu CLAUDE.md?
Confirme se o ficheiro foi carregado antes de concluir que foi ignorado. Execute /context e consulte a lista Memory files; se um ficheiro não aparecer nessa lista, não foi carregado no arranque. Os ficheiros de instruções são enviados como uma mensagem de utilizador depois do prompt de sistema e tratados como contexto, não como configuração obrigatória. Por isso, não existe uma garantia estrita de conformidade. Na maioria dos casos, a causa é uma de quatro: o ficheiro está num subdiretório que o agente nunca leu, dois ficheiros entram em conflito e o modelo escolheu um deles arbitrariamente, a regra é demasiado vaga para permitir verificar uma ação, ou o código envolvente demonstra o oposto do que a regra determina.
Editar o ficheiro de instruções durante a sessão altera alguma coisa?
Não altera a cópia que já está na conversa. Os ficheiros acima do diretório de trabalho são carregados integralmente no arranque. Por isso, o texto que o modelo tem é o texto existente no momento do arranque. Para aplicar uma edição, inicie uma nova sessão ou peça ao agente para ler o ficheiro com as ferramentas normais de ficheiros. Isto coloca a versão atual na conversa como uma nova mensagem. Depois de uma compactação, o ficheiro da raiz do projeto é lido novamente a partir do disco. A nova versão também fica disponível nesse momento.
Qual ficheiro prevalece quando um CLAUDE.md na raiz e outro num subdiretório entram em conflito?
Nenhum prevalece de forma fiável. Os ficheiros encontrados são concatenados no contexto, em ordem descendente, desde a raiz do sistema de ficheiros até ao diretório de trabalho. Assim, o ficheiro mais próximo é simplesmente lido por último. Não existe um mecanismo de precedência para resolver contradições, e a documentação do Claude Code indica que regras contraditórias podem ser resolvidas arbitrariamente. Escreva os ficheiros aninhados como adições que indiquem o caminho a que se aplicam. Remova a contradição em vez de tentar dar prioridade a uma regra.
As minhas instruções sobrevivem a /compact?
Depende de como foram carregadas. A raiz do projeto CLAUDE.md, as regras sem escopo e a memória automática são reinseridas a partir do disco depois de uma compactação. As regras com frontmatter paths: e os ficheiros CLAUDE.md aninhados em subdiretórios perdem-se até que um ficheiro correspondente seja lido novamente. Qualquer conteúdo que tenha escrito apenas no chat sobrevive somente se o resumidor o tiver mantido. Se uma regra tiver de permanecer válida durante toda a sessão, coloque-a no ficheiro da raiz do projeto sem frontmatter paths:.
Quando deve uma regra tornar-se um hook em vez de prosa?
Quando a verificação é determinística e o custo de uma falha é superior ao custo de escrever um script pequeno. Restrições de caminhos de ficheiros, comandos obrigatórios antes de um commit e chamadas de ferramentas proibidas são exemplos. Um hook PreToolUse que termina com o estado 2 bloqueia diretamente a chamada da ferramenta e devolve o texto de stderr ao modelo como motivo. Assim, a regra continua a ser aplicada, esteja ou não presente no contexto. Tudo o que um formatter ou um linter consiga decidir deve ficar a cargo dessa ferramenta e ser removido integralmente do ficheiro de instruções.