El hook de pre-commit de Git evita que los agentes de codificación con IA realicen commits con documentación desactualizada.

Problema: Los agentes de codificación con IA realizan commits con documentación desactualizada

Al trabajar con asistentes de codificación con IA como Claude Code a lo largo de múltiples sesiones, los desarrolladores encuentran un problema específico: la IA realiza cambios en el código (agrega rutas, refactoriza componentes, renombra elementos) pero no actualiza los archivos de documentación como ARCHITECTURE.md y README. Esto hace que las sesiones posteriores comiencen con la IA leyendo documentación que describe código de semanas atrás.

Las consecuencias incluyen:

• Claude alucina nombres de funciones que ya no existen
• Hace referencia a endpoints de API que fueron renombrados
• Sugiere patrones que contradicen la arquitectura actual

Las advertencias de asesoramiento no funcionan porque cuando Claude está realizando un commit, nadie ve la salida de stderr.

Solución: Un hook de pre-commit bloqueante

El desarrollador creó un hook de pre-commit de Git con este flujo de trabajo:

• El hook sabe qué cambios de archivo deberían activar actualizaciones de documentación (patrones configurables por proyecto)
• Cuando Claude Code realiza un commit, el hook lo detecta a través de variables de entorno
• El hook omite intentar corregir automáticamente la documentación (lo que causaría un punto muerto al generar Claude desde dentro de Claude)
• En su lugar, sale con el código 1 y muestra un mensaje claro: "la documentación está desactualizada, actualiza estos archivos y luego reintenta"
• Claude lee el error, actualiza la documentación, reintenta el commit, y el commit se realiza

Para commits humanos, el hook llama directamente a la API de Anthropic y corrige las secciones relevantes (tomando aproximadamente 20 segundos).

Cada commit genera un archivo session-context.md con un resumen de la actividad reciente para que la siguiente sesión tenga continuidad.

Detalles de implementación

La herramienta está disponible como un paquete npm: @mossrussell/agent-guard

Características clave:

• Funciona con Claude Code, Cursor, Windsurf y Copilot
• Cero dependencias
• Disponible en: https://www.npmjs.com/package/@mossrussell/agent-guard