3 hooks pre-commit antes del review con IA

El review de código con IA se contamina rápido. Le pides a Claude Code que lea un diff de 400 líneas, y la mitad de sus comentarios son sobre comillas simples, imports sin usar o dos espacios donde debía haber cuatro. Comentarios reales, técnicamente correctos, y completamente inútiles: son cosas que una regex resolvía sola desde hace veinte años.

El problema está en lo que le entregas para revisar. Cuando el diff llega con ruido mecánico incluido, la atención del modelo se reparte entre lo que un linter arregla en 3 segundos y lo que solo un humano (o un LLM con contexto) puede juzgar.

La capa 1 de un harness de code review resuelve esto antes de que la IA vea el archivo: tres hooks pre-commit que filtran el ruido en la máquina del desarrollador, no en la conversación con el modelo.

Qué es un hook pre-commit (y qué no)

Un hook pre-commit es un script que git ejecuta antes de que un commit se concrete. Si el script devuelve exit code distinto de cero, el commit se aborta. Es un checkpoint local del lado del desarrollador.

Esto tiene dos consecuencias que la gente suele confundir:

Es distinto de CI. CI se ejecuta en el servidor después del push. El hook pre-commit se ejecuta en tu computadora, antes. Si te saltas el hook con --no-verify, git te deja pasar. En CI eso mismo bloquea el merge.
Es una comodidad para el desarrollador. Cualquiera con --no-verify lo evade. Su función real es ahorrarte tiempo; si buscas defenderte de un compañero de equipo que quiere saltárselo a propósito, CI cumple ese papel.

Con esas dos advertencias en mente, el pre-commit hook es la primera línea del harness: barato, rápido, y en el lugar correcto (antes de que el ruido llegue al PR, al revisor humano, y a la IA).

Lo que el libro dice: 3 verificaciones en el pre-commit

El libro harness-code-review dedica el capítulo 3 al primer piso del harness. La receta base para un proyecto JavaScript o TypeScript es corta:

#!/bin/bash
# harness/hooks/pre-commit.sh
set -e

# 1. Formateador
npx prettier --check . --ignore-unknown || {
  echo "Format error. Corre: npx prettier --write ."
  exit 1
}

# 2. Linter
npx eslint . --max-warnings 0

# 3. Chequeo de tipos
npx tsc --noEmit

echo "Pre-commit ok."

La versión Python es la misma idea con Ruff y mypy:

#!/bin/bash
set -e
ruff check .
ruff format --check .
mypy src/

Se activa apuntando git a la carpeta:

git config core.hooksPath harness/hooks
chmod +x harness/hooks/pre-commit.sh

Nota mental que el libro señala: el pre-commit debe ejecutarse en 5 segundos o menos. Si tarda más, la gente lo desactiva con --no-verify y el harness deja de existir. Los tests unitarios pesados van en pre-push. Los E2E van en CI. En pre-commit solo lo que da retroalimentación instantánea.

Lo que probé en mi propia máquina: el tercer hook

Las 3 verificaciones del libro cubren dos capas de ruido: formato y errores de linter/tipos. Cubren la mayoría de los diffs. Pero hay una tercera capa que la receta genérica no toca y que a mí me mordió con dientes.

En agosto de 2026 hice público un repo llamado claude-shift. Lo revisé antes de push, lo pasé por linter, lo pasé por type checker. Y unos días después me di cuenta de que había dejado un email personal y un nombre real en un archivo de configuración que había convertido a ejemplo pero no había limpiado a fondo. Formato correcto, tipos correctos, contexto humano incorrecto.

Escribí un hook para eso y lo publiqué en un repo aparte: private-lint. Es un ejecutable que se instala como pre-commit y hace dos cosas:

private-lint check --identity: verifica que el email del autor del commit esté en una lista local de emails permitidos. Si git config user.email no está configurado en el repo y git recae en el global (donde tengo mi email privado), el commit se aborta.
private-lint check --staged: escanea el diff staged buscando patrones de nombres personales, dominios internos, direcciones de email privadas. La lista de patrones reside en ~/.config/private-lint/patterns y nunca se agrega al commit (los patrones de detección son de por sí sensibles).

Mi herramienta es solo un ejemplo. La lección es que “secret leak” es el tercer hook que la receta del libro no incluye y que a mí me hizo falta después de un incidente real. Otras opciones equivalentes que se instalan igual:

gitleaks: patrones para tokens de AWS, GCP, GitHub, Slack, Stripe, y varios cientos más.
detect-secrets (Yelp): baseline system para no romperse con secretos ya presentes.
ggshield (GitGuardian): API contra su base de patrones, más pesado.

Los 3 hooks juntos: qué queda en el diff cuando la IA lo ve

Los 3 hooks, ejecutándose antes del commit:

Los 3 hooks pre-commit filtran ruido antes de que la IA lea el diff

Cuando esas 3 verificaciones pasan, el diff que llega al PR (y al agente de IA que lo revise) ya no contiene:

Espacios en blanco raros, indentación inconsistente, imports desordenados
any implícitos, variables no usadas, errores de tipo obvios
Emails personales, tokens de API en texto claro, nombres reales que debían ser genéricos

Lo que sí contiene: lógica, estructura de datos, decisiones de diseño. Eso es exactamente lo que Claude Code o CodeRabbit sabe leer con contexto. Y también es lo que un revisor humano no puede automatizar.

Dónde este esquema NO ayuda

Este harness no aporta nada en estos escenarios:

PRs de una sola línea que tocan lógica. Si cambias un if x > 0 por if x >= 0, ni prettier ni eslint ni private-lint tienen nada que decir. El único revisor que sirve ahí es la IA con contexto o el humano. Los 3 hooks pasan silenciosos y no aportan.

Refactors masivos generados por la propia IA. Si Claude Code te reescribe 800 líneas de una función, los 3 hooks pasan porque el modelo ya sabe formatear y usar tipos. Pero eso no significa que el refactor sea correcto. Los hooks te aseguran un mínimo, y su alcance termina ahí.

Repos que ya tienen CI estricto y bloqueo de merge. Si tu CI ya ejecuta prettier, eslint y type-check en cada PR, agregar hooks locales es opcional. Ganas velocidad de retroalimentación (5 segundos vs 3 minutos) pero no ganas seguridad. En equipos donde el pre-commit siempre se saltea con --no-verify, mover todo a CI es más honesto.

Qué cambia para el lector

Si escribes código con Claude Code, Cursor o Copilot Autofix revisando tus PRs, el consejo cabe en tres pasos:

Copia el script de pre-commit del capítulo 3 (o su equivalente para tu stack) y actívalo con git config core.hooksPath.
Agrega un secret-scanner (gitleaks, detect-secrets, o el que sea). Configura una allowlist local para tus ejemplos legítimos.
Mide tu propio antes/después. No confíes en el “40% menos ruido” que verás en artículos de blog (incluido este si me hubieras dejado escribirlo así): el número depende de qué escribías antes de tener los hooks.

El resultado que sí puedo garantizar cualitativamente: la IA deja de escribir comentarios sobre imports y empieza a comentar sobre lógica. El mérito está en lo que le entregas para revisar, más que en la propia IA.

Relación con el resto del harness

Este artículo es el capítulo 1 de un modelo de 3 capas que ya está escrito completo aquí:

Code review IA en 3 capas: hooks + IA + humano — el pipeline completo.
Claude Code vs ChatGPT Codex — cuando la capa 2 es un agente vs cuando es una función de plataforma.

Los hooks pre-commit preparan el terreno para que el review con IA valga los tokens que gasta.

Cierre

Tres hooks. Formato, linter, secret leak. Cinco segundos antes del commit. Y de repente los comentarios de tu agente de código dejan de parecerse a los de un linter con acceso a un LLM y empiezan a parecerse a los de alguien que leyó tu código.

Es división del trabajo: dale a la máquina lo mecánico y a la IA lo contextual. La receta del libro se ocupa de los primeros dos hooks. El tercero lo aprendí a golpes, y por eso está en un repo aparte.

Referencias

Zenn Book: harness-code-review, capítulo 3
Repo private-lint (público, MIT)
gitleaks, detect-secrets, ggshield
git-scm.com — Customizing Git Hooks

ken imoto · WebRTC & Voice AI engineer · kenimoto.dev