O hook de pre-commit do Git impede que agentes de IA de codificação façam commits com documentação desatualizada.

Problema: Agentes de codificação de IA fazem commit de código com documentação desatualizada

Ao trabalhar com assistentes de codificação de IA como o Claude Code em múltiplas sessões, os desenvolvedores encontram um problema específico: a IA faz alterações no código (adicionando rotas, refatorando componentes, renomeando coisas) mas não atualiza arquivos de documentação como ARCHITECTURE.md e README. Isso faz com que sessões subsequentes comecem com a IA lendo documentação que descreve código de semanas atrás.

As consequências incluem:

• Claude alucinando nomes de funções que não existem mais
• Referenciando endpoints de API que foram renomeados
• Sugerindo padrões que contradizem a arquitetura atual

Avisos de advertência não funcionam porque quando o Claude está fazendo commit, ninguém vê a saída stderr.

Solução: Um hook de pré-commit bloqueador

O desenvolvedor criou um hook de pré-commit do Git com este fluxo de trabalho:

• O hook sabe quais alterações de arquivo devem acionar atualizações de documentação (padrões configuráveis por projeto)
• Quando o Claude Code faz commit, o hook o detecta através de variáveis de ambiente
• O hook evita tentar corrigir automaticamente a documentação (o que causaria um deadlock ao gerar Claude de dentro do Claude)
• Em vez disso, ele sai com código 1 e exibe uma mensagem clara: "docs estão desatualizados, atualize estes arquivos, depois tente novamente"
• Claude lê o erro, atualiza a documentação, tenta o commit novamente, e o commit é realizado

Para commits humanos, o hook chama a API da Anthropic diretamente e corrige as seções relevantes (levando aproximadamente 20 segundos).

Cada commit gera um arquivo session-context.md com um resumo da atividade recente para que a próxima sessão tenha continuidade.

Detalhes de implementação

A ferramenta está disponível como um pacote npm: @mossrussell/agent-guard

Características principais:

• Funciona com Claude Code, Cursor, Windsurf e Copilot
• Zero dependências
• Disponível em: https://www.npmjs.com/package/@mossrussell/agent-guard