---
title: "Lo que aprendimos montando hooks en Claude Code (y lo que no hacen aunque lo parezca)"
description: "Un hook parece un muro y es un script, con formas de fallar casi siempre en silencio. Siete trampas al usar hooks de Claude Code como guardas de un equipo."
url: https://blablanote.com/es/blog/lo-que-aprendimos-montando-hooks-en-claude-code/
lang: es
author: Gorka Mendez
published: 2026-11-04
tags: engineering
translations:
  ca: https://blablanote.com/ca/blog/el-que-hem-apres-muntant-hooks-a-claude-code/
  en: https://blablanote.com/blog/what-we-learned-building-claude-code-hooks/
  eu: https://blablanote.com/eu/blog/claude-codeko-hookekin-ikasi-duguna/
  fr: https://blablanote.com/fr/blog/ce-que-nous-avons-appris-avec-les-hooks-de-claude-code/
  gl: https://blablanote.com/gl/blog/o-que-aprendemos-montando-hooks-en-claude-code/
---

# Lo que aprendimos montando hooks en Claude Code (y lo que no hacen aunque lo parezca)

Hace unas semanas contamos [cómo trabajamos con Claude Code](https://blablanote.com/es/blog/asi-trabajamos-con-claude-code/): diez repositorios, varios agentes programando a la vez y una regla de fondo, que ninguna regla importante dependa de que alguien se acuerde de ella.

La pieza que sostiene esa regla son los *hooks*. Un hook es un pequeño programa que Claude Code ejecuta en momentos fijos: al empezar la sesión, después de cada cambio en un fichero, antes de cada orden en la terminal. Y puede decir «no»: si la orden es peligrosa, la bloquea antes de que pase.

Piensa en el control de seguridad de un aeropuerto. Nadie confía en que cada pasajero recuerde qué no puede llevar: hay un arco y una cinta por los que pasa todo el mundo. Los hooks son ese arco para los agentes.

(Image: Ilustración: una fila de personas y un pequeño robot, el agente, pasan por el arco de seguridad de un aeropuerto, con la luz verde encendida. Al lado, la cinta con las maletas.)

En un aeropuerto, que el arco falle sin que nadie se entere es muy raro. Tiene una luz que dice si está encendido, un operario al lado y una prueba cada mañana con un objeto de metal. Un hook no trae nada de eso: si no se ejecuta, se le acaba el tiempo o grita donde nadie escucha, todo sigue en verde. Esas comprobaciones las tienes que poner tú.

Este artículo va de eso: siete formas en que nuestros hooks fallaron sin decir nada, cómo nos dimos cuenta y qué cambiamos. Si usas hooks, o cualquier automatismo que haga de guarda, es probable que te encuentres alguna.

## Un hook, en quince líneas

Antes de las trampas, veamos cómo es un hook por dentro. Este bloquea cualquier intento de subir cambios directamente a la rama principal (`git push` a `main`). No es nuestra guarda real, que hace bastante más, pero funciona y se puede copiar.

Primero, la línea que lo conecta. Va en `.claude/settings.json`, dentro del proyecto:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "sh \"$CLAUDE_PROJECT_DIR/.claude/hooks/no-push-main.sh\"",
            "timeout": 10
          }
        ]
      }
    ]
  }
}
```

Traducido: antes de cada orden de terminal (`PreToolUse` con `Bash`), ejecuta este script, y dale como mucho diez segundos.

Y el script:

```sh
#!/bin/sh
# Bloquea `git push` a main. Claude Code pasa la orden en JSON por la entrada estándar.
# Salir con 2 la bloquea, y lo que se escribe en stderr le llega al agente como motivo.

orden=$(jq -r '.tool_input.command // empty') || {
  echo "No puedo leer la orden (¿falta jq?). La bloqueo por si acaso." >&2
  exit 2
}

# Solo cuenta si git está donde la terminal lo ejecutaría: al principio o tras ; & | (
# Un grep o un echo que mencionan «git push origin main» pasan.
if printf '%s\n' "$orden" | grep -Eq '(^|[;&|(])[[:space:]]*((rtk|sudo)[[:space:]]+)?git([[:space:]]+-C[[:space:]]+[^[:space:]]+)?[[:space:]]+push([[:space:]]+[^;&|]*)?([[:space:]]|:)(refs/heads/)?main([[:space:];&|)]|$)'; then
  echo "A main solo se llega por PR: empuja tu rama y abre una." >&2
  exit 2
fi
exit 0
```

Cuando el agente intenta `git push origin main`, la orden no llega a ejecutarse y el agente recibe el motivo. En una sesión de prueba respondió así: «El push a `main` se bloqueó: un hook del proyecto responde "A main solo se llega por PR: empuja tu rama y abre una"». Y en vez de insistir, sigue por el camino que le has indicado.

En esas quince líneas ya hay tres de las lecciones que vienen ahora: si no puede leer la orden, bloquea; distingue entre ejecutar un comando y mencionarlo; y el motivo va por el canal que el agente sí lee. Las siete trampas explican por qué cada detalle está ahí.

## 1. El portero que tarda demasiado deja pasar a todo el mundo

(Image: Ilustración: un portero habla por teléfono, con un reloj en rojo encima de él, mientras la puerta se queda abierta y entran personas y el robot sin que nadie las mire.)

Imagina un portero que, antes de dejar entrar a nadie, llama por teléfono para comprobar la lista. Un día la línea va lenta. Lo lógico sería que nadie entrase hasta que el portero tenga respuesta. Lo que pasa en realidad es que, pasado un tiempo, **la puerta se abre sola**.

Eso hace un hook cuando se le acaba el tiempo. Cada hook tiene un plazo máximo, y suponíamos que, si se agotaba, la orden quedaba bloqueada. No es así. Lo medimos con un hook de prueba que tenía dos segundos de plazo, tardaba seis y al final decía «no»: la orden se ejecutó igual. El registro del hook tenía la línea de inicio y nunca la del final, porque Claude Code lo cortó antes de que pudiera decir nada.

Lo repetimos al escribir este artículo, con la versión 2.1.318 de Claude Code, y al lado de un hook de control idéntico pero rápido. El rápido bloqueó la orden y el lento la dejó pasar.

En nuestro flujo, CI pasa los tests y despliega, pero quien pulsa el botón de merge es el agente, con una orden en la terminal. Delante de esa orden hay una guarda: antes de dejar que un cambio entre en la rama principal, la que se despliega a producción, pregunta a GitHub si los tests están en verde y si la rama principal se ha movido mientras tanto. Con la red lenta, esa consulta se comía el plazo y la puerta quedaba abierta. Nadie vio ningún error, porque no lo hubo.

(Image: Dos líneas de tiempo. Arriba, lo que esperas: el hook se pasa de su plazo y la orden queda bloqueada. Abajo, lo que pasa: el hook se pasa de su plazo, Claude Code deja de esperarlo y la orden se ejecuta.)

Lo que cambiamos:

- **El portero tiene su propio reloj, más corto que el de la puerta.** Cada guarda se pone un límite de tiempo a sí misma para cada consulta, y lo hace antes de que se agote el del hook.
- **Si no puede comprobar, no deja pasar.** Sin red, sin una herramienta que necesita o con el ordenador tan cargado que no llega a tiempo: bloquea y explica por qué.
- **Un test vigila que los dos relojes cuadren.** Si alguien cambia uno y no el otro, se pone en rojo. Ya saltó una vez: una copia de la guarda tenía 60 segundos de plazo y necesitaba 120.

Y una confesión: la primera versión de ese test no comprobaba nada. Un error en una ruta hacía que se saltase todos los ficheros, y salía siempre en verde. Lo descubrimos cuando rompimos un plazo a propósito y el test siguió en verde. Una guarda muerta se lee igual de bien que una viva.

## 2. La alarma que suena en el sótano

(Image: Ilustración: una casa en sección. En la planta, el robot trabaja tranquilo junto a su mesa; en el sótano, una alarma suena sin que nadie la oiga.)

Uno de nuestros hooks revisa cada fichero después de que el agente lo edita y avisa de problemas: «a este plan le falta su estado», «este documento se ha pasado de tamaño». Lo probábamos a mano y el aviso salía perfecto.

Durante semanas, el agente no recibió ni uno.

Era como una alarma que suena en el sótano, donde no hay nadie. Lo que ese tipo de hook escribe como texto normal va al registro que puede leer la persona, no al agente. Para que el agente lo reciba, el aviso tiene que ir en un formato concreto (un pequeño JSON con un campo llamado `additionalContext`). En el hook de inicio de sesión, en cambio, el texto normal sí llega, y por eso uno funcionaba y el otro parecía funcionar.

También lo repetimos con la versión 2.1.318. Un hook que corre después de cada edición le pasaba al agente una palabra clave inventada en el momento, y luego le preguntábamos cuál era. Cuando el hook la escribía como texto normal, el agente respondía «ninguna». Cuando la escribía en el JSON, respondía la palabra exacta.

(Image: Un hook que se ejecuta después de cada edición puede avisar de dos formas. Si escribe texto normal, el aviso va al registro que lee la persona y el agente no lo ve. Si escribe un JSON con additionalContext, el aviso llega al agente.)

Ahora todos los avisos salen en ese formato, y un test se pone en rojo si alguien vuelve a escribir texto normal.

**La lección general:** comprobar que una alarma suena no basta. Hay que comprobar que la oye quien tiene que oírla. Con un hook, eso significa provocar la situación dentro de una sesión de verdad y ver si el agente reacciona.

## 3. La alarma instalada que no estaba conectada

(Image: Ilustración: un edificio de cuatro plantas. El robot entra por el portal, donde la alarma está encendida en verde; las de las plantas de arriba están apagadas en gris.)

Nuestro trabajo está repartido en diez repositorios. Las guardas son las mismas para todos: una sola copia de cada script, en el repositorio de planificación. Lo que tiene cada repositorio es el cableado, una línea en su configuración que dice «antes de cada orden, ejecuta esta guarda». Los dos principales, la aplicación y la plataforma de eventos, la tenían. Pero nuestras sesiones no arrancan dentro de un repositorio de producto: arrancan en el de planificación y abren los demás desde ahí.

Resulta que Claude Code lee la configuración de dos sitios: la tuya de usuario y la del proyecto donde arranca la sesión. La de los repositorios que abre después, no. Lo volvimos a comprobar con la versión 2.1.318: el mismo hook que bloqueaba una orden cuando la sesión arrancaba en su repositorio no se ejecutaba cuando ese repositorio se abría desde otro. Es como un edificio en el que solo se conecta la alarma del portal. Subías a las plantas donde está lo valioso y su alarma, instalada y en su sitio, estaba apagada. Y otras siete plantas ni siquiera tenían alarma.

(Image: Cuatro plantas. La sesión entra por el portal, el repositorio de planificación, y solo se activa su alarma. Las de la aplicación y de la plataforma de eventos están cableadas a la misma guarda, pero apagadas. Los otros siete repositorios no tienen cableado.)

Había dos variantes más del mismo problema:

- **Hooks que miraban la planta equivocada.** Algunos deducían en qué repositorio estaban a partir de dónde había empezado la sesión, no del fichero que se acababa de tocar. El que formatea el código después de cada edición no se ejecutaba nunca en el modo normal de trabajo.
- **Una guarda que solo miraba desde dónde se lanzaba la orden.** Si la orden salía de una carpeta temporal, la guarda se apagaba, aunque la orden apuntase directamente al repositorio que había que proteger. Es como un vigilante que solo revisa a quien entra por la puerta principal y no mira a dónde va.

Ahora la guarda principal está instalada a nivel de usuario, así que cubre el edificio entero. Los hooks deducen el repositorio a partir del fichero tocado, y las guardas miran a dónde apunta cada orden, no desde dónde se lanza. Cuando no pueden saberlo, bloquean lo que sea destructivo.

## 4. El filtro que no te deja explicar el filtro

(Image: Ilustración en dos mitades. A la izquierda, el robot junto a un libro de recetas abierto, con un visto verde: escribirla es inofensivo. A la derecha, el robot le da la receta a un cocinero junto a los fogones, con un aspa roja: eso sí se ejecuta.)

La primera versión de nuestra guarda buscaba palabras: si la orden contenía el nombre de un comando peligroso, la bloqueaba. Lo primero que bloqueó fue la edición del documento que explicaba por qué ese comando estaba prohibido.

Es como un filtro de spam que manda a la papelera el correo de seguridad que te avisa de cómo reconocer el spam. O un detector que no te deja decir «cuchillo» para explicar que no se pueden llevar cuchillos.

Una guarda así es peor que no tenerla. Molesta al documentarla, al probarla y al hablar de ella, y a la tercera vez alguien busca la forma de apagarla.

(Image: Tres órdenes que nombran el mismo comando peligroso. Ejecutarlo: bloquea, correcto. Buscarlo en un documento con grep: pasa, correcto. Mandarlo a un intérprete dentro de un bloque de texto: bloquea, correcto, porque ese texto se ejecuta.)

La solución es distinguir entre **nombrar** un comando y **ejecutarlo**. La guarda solo bloquea cuando la palabra está en el lugar donde la terminal la ejecutaría: al principio de la orden o justo después de los símbolos que encadenan órdenes. Buscarla en un fichero o escribirla en un documento pasa.

Con un matiz que nos costó dos sustos: un bloque de texto que se manda a un intérprete **sí se ejecuta**. Es la diferencia entre escribir una receta y dársela al cocinero. Nuestro primer filtro trataba igual las dos cosas y dejaba pasar las órdenes peligrosas escondidas dentro de una receta que alguien le daba al cocinero.

Y una sorpresa más: otros hooks pueden reescribir la orden antes que el tuyo. Usamos [rtk](https://www.rtk-ai.app/), una herramienta que recorta la salida de los comandos para que el agente gaste menos tokens. Funciona con su propio hook, que reescribe cada orden añadiéndole un prefijo: `gh pr merge` pasa a ser `rtk gh pr merge`. Y Claude Code no garantiza en qué orden corren los hooks. Cuando la otra iba primero, nuestra guarda no reconocía la orden y la dejaba pasar. La misma orden se bloqueó en un repositorio y pasó en otro.

El arreglo fue dejar de suponer en qué forma llega la orden. La guarda reconoce el comando tanto solo como con ese prefijo delante, y cada forma tiene su caso en el test. Si mañana otra herramienta reescribe las órdenes de otra manera, el test es el sitio donde añadirla.

## 5. La lista de vetados frente a la lista de invitados

(Image: Ilustración de dos puertas de discoteca. A la izquierda, un portero con una lista de vetados mientras alguien que no está en ella se cuela, con un aspa roja. A la derecha, un portero con la lista de invitados: entra quien está apuntado y quien no se queda tras el cordón, con un visto verde.)

Una discoteca puede controlar el acceso de dos formas: con una lista de personas vetadas o con una lista de invitados. Con la primera, entra todo el mundo menos los que ya dieron problemas. Con la segunda, solo entra quien está apuntado.

Nuestra guarda de producción empezó con una lista de vetados: estas órdenes contra los servidores, no. Cuando la pusimos a prueba de verdad, encontramos un camino que no estaba en la lista y que permitía ejecutar lo que quisieras en producción. Era justo lo que la guarda pretendía impedir, por una puerta que nadie había apuntado.

Le dimos la vuelta. Ahora es una lista de invitados: enumera las consultas de solo lectura que se permiten y bloquea todo lo demás. Una herramienta nueva o un comando que no conocíamos cuentan como peligrosos hasta que alguien decida lo contrario.

El mismo principio vale dentro del código. Compara estas dos reglas para un comando que borra datos:

(Image: Una tabla con cinco valores posibles del entorno: producción, vacío, mal escrito, un entorno creado después y local. La lista negra solo para en producción y destruye en los tres casos raros. La lista blanca para en todos menos en local.)

La lista de vetados deja pasar, y destruye, cuando la variable viene vacía, mal escrita o con el nombre de un entorno nuevo. La de invitados trata como producción todo lo que no reconoce.

## 6. Un cartel no es un torno

(Image: Ilustración en dos mitades. A la izquierda, una señal de prohibido el paso y una persona y el robot que pasan por delante sin detenerse. A la derecha, el robot frente a un torno de metro cerrado, con un aspa roja.)

Las normas escritas son carteles: «prohibido el paso», «no pisar el césped». Una guarda es un torno de metro: sin billete, no pasas, lo hayas leído o no.

Nosotros teníamos la norma escrita: los cambios a la rama principal entran siempre por una PR revisada, nunca directamente. Y el agente la conocía, porque está en el protocolo que lee al empezar cada sesión. Cuando por fin medimos, encontramos **21 cambios directos a la rama principal de la aplicación en una semana**. Cada uno se desplegó a producción sin revisión. Nadie se saltó la norma a propósito. Simplemente, no había ningún torno que la hiciera cumplir.

(Image: Antes de la guarda: 21 cambios directos a la rama principal en una semana, cada uno desplegado a producción sin revisión. Después: 0, porque la guarda bloquea el intento y explica el camino correcto, que es abrir una PR.)

El otro aviso nos llegó por producción. Una sesión escribió 20 filas en la base de datos de producción mediante un comando remoto, y nada entre la credencial y la base de datos preguntó nada. Desde entonces, contra producción solo se lee, y la llave no está al alcance del agente: la tiene una persona.

¿Por qué hooks y no las reglas de permisos que trae Claude Code? Porque queríamos que la protección no dependiera de cómo se configurase cada sesión. Trabajamos con sesiones largas y bastante autónomas, y un hook se ejecuta siempre.

## 7. Dos personas editan el mismo documento y una lo pisa con su copia vieja

(Image: Ilustración: una persona y el robot, cada uno con su portátil, guardan en el mismo documento. La persona había añadido cuatro secciones; el robot guarda su copia de la mañana y las cuatro secciones quedan marcadas en rojo, perdidas.)

Esta la conoce cualquiera que haya trabajado con documentos compartidos. Abres el documento por la mañana y trabajas en tu parte. Mientras, una compañera añade su sección y guarda. Por la tarde guardas tú, desde tu copia de la mañana, y su sección desaparece. Nadie ha borrado nada a propósito.

Nos pasó con código y en producción. Varias sesiones trabajan a la vez sobre el mismo repositorio. Una preparó su cambio a partir de una foto de la rama principal que otra sesión acababa de mover. El resultado parecía un cambio normal, pasó todos los tests y la revisión, y al entrar **deshizo cuatro cambios anteriores** que ya estaban en producción.

(Image: Una línea de tiempo con la rama principal. Entran cuatro cambios: A, B, C y D. Una rama preparada sobre una foto vieja, anterior a esos cuatro, entra después y los devuelve a su estado anterior. La guarda nueva compara lo que la rama deja con lo que acaba de entrar y bloquea el merge.)

La guarda que salió de ahí comprueba, antes de cada envío y cada merge, si el cambio devuelve a su estado anterior ficheros que acaban de cambiar en la rama principal. Antes de activarla la probamos contra las 60 últimas PRs de nuestros dos repositorios principales: salta en los dos incidentes reales y en ninguna PR legítima. Si de verdad quieres deshacer algo, lo dices en el mensaje del cambio y pasa.

Nadie habría escrito esa guarda por adelantado. Sale de tratar cada incidente como una pregunta: ¿esto lo podría detectar una máquina? Si la respuesta es sí, se convierte en guarda, con sus tests.

## Lo que quitamos

(Image: Ilustración en dos mitades. A la izquierda, la gente cruza el arco de seguridad sin pararse. A la derecha, una maleta abierta y deshecha sobre la mesa, un reloj de arena y una cola de personas esperando.)

Todo esto suma, y llegó un momento en que sumaba demasiado. «Todo lo que hacemos es muy lento»: esperas de más de una hora para algunas comprobaciones y despliegues de prueba que el siguiente cambio dejaba viejos.

Al medir, vimos que bajo la palabra «guardas» había dos cosas muy distintas. Volviendo al aeropuerto:

- **El arco de seguridad** son las guardas que bloquean órdenes peligrosas. Cuestan milisegundos por orden y evitan los desastres.
- **El registro a fondo de cada maleta** son las comprobaciones lentas: ciertas pruebas exhaustivas o desplegar un entorno de prueba con cada cambio. Ahí se iban las horas, y nadie había vuelto a mirar si cada una seguía mereciendo la pena.

Dos ya no lo merecían, y las sacamos del camino de cada cambio:

- **Las pruebas de mutación en local.** Una prueba de mutación mete pequeños errores a propósito en el código (cambia un `>` por un `>=`, borra una línea) y comprueba si los tests se dan cuenta. Si no se dan cuenta, esos tests no protegen tanto como parece. Es muy útil, pero en la aplicación mutábamos los ficheros enteros que tocaba cada cambio, y eso tardaba entre seis y diez minutos, y a veces horas. Ahora cada tarea muta solo lo que su cambio añade: quita cada condición nueva, una a una, y mira si algún test se da cuenta. Tarda segundos y apunta justo a lo que importa, porque con miles de tests la pregunta útil no es si hay tests, sino si este cambio trae uno que lo vigile.

  También apagamos la medición semanal del código entero. Costaba miles de minutos de CI al mes y casi nunca llegaba al final: de las últimas ocho, terminó una. Daba una nota global sobre la que nadie actuaba.
- **El despliegue a staging en cada envío de una PR a medio hacer.** Staging es una copia de la aplicación donde se mira el cambio antes de producción. Antes, cada vez que el agente subía un cambio a su PR, se desplegaba staging entero: unos 8 minutos. Una PR recibía de media casi tres envíos, y cada despliegue dejaba viejo al anterior antes de que nadie lo mirase. En la aplicación eran unos 16 minutos por PR construyendo algo que nadie miraba. Ahora la PR nace en borrador y solo despliega cuando está lista.

El arco se quedó. Una guarda que cuesta milisegundos y para un desastre al mes es lo más barato de todo el sistema.

## Un hook es código de producción

Si hay que resumirlo en una idea: un hook que hace de guarda es código de producción y merece el mismo trato.

- **Tiene tests.** Los nuestros son 336 casos, cada uno con una orden real y lo que la guarda debería hacer con ella. Empiezan por las órdenes inofensivas que no deberían bloquearse.
- **Se pone a prueba a sí mismo.** Para cada guarda tenemos una versión rota a propósito, y los tests tienen que detectarla. Es como hacer un simulacro con una maleta trampa: si el arco no pita, el arco no funciona.
- **Ante la duda, cierra.** Si no puede comprobar, bloquea.
- **Se prueba donde se usa.** Que el script funcione no basta. El agente tiene que recibir el aviso.
- **Se gana el sitio.** Solo automatizamos lo que falla sin avisar y una máquina puede detectar. Lo demás se escribe, con su porqué.

Los agentes no se cansan, pero tampoco desconfían. Esa desconfianza la ponemos nosotros, en forma de guardas que se cumplen solas. Somos muy desconfiados, aunque solo con los agentes: por eso cada norma que importa es un torno, no un cartel.

Y seguiremos siendo muy desconfiados.
