Referencia de ganchos para desarrolladores de Claude Code: Automatizando tu agente de IA

Si has pasado algo de tiempo trabajando con agentes de codificación de IA como Claude Code, probablemente hayas sentido tanto la magia como la frustración. En un minuto, está escribiendo código repetitivo impecable; al siguiente, ignora por completo las instrucciones cuidadosamente elaboradas en tu archivo CLAUDE.md. Es una historia común que ves aparecer en Reddit y Hacker News, obtienes resultados inconsistentes, o lo que algunas personas han comenzado a llamar "chapuzas de LLM".

Esa sensación de perder el control durante una sesión larga es exactamente la razón por la que existen los hooks de Claude Code. Son tu manera de devolver un control predecible y sólido a tu asistente de IA. En lugar de sugerir amablemente un flujo de trabajo, puedes imponerlo. Esta guía es tu referencia práctica de hooks para Claude Code, desglosando qué son, por qué son importantes y cómo puedes usarlos para hacer que tu desarrollo impulsado por IA sea mucho más fiable.

¿Qué son los hooks de Claude Code?

En pocas palabras, los hooks son comandos de shell que defines para que se ejecuten automáticamente en ciertos puntos del flujo de trabajo de Claude Code. Si alguna vez has usado hooks de Git como pre-commit o post-commit para mantener tu repositorio limpio, el concepto te resultará inmediatamente familiar. Así como los hooks de Git pueden forzar que cada confirmación sea analizada y probada, los hooks de Claude Code se aseguran de que tu agente de IA siga tus reglas, siempre.

La verdadera diferencia entre un hook y un prompt se reduce a una cosa: ejecución garantizada. Una instrucción en tu archivo CLAUDE.md es una sugerencia. La IA probablemente la seguirá, pero en una conversación larga, podría quedar fuera de la ventana de contexto o simplemente perder prioridad. Un hook, por otro lado, es una regla codificada. Es un comando que se garantiza que se ejecutará cuando ocurra su evento específico. Sin peros que valgan.

Puedes configurarlos en dos lugares, lo que te da una flexibilidad agradable:

• ~/.claude/settings.json: Esto es para tus hooks personales a nivel de usuario. Cualquier cosa que pongas aquí se aplicará a todos tus proyectos. Piensa en ello como tu configuración global.

• .claude/settings.json: Esto es para hooks específicos del proyecto. Puedes incluir este archivo en el control de versiones, para que todos en tu equipo tengan las mismas reglas automatizadas. Es perfecto para hacer cumplir los estándares de todo el equipo.

Esta configuración transforma a tu asistente de IA de un socio brillante pero a veces inconsistente a una herramienta automatizada y fiable en la que puedes confiar.

De prompts poco fiables a un control sólido con hooks

Confiar únicamente en prompts y archivos CLAUDE.md puede parecer una lotería. Los grandes modelos de lenguaje tienen una capacidad de atención limitada (su ventana de contexto), y a medida que avanza tu sesión, esas instrucciones iniciales pueden perderse en el ruido. Los comentarios de los desarrolladores son bastante claros en este punto; las instrucciones pueden ser "impredecibles", lo que a menudo te obliga a volver y arreglar las cosas manualmente. Los hooks son la respuesta para convertir esas sugerencias en acciones que siempre ocurren.

Recurso 1: [Flujo de trabajo] , Un diagrama que compara un flujo de trabajo basado en prompts con uno que usa hooks, mostrando cómo los hooks proporcionan una ejecución garantizada.

Entonces, ¿cómo se ve esto realmente en tu flujo de trabajo diario?

• Garantiza la calidad del código en piloto automático. Puedes ejecutar automáticamente analizadores estáticos como ruff o formateadores como prettier después de que Claude modifique un archivo. Nunca más tendrás que recordarle a la IA que formatee su código, y no tendrás que corregir problemas de estilo tú mismo.

• Automatiza las tareas aburridas. ¿Alguna vez has querido una notificación de escritorio cuando una tarea larga finalmente termina? ¿O qué tal crear automáticamente una confirmación de git con el prompt del usuario como mensaje después de cada ejecución exitosa? Incluso puedes registrar cada comando de shell para auditoría. Todo esto es posible con hooks.

• Mejora la seguridad y previene errores. Puedes configurar hooks para bloquear a Claude para que no ejecute comandos potencialmente destructivos como rm -rf. También podrías evitar que toque archivos sensibles como tu .env o package-lock.json, dándote tranquilidad.

Una referencia práctica para los hooks de Claude Code

Bien, entremos en detalles. Esta sección es tu referencia principal para comenzar con los hooks más comunes y útiles. Piénsalo como una guía de referencia rápida para poner a tu agente de IA sobre rieles.

Eventos de hook clave

Los hooks tienen que ver con el momento oportuno. Están vinculados a eventos específicos que ocurren mientras el agente está trabajando. Aunque la documentación oficial tiene la lista completa, estos son los cuatro que probablemente usarás una y otra vez.

Evento de Hook	Cuándo se ejecuta	Un caso de uso común
UserPromptSubmit	Antes de que Claude vea tu prompt.	Puedes inyectar contexto adicional aquí, como la fecha actual o tu rama de git, o incluso bloquear prompts que no quieres que la IA maneje.
PreToolUse	Justo antes de que Claude ejecute una herramienta (como Bash o Write).	Esta es tu oportunidad para bloquear comandos inseguros, solicitar la aprobación del usuario o configurar un entorno temporal para que la herramienta se ejecute.
PostToolUse	Justo después de que una herramienta finalice con éxito.	Perfecto para ejecutar formateadores o analizadores estáticos en código recién creado, registrar la acción o verificar la salida de la herramienta.
Stop / SubagentStop	Cuando el agente principal o un subagente finaliza su tarea.	Un buen lugar para enviar una notificación, ejecutar un script de limpieza o confirmar automáticamente el trabajo que se acaba de hacer.

Ejemplo 1: Mantener el código limpio con un hook PostToolUse

Comencemos con un clásico. El formateo automático de código es una victoria simple que ahorra un montón de tiempo y mantiene tu base de código con un aspecto profesional.

El objetivo: Ejecutar automáticamente prettier en cualquier archivo TypeScript que Claude escriba o edite.

Para que esto funcione, añadirás un hook a tu archivo settings.json. Usaremos un matcher para asegurarnos de que este hook solo se active para las herramientas Write, Edit y MultiEdit, ya que son las que modifican archivos.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -qE '\\.(ts|tsx)'; then npx prettier --write \"$file_path\"; fi; }"
          }
        ]
      }
    ]
  }
}

Ese comando de shell puede parecer un poco intimidante, pero aquí tienes un desglose rápido de lo que está haciendo:

1. jq -r '.tool_input.file_path': El hook recibe un montón de datos JSON sobre el evento a través de la entrada estándar (stdin). Este comando usa jq para extraer la ruta del archivo que acaba de ser modificado.
2. | { read file_path; ... }: Luego, "conecta" esa ruta de archivo a un pequeño bloque de script para que podamos trabajar con ella.
3. if echo \"$file_path\" | grep -qE '\\.(ts|tsx)': Esta es una simple verificación para ver si la ruta del archivo termina en .ts o .tsx.
4. then npx prettier --write \"$file_path\"; fi; }: Si es un archivo TypeScript, ejecuta prettier para formatearlo en ese mismo momento.

Una vez que este hook esté activo, cualquier código TypeScript que Claude toque estará perfectamente formateado, garantizado.

Ejemplo 2: Recibir notificaciones personalizadas con un hook Stop

¿Alguna vez has iniciado una tarea larga con Claude, has cambiado a otra ventana y luego te has olvidado por completo de ella? Una simple notificación de escritorio puede hacer que tu flujo de trabajo sea mucho más fluido.

El objetivo: Recibir una notificación de escritorio en macOS cuando Claude termine su tarea actual.

Este es mucho más simple. Solo necesitamos configurar un hook para el evento Stop.

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude has finished!\" with title \"Claude Done\" sound name \"Glass\"'"
          }
        ]
      }
    ]
  }
}

Este comando usa osascript, una herramienta práctica integrada en macOS, para mostrar una notificación del sistema. Ahora puedes lanzar una tarea compleja, ir a por un café y recibir un aviso amistoso en el momento en que tu asistente de IA esté listo para lo que venga después.

Este video ofrece un análisis detallado de cómo puedes usar los cinco hooks clave para un control y observabilidad más avanzados sobre Claude Code.

¿Y qué hay de automatizar el trabajo más allá de la línea de comandos?

El poder de los hooks es increíble para los desarrolladores. Estamos cómodos escribiendo scripts, investigando JSON y viviendo en la shell. Pero, ¿y si eres un gerente de soporte, no un desarrollador? Aún necesitas automatizar flujos de trabajo con el mismo nivel de fiabilidad, pero lo necesitas sin el código.

Aquí es donde una herramienta como eesel AI entra en juego. Ofrece el mismo tipo de control fiable y determinista que obtienes con los hooks, pero a través de una interfaz visual sin código que está diseñada para equipos de negocio. Se conecta a tu plataforma de soporte existente (como Zendesk) y a tus fuentes de conocimiento, permitiéndote automatizar el soporte sin necesidad de escribir una sola línea de código.

Los paralelismos entre los dos enfoques son bastante claros:

• Un desarrollador escribe un hook PreToolUse para bloquear comandos peligrosos. Un líder de soporte utiliza el constructor de flujos de trabajo de eesel AI para crear una regla que escala automáticamente cualquier ticket de un cliente VIP que contenga la palabra "urgente".
• Un desarrollador configura un hook PostToolUse para ejecutar un analizador estático en código nuevo. Un equipo de soporte utiliza el Triage con IA de eesel AI para etiquetar, enrutar y categorizar instantáneamente nuevos tickets según su contenido, todo configurado con unos pocos menús desplegables.
• Un desarrollador podría escribir un script personalizado para probar sus hooks. Con eesel AI, obtienes un potente modo de simulación listo para usar. Puedes probar de forma segura tu agente de IA en miles de tickets pasados de tu equipo para ver exactamente cómo se comportará antes de que hable con un cliente real.

Con una plataforma como eesel AI, los equipos de negocio obtienen ese mismo control granular y automatización fiable, pero pueden ponerlo en marcha en minutos, no en meses. Obtienes control total sobre el comportamiento de la IA a través de una interfaz de usuario simple, y puedes probar todo sin ningún riesgo.

Automatización de IA fiable para cualquier equipo

Esta referencia de hooks para Claude Code es más que una nueva característica; se trata de un cambio mayor hacia la construcción de sistemas de IA más robustos y fiables. Para los desarrolladores, los hooks son una herramienta fantástica para añadir automatización predecible a los flujos de trabajo de codificación, permitiéndonos superar la naturaleza a veces poco fiable de los prompts.

Pero el principio subyacente es universal. Ya seas un desarrollador creando scripts para un agente de codificación o un líder de soporte configurando un bot de servicio, el objetivo final es el mismo: crear una automatización de IA fiable y personalizable en la que realmente puedas confiar para hacer bien el trabajo.

Si eres un desarrollador, te animo a que empieces a experimentar con los hooks hoy mismo. Pueden mejorar seriamente tu flujo de trabajo. Y si buscas llevar ese mismo nivel de automatización de IA fiable a tu equipo de soporte al cliente, configura tu primer agente de IA con eesel AI en minutos.