Pular para o conteúdo
LabS Atlas
Agentic AI
Entrar

Hooks de Verificação em Agentes de Código

Ir para notas que citam esta
atualizado há 25 diasEntre para perguntar ao Labinho sobre esta notaO Labinho é o assistente que responde com as notas e as sessões do LabS e mostra de onde tirou cada resposta.

Hooks de verificação são scripts que rodam sozinhos antes ou depois de uma ação do agente de código, checando o que foi feito e bloqueando ou corrigindo o comportamento indesejado.

Eles materializam a frente de verificação do harness. A diferença para uma instrução escrita é de natureza: uma regra num arquivo markdown é uma sugestão que o modelo pode ignorar, e quando ignora o resultado aparece como alucinação. Um hook é código determinístico executado em pontos fixos do ciclo do agente. A checagem não depende de o modelo lembrar ou querer verificar; ela acontece de qualquer jeito, e o modelo recebe o resultado.

Isso separa hooks dos Guardrails feitos por prompt. Pedir no prompt que o agente não faça algo continua sendo pedir. O hook deixa de pedir e passa a impedir, que é o sentido do cabresto na metáfora do harness.

Onde ficam e quando disparam

No Claude Code, hooks são configurados no arquivo de settings e apontam para scripts, em geral JavaScript. Podem ser locais, valendo só para o projeto, ou globais, valendo para todos os projetos da máquina. Existe uma listagem oficial dos pontos do fluxo em que um hook pode ser disparado, como antes ou depois do uso de uma ferramenta de escrita ou edição, no início de uma sessão e ao fim da execução de um comando.

Exemplos de hooks úteis

  • Checagem de tipos após edição: sempre que o agente usa a ferramenta de escrever ou editar num arquivo TypeScript, um script roda lint sobre o arquivo alterado. Se o modelo alucinou uma sintaxe ou desconhece a versão atual da linguagem, o erro volta para ele, que analisa e reescreve. Código sintaticamente errado não fica no projeto.
  • Sincronia de dependências: uma mudança no package.json dispara a checagem de que a nova dependência também está refletida nos arquivos Docker do projeto.
  • Migration imutável: uma migration de banco já executada não pode ser editada. O hook nega a edição e orienta o agente a gerar uma migration nova. Na mesma linha, um hook pode impedir um push forçado no git.
  • Guardrail de stack: antes de instalar um pacote, o hook consulta uma lista de bloqueio do time, por exemplo SDKs de provedores de IA diferentes do provedor já definido, e explica ao agente por que bloqueou. Assim ele não troca de provedor sem permissão.
  • Início de sessão: antes da primeira resposta, o hook injeta contexto buscado automaticamente, como a documentação de design, o schema do banco se ele estiver rodando e o git status. O custo é consumir mais janela de contexto; o ganho é não precisar rodar esses comandos à mão.
  • Notificação: um som toca quando o agente termina ou faz uma pergunta, para que ninguém perca tempo sem perceber que ele está esperando.

O mesmo pedido com e sem hook

Um experimento com dois projetos quase idênticos mostra o efeito. No projeto com harness, o pedido de alterar uma migration já aplicada levou o agente a consultar a skill do ORM, tentar a edição e ser barrado pelo hook de guarda. Ele então apresentou um plano alternativo e gerou uma migration nova, sem tocar na antiga. No projeto sem esses hooks e sem skills, um pedido equivalente, remover a tabela de usuários direto na migration existente, foi simplesmente obedecido: a migration foi editada e a tabela sumiu.

Por que o modelo não recusa sozinho

Modelos são treinados para obedecer e agradar quem pede. Sem uma barreira explícita, um pedido problemático é executado. O hook é essa barreira.

Os hooks complementam os arquivos de contexto: o contexto diz ao agente como trabalhar, e o hook garante que as regras que não podem ser quebradas não sejam.