DevPawDEVPAW · GROUND-UP DEV NOTES
Buscar
Menu
PT-BR
한국어English日本語繁體中文EspañolPortuguês简体中文
Programação e agentes de IA

[Claude Code #11] Hooks: automatize com mecanismos, não com pedidos

Os hooks do Claude Code executam comandos de shell automaticamente em momentos como antes e depois de chamadas de ferramentas e no fim de um turno. Este guia reúne a configuração do settings.json, eventos e matchers, formatação automática, bloqueio de arquivos protegidos e prompt hooks.

4 min de leitura
Imagem de capa de [Claude Code #11] Hooks: automatize com mecanismos, não com pedidos

Mesmo que você escreva “Sempre execute o formatador depois de editar” no CLAUDE.md, há dias em que a IA esquece. Afinal, instruções são apenas pedidos.

O que precisa acontecer obrigatoriamente deve virar um mecanismo, não um pedido. No Claude Code, esse mecanismo é um hook.

Um hook é um comando de shell definido pelo usuário. Ele é executado automaticamente em momentos específicos enquanto o Claude Code funciona e é aplicado de forma determinística, independentemente do que o modelo escolher.

Se os comandos até Claude Code, episódio 10 eram acionados manualmente, hooks são mecanismos automáticos que se acionam sozinhos.

Crie seu primeiro hook em 5 minutos

Os hooks são definidos no bloco hooks do settings.json. Veja um exemplo que exibe uma notificação do macOS enquanto o Claude aguarda uma entrada.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Entrada necessária\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Salve e digite /hooks para ver a lista de hooks registrados. Esta tela é somente leitura; edite o settings.json diretamente ou peça ao Claude para fazer isso.

Em quais momentos é possível acionar um hook

Com base em Guia oficial de hooks, estes são os eventos mais usados.

  • SessionStart: quando uma sessão começa ou é retomada
  • UserPromptSubmit: logo depois de enviar um prompt, antes de o Claude processá-lo
  • PreToolUse: imediatamente antes de uma chamada de ferramenta; pode bloquear a chamada
  • PostToolUse: logo depois de uma chamada de ferramenta bem-sucedida
  • Stop: quando o turno do Claude termina
  • Notification: quando o Claude aguarda uma entrada

Use um matcher para restringir o alvo. Se você escrever "matcher": "Edit|Write", o hook será executado somente quando uma ferramenta de edição de arquivos for usada.

Diagrama dos momentos de disparo dos seis eventos de hook do Claude Code
É possível configurar hooks nos principais momentos de uma sessão

Três usos representativos

Formatação automática após a edição. Configure o matcher Edit|Write em PostToolUse e execute o prettier. A formatação será obrigatória, qualquer que seja o arquivo alterado pela IA.

Bloqueio de arquivos protegidos. Um hook PreToolUse verifica caminhos específicos e Quando termina com o código de saída 2 bloqueia a edição. Não pode ser qualquer código de falha: precisa ser exatamente 2. Diferentemente de uma instrução no CLAUDE.md, não há como contornar isso mesmo que o modelo esqueça.

Notificação ao terminar. Assim como no exemplo anterior de Notification, você não precisa ficar olhando o terminal.

Quando é preciso julgar: prompt hooks

Há condições difíceis de avaliar com um script de shell, como “O trabalho solicitado terminou por completo?”.

Nesses casos, use um hook type: "prompt". Em vez de um comando de shell, defina os critérios de avaliação, e o modelo Haiku padrão decidirá com yes/no.

Ao configurar um prompt hook no evento Stop, você obtém “se não terminou, continue trabalhando”. Na prática, /goal, abordado no episódio 6 é um wrapper limitado à sessão baseado nessa estrutura.

Hooks executam o shell exatamente como está

Esse poder também traz riscos. A estrutura executa automaticamente comandos de shell arbitrários com as suas permissões.

Os hooks no settings.json do projeto exigem a confirmação de que você confia no repositório. Ao abrir o repositório de outra pessoa, não trate essa confirmação com descaso.

Dentro dos comandos dos hooks, coloque as variáveis entre aspas e mantenha a prática básica de nunca executar entradas externas sem validação.

Ilustração contrastando “PROMISE vs MACHINE” com um pedido em um post-it e uma máquina de imposição automática
O post-it é um pedido; a máquina impõe o cumprimento

Resumo

Hooks são mecanismos que tiram da memória do modelo as “coisas que precisam acontecer” e as entregam ao sistema.

Comece forçando a formatação, bloqueando arquivos protegidos e exibindo notificações de conclusão. Quando houver condições que exigem julgamento, expanda para prompt hooks.

No próximo episódio, veremos /loop, que executa prompts repetidamente em intervalos definidos. Se hooks automatizam eventos, /loop automatiza o tempo.

Fontes e critérios de verificação

Continue lendo

Série Claude Code

Tópicos relacionados