Nível 3 — Automação e escala · Módulo 3.2 — Hooks: da recomendação à garantia

3.2.1 · Por que hooks existem

4 min de vídeo TODOS

Objetivo: ao final, o consultor distingue uma instrução que o Claude geralmente segue de um código que sempre roda, e identifica em quais situações de projeto essa diferença deixa de ser teórica.

O que você precisa levar desta aula

CLAUDE.md influencia; hook garante. O hook é um comando de shell que o próprio Claude Code executa num ponto fixo do ciclo de vida — o modelo não é consultado e não pode pular.
O ganho de hook aparece justamente onde você não está olhando: execução headless, routine agendada, subagente em paralelo, sessão de um colega novo no projeto.
Hook roda com as permissões completas do seu usuário e pode ser distribuído por projeto, por managed policy ou por plugin — quem escreve decide quem herda a garantia, e por isso hook de terceiro precisa de revisão.

Continuando a aula 2.3.1

O Nível 2 estabeleceu a distinção e parou ali. Este módulo retoma exatamente do mesmo ponto:

	CLAUDE.md (guia)	Hook (configuração)
Onde vive	No contexto da sessão	Em `settings.json`, fora do contexto
Quem executa	O modelo decide se segue	O Claude Code roda, sempre
Garantia	Nenhuma — depende de atenção	Determinística no ponto onde está registrado
Falha típica	Arquivo cresce, regra antiga para de ser seguida	Script mal escrito, exit code errado (aula 3.2.4)
Custo de contexto	Consome contexto a cada sessão	Zero, até o hook devolver algo

A leitura prática: convenção, preferência e contexto de projeto continuam no CLAUDE.md. Regra que nunca pode ser violada vira hook. E as duas coisas convivem — o hook barra, e o CLAUDE.md explica por que a regra existe.

Onde um hook pode morar

Local	Escopo	Compartilhável
`~/.claude/settings.json`	Todos os seus projetos	Não — é local à sua máquina
`.claude/settings.json`	Um projeto	Sim — vai para o repositório
`.claude/settings.local.json`	Um projeto	Não — fica fora do versionamento
Managed policy settings	Organização inteira	Sim — controlado pela administração
Plugin `hooks/hooks.json`	Enquanto o plugin está ativo	Sim — módulo 3.3
Frontmatter de skill ou subagente	Enquanto o componente está ativo	Sim

Os níveis somam, não se substituem: um hook de projeto não apaga um hook de managed policy. E disableAllHooks não desliga hooks que vieram de managed settings.

Onde a diferença aparece de verdade

Situação	Você está olhando?	O que garante a regra
Sessão interativa, você acompanhando	Sim	Você mesmo — você vê e interrompe
Sessão headless em pipeline (módulo 3.5)	Não	Só o hook
Routine agendada rodando de madrugada	Não	Só o hook
Subagente trabalhando em paralelo	Não de perto	Só o hook — que também dispara lá dentro
Consultor novo no projeto, primeira semana	Não	Só o hook

Inspecionar o que está configurado

/hooks

Abre o navegador de hooks: lista de eventos, contagem de hooks por evento e, ao selecionar um, o detalhe — evento, matcher, tipo, arquivo de origem e comando. É somente leitura: para adicionar, alterar ou remover, edite o JSON de settings (ou peça ao Claude para editar).

Regra Wayon Hook que implementa política — ambiente, dado pessoal, nomenclatura de transporte — vive no .claude/settings.json do projeto ou em managed policy, nunca só no settings pessoal de quem escreveu. Uma garantia que existe só na máquina de uma pessoa não é uma garantia da consultoria. Hook vindo de fora (repositório público, plugin de terceiro) passa pela mesma revisão de um servidor MCP: alguém lê o script antes de ele entrar em máquina com dado de cliente.

📖 Hooks — referência oficial · Automatizar ações com hooks (guia)

Quiz — 4 questões

1.A regra "nunca execute comando que toque QAS ou PRD do MRD" está no CLAUDE.md do Meridiano há meses e foi seguida em quase todas as sessões. Numa delas, não foi. Qual leitura é correta?

a)CLAUDE.md nunca oferece garantia — ele influencia a decisão do modelo, e uma regra que "quase sempre" é seguida continua sendo uma regra sem garantia
Correto. É a distinção que abre o módulo: guia influencia, hook garante.
b)A regra precisa ser reescrita em linguagem mais forte, em maiúsculas e no topo do arquivo
Melhora a chance marginalmente, mas o mecanismo continua sendo atenção disputada — nenhuma redação transforma guia em garantia.
c)O modelo tem um bug: uma regra explícita no CLAUDE.md deveria ser sempre obedecida
Não é bug, é a natureza documentada do arquivo — ele entra no contexto, e o que está no contexto é ponderado, não executado.

Ver resposta e por quê

✅a) Correto. É a distinção que abre o módulo: guia influencia, hook garante.

❌b) Melhora a chance marginalmente, mas o mecanismo continua sendo atenção disputada — nenhuma redação transforma guia em garantia.

❌c) Não é bug, é a natureza documentada do arquivo — ele entra no contexto, e o que está no contexto é ponderado, não executado.

2.Qual descrição de hook está tecnicamente correta?

a)É uma seção especial do CLAUDE.md, com prioridade maior que o resto do arquivo
Hook não fica no CLAUDE.md nem no contexto — é configuração em settings.json.
b)É uma instrução que o Claude lê no início da sessão e se compromete a seguir
Isso descreve exatamente o que hook não é. Se dependesse de o modelo ler e se comprometer, seria guia outra vez.
c)É um comando que o Claude Code executa num ponto fixo do ciclo de vida, sem consultar o modelo
Correto. Quem dispara é o Claude Code, não o modelo — e é por isso que a execução é determinística.

Ver resposta e por quê

❌a) Hook não fica no CLAUDE.md nem no contexto — é configuração em settings.json.

❌b) Isso descreve exatamente o que hook não é. Se dependesse de o modelo ler e se comprometer, seria guia outra vez.

✅c) Correto. Quem dispara é o Claude Code, não o modelo — e é por isso que a execução é determinística.

3.Em qual destas situações a diferença entre CLAUDE.md e hook tem a maior consequência prática?

a)Você conduzindo uma sessão interativa, lendo cada proposta antes de aprovar
É a situação de menor consequência: nessa configuração você mesmo funciona como o portão.
b)Uma routine agendada rodando de madrugada, sem ninguém acompanhando
Correto. Sem supervisão humana, o hook é o único portão que sobra.
c)Você escrevendo o CLAUDE.md do projeto pela primeira vez
É o momento de decidir o que vira hook, mas a consequência só se materializa na execução — especialmente na não supervisionada.

Ver resposta e por quê

❌a) É a situação de menor consequência: nessa configuração você mesmo funciona como o portão.

✅b) Correto. Sem supervisão humana, o hook é o único portão que sobra.

❌c) É o momento de decidir o que vira hook, mas a consequência só se materializa na execução — especialmente na não supervisionada.

4.Você escreveu um hook que barra comandos em QAS e PRD e o colocou no seu ~/.claude/settings.json. Um colega clona o projeto do Meridiano e começa a trabalhar. O que acontece? ---

a)O hook vai com o projeto, porque foi escrito para o projeto
O escopo é definido pelo arquivo onde o hook está, não pela intenção de quem escreveu — ~/.claude/settings.json é local à sua máquina.
b)O hook é replicado automaticamente para o time na primeira sessão dele
Não existe replicação automática de settings pessoais; a distribuição é explícita, por projeto, managed policy ou plugin.
c)O colega fica sem a garantia — o hook precisa estar no .claude/settings.json do projeto, em managed policy ou num plugin
Correto. Garantia que só existe numa máquina não é garantia da consultoria.

Ver resposta e por quê

❌a) O escopo é definido pelo arquivo onde o hook está, não pela intenção de quem escreveu — ~/.claude/settings.json é local à sua máquina.

❌b) Não existe replicação automática de settings pessoais; a distribuição é explícita, por projeto, managed policy ou plugin.

✅c) Correto. Garantia que só existe numa máquina não é garantia da consultoria.