Explore o conteúdo

O que você procura?

Pesquise por assunto, palavra ou título.

Ferramentas de IA

CLAUDE.md é pedido, hook é regra: os hooks do Claude Code que eu uso para o agente não sair do trilho

O CLAUDE.md é contexto, não regra obrigatória. Por isso eu passei para hooks do Claude Code tudo o que precisa valer sempre: proteger arquivos sensíveis, barrar comandos perigosos, formatar a cada edição e não deixar o agente encerrar com teste quebrado. Os scripts e as armadilhas.

Thiago9 min de leitura
⏱ 10 min de leitura
Neste artigo
  1. O que são hooks no Claude Code (em 30 segundos)
  2. Como eu decido: vai para o CLAUDE.md ou vira hook?
  3. Hook 1: bloquear edição em arquivos sensíveis
  4. Hook 2: barrar comandos que eu nunca quero ver o agente rodar
  5. Hook 3: formatar e checar lint depois de cada edição
  6. Hook 4: não deixar o agente dizer “pronto” com teste quebrado
  7. Bônus: devolver o contexto depois da compactação
  8. As armadilhas que me fizeram perder tempo
  9. Minha opinião: hooks são o “CI local” do agente
  10. Perguntas frequentes
  11. Hooks substituem o CLAUDE.md?
  12. Preciso saber Bash para usar hooks?
  13. Hook deixa o Claude Code mais lento?

Todo mundo que usa Claude Code por algumas semanas passa pelo mesmo momento: você escreve no CLAUDE.md “nunca edite o .env“, “sempre rode o formatter”, “não termine sem rodar os testes”… e um dia o agente simplesmente não faz. Não por maldade. Ele leu, entendeu e, no meio de uma tarefa longa, com o contexto cheio, priorizou outra coisa.

Demorei para aceitar o óbvio, que a própria documentação do Claude Code diz com todas as letras: o CLAUDE.md é tratado como contexto, não como configuração obrigatória. Se uma regra precisa valer sempre, ela não pode depender da boa vontade do modelo. Ela tem que virar código. E no Claude Code isso tem nome: hooks.

Minha tese é simples: instrução no CLAUDE.md é pedido; hook é regra. Neste artigo eu mostro como eu separo uma coisa da outra e os hooks que uso de verdade, com os scripts, e as armadilhas que me fizeram perder tempo.

O que são hooks no Claude Code (em 30 segundos)

Hooks são comandos (ou endpoints HTTP, prompts e até subagentes) que o Claude Code executa automaticamente em pontos fixos do ciclo de vida da sessão. Os que mais importam no dia a dia são:

  • PreToolUse: roda antes de uma ferramenta ser executada (editar arquivo, rodar comando no terminal). Pode bloquear a ação.
  • PostToolUse: roda depois que a ferramenta deu certo. Não desfaz nada, mas pode devolver um aviso para o Claude corrigir.
  • Stop: roda quando o Claude termina de responder. Pode impedir que ele “dê por encerrado”.
  • SessionStart: roda quando a sessão começa, retoma ou volta de uma compactação. O que o script imprime vira contexto.

O hook recebe um JSON no stdin com os dados do evento (por exemplo, tool_input.file_path numa edição ou tool_input.command num comando Bash) e responde por código de saída, stderr ou um JSON no stdout. Você configura em .claude/settings.json (vale para o projeto e pode ir para o repositório), em ~/.claude/settings.json (todos os seus projetos) ou em .claude/settings.local.json (só na sua máquina). A referência oficial de hooks lista todos os eventos; o guia prático tem exemplos prontos.

Como eu decido: vai para o CLAUDE.md ou vira hook?

Eu uso uma pergunta só: “se o agente ignorar isso uma vez, qual é o estrago?”

  • Estrago pequeno, é questão de estilo ou preferência: fica no CLAUDE.md. “Prefira composição a herança”, “nomes de teste em português”, “use o service X para chamadas externas”. Se ele errar, eu corrijo na revisão.
  • Estrago real ou regra que tem que valer 100% das vezes: vira hook. Mexer em segredo, em lockfile, em migration já aplicada, rodar git push --force, entregar código sem formatar, dizer “pronto” com teste quebrado.

Um efeito colateral bom: o CLAUDE.md fica mais curto. Tirei dele um monte de “NUNCA” em caixa alta que só ocupava contexto. A documentação de memória do Claude Code vai na mesma linha: quanto mais específicas e concisas as instruções, mais consistentemente ele segue, e o que precisa rodar num ponto fixo (antes de commit, depois de cada edição) deve ser hook.

Hook 1: bloquear edição em arquivos sensíveis

É o primeiro que eu instalo em qualquer projeto. Um PreToolUse com matcher Edit|Write que olha o caminho do arquivo e sai com código 2 se for algo protegido. Salvo em .claude/hooks/protege-arquivos.sh:

#!/bin/bash
# .claude/hooks/protege-arquivos.sh
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

PROTEGIDOS=(".env" "composer.lock" "package-lock.json" ".git/" "database/migrations/")

for p in "${PROTEGIDOS[@]}"; do
  if [[ "$FILE_PATH" == *"$p"* ]]; then
    echo "Bloqueado: $FILE_PATH é protegido ($p). Crie uma migration nova ou me peça para editar manualmente." >&2
    exit 2
  fi
done
exit 0

E registro no .claude/settings.json:

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

O detalhe que faz diferença é a mensagem no stderr. Com exit 2, o Claude recebe esse texto como erro da ferramenta e ajusta o plano. Por isso eu escrevo a mensagem como instrução (“crie uma migration nova”), não só como “proibido”. No meu caso, que trabalho muito com Laravel, travar database/migrations/ evitou o clássico “vou só ajustar essa coluna na migration que já rodou em produção”.

Um aviso honesto: isso bloqueia as ferramentas de edição, não o terminal. O agente ainda pode mudar o arquivo com um comando shell. Para fechar mais, a documentação recomenda somar regras de permissions.deny e, se precisar de garantia de verdade, sandbox. Hook é uma camada, não a fortaleza inteira.

Hook 2: barrar comandos que eu nunca quero ver o agente rodar

Mesma ideia, agora com matcher Bash, lendo tool_input.command:

#!/bin/bash
# .claude/hooks/comandos-proibidos.sh
CMD=$(jq -r '.tool_input.command // empty')

if echo "$CMD" | grep -Eq 'git push .*(--force|-f)( |$)|rm -rf /|DROP (TABLE|DATABASE)|--env=production'; then
  echo "Bloqueado: comando destrutivo ou de produção. Explique o que quer fazer e eu executo." >&2
  exit 2
fi
exit 0

Aqui eu sou bem pragmático: regex em string de comando é fácil de contornar e não é controle de segurança sério. O objetivo não é parar um atacante; é parar o agente bem-intencionado que, às 23h, decidiu que um force push “resolve o conflito”. Para isso funciona muito bem. Um ponto que me deu confiança: segundo a documentação, um PreToolUse que nega a ação vale em todos os modos de permissão, inclusive quando alguém roda com --dangerously-skip-permissions.

Hook 3: formatar e checar lint depois de cada edição

Esse é o que mais melhorou a qualidade dos diffs que eu reviso. Um PostToolUse em Edit|Write que escolhe a ferramenta pela extensão:

#!/bin/bash
# .claude/hooks/formata.sh
F=$(jq -r '.tool_input.file_path // empty')
[ -z "$F" ] && exit 0

case "$F" in
  *.php)          vendor/bin/pint "$F" >/dev/null ;;
  *.py)           ruff format "$F" >/dev/null
                  ruff check "$F" 1>&2 || exit 2 ;;
  *.ts|*.tsx|*.vue) npx prettier --write --ignore-unknown "$F" >/dev/null ;;
esac
exit 0

Repare na linha do ruff check: se o lint falha, eu mando a saída para o stderr e saio com 2. Num PostToolUse isso não desfaz a edição (a ferramenta já rodou), mas mostra o erro para o Claude, que corrige na hora. Antes, eu descobria o problema no CI, 10 minutos depois. Agora o agente descobre no mesmo passo.

Uma escolha consciente: eu não rodo a suíte de testes aqui. Teste depois de cada edição deixa a sessão lenta e gera ruído, porque no meio de uma refatoração o código fica quebrado de propósito por alguns passos.

Hook 4: não deixar o agente dizer “pronto” com teste quebrado

Os testes entram no Stop, que roda quando o Claude termina de responder. Se os testes falham, saio com 2 e ele continua trabalhando:

#!/bin/bash
# .claude/hooks/testes-antes-de-parar.sh
INPUT=$(cat)

# evita loop: se já estou numa continuação causada por este hook, deixa parar
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0
fi

# só roda se houve mudança em código
git diff --quiet -- app/ src/ tests/ && exit 0

if ! OUT=$(php artisan test --stop-on-failure 2>&1); then
  echo "Os testes falharam. Corrija antes de encerrar:" >&2
  echo "$OUT" | tail -n 30 >&2
  exit 2
fi
exit 0

Duas coisas que aprendi apanhando. Primeiro: o Stop dispara sempre que o Claude termina uma resposta, não só quando a tarefa acabou. Se você faz uma pergunta rápida, ele roda também. Por isso o git diff --quiet: sem mudança em código, não tem por que rodar teste. Segundo: sem checar stop_hook_active, um teste que o agente não consegue consertar vira um loop. A documentação informa que o Claude Code sobrepõe o hook depois de oito bloqueios seguidos sem chamada de ferramenta no meio, mas é melhor não depender disso. Eu prefiro deixar ele parar e me explicar o que está travado.

Bônus: devolver o contexto depois da compactação

Em sessões longas, o contexto é compactado e detalhes se perdem. Um SessionStart com matcher compact resolve: o que o comando imprime no stdout volta para o contexto do Claude.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          { "type": "command", "command": "echo \"Branch: $(git branch --show-current)\"; git log --oneline -5; cat .claude/tarefa-atual.md 2>/dev/null" }
        ]
      }
    ]
  }
}

Eu mantenho um tarefa-atual.md curto com o objetivo da tarefa e as decisões já tomadas. Depois da compactação, o agente “lembra” em que branch está e o que já foi decidido, sem eu ter que repetir.

As armadilhas que me fizeram perder tempo

  • Exit 1 não bloqueia nada. Esse é o maior. Só o código 2 bloqueia. Qualquer outro código diferente de zero é tratado como erro não bloqueante: a ação segue. Já vi hook de proteção “funcionando” por semanas sem bloquear nada porque terminava com exit 1.
  • Script sem permissão de execução. Esqueceu o chmod +x, o hook não roda.
  • JSON inválido no settings. Vírgula sobrando ou comentário e os hooks somem. O comando /hooks dentro do Claude Code mostra o que foi carregado e de onde; é a primeira coisa que eu olho.
  • Matcher é sensível a maiúsculas. edit|write não casa com Edit|Write.
  • Dependências do script. Os exemplos usam jq. Na máquina de um colega sem jq, o hook quebra. Para testar fora do Claude, eu faço: echo '{"tool_input":{"file_path":".env"}}' | .claude/hooks/protege-arquivos.sh; echo $?.
  • Hook roda com as suas permissões. Hook de projeto é código executando na sua máquina. Antes de abrir um repositório de terceiros com Claude Code, eu leio o .claude/settings.json dele.

Minha opinião: hooks são o “CI local” do agente

Quando comecei a usar agentes de código, eu tentava resolver tudo no prompt e no arquivo de regras. Funcionava 90% das vezes, e os 10% restantes eram justamente os que doíam. O que mudou o jogo foi tratar o agente como trato um dev novo no time: eu não confio que ele vai lembrar de rodar o lint, eu coloco o lint no pipeline. Hooks são esse pipeline, rodando dentro da sessão.

Se você vai começar, não instale dez de uma vez. Comece pelo hook 1 (arquivos protegidos) e pelo hook 3 (formatter). São os de menor atrito e maior retorno. Depois de uma semana, você vai saber onde o agente mais escorrega no seu projeto, e o próximo hook se escreve sozinho. Escrevi sobre o resto do meu ambiente em meu setup Cursor + Claude Code em 2026, e o que eu olho na revisão do que sai do agente está em como eu reviso PR gerado por IA.

Perguntas frequentes

Hooks substituem o CLAUDE.md?

Não. O CLAUDE.md continua sendo o lugar de contexto: arquitetura, convenções, como o projeto funciona. Hooks são para o que precisa ser garantido. Os dois se complementam.

Preciso saber Bash para usar hooks?

Ajuda, mas o hook pode ser qualquer executável que leia JSON do stdin: Python, Node, PHP. O que importa é o contrato: ler o JSON, decidir e sair com 0 (segue) ou 2 (bloqueia).

Hook deixa o Claude Code mais lento?

Depende do que você roda. Formatter num arquivo é quase instantâneo. Suíte de testes inteira a cada edição deixa tudo lento, por isso eu coloco testes só no Stop e só quando há mudança em código.

Prefere a versão rápida? Veja a Web Story com os hooks em 11 telas.

Quer ir além? No Labs de IA eu mostro na prática como uso Claude Code, agentes e automações no trabalho, do jeito que faço no dia a dia.

Compartilhe conhecimento

Este conteúdo foi útil para você?

Envie para alguém que também pode aproveitar.

Conteúdo recomendado

Continue explorando