# Geoffrey Huntley: hooks de pré-commit ensinam agentes de código a usar bibliotecas internas

> Geoffrey Huntley descreveu uma técnica prática para alinhar agentes de código às convenções de um repositório: um hook de pré-commit que falha quando detecta chamadas diretas a módulos de observabilidade, injetando um prompt que orienta o agente a usar a biblioteca de diagnósticos. A abordagem importa agora porque mostra como regras executáveis podem substituir instruções em arquivos que tendem a divergir do código real.

Publicado em 2026-10-13 · https://invision.dreamvision.com.br/blog/geoffrey-huntley-hooks-de-pre-commit-ensinam-agentes-de-codigo-a-usar-biblioteca

## Pontos-chave
- Geoffrey Huntley usou um hook de pré-commit para impedir chamadas que contornam a biblioteca de diagnósticos.
- O hook falha o commit e injeta um prompt dizendo ao agente qual biblioteca usar.
- Huntley argumenta que atualizar o AGENTS.md sozinho deixa um delta que tende a crescer.
- Segundo o relato, o resultado com o hook passou a ser 'dez de dez'.

## O que Geoffrey Huntley propôs?
Em uma citação reunida por Simon Willison, Geoffrey Huntley descreve um problema recorrente ao trabalhar com agentes de código: o agente não usa a biblioteca de diagnósticos do projeto.

A solução apresentada não é reescrever instruções nem tentar manter o AGENTS.md perfeitamente sincronizado. Em vez disso, Huntley cria um hook de pré-commit que analisa o git diff em busca de chamadas diretas a módulos de observabilidade que contornem a biblioteca de diagnósticos.

Quando o hook encontra esse padrão, o commit falha e um prompt é injetado informando ao agente que ele deve usar a biblioteca correta. Segundo o relato, o resultado passou a ser 'dez de dez'.


## Por que atualizar o AGENTS.md não basta?
Huntley explica que, se o agente não estiver usando a biblioteca, seria possível introspecção e atualização do AGENTS.md. Mas ele aponta que sempre resta um delta entre o que está escrito e o comportamento real, e esse delta tende a crescer.

O arquivo de instruções é estático, enquanto o código muda a cada commit. A cada alteração, a chance de o documento ficar defasado aumenta, e o agente passa a agir com base em uma descrição que já não corresponde ao repositório.

Esse é o ponto central do argumento: documentação em texto é útil, mas não tem mecanismo próprio para impedir desvios.


## Como funciona o hook de pré-commit como professor do agente?
O hook funciona como uma verificação automatizada no momento do commit. Ele inspeciona o diff e procura chamadas que ignorem a camada de diagnósticos.

Ao encontrar uma violação, o commit é rejeitado. Junto com a falha, o agente recebe uma mensagem que explica qual biblioteca usar e por quê.

Na prática, o agente aprende pelo atrito: a convenção deixa de ser uma recomendação em um arquivo e passa a ser uma regra verificada pelo próprio fluxo de versionamento.

- A regra é aplicada no momento do commit, não em uma revisão posterior.
- O agente recebe o feedback no contexto da tarefa que está executando.
- A correção é repetível, porque o hook roda do mesmo jeito em cada alteração.

## Quais são os limites dessa abordagem?
A notícia não detalha como o hook identifica as chamadas diretas aos módulos de observabilidade, nem se ele cobre todos os casos. Também não informa em qual repositório ou projeto a técnica foi aplicada, nem qual biblioteca de diagnósticos estava em uso.

O relato se concentra no princípio: transformar uma convenção em verificação executável. Detalhes de implementação, cobertura de linguagens e manutenção do próprio hook não são descritos.

Também não há indicação de que a técnica elimine totalmente a necessidade de documentação. O argumento é que o hook reduz a dependência de instruções que se degradam com o tempo.


## O que isso ensina sobre instruções para agentes?
A lição prática é que instruções em linguagem natural funcionam melhor quando acompanhadas de mecanismos que verificam o resultado. O hook não pede que o agente lembre da regra: ele mostra a consequência de ignorá-la.

Para equipes que já usam linters, testes e verificações de estilo, o hook de pré-commit é uma extensão natural desse modelo. A diferença é que o feedback é direcionado ao próprio agente, dentro do ciclo de edição.

Huntley resume a ideia na frase que dá título à sua publicação: ninguém deveria digitar código à mão, e o que resta são justamente esses mecanismos de controle.

- Prefira regras verificáveis a instruções apenas descritivas.
- Faça o feedback chegar no momento em que o agente pode agir sobre ele.
- Trate o arquivo de instruções como complemento, não como garantia.

## O que isso muda para quem usa IA
Para quem desenvolve com modelos de linguagem, o caso reforça que a qualidade do resultado depende também do ambiente ao redor do agente: hooks, testes e verificações que delimitam o comportamento aceitável.

A Invision, API multimodelo da Dream Vision, permite acessar vários modelos por uma única chave, com saldo em reais. Isso ajuda a testar diferentes agentes sobre o mesmo conjunto de regras executáveis, sem trocar de integração a cada experimento.

A técnica descrita por Huntley não promete resolver todos os desvios, mas oferece um caminho concreto para quem quer que agentes sigam convenções internas de forma consistente.


## Perguntas frequentes
### O que Geoffrey Huntley fez para o agente usar a biblioteca de diagnósticos?
Ele criou um hook de pré-commit que verifica o git diff e falha o commit quando encontra chamadas diretas a módulos de observabilidade que contornam a biblioteca de diagnósticos. Junto com a falha, um prompt orienta o agente a usar a biblioteca correta.

### Por que não basta atualizar o AGENTS.md?
Segundo Huntley, sempre existe um delta entre o que está escrito no arquivo e o comportamento real do código, e esse delta tende a crescer. O hook aplica a regra de forma verificável a cada commit.

### O hook de pré-commit garante que o agente nunca erre?
A notícia não afirma isso. O relato descreve um caso em que o resultado passou a ser 'dez de dez', mas não detalha a cobertura do hook nem sua implementação completa.

### A notícia informa qual projeto ou biblioteca foi usada?
Não. O texto não especifica o repositório, a linguagem nem o nome da biblioteca de diagnósticos envolvida.

### Qual é a ideia central da citação?
Transformar convenções de código em verificações executáveis no fluxo de commits, em vez de depender apenas de instruções em texto que se desatualizam.

Fonte original: [Quoting Geoffrey Huntley](https://simonwillison.net/2026/Oct/13/geoffrey-huntley/) (Simon Willison).
