Hooks de Claude Code: reglas que se cumplen siempre

Los hooks de Claude Code son comandos de shell que se ejecutan automáticamente en puntos fijos de una sesión. Ese es todo el mecanismo. Lo que los hace valiosos es la distinción que crean: un hook se ejecuta siempre, mientras que una instrucción escrita en un archivo se cumple casi siempre.

Para todo aquello donde "casi siempre" salga caro, esa diferencia es el argumento entero.

Para qué sirven los hooks de Claude Code#

Tres categorías, y conviene tener claro en cuál estás antes de escribir nada.

Cumplimiento. Reglas que no se pueden saltar. Formatear tras cada edición. Ejecutar los tests de la zona tocada. Negarse a ejecutar un comando de tu lista negra. Son los que pagan de inmediato, porque eliminan una clase de error en vez de reducirla.

Contexto. Cargar información al inicio de una sesión para no volver a pegarla: rama actual, entorno, qué servicios están arriba.

Señales. Avisarte cuando termina una tarea larga, o registrar lo ocurrido para revisarlo luego.

El cumplimiento es donde está casi todo el valor. Las otras dos son comodidad.

Los cinco que merece montar primero#

Formatear tras editar. Pasa tu formateador por los archivos que cambiaron. Elimina una categoría entera de ruido en los diffs y los comentarios de revisión que la acompañan.

Tests tras un cambio. Ejecuta los tests relevantes a lo tocado, no la suite entera. El feedback llega mientras el razonamiento sigue fresco, que es cuando sale más barato actuar.

Bloquear comandos peligrosos. Una lista negra para lo que nunca quieres que se ejecute: force push a la rama principal, comandos destructivos de base de datos, borrados fuera del proyecto. Este es el hook que te salva una tarde mala.

Cargar contexto al inicio. Rama, entorno y lo que escribirías en el primer mensaje.

Notificar al terminar. Para trabajo largo del que te has ido.

Empieza por los tres primeros. Son los que cambian comportamiento en vez de comodidad.

Hooks frente a las otras capas de configuración#

Claude Code te da varios sitios donde poner una regla, y elegir mal es cómo se acaba con una configuración que se pelea consigo misma.

El archivo de contexto del proyecto es para contexto y convenciones: qué es esto, cómo está estructurado, qué comandos usar, qué dejar en paz. El modelo lo lee y generalmente cumple. Perfecto para orientación, malo para garantías.

Los hooks son para garantías. Deterministas, incondicionales, sin criterio de por medio.

Las skills son para procedimientos repetibles con pasos. Un hook es un reflejo; una skill es un método.

Los subagentes son para trabajo delegado que necesita su propio contexto.

La prueba que uso: si la regla admite excepciones, va en el archivo de contexto. Si no admite ninguna, es un hook.

Escribir uno que no arruine tu sesión#

Los hooks se ejecutan constantemente, así que su coste se multiplica por todo lo que haces. Cuatro reglas evitan que se conviertan en el problema.

Rápido. Menos de un segundo. Un hook de tres segundos en cada edición es un impuesto que pagarás cientos de veces al día y que acabarás desactivando con rabia.

Silencioso. No imprimas nada cuando todo va bien. Cada línea de salida compite con tu trabajo real por el contexto.

Específico. Ejecuta los tests de la zona que cambió, no la suite. Formatea el archivo editado, no el repositorio.

Probado. Ejecuta el comando tú primero, incluido el caso raro. Un hook que peta con archivos que tienen espacios en el nombre encontrará uno.

Además: los códigos de salida importan. Un código distinto de cero en un hook bloqueante detiene la acción, que es justo lo que quieres de la lista negra y justo lo que no quieres de un formateador que falla por un archivo sin relación.

Un hook es código que ahora mantienes#

Lo que se olvida es que un hook pasa a formar parte de tu entorno de forma permanente, y todo el que clone el proyecto lo hereda.

Trátalo en consecuencia. Guárdalos en control de versiones con el proyecto en vez de en un ajuste personal, para que un compañero no obtenga un comportamiento distinto del mismo repositorio. Comenta los que no sean obvios, porque un comando de shell que bloquea una acción sin explicación es desesperante de depurar seis meses después. Y revísalos cuando el proyecto cambie: un hook de tests apuntando a un directorio renombrado falla en silencio, y el fallo silencioso es peor que no tener hook, porque dejaste de comprobarlo a mano el día que lo escribiste.

La lista negra merece cuidado especial. Escríbela estrecha y prueba cada patrón contra el comando que quieres bloquear y contra el parecido que quieres permitir. Un patrón demasiado amplio que bloquea la mitad de tu uso legítimo de git enseña a la gente a saltarse el mecanismo entero.

Los errores que veo#

Hooks que duplican el archivo de contexto. Si el modelo ya lo cumple, el hook añade latencia por nada.

Hooks bloqueantes con fallos. Una lista negra con un patrón demasiado amplio bloquea trabajo legítimo y el fallo parece que la herramienta se porta mal.

Hooks habladores. Registrar el éxito en cada llamada llena de ruido el contexto que pagaste.

Ejecutarlo todo. La suite completa tras cada edición suena riguroso y es por lo que la gente desactiva los hooks.

La versión corta#

Usa hooks para las reglas que nunca se pueden saltar y el archivo de contexto para las que necesitan criterio. Empieza por formatear, tests y lista negra. Que sean rápidos, silenciosos en el éxito, estrechos y probados con el caso feo.

Si quieres la configuración montada bien, qué es Claude Code cubre los fundamentos y mi curso de Claude Code cubre el montaje que uso en trabajo con clientes.