O que é um hook, em uma frase?

É um comando que o Claude Code roda automaticamente quando um evento acontece, como antes de rodar uma ferramenta ou depois de editar um arquivo. Ele executa de forma garantida, sem depender do agente decidir, o que o torna ideal para regras que precisam valer sempre.

Qual a diferença entre um hook e o CLAUDE.md?

O CLAUDE.md sugere: guia o comportamento do agente, que pode escapar às vezes. O hook garante: roda um comando automaticamente quando o evento acontece, sem exceção. Para preferências, o CLAUDE.md basta; para regras críticas que precisam valer sempre, o hook é a ferramenta certa.

Preciso saber programar para usar hooks?

Um hook é um comando comum, como os que você rodaria no terminal, só que automático. Se você consegue descrever a regra como quando tal evento acontecer, rode tal comando, já entende a essência. Não exige linguagem nova; exige conhecer os eventos e ligar um comando a eles, o que este módulo ensina.

Todo mundo precisa de hooks?

Não. São um recurso mais avançado. Para o uso comum, o CLAUDE.md e as skills resolvem muita coisa. Os hooks brilham quando você tem uma regra crítica que não pode falhar, como bloquear um comando perigoso ou sempre formatar o código, ou quer automatizar uma tarefa repetitiva de forma confiável.

Hooks são perigosos?

Eles rodam comandos com os seus poderes no sistema, então merecem o mesmo cuidado de qualquer comando automático. Os seus próprios hooks você controla; hooks de fontes não confiáveis pedem revisão, como skills e plugins de terceiros. Com consciência, são uma ferramenta poderosa e segura de automação.

Módulo 12 - Hooks

O que é um hook

8 min de leitura · por Cesar Gargiulo, revisado pela equipe ValorFinal e GuardiaSec · Atualizado em 13/07/2026

O que você vai aprender

Explicar o que é um hook.
Entender a diferença entre garantir e sugerir.
Reconhecer a automação determinística.
Saber quando um hook é a ferramenta certa.

Quando X acontecer, faça Y

Até aqui, você aprendeu formas de orientar o Claude Code, como o CLAUDE.md, os comandos e as skills. Todas têm uma característica em comum: elas guiam o comportamento do agente, mas dependem de ele decidir seguir. Os hooks são diferentes. Um hook é um comando que o Claude Code roda automaticamente quando um evento específico acontece, e ele roda de forma garantida, sem passar pelo julgamento do agente. A lógica é sempre a mesma: quando X acontecer, faça Y. Por exemplo, quando o agente terminar de editar um arquivo, rode o formatador de código. Sempre que a edição acontece, o formatador roda, sem falta.

Essa diferença entre garantir e sugerir é o coração dos hooks. Lembre do módulo de memória: o CLAUDE.md é contexto, não uma trava, e o próprio curso avisou que, para regras que precisam acontecer sempre, o certo é usar hooks. Agora você entende por quê. Se você escreve no CLAUDE.md rode o lint antes de commitar, o agente tende a seguir, mas pode escapar numa hora ou outra. Se você configura um hook para isso, o lint roda sempre, porque é um comando automático ligado ao evento, não uma orientação que depende de boa vontade. Onde a sugestão falha em confiabilidade, o hook entrega garantia.

Diagrama mostrando um evento no Claude Code (por exemplo, um arquivo sendo editado) disparando automaticamente um comando de hook (rodar o formatador), com uma engrenagem indicando que isso acontece sempre, de forma garantida, sem passar pelo julgamento do agente. — Quando o evento acontece, o hook roda automaticamente e de forma garantida, sem depender do agente.

Por que a garantia importa

Pode parecer detalhe, mas a diferença entre sugerir e garantir muda tudo em certas situações. Pense em regras de segurança ou de qualidade que não podem falhar nunca: nunca rodar um comando destrutivo, sempre formatar o código antes de salvar, sempre registrar quem mexeu no quê. Para essas, uma sugestão que o agente segue na maioria das vezes não basta, porque a exceção é justamente o problema. O hook resolve ao transformar a regra numa lei da física do seu ambiente: aconteceu o evento, o comando roda. Não há como escapar, esquecer ou o agente decidir diferente. Essa confiabilidade absoluta é o que torna os hooks insubstituíveis para o que é crítico.

Sugestão (CLAUDE.md, skill)

Guia o comportamento do agente.
O agente decide seguir; pode escapar às vezes.
Bom para preferências e orientações.

Garantia (hook)

Roda um comando automaticamente.
Acontece sempre, sem depender do agente.
Bom para regras que precisam valer sempre.

🎮 Jogo da aula

Sugestão ou garantia?

Classifique cada necessidade conforme ela pede uma sugestão (CLAUDE.md/skill) ou uma garantia (hook).

Vale marcar que os hooks são um recurso mais avançado, e nem todo mundo precisa deles no começo. Eles brilham quando você tem uma regra crítica que não pode falhar, ou quando quer automatizar uma tarefa repetitiva de forma confiável. Para o uso comum, o CLAUDE.md e as skills já resolvem muita coisa. Mas, quando a confiabilidade absoluta importa, os hooks são a única resposta. Ao longo deste módulo, você vai aprender os momentos em que os hooks disparam, como configurá-los e como usá-los com segurança, para adicionar essa camada de garantia ao seu Claude Code quando ela for necessária.

O hook é um comando comum, só automático

Não há mágica no hook: ele é apenas um comando comum, como os que você rodaria no terminal, só que o Claude Code o dispara sozinho no momento certo. Se você sabe rodar um formatador de código pela linha de comando, você sabe o que um hook de formatação faz; a diferença é só que ele roda automaticamente depois de cada edição, em vez de você digitar. Essa simplicidade é boa: hooks não exigem uma linguagem nova nem conceitos exóticos. Se você consegue descrever a regra como quando tal evento acontecer, rode tal comando, você já entende a essência. O resto é aprender quais eventos existem e como ligar o comando a eles.

Por serem comandos comuns, os hooks herdam um cuidado importante que vamos aprofundar: eles rodam com os seus poderes no sistema. Um hook mal escrito ou vindo de fonte não confiável pode causar estrago, porque executa de verdade. Isso não é motivo para evitá-los, mas para tratá-los com o mesmo respeito que você teria com qualquer comando que roda automaticamente na sua máquina. Ao criar os seus, você tem controle total; ao adotar hooks de fora, o mesmo cuidado das skills e plugins de terceiros se aplica. Com essa consciência, os hooks são uma ferramenta poderosa e segura de automação determinística.

Teste rápido

Qual é a diferença central entre um hook e uma orientação no CLAUDE.md?

Perguntas frequentes

O que é um hook, em uma frase?: É um comando que o Claude Code roda automaticamente quando um evento acontece, como antes de rodar uma ferramenta ou depois de editar um arquivo. Ele executa de forma garantida, sem depender do agente decidir, o que o torna ideal para regras que precisam valer sempre.
Qual a diferença entre um hook e o CLAUDE.md?: O CLAUDE.md sugere: guia o comportamento do agente, que pode escapar às vezes. O hook garante: roda um comando automaticamente quando o evento acontece, sem exceção. Para preferências, o CLAUDE.md basta; para regras críticas que precisam valer sempre, o hook é a ferramenta certa.
Preciso saber programar para usar hooks?: Um hook é um comando comum, como os que você rodaria no terminal, só que automático. Se você consegue descrever a regra como quando tal evento acontecer, rode tal comando, já entende a essência. Não exige linguagem nova; exige conhecer os eventos e ligar um comando a eles, o que este módulo ensina.
Todo mundo precisa de hooks?: Não. São um recurso mais avançado. Para o uso comum, o CLAUDE.md e as skills resolvem muita coisa. Os hooks brilham quando você tem uma regra crítica que não pode falhar, como bloquear um comando perigoso ou sempre formatar o código, ou quer automatizar uma tarefa repetitiva de forma confiável.
Hooks são perigosos?: Eles rodam comandos com os seus poderes no sistema, então merecem o mesmo cuidado de qualquer comando automático. Os seus próprios hooks você controla; hooks de fontes não confiáveis pedem revisão, como skills e plugins de terceiros. Com consciência, são uma ferramenta poderosa e segura de automação.

Fontes

Seu progresso fica salvo neste aparelho. Assinantes sincronizam entre os aparelhos.

← Skills, comandos e subagentes: quando usar cada um Concluir e avançar →