Ganchos Git de Claude Code para commits más seguros y revisiones más rápidas

Por qué la automatización en el momento del commit importa

La mayoría del dolor en las revisiones no viene del código “difícil”. Viene de errores evitables que se cuelan en un commit: una bandera de depuración activada, un archivo sin formatear que genera diffs ruidosos, una prueba que no se actualizó o un secreto copiado en una configuración. Cada uno es pequeño, pero juntos convierten una revisión limpia en un ida y vuelta lento.

La automatización en el momento del commit es el lugar más fácil para detener eso. Cuando las comprobaciones se ejecutan justo antes de crear un commit, atrapan problemas mientras el cambio aún está fresco en tu cabeza. Arreglar un error toma segundos porque ya estás en el contexto del trabajo. Compáralo con encontrarlo dos días después en un pull request, tras más commits y con el revisor preguntando qué sucedió.

Los ganchos de Git son una herramienta práctica porque se ejecutan localmente, sin esperar a CI. Pero no son magia. Los ganchos se pueden omitir, configurar mal o ser inconsistentes entre máquinas si tu equipo no los estandariza. Tampoco garantizan calidad por sí solos. Piensa en ellos como guardarraíles, no portones.

Donde más ayudan es en prevenir el “impuesto de revisión”, ese feedback repetitivo y de bajo valor que sigue apareciendo. Ejemplos comunes: cadenas sensibles que parecen tokens, ruido de formateo y lint, comprobaciones básicas de “¿corriste las pruebas correctas?” y resúmenes cortos que ayudan al revisor a entender la intención.

Aquí es donde los ganchos de Claude Code encajan bien: pueden hacer el trabajo aburrido de verificación y añadir un poco de contexto legible por humanos en el momento exacto en que haces el commit.

Poner expectativas claras importa. Mantén los ganchos locales rápidos y predecibles para que la gente no los odie. Comprobaciones rápidas pertenecen a tu laptop; las lentas, después. Una buena división es segundos en el momento del commit y minutos en CI. Si un gancho tarda tanto que alguien usa “skip” con frecuencia, deja de proteger tu repo.

Un ejemplo simple: cambias un módulo y refactorizas un par de funciones. Sin automatización, el revisor ve 400 líneas movidas, no se mencionan pruebas y tiene que preguntar cosas básicas. Con comprobaciones en el commit, el commit está formateado, se ejecutó un conjunto relevante de pruebas y el mensaje incluye un resumen corto. La revisión empieza donde debe: en el diseño, no en la limpieza.

Qué añade Claude Code a los ganchos de Git

Los ganchos de Git son excelentes para comprobaciones simples, pero normalmente se quedan en reglas sí-o-no: “¿está el archivo formateado?” o “¿corriste el linter?”. Claude Code puede añadir una capa ligera de juicio leyendo tu diff staged y unos archivos relacionados, luego tomando decisiones que se asemejan más a cómo los humanos revisan cambios.

Con los ganchos de Claude Code, el gancho puede mirar lo que realmente cambiaste, no solo lo que existe en el repo. Eso hace la automatización más selectiva. Puede enfocarse en módulos tocados, archivos de configuración editados y nuevas variables de entorno, en lugar de tratar cada commit como una build completa.

Tareas prácticas donde “leer el diff y pensar” rinde:\n

• Señalar secretos probables (claves API, tokens, claves privadas), incluso cuando están ligeramente ofuscados o divididos en líneas.\n- Imponer formateo con contexto, por ejemplo, ejecutando formateadores solo en archivos staged y avisando cuando un formateador causaría un gran churn no relacionado.\n- Sugerir o requerir pruebas en función de lo que cambió (por ejemplo, “tocaste la lógica de pagos, ejecuta estos unit tests”) en lugar de “ejecuta todo”.\n- Generar un breve resumen para el revisor a partir del diff: qué cambió, por qué, áreas de riesgo y qué verificar.\n Las restricciones importan porque un gancho lento se convierte en un gancho omitido. Mantén el objetivo pequeño: añade guardarraíles que atrapen errores comunes temprano, no un segundo sistema CI en cada commit.

Velocidad y fiabilidad primero

Una buena regla: si no puede terminar en unos segundos, probablemente pertenece a CI o a un pre-push. Muchos equipos ejecutan comprobaciones locales rápidas en el commit y dejan suites más pesadas para después.

Planifica modos de fallo. Si una llamada a un modelo agota tiempo, decide si bloquear el commit o recurrir a una comprobación más simple. Un fallback mantiene el flujo predecible y evita que la gente aprenda a desactivar los ganchos.

Privacidad y offline vs online

Algunas configuraciones llaman a un modelo hospedado; otras corren en un entorno más aislado. Decide qué código puede salir de la máquina del desarrollador (si es que puede) y limita lo que envías. El diff staged más un pequeño conjunto de archivos referenciados suele ser suficiente.

Si trabajas con repositorios sensibles, sé explícito sobre dónde corre el análisis y qué se registra. Un ejemplo concreto: si un commit añade un valor de config como STRIPE_SECRET=..., el gancho puede detener el commit, explicar qué parece arriesgado y sugerir moverlo a un gestor de secretos o a un archivo env local antes de que llegue al remoto.

Elige los ganchos adecuados y mantenlos rápidos

Los ganchos de Git solo son útiles si la gente los mantiene activados y no aprende a temer los commits. El truco es escoger el gancho correcto para la tarea adecuada y mantener cualquier cosa lenta fuera del camino crítico.

Un mapa simple de dónde suelen pertenecer las comprobaciones:

• pre-commit: comprobaciones rápidas y locales que bloquean problemas obvios (formateo, escaneo de secretos, lint rápido)\n- commit-msg: comprobaciones que solo necesitan el mensaje (ID de ticket, longitud, formato convencional)\n- pre-push: trabajo más pesado que aún vale la pena atrapar antes de que llegue al repo compartido (tests más lentos, comprobaciones de tipos, build)\n Cuando añades ganchos de Claude Code, trátalos como un revisor útil que aparece al instante, no como un cuello de botella. Pon cualquier cosa que necesite llamadas de red, suites completas de tests o análisis largos en pre-push o CI, no en pre-commit.

Una manera práctica de decidir qué ejecuta dónde es ordenar las comprobaciones por velocidad e impacto. Si atrapa problemas de alto riesgo (como claves filtradas) y puede correr en uno o dos segundos, pertenece a pre-commit. Si tarda 30–90 segundos, muévela a pre-push o ejecútala solo cuando cambian ciertos archivos.

Los equipos también necesitan una postura clara sobre la aplicación. En un repo personal, los ganchos opt-in pueden estar bien. En un repo de equipo, es común hacer obligatorios los básicos (secretos, formateo, reglas de mensaje de commit) y mantener las comprobaciones más pesadas como consultivas localmente, mientras CI sigue siendo la puerta final.

La salida del gancho importa más de lo que parece. Un gancho que falla debe decir qué pasó y qué hacer a continuación. Mantén los mensajes cortos y específicos. Muestra el archivo y la línea exacta cuando sea posible, da un único comando claro para arreglarlo, explica cómo omitir solo para emergencias reales (y cuándo no hacerlo), y evita logs enormes a menos que el usuario pida “verbose”.

Ejemplo: si exportas un proyecto desde Koder.ai y empiezas a commitear localmente, un pre-commit rápido puede detectar un token de API copiado de inmediato, mientras que pre-push ejecuta la regla más lenta de “solo tests para módulos cambiados” antes de que alguien vea la rama.

Bloquea secretos antes de que se commiteen

Un secreto es cualquier cosa que permita a alguien actuar como tú o acceder a sistemas privados. Piensa en tokens de API, secretos de OAuth, claves cloud, contraseñas de base de datos, URLs privadas con credenciales, claves de firma e incluso credenciales de prueba “temporales”. Un commit accidental puede terminar en un fork, un log de CI o un diff pegado, y entonces deja de ser temporal.

La victoria más fácil es escanear solo lo que estás a punto de commitear. Un gancho debe comprobar cambios staged (el index), no todo tu repo. Eso lo mantiene rápido y evita ruido de archivos antiguos que no tocaste. También hace que el feedback sea justo: “este commit incluye un problema” en lugar de “tu repo tuvo un problema alguna vez”.

Cosas comunes para marcar temprano incluyen tokens de alta entropía (cadenas largas que parecen aleatorias), formatos conocidos de claves (claves AWS, tokens de GitHub, JWTs), patrones como password=... o api_key: ... en config, URLs privadas con credenciales embebidas y archivos .env o configs de producción copiados.

Los falsos positivos ocurren, sobre todo con datos de prueba, hashes o docs de ejemplo. Implementa una allowlist para que la gente pueda seguir adelante sin desactivar la comprobación. Mantén la allowlist estrecha: rutas de archivos exactas para fixtures o marcadores explícitos como “dummy” o “example” que tu detector reconozca.

Cuando se encuentra un secreto, falla el commit con un mensaje que diga qué hacer a continuación. Los ganchos de Claude Code pueden hacer esto más amigable produciendo una explicación corta basada en el diff, pero lo clave son acciones siguientes claras y seguras:

ERROR: Possible secret detected in staged file: config/app.yaml (line 12)
Reason: looks like an API token
Next steps:
1) Remove it from the change or move it to env vars
2) Rotate the token (assume it is compromised)
3) Re-stage and retry commit
If this is a false positive, add a narrow allowlist rule in .secrets-allowlist

Un ejemplo concreto: alguien actualiza una config backend y añade TEMP_API_KEY para que una característica funcione en dev. El gancho detiene el commit, sugiere moverlo a una variable de entorno y les recuerda rotar la clave si era real. Es una pequeña interrupción que evita una limpieza grande después.

Imponer formateo sin ralentizar a la gente

Las peleas por el formateo desperdician tiempo del revisor, pero los ganchos lentos son una vía rápida para que los ganchos se desactiven. El punto óptimo son reglas simples, una herramienta por lenguaje y tocar solo lo que vas a commitear.

Elige un formateador único por lenguaje y hazlo la fuente de la verdad. Dos formateadores que discrepen (o un formateador más un linter que reescriba código) crearán diffs ruidosos y churn infinito. Mantenlo aburrido: un formateador JS/TS, uno Go, uno Dart. Asegúrate de que todos usen las mismas versiones para que la salida del gancho sea estable entre máquinas.

La mayor ganancia de velocidad es formatear solo archivos staged. Formatear todo el repo en cada commit es la razón principal por la que los equipos se quejan de pre-commit. Un enfoque solo-stage también mantiene el diff enfocado en lo que cambiaste, que es exactamente lo que quieren los revisores.

Un conjunto práctico de elecciones que mantiene los commits rápidos:\n

• Ejecuta formateo en archivos staged solamente.\n- Usa auto-fix para cambios seguros (espaciado, comillas, orden de imports).\n- Falla rápido cuando se necesita una decisión humana (regla que puede cambiar comportamiento).\n- Mantén la salida del formateador silenciosa salvo que cambie algo.\n- Cachea cuando sea posible, pero nunca a costa de la corrección.\n Auto-fix vs fallar es preferencia de equipo, pero un enfoque mixto funciona bien. Auto-fix evita el bucle “commit, falló, re-ejecutar, commit otra vez” para ediciones mecánicas. Fallar puede ser mejor cuando quieres que la gente vea el problema y elija una dirección. Si fallas, imprime un único comando que cualquiera pueda seguir en 10 segundos.

Estandariza las pequeñas cosas que causan ruido entre plataformas. Finales de línea y espacios finales son los habituales, sobre todo cuando la gente cambia entre Windows, macOS y CI.

Una política simple que raramente causa problemas:\n

• Forzar finales de línea LF en el repo.\n- Eliminar espacios finales en líneas modificadas.\n- Asegurar que los archivos terminen con una nueva línea.\n- Omitir formateo para archivos generados y directorios vendor.\n Donde los ganchos de Claude Code pueden ayudar es en el pegamento: detectar qué archivos staged necesitan qué formateador, ejecutarlos en el orden correcto y explicar fallos en lenguaje llano. Por ejemplo, si alguien stageda un archivo Go y uno TS, el gancho puede formatear cada uno con la herramienta correcta, volver a hacer stage de los resultados y luego mostrar una nota corta como “2 archivos reformateados, sin cambios de comportamiento”. Los revisores ven diffs más limpios y los desarrolladores no se sienten castigados por commitear a menudo.

Requerir pruebas para lo que cambiaste

Una regla simple hace los commits más seguros sin volverlos dolorosos: ejecuta solo las pruebas que coinciden con lo que stagedaste. Cuando el gancho mira el diff staged (no tu working tree), evita alarmas falsas por archivos a medio terminar.

Comienza detectando qué áreas fueron tocadas. La mayoría de repos tiene una estructura natural: paquetes, servicios, apps o módulos. Un gancho puede leer git diff --cached --name-only y mapear esas rutas a un pequeño conjunto de comandos de test.

Aquí hay algunas reglas de mapeo que siguen siendo comprensibles cuando vuelves a ellas más tarde:\n

• web/ o frontend/ -> ejecutar npm test (o el comando de objetivo más pequeño que tengas)\n- api/ o server/ -> ejecutar tests unitarios backend (omitir integración por defecto)\n- mobile/ -> ejecutar tests rápidos de widgets/unit, no suites en dispositivo completas\n- db/ o migrations/ -> ejecutar lint de migraciones más una pequeña comprobación de esquema\n- shared/ -> ejecutar tests del paquete compartido, más cualquier consumidor rápido\n Si usas ganchos de Claude Code, puedes ir un paso más: hacer que Claude mire los nombres de archivos staged y proponga un conjunto mínimo de tests, luego el gancho ejecuta esos comandos. Mantén la regla final basada en normas, para que el equipo pueda predecir qué ocurrirá.

Divide la carga entre commit y push. Los commits deben seguir rápidos para que la gente no empiece a saltarse ganchos. Un patrón práctico es:\n

• En commit: ejecutar un conjunto rápido y selectivo (lint + unit tests para módulos tocados)\n- En push: ejecutar un conjunto más amplio (integración, e2e smoke, tests cross-module)\n- En CI: ejecutar la suite completa y aplicar puertas de cobertura\n Las pruebas inestables y lentas necesitan una política explícita, o tu gancho se convierte en ruido. Acordad en equipo qué bloquea un commit y qué solo avisa. Un enfoque razonable es bloquear en fallos claros (formateo, unit tests normalmente estables), advertir en tests conocidos por ser flaky con un mensaje corto y mover suites lentas a push/CI. Si un test es flaky, trátalo como un bug: pistaarlo, arreglarlo y quitar el modo de advertencia tan pronto sea estable.

Generar resúmenes cortos para el revisor en el momento del commit

Un buen diff no siempre es fácil de revisar. Un breve resumen en el momento del commit puede convertir una lectura de 10 minutos en una comprobación de 2, especialmente cuando los cambios tocan varios archivos o incluyen refactors.

La idea es simple: cuando haces git commit, tu gancho pide a Claude Code que lea el diff staged y produzca una nota de 3 a 6 líneas que responda las preguntas que siempre tienen los revisores: qué cambió, por qué, cuán riesgoso es y cómo se probó.

Plantilla simple de resumen

Mantén la salida apretada y consistente para que los revisores aprendan a confiar en ella:\n

• Qué: una oración sobre el cambio principal (no una lista de archivos)\n- Por qué: el problema de usuario o bug que se arregla\n- Riesgo: bajo, medio o alto con una razón\n- Pruebas: qué ejecutaste (o decir “no ejecutado”)\n- Notas: migraciones, flags, pasos de rollout o cualquier cosa crítica para la revisión\n Puedes poner esto directamente en el mensaje de commit (por ejemplo, como un footer corto) o guardarlo en un archivo que el equipo copie en la descripción del pull request. El mensaje de commit funciona bien si quieres que el contexto viaje con el cambio. Un archivo separado va mejor si el equipo prefiere subjects de commit limpios y convencionales.

No filtrar secretos en el resumen

Una herramienta de resúmenes debe ser más estricta que un revisor. Antes de enviar cualquier contenido del diff al modelo, filtra líneas que coincidan con patrones como claves API, claves privadas, tokens, valores .env y credenciales. También filtra cabeceras y cookies comunes si tu repo incluye tráfico HTTP capturado. Cuando el gancho detecta patrones sensibles, puede redactar las líneas o recurrir a un resumen genérico como “cambios relacionados con credenciales redactados”.

Ejemplo: actualizas un endpoint de facturación y tocas tres archivos. El diff staged está ruidoso por renames, pero el resumen dice: “Añade manejo de idempotencia para la creación de cargos para evitar cobros dobles. Motivo: reintentos causaban cargos duplicados. Riesgo: medio (ruta de pagos). Pruebas: tests unitarios del servicio de facturación, replay manual de peticiones.” Eso es exactamente lo que necesita un revisor, sin leer cada línea primero.

Ejemplo de flujo: un commit, menos sorpresas

Arreglas un bug pequeño y retocas una config en el mismo commit. El bug es un cambio de una línea en billing/tax.go. El cambio de config actualiza config/staging.yaml para apuntar a un nuevo endpoint.

Ejecutas git commit -am "Fix tax rounding". Tus ganchos de Claude Code se activan y hacen un rápido conjunto de comprobaciones, en un orden predecible.

Primero, el escaneo de secretos mira lo que cambió, no todo tu repo. Señala que la config de staging incluye algo que parece una API key.

ERROR: Possible secret detected in config/staging.yaml:12
Pattern: api_key=sk_live_...
Fix: remove the key and use an env var reference (e.g., API_KEY)
Override: set ALLOW_SECRETS=1 (not recommended)

Sustituyes el valor por una referencia a variable de entorno y vuelves a commitear.

Luego, el formateo se ejecuta solo donde importa. Si tu archivo Go no está formateado, falla con una pista corta como “run gofmt on billing/tax.go”. Ejecutas el formateador y el gancho pasa en segundos.

Después, la puerta de tests ejecuta un conjunto dirigido. Como tocaste billing/, corre solo los unit tests de billing (no la suite completa). Si un test falla, el gancho muestra el comando exacto para reproducir localmente. Arreglas el caso límite de redondeo y vuelves a ejecutar los mismos tests.

Finalmente, el gancho genera un resumen para el revisor a partir del diff. Es corto y específico, como:

• What changed: Fix rounding in tax calculation for values ending in .005
• Config: staging now reads API key from env var
• Tests: billing unit tests passed
• Risk: affects billing totals, but limited to tax rounding path

Lo que ve el revisor es un commit ya limpio: sin secretos filtrados, formateo consistente y tests que coinciden con el cambio. También obtiene un resumen listo para usar, así que puede centrarse en la lógica en lugar de buscar la intención.

Errores comunes y cómo evitarlos

La forma más rápida de hacer que los ganchos fallen es hacerlos dolorosos. Si un gancho tarda lo suficiente como para romper el flujo de alguien, la gente lo omitirá con --no-verify o lo eliminará. Mantén lo pesado fuera de pre-commit y ejecútalo en CI o bajo demanda.

Una regla práctica: pre-commit debe sentirse como una comprobación de typos, no una suite de tests. Si quieres comprobaciones más inteligentes de Claude Code, úsalas para decidir qué ejecutar, no para ejecutar todo.

1) Ganchos demasiado lentos

Haz que los ganchos sean rápidos por defecto y estrictos solo cuando haga falta. Por ejemplo, ejecuta formateo rápido + escaneo de secretos en cada commit, pero tests solo para módulos afectados.

Un presupuesto de velocidad simple que funciona bien:\n

• pre-commit: 1 a 5 segundos en total\n- commit-msg: menos de 1 segundo\n- Cualquier cosa más larga: mover a pre-push o CI

2) Salidas de IA sin reglas claras

La IA es excelente en sugerencias, no en políticas. Si pides a una IA “revisar el diff” sin reglas, obtendrás resultados distintos cada vez. Define lo que el gancho debe hacer (y lo que nunca debe hacer). Por ejemplo: puede generar un resumen para el revisor, pero no puede reescribir código a menos que un formateador ya haya producido cambios deterministas.

3) Confusión staged vs unstaged

Muchos ganchos escanean accidentalmente tu working tree y luego fallan el commit por cambios que no stagedaste. Eso resulta injusto.

Evítalo usando siempre el contenido staged como entrada. Una buena prueba: edita un archivo, haz stage solo de la mitad y verifica que el gancho reporte solo lo staged.

4) Demasiados falsos positivos

Si cada commit lanza una advertencia, las advertencias se vuelven ruido. Ajusta patrones, añade allowlists para cadenas seguras conocidas y degrada hallazgos “quizás” a una advertencia con una solución clara.

Ejemplo concreto: si tu escáner de secretos marca claves de pruebas en fixtures/, añade una regla para ignorar esa carpeta, pero sigue bloqueando claves reales en archivos de config de la app.

Checklist rápido y siguientes pasos

Si quieres que los ganchos de Claude Code ayuden sin molestar a tu equipo, el objetivo es simple: atrapar problemas reales temprano, mantenerse silencioso cuando todo está normal y mantener el bucle de commit rápido.

Una checklist práctica que funciona para la mayoría de repos:\n

• Mantén pre-commit por debajo de unos segundos para la mayoría de cambios. Si se vuelve lento, la gente lo omitirá.\n- Solo escanea, formatea y lint los archivos staged. Todo lo demás pertenece a pre-push o CI.\n- Bloquea secretos obvios (API keys, claves privadas, tokens). Para casos “quizás”, avisa y deja que el desarrollador confirme.\n- Requiere tests dirigidos en el commit para los módulos tocados, luego ejecuta tests más amplios en push o CI.\n- Añade un resumen corto y consistente del commit para que los revisores sepan qué cambió y dónde enfocarse.\n Un pequeño detalle que rinde: haz que el resumen del revisor se vea igual cada vez. Una plantilla simple es suficiente y entrena a los revisores a escanear rápido.

Review summary:
- What changed: <1-2 bullets>
- Risky areas: <files/modules>
- Tests run: <command or “not run + why”>

Siguientes pasos para adoptar esto fácilmente:\n

• Prototipa el flujo en un proyecto sandbox primero y luego cópialo al repo real cuando se sienta bien.\n- Empieza en modo “solo advertir” por una semana, mide falsos positivos y luego cambia las comprobaciones más fiables a “bloquear”.\n- Añade vías de escape para emergencias (por ejemplo, permitir saltar un gancho con una razón clara en el mensaje de commit) y registra cuándo ocurre.\n- Mueve lo pesado (suites completas, escaneos de secretos profundos, auditorías de dependencias) a pre-push o CI para que los commits sigan siendo rápidos.

Si te gusta construir herramientas en un flujo centrado en chat, Koder.ai (koder.ai) puede ser útil para generar scripts auxiliares alrededor de tus ganchos e iterar con snapshots y rollback antes de exportar el código fuente a tu repo.