Instala uma salvaguarda: os hooks

O risco: publicar um erro

O teu skill redige e publica. Mas o que acontece se um post contiver um travessão que detestas, ultrapassar o limite de caracteres da plataforma, ou partir para o Instagram sem imagem? Por enquanto, nada o impede. Poderias reler cada post à mão — mas então para quê automatizar? Poderias adicionar «verifica bem antes de publicar» no skill — mas uma instrução num prompt continua a ser probabilística: o modelo segue-a quase sempre, e «quase» não chega quando o erro é público e instantâneo.

Precisas de uma salvaguarda de outra natureza: uma verificação que se executa sistematicamente, que o Claude não pode esquecer nem contornar. É exatamente isso que são os hooks.

O que é um hook?

Um hook executa código em momentos-chave do ciclo de vida do Claude Code. Ativa-se automaticamente: não tens de pensar em chamá-lo, e o Claude não tem de pensar em respeitá-lo — impõe-se a ele. Um hook pode formatar ficheiros após modificação, bloquear um comando antes da sua execução, injetar contexto no arranque de uma sessão, ou notificar quando uma tarefa termina.

Os momentos de ativação (os «eventos») cobrem todo o ciclo de vida: antes de uma ferramenta executar (o evento PreToolUse — é ele que nos interessa para bloquear uma publicação), depois da sua execução (PostToolUse — perfeito para reformatar um ficheiro modificado), na submissão da tua mensagem, no arranque da sessão, ou quando o Claude termina a sua resposta. Cada hook está associado a um evento e, opcionalmente, a um filtro (por exemplo: apenas os comandos Bash que contêm «publish»).

As três formas de validar

A regra de escolha: usa o menos poderoso que chegue. Verificar um limite de caracteres com um agent hook é tirar o bulldozer para plantar uma alface — lento, caro e mais frágil. O nosso quality gate combina regras simples e objetivas: um command hook é a ferramenta certa.

Onde vivem os hooks

Os hooks configuram-se nos teus ficheiros de configurações (.claude/settings.json para os partilhar com o projeto, ou settings.local.json só para ti). A estrutura associa um evento, um filtro («matcher») e o comando a lançar. Eis a forma geral de um hook que se ativa antes dos comandos Bash:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/quality-gate.js"
          }
        ]
      }
    ]
  }
}

O mecanismo de bloqueio é elegante de tão simples: o script do hook recebe os detalhes da ação à entrada, e o seu código de saída decide o que se segue. Saída 0: está tudo bem, a ação continua. Saída 2: a ação é bloqueada, e o que o script escreveu na saída de erro é devolvido ao Claude — que o lê e corrige. O hook não se limita portanto a dizer não: explica porquê, e o Claude usa essa explicação para reparar.

Construir o quality gate

Criamos um hook que se ativa antes de qualquer publicação e verifica o conteúdo. Se falhar, o comando é bloqueado e o Claude vê precisamente o que corrigir:

cria um command hook que se ativa antes de qualquer comando Bash de publicação.

o hook verifica o conteúdo do post:
- travessões (a substituir por «...»)
- ultrapassagem do limite de caracteres da plataforma
- média em falta para as plataformas que o exigem
- palavras proibidas do meu guia de voz de marca

se uma verificação falhar: bloqueia o comando e mostra precisamente o que corrigir.

flowchart TD
  P["Tentativa de publicação"] --> H{"Hook: quality gate"}
  H -->|"Conforme"| OK["Publicação"]
  H -->|"Não conforme"| KO["Bloqueado + lista das correções"]
  KO --> F["O Claude corrige o conteúdo"]
  F --> P

Observa o ciclo no diagrama: bloqueado não quer dizer morto. O Claude lê a mensagem de erro, corrige o conteúdo e tenta de novo — na maioria das vezes sem qualquer intervenção da tua parte. A salvaguarda não abranda o sistema: torna-o autocorretivo.

Testar o hook (provocando a falha)

Uma salvaguarda não testada é uma salvaguarda decorativa. O método: provocar voluntariamente cada tipo de falha e verificar o bloqueio. É o mesmo reflexo de um programador que testa os seus casos de erro, não apenas o seu caminho feliz:

testa o hook num tweet que ultrapassa o limite de caracteres

testa o hook num post instagram sem imagem

testa o hook num post que contém a palavra "revolucionário"

Para cada teste, o resultado deve indicar que a ação foi bloqueada («validação falhada») com a razão exata. Se um caso passar quando devia bloquear, é agora que o descobrimos — não no dia em que um post não conforme parte para produção. Perfeito: o teu pipeline nunca publicará um conteúdo não conforme.

Para além do quality gate

Uma vez compreendido o mecanismo, os hooks tornam-se um reflexo para tudo o que deve ser sistemático. Alguns usos clássicos: reformatar automaticamente cada ficheiro modificado (PostToolUse), proibir qualquer comando que toque numa pasta sensível, carregar o estado do projeto no arranque da sessão, ou enviar uma notificação quando uma tarefa longa termina. A pergunta a fazer é sempre a mesma: «quero que isto aconteça de cada vez, sem depender da memória de quem quer que seja?» Se sim, é um hook.

Para a Lea, este capítulo muda a natureza do seu sistema: antes, a automatização era rápida mas exigia a sua releitura; agora é rápida e digna de confiança. É isso que tornará possível a mudança de escala dos dois próximos capítulos — só se paraleliza o que se securizou.