Agentes· atualizado em · 4 min de leitura· Redação Invision

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

Geoffrey Huntley relata que um hook de pré-commit que bloqueia chamadas diretas a módulos de observabilidade fez o agente passar a usar a biblioteca de…

Resumo: 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.

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'.
Nesta matéria

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.

agentes de códigopré-commitengenharia de softwareagents.mdobservabilidade

Fonte original: Quoting Geoffrey Huntley (Simon Willison). Matéria escrita pela redação da Invision a partir dessa notícia. Versão em texto.