DevPawDEVPAW · GROUND-UP DEV NOTES
Buscar
Menú
ES
한국어English日本語繁體中文EspañolPortuguês简体中文
Programación y agentes de IA

[Claude Code #11] Hooks: automatiza con mecanismos, no con peticiones

Los hooks de Claude Code ejecutan automáticamente comandos de shell en momentos como antes y después de las llamadas a herramientas y al final de un turno. Aquí se resumen la configuración de settings.json, los eventos y matchers, el formateo automático, el bloqueo de archivos protegidos y los prompt hooks.

4 min de lectura
Imagen de portada de [Claude Code #11] Hooks: automatiza con mecanismos, no con peticiones

Aunque escribas «Después de editar, ejecuta siempre el formateador» en CLAUDE.md, hay días en que la IA lo olvida. Al fin y al cabo, una instrucción no deja de ser una petición.

Lo que debe ocurrir siempre debe convertirse en un mecanismo, no quedarse en una petición. En Claude Code, ese mecanismo es un hook.

Un hook es un comando de shell definido por el usuario. Se ejecuta automáticamente en momentos concretos mientras funciona Claude Code y se aplica de forma determinista, independientemente de lo que elija el modelo.

Si los comandos hasta Claude Code, capítulo 10 se activaban manualmente, los hooks son mecanismos automáticos que se activan por sí solos.

Crea tu primer hook en 5 minutos

Los hooks se escriben en el bloque hooks de settings.json. Veamos un ejemplo que muestra una notificación de macOS mientras Claude espera una entrada.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Se necesita entrada\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Guarda y escribe /hooks para ver la lista de hooks registrados. Esta pantalla es de solo lectura, así que modifica settings.json directamente o pídele a Claude que lo haga.

¿En qué momentos se pueden activar?

Según Guía oficial de hooks, estos son los eventos más utilizados.

  • SessionStart: Cuando se inicia o reanuda una sesión
  • UserPromptSubmit: Justo después de enviar un prompt y antes de que Claude lo procese
  • PreToolUse: Justo antes de una llamada a herramienta; puede bloquearla
  • PostToolUse: Justo después de que una llamada a herramienta se complete correctamente
  • Stop: Cuando termina el turno de Claude
  • Notification: Cuando Claude espera una entrada

Usa un matcher para limitar el objetivo. Si escribes "matcher": "Edit|Write", el hook solo se ejecuta cuando se usa una herramienta de edición de archivos.

Diagrama de los momentos de activación de los seis eventos de hooks de Claude Code
Puedes añadir hooks a los momentos clave de una sesión

Tres usos representativos

Formateo automático después de editar. Configura el matcher Edit|Write en PostToolUse y ejecuta prettier. El formateo se fuerza independientemente del archivo que modifique la IA.

Bloqueo de archivos protegidos. Un hook PreToolUse comprueba rutas concretas y Cuando termina con el código de salida 2 bloquea esa edición. No sirve cualquier código de error: debe ser exactamente 2. A diferencia de una instrucción en CLAUDE.md, no se puede eludir aunque el modelo la olvide.

Notificación al terminar. Como en el ejemplo anterior de Notification, no hace falta vigilar el terminal continuamente.

Cuando hace falta criterio: prompt hooks

Hay condiciones difíciles de determinar con un script de shell, como «¿Se ha terminado todo el trabajo solicitado?».

En ese caso, usa un hook type: "prompt". Especifica los criterios de evaluación en lugar de un comando de shell y el modelo Haiku predeterminado decidirá con yes/no.

Si añades un prompt hook al evento Stop, se convierte en «Si no ha terminado, sigue trabajando». De hecho, /goal, tratado en el capítulo 6 es un wrapper limitado a la sesión basado en esta estructura.

Los hooks ejecutan el shell tal cual

Su potencia también implica riesgos. La estructura ejecuta automáticamente comandos de shell arbitrarios con tus permisos.

Los hooks del settings.json del proyecto requieren confirmar que confías en el repositorio. No pases por alto esta confirmación al abrir el repositorio de otra persona.

Dentro de los comandos de los hooks, encierra las variables entre comillas y sigue aplicando la regla básica de no ejecutar entradas externas sin validarlas.

Ilustración que contrasta «PROMISE vs MACHINE» con una petición en una nota adhesiva y una máquina de aplicación automática
La nota adhesiva es una petición; la máquina impone el cumplimiento

Resumen

Los hooks son mecanismos que sacan las «cosas que deben ocurrir siempre» de la memoria del modelo y se las confían al sistema.

Empieza forzando el formateo, bloqueando archivos protegidos y enviando notificaciones de finalización. Amplíalo con prompt hooks cuando las condiciones requieran criterio.

En el próximo capítulo veremos /loop, que ejecuta prompts repetidamente a intervalos definidos. Si los hooks automatizan eventos, /loop automatiza el tiempo.

Fuentes y criterios de verificación

Seguir leyendo

Serie de Claude Code

Temas relacionados