Hook, a regra que você impõe

O que é cada coisa

• CLAUDE.md: texto que o Claude lê como contexto. Pela documentação, ele orienta, mas não é regra imposta pelo sistema, e não há garantia de que seja seguido à risca.
• Hook: um comando (script) que o Claude Code executa em pontos fixos do funcionamento, como antes de usar uma ferramenta. Pela documentação, ele roda independentemente do que o Claude decidir.
• PreToolUse: o evento que dispara antes de a ferramenta rodar e pode bloquear a ação.
• Matcher: o filtro que diz para quais ferramentas o hook vale. Edit|Write cobre editar e criar arquivo; não cobre comandos de terminal.

Prepare uma pasta de teste

Pré-requisitos: Claude Code instalado e a ferramenta jq, que lê o JSON que o Claude Code manda para o hook. No Mac, confira com which jq.

Use uma pasta de teste, não um projeto de verdade. Crie um arquivo .env com um conteúdo de exemplo e a pasta dos hooks:

echo "CHAVE=EXEMPLO" > .env
mkdir -p .claude/hooks

Crie o script do hook

Salve como .claude/hooks/protect-env.sh. Ele lê o caminho do arquivo que o Claude quer mexer e, se o nome começar com .env, sai com código dois, que é o código que bloqueia.

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
FILE_PATH="${FILE_PATH//\\//}"
NAME="${FILE_PATH##*/}"

if [[ "$NAME" == .env* ]]; then
  echo "Bloqueado: $FILE_PATH é um arquivo .env protegido por hook" >&2
  exit 2
fi

exit 0

O script compara só o nome do arquivo (o que vem depois da última barra). Assim ele bloqueia .env, .env.local e .env.production, e não bloqueia uma pasta que só tenha ".env" no nome, como .environments. O .env.example também fica bloqueado; ajuste se precisar liberá-lo.

Torne o script executável:

chmod +x .claude/hooks/protect-env.sh

Registre o hook no settings.json

Crie .claude/settings.json com este conteúdo. Se o arquivo já existir, junte o bloco hooks ao que já está lá.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-env.sh"
          }
        ]
      }
    ]
  }
}

Abra o Claude Code na pasta de teste e digite /hooks. O hook deve aparecer na lista, em PreToolUse.

Teste

Faça estes três pedidos ao Claude, um de cada vez:

Adicione um comentário no arquivo .env

Esperado: a edição é bloqueada antes de acontecer e o Claude recebe a mensagem "Bloqueado: ...".

Crie um arquivo teste.txt com a palavra oi

Esperado: funciona, porque o script sai com código zero para outros arquivos.

Rode no terminal: echo oi >> .env

Esperado: passa. O matcher Edit|Write não vê comandos de terminal. É o limite avisado no começo.

Se o hook não aparecer ou não disparar, inicie com claude --debug-file /tmp/claude.log e acompanhe com tail -f /tmp/claude.log, ou use /debug dentro da sessão.

O que verificar

• Só o código de saída dois bloqueia. Código um sem JSON válido é erro não bloqueante: a ação segue.
• O script precisa estar executável e o jq instalado. Sem isso, o hook falha e, em geral, a ação segue.
• Código zero em PreToolUse não aprova a ação: ela segue o fluxo normal de permissões.
• Hooks de comando são regras fixas. Hooks de prompt e de agente usam um modelo para decidir; servem para julgamento, não para regra fixa.
• Onde guardar: .claude/settings.json vale para o projeto e pode ir para o Git; .claude/settings.local.json vale só para você; ~/.claude/settings.json vale para todos os seus projetos.
• Para proibir uma ação de forma ampla, as regras de permissão (permissions.deny) são outra camada que a documentação aponta.

Regra de bolso

• Hook ou permissão: regra que precisa valer sempre, como proteger arquivo ou bloquear comando.
• CLAUDE.md: preferência de estilo e contexto do projeto.

Fontes

Documentação oficial do Claude Code, conferida em 09/11/2026: Memory (CLAUDE.md), Hooks guide e Hooks reference. O script é inspirado no exemplo "Block edits to protected files" da documentação, com a comparação pelo nome do arquivo e a mensagem adaptadas.