Los ganchos Git de Claude Code pueden evitar filtraciones de secretos, imponer formato, ejecutar las pruebas correctas y redactar resúmenes breves de commit para acelerar las revisiones.
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.
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
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.
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.
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:
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.
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.
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
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
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
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ó.
Mantén la salida apretada y consistente para que los revisores aprendan a confiar en ella:\n
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.
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:
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.
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.
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 CILa 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.
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.
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.
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
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
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.
Comienza con los reincidentes que más tiempo le quitan al revisor:\n\n- Escaneo de secretos en los cambios staged\n- Formateo solo de los archivos staged\n- Lint rápido (o comprobación de tipos) para los archivos tocados\n- Un breve resumen para el revisor generado a partir del diff\n\nDeja todo lo lento (suite completa de tests, análisis profundo) para pre-push o CI.
Un buen valor por defecto es:\n\n- pre-commit para comprobaciones rápidas que miran los cambios staged (secretos, formateo, lint rápido, tests unitarios selectivos)\n- commit-msg para reglas del mensaje de commit (longitud, formato, ID de ticket)\n- pre-push para comprobaciones más lentas pero aún locales (tests más amplios, builds)\n\nSi una comprobación suele tardar más de unos segundos, muévela a un paso posterior.
Trata los ganchos en tiempo de commit como guardarraíles, no como la única aplicación de políticas.\n\n- Usa ganchos locales para atrapar errores temprano y reducir el ruido en las revisiones.\n- Aun así, aplica las reglas que deben cumplirse en CI, porque los ganchos pueden saltarse o configurarse mal.\n\nPolítica práctica: los ganchos ayudan a los desarrolladores; CI protege la rama principal.
Escanea el diff staged (el index), no todo el repo.\n\n- Es más rápido.\n- Es más justo (marca lo que estás a punto de commitear, no archivos antiguos).\n- Reduce ruido por historial no relacionado.\n\nSi necesitas un escaneo de todo el repositorio, ejecútalo por agenda o en CI.
Bloquea cuando la coincidencia es de alta confianza (formatos reales de claves, bloques de claves privadas, valores password= obvios en config). Advierte cuando es ambiguo.\n\nAdemás, añade una allowlist estrecha para casos seguros conocidos, como:\n\n- Rutas específicas de fixtures\n- Cadenas de ejemplo claramente marcadas (p. ej., DUMMY_KEY)\n\nSi la gente ve alarmas constantes, desactivarán el gancho.
Formatea solo los archivos staged y usa un único formateador por lenguaje.\n\nDefaults prácticos:\n\n- Auto-corrige los cambios de formato seguros y vuelve a staged\n- Falla mostrando un comando único cuando se necesita una decisión humana\n- Omite directorios generados/vendor\n\nAsí mantienes los diffs limpios sin convertir cada commit en una reescritura larga.
Mapea las rutas cambiadas a un pequeño conjunto de comandos de test rápidos.\n\nEjemplo de enfoque:\n\n- Detecta áreas cambiadas con git diff --cached --name-only\n- Ejecuta solo los tests unitarios de esos módulos\n- Deja integración/e2e para pre-push o CI\n\nAsí mantienes los commits rápidos y aún detectas las roturas más comunes temprano.
Mantenlo corto y consistente (3–6 líneas). Una plantilla simple:\n\n- Qué cambió\n- Por qué\n- Riesgo (bajo/medio/alto + una razón)\n- Pruebas (qué ejecutaste, o “no ejecutado”)\n\nPuedes añadirlo al mensaje de commit o guardarlo como salida de texto para la descripción del PR.
Redacta antes de enviar cualquier cosa a un modelo y sé conservador.\n\n- Elimina líneas que parezcan tokens, secretos, valores de .env, claves privadas, cookies o cabeceras de auth\n- Si hay patrones sensibles, haz un fallback a un resumen genérico (p. ej., “líneas relacionadas con credenciales redactadas”)\n- Envía solo el diff staged más el contexto mínimo referenciado\n\nPor defecto, “comparte menos”, especialmente en repos privados.
Haz los ganchos predecibles y rápidos:\n\n- Fija un presupuesto de tiempo (p. ej., 1–5 segundos para pre-commit)\n- Añade mensajes de error claros: archivo, línea y un comando de corrección\n- Decide una política de fallos para timeouts (bloquear, advertir o fallback)\n- Registra los “saltos” con moderación para que la gente no oculte bypasses\n\nSi el gancho parece inestable o lento, los desarrolladores usarán --no-verify.