A Anthropic publicou um guia oficial de boas práticas para o Claude Code que deixa claro: texto escrito em um arquivo CLAUDE.md é um pedido, não uma ordem. O modelo lê, pondera e pode decidir não seguir. A diferença entre hooks e CLAUDE.md no Claude Code é fundamental: hooks, deny rules e configurações gerenciadas são aplicados pelo próprio harness, sem passar pelo julgamento do modelo.
Essa distinção parece pequena, mas tem impacto direto em quem usa agentes de IA em produção.
O que a Anthropic diz sobre o CLAUDE.md
O guia de boas práticas da Anthropic é direto: prompts, arquivos CLAUDE.md e skills são pedidos — o modelo os avalia e pode optar por não seguir. A frase-chave do documento é que hooks, deny rules e managed settings são aplicados "no matter what the model decided to do" (independentemente do que o modelo decidiu fazer).
Na prática, escrever "SEMPRE confirmar antes de deletar arquivos" em letras maiúsculas no CLAUDE.md não garante nada. O próprio guia lista o uso de maiúsculas como um hábito antigo que pode atrapalhar: tende a levar o modelo a aplicar a regra de forma excessiva ou fora de contexto.
Outra recomendação do documento: depois de duas tentativas falhas de corrigir um problema em sessão, o caminho certo é limpar a conversa e reescrever o prompt, não insistir na mesma direção.
Quando usar hooks — e quais funcionam de verdade
Entender a diferença entre hooks e CLAUDE.md no Claude Code muda a forma de configurar agentes. Hooks que delegam a decisão para outro modelo não são determinísticos. Para aplicação real, o guia recomenda hooks de tipo command ou http: eles executam código ou chamam um endpoint, sem depender da avaliação de um LLM.
Um detalhe que engana: uma deny rule configurada para bloquear o WebFetch em um domínio específico não impede o acesso a esse mesmo domínio via curl, a menos que o sandbox esteja ativo. A regra existe no nível do harness, não do sistema operacional.
Addy Osmani, citado no levantamento da FourWeekMBA, chama de "orchestration tax" o custo oculto de coordenar muitos agentes ao mesmo tempo — uma sobrecarga que cresce com cada camada de automação sem controle real. Ele também nomeia "code ratification" a prática de aprovar código só porque os testes passaram, sem entendê-lo de fato.
Por que isso importa para o seu negócio
Empresas que colocam Claude Code (ou qualquer agente de IA) para executar tarefas críticas — deletar registros, enviar e-mails, fazer deploys — precisam saber onde está a fronteira entre "o agente vai tentar" e "o agente vai fazer". Essa fronteira é exatamente o que separa hooks e CLAUDE.md no Claude Code.
Sem hooks e deny rules configurados, qualquer instrução de segurança no CLAUDE.md é uma expectativa, não uma garantia. Claude Code nas empresas: o que CIOs precisam entender para governar o agente sem perder o controle já é pauta em equipes de tecnologia que adotaram o agente em fluxos sensíveis.
A recomendação prática do guia: use o CLAUDE.md para diretrizes gerais e comportamento esperado; reserve os hooks para o que não pode falhar.
Um desenvolvedor foi embora — e os números por trás do adeus
No mesmo período em que o guia ganhou atenção, um post do blog caleb.software chegou à primeira página do Hacker News com 306 pontos. O desenvolvedor anunciou que trocou o Claude Code pelo Pi, alternativa de código aberto com 120,7 mil estrelas e 15,5 mil forks no GitHub.
O motivo não foi um único problema. Entre os itens: manutenção paralela de CLAUDE.md e AGENTS.md, apenas uma sessão ativa por vez no VS Code e o overhead de tokens — a descrição padrão da ferramenta Bash tem quase 3.000 tokens. O autor estima que cortar 1.000 tokens poderia economizar milhões de dólares por ano em custos de inferência, partindo da premissa de um milhão de usuários diários.
No ano, o Claude Code teve 244 lançamentos, e mais de três quartos deles alteraram o system prompt ou as descrições das ferramentas — o equivalente a mais de 183 versões mexendo nos fundamentos do harness.
Curiosamente, um dia depois de o desenvolvedor decidir migrar, a Anthropic anunciou suporte a arquivos AGENTS.md no Claude Code. As queixas eram sobre o harness, não sobre os modelos Claude. O Pi, com suporte a mais de 15 provedores, permite continuar usando modelos da Anthropic. Alternativas ao Claude Code ganham força: OpenCode, Cursor, Codex e Copilot CLI
Conteúdo reescrito e traduzido para PT pela redação luiscortex, revisado por humano.
Fontes:
