Oito Hooks que Garantem a Confiabilidade de Agentes IA

O CLAUDE.md é uma sugestão. Se você escreve “rode o Prettier antes de commitar”, o agente vai pular essa instrução em aproximadamente uma de cada três vezes. Instruções mais precisas não resolvem o problema. Uma taxa de conformidade de 80% não é falha do modelo. É uma limitação estrutural de colocar regras dentro da janela de contexto e torcer para o modelo seguir.

Hooks operam em um plano completamente diferente. São scripts que executam automaticamente em pontos específicos do ciclo de vida do agente, independentemente do que o modelo decide fazer. O PreToolUse dispara antes de o agente modificar um arquivo ou executar um comando. O PostToolUse dispara logo depois. O modelo não escolhe se vai rodar esses scripts ou não. Eles simplesmente rodam.

A diferença prática é imediata. Adicionar dez linhas de regras ao CLAUDE.md e adicionar um Hook ao .claude/settings.json são intervenções de natureza completamente diferente. O código de saída 2 bloqueia a ação do agente imediatamente. O código 0 deixa passar. Qualquer outro código registra um aviso mas não bloqueia. E como os hooks ficam no settings.json, você faz o commit uma vez e o time inteiro os recebe pelo git.

Os quatro guardas antes da execução

Tenho rodado hooks por mais de seis meses. Esses quatro PreToolUse sobreviveram a todos os projetos sem ser removidos nenhuma vez.

Bloquear Comandos Perigosos captura padrões destrutivos como rm -rf, git reset --hard e DROP TABLE via correspondência com regex, então retorna código de saída 2 para matar a ação antes que ela aconteça. Já vi agentes tentarem rm -rf em diretórios que não deveriam ser tocados. Sem esse hook, o estrago teria sido real.

Proteger Arquivos Sensíveis bloqueia qualquer tentativa de modificação em .env, package-lock.json, *.pem e arquivos similares. O agente nunca tem a chance de sobrescrever seu lockfile ou vazar credenciais em um commit.

Exigir Testes Antes do PR condiciona a criação de pull requests a testes passando. Configure o matcher para mcp__github__create_pull_request e o agente literalmente não consegue abrir um PR enquanto os testes não passarem. Nada de “vou corrigir os testes num PR de acompanhamento.”

Registrar Cada Comando escreve cada comando bash executado pelo agente em .claude/command-log.txt com timestamps. Três dias depois, quando algo parece errado, você consegue rastrear exatamente o que aconteceu.

Os três inspetores após a execução

Hooks PostToolUse rodam imediatamente depois de o agente modificar um arquivo. Eu encadeio três deles em sequência.

Auto-Formatação roda o Prettier em cada arquivo alterado. Para projetos Python, troque pelo Black. Para Go, use o gofmt. O formatador roda independentemente de o agente ter lembrado de formatar ou não.

Auto-Lint roda o ESLint logo depois da formatação. Se o ESLint encontra erros, o agente os vê imediatamente e corrige na mesma rodada. O número de problemas de lint que chegam à revisão humana de código cai para quase zero.

Auto-Testes roda a suíte de testes relevante após cada alteração de arquivo. Quando um teste falha, o agente sabe em segundos e tenta corrigir. Eu redireciono a saída pelo tail -5 para manter apenas o resumo, o que evita que a saída dos testes inunde a janela de contexto.

A ordem importa. Prettier primeiro, depois ESLint, depois testes. Quando um humano olha para o código, formatação e lint já passaram. Comentários de estilo na revisão de código desaparecem.

Preservando o trabalho quando o agente para

Um hook Stop cuida disso: Auto-Commit roda git add -A && git commit toda vez que o agente termina uma resposta. Cada unidade de trabalho recebe seu próprio commit. Duas tarefas nunca se misturam em um único commit.

Combine isso com git worktrees e você tem commits automáticos por branch em branches de feature. Se o agente travar ou você interrompê-lo, você nunca perde o último pedaço de trabalho.

O que não funcionou de forma limpa

Encadeamento de hooks parece elegante, mas depurar uma cadeia com falha é mais difícil do que depurar um script único. Quando o hook de auto-testes começou a falhar silenciosamente porque o executor de testes não estava instalado em um projeto novo, passei uma hora tentando entender por que o agente continuava produzindo código sem teste. O hook retornava código de saída 0 (passou) porque o script de teste em si não era encontrado, e o shell tratou “command not found” como condição não bloqueante. Tive que adicionar uma verificação explícita da existência do executor de testes antes de invocá-lo.

Performance é a outra limitação. A preocupação convencional é que muitos hooks deixam tudo lento, mas isso não é bem assim. A pergunta real é se cada hook individualmente termina em menos de 200 milissegundos. Uma rodada do Prettier em um arquivo único leva cerca de 50ms. Uma verificação do ESLint leva cerca de 80ms. Os testes variam, mas limitar o escopo aos arquivos afetados mantém a maioria das execuções rápidas. Se qualquer hook único ultrapassar um segundo, o ciclo de feedback do agente começa a parecer pesado.

Por que isso mapeia para um padrão mais amplo

O blog de Harness Engineering da OpenAI fez um ponto que agentes funcionam melhor dentro de fronteiras rígidas e estrutura previsível. A filosofia de design do React diz a mesma coisa sobre componentes: unidades composáveis com fases de ciclo de vida definidas e estado.

Hooks no Claude Code seguem a mesma abstração. Estado corresponde a sessões e memória. Hooks são as funções que intervêm nas fronteiras do ciclo de vida. PreToolUse define as fronteiras. PostToolUse torna a estrutura previsível. Stop preserva o resultado.

A linha “rode o Prettier” que eu costumava manter no CLAUDE.md sumiu. O hook roda sempre, sem precisar ser pedido.