Qué son los Code Hooks de Claude y cómo usarlos

Para Vibe Coders, herramientas como Claude Code de Anthropic están transformando la forma en que los desarrolladores escriben, depuran y gestionan sus proyectos. Claude Code actúa como una "herramienta de codificación agéntica" que reside en tu terminal, capaz de entender toda tu base de código, interactuar con tu sistema de archivos, ejecutar comandos e incluso navegar por la web en busca de documentación. Sobresale en tareas como escribir nuevas funcionalidades, corregir errores y refactorizar código mediante indicaciones en lenguaje natural.

Sin embargo, una característica fundamental de los Grandes Modelos de Lenguaje (LLM) es su naturaleza probabilística. Si bien esto permite la resolución creativa de problemas, a veces puede llevar a la imprevisibilidad. Es posible que desees que ciertas acciones —como la verificación de estilo de un archivo después de ser modificado o la ejecución de pruebas después de escribir una nueva función— ocurran siempre sin falta. Depender del LLM para que recuerde hacer esto en cada instancia puede ser inconsistente.

Aquí es donde entran en juego los Ganchos (Hooks) de Claude Code. Los ganchos son una característica poderosa que proporciona un control determinista y programático sobre el comportamiento de Claude Code, asegurando que ciertas acciones siempre ocurran en lugar de depender de que el LLM elija ejecutarlas.

Este artículo sirve como una guía completa para comprender, configurar y aprovechar los Ganchos de Claude Code para crear un flujo de trabajo de desarrollo totalmente automatizado y optimizado.

¿Qué son los Ganchos de Claude Code?

En esencia, los Ganchos de Claude Code son comandos de shell definidos por el usuario que se ejecutan automáticamente en puntos específicos del ciclo de vida de Claude Code. Actúan como disparadores que puedes configurar para que se activen antes o después de ciertas acciones, permitiéndote inyectar tu propia lógica personalizada, scripts y comandos directamente en las operaciones de Claude.

Los ganchos cierran la brecha entre la asistencia impulsada por IA y la automatización basada en reglas. Te permiten aplicar estándares, automatizar tareas repetitivas e integrar herramientas externas sin problemas en tu flujo de trabajo con total fiabilidad.

Hay cuatro eventos clave del ciclo de vida donde se puede activar un gancho:

1. PreToolUse: Se ejecuta antes de que Claude use una herramienta específica (por ejemplo, antes de escribir en un archivo).
2. PostToolUse: Se ejecuta después de que una herramienta se haya utilizado con éxito (por ejemplo, después de que un archivo haya sido modificado).
3. Notification: Se ejecuta cada vez que Claude envía una notificación (por ejemplo, cuando necesita la entrada del usuario o ha completado una tarea larga).
4. Stop: Se ejecuta cuando Claude termina de generar su respuesta y se detiene.

Al apuntar a estos eventos, puedes crear automatizaciones potentes que reflejan las mejores prácticas del desarrollo de software moderno, como las comprobaciones de integración continua (CI), pero a la velocidad del desarrollo local.

La Anatomía de los Ganchos de Claude Code: Una Inmersión Profunda en la Configuración

Para usar los ganchos, necesitas definirlos en el archivo de configuración de Claude Code. Esto se hace añadiendo una tabla [[hooks]] a tu archivo settings.toml, que se encuentra en el directorio .claude/ dentro de tu proyecto. Cada configuración de gancho tiene algunos componentes clave.

# Gancho de ejemplo en .claude/settings.toml

[[hooks]]
# El evento que activa el gancho.
event = "PostToolUse" 

# (Opcional) Condiciones para que se ejecute el gancho.
[hooks.matcher]
tool_name = "edit_file"
file_paths = ["*.py", "api/**/*.py"]

# El comando de shell a ejecutar.
command = "ruff check --fix $CLAUDE_FILE_PATHS && black $CLAUDE_FILE_PATHS"

# (Opcional) Si se ejecuta el comando en segundo plano.
run_in_background = false 

Analicemos cada parte en detalle.

El Campo event en los Ganchos de Claude Code (Obligatorio)

Esta cadena especifica cuál de los cuatro eventos del ciclo de vida activará el gancho.

• "PreToolUse"
• "PostToolUse"
• "Notification"
• "Stop"

El hooks.matcher en los Ganchos de Claude Code (Opcional)

El `matcher` es lo que te permite definir con precisión cuándo debe ejecutarse un gancho. Si omites el `matcher`, el gancho se ejecutará para cada instancia del evento especificado. Por ejemplo, un gancho PostToolUse sin `matcher` se activará después de cada llamada a una herramienta.

El `matcher` tiene tres campos que puedes usar para filtrar eventos:

• tool_name: Una cadena que coincide con el nombre de la herramienta que se está utilizando. Esto es perfecto para apuntar a acciones específicas como edit_file, git_commit o run_command.
• file_paths: Un array de cadenas que contienen patrones glob. El gancho solo se ejecutará si los archivos involucrados en el uso de la herramienta coinciden con uno de estos patrones. Por ejemplo, ["*.py"] apunta a todos los archivos Python, mientras que ["src/components/**/*.jsx"] apunta a archivos JSX en un directorio específico.
• query: Una cadena que coincide con la entrada dada a una herramienta. Esto es útil para disparadores más específicos, como ejecutar un gancho solo cuando se utiliza una herramienta run_command con un comando que incluye npm.

El Campo command para los Ganchos de Claude Code (Obligatorio)

Este es el corazón del gancho: el comando de shell que se ejecutará cuando se cumplan las condiciones del disparador. Este comando se ejecuta con los mismos permisos que tu cuenta de usuario, por lo que puede hacer cualquier cosa que puedas hacer en tu terminal.

Para hacer los comandos dinámicos, Claude Code proporciona un conjunto de variables de entorno que se rellenan con el contexto del evento que activó el gancho.

Variables de Entorno Disponibles:

• $CLAUDE_EVENT_TYPE: El tipo de evento (PreToolUse, PostToolUse, etc.).
• $CLAUDE_TOOL_NAME: El nombre de la herramienta que se utilizó (por ejemplo, edit_file).
• $CLAUDE_TOOL_INPUT: Los parámetros de entrada brutos pasados a la herramienta en formato JSON.
• $CLAUDE_FILE_PATHS: Una lista de rutas de archivo separadas por espacios relevantes para la llamada a la herramienta. Esto es increíblemente útil para pasar archivos a formateadores, linters o ejecutores de pruebas.
• $CLAUDE_NOTIFICATION: El contenido del mensaje de notificación (solo para el evento Notification).
• $CLAUDE_TOOL_OUTPUT: La salida de la ejecución de la herramienta (solo para el evento PostToolUse).

La Configuración run_in_background para los Ganchos de Claude Code (Opcional)

Este es un valor booleano (true o false). Si se establece en true, el comando del gancho se ejecutará en un proceso separado, y Claude no esperará a que se complete antes de continuar. Esto es ideal para tareas de larga duración como suites de pruebas exhaustivas o procesos de construcción que no quieres que bloqueen las acciones subsiguientes de Claude. El valor predeterminado es false.

Casos de Uso Prácticos y Ejemplos para los Ganchos de Claude Code

El verdadero poder de los ganchos se revela cuando los aplicas a flujos de trabajo de desarrollo del mundo real. Aquí tienes algunos ejemplos prácticos para empezar.

1. Linting y Formateo Automático con Ganchos de Claude Code

Aplica un estilo de código consistente en todo tu proyecto de forma automática. Este gancho ejecuta el linter ruff y el formateador black en cualquier archivo Python que Claude edite.

Archivo: .claude/settings.toml

[[hooks]]
event = "PostToolUse"

[hooks.matcher]
tool_name = "edit_file"
file_paths = ["*.py"]

# Comando para verificar el estilo, corregir y formatear los archivos Python editados.
command = "echo 'Running auto-formatter...' && ruff check --fix $CLAUDE_FILE_PATHS && black $CLAUDE_FILE_PATHS"

2. Ejecución Automática de Pruebas con Ganchos de Claude Code

Una práctica fundamental del desarrollo guiado por pruebas (TDD) es escribir pruebas y luego escribir código para que esas pruebas pasen, iterando hasta que todo funcione. Puedes automatizar el paso de "ejecutar pruebas" con un gancho. Este ejemplo ejecuta pytest cada vez que se modifica un archivo en el directorio src/ o tests/.

Archivo: .claude/settings.toml

[[hooks]]
event = "PostToolUse"
run_in_background = true # Las pruebas pueden ser lentas, ejecutar en segundo plano.

[hooks.matcher]
tool_name = "edit_file"
file_paths = ["src/**/*.py", "tests/**/*.py"]

# Comando para ejecutar la suite de pruebas.
command = "pytest"

3. Notificaciones de Escritorio Personalizadas a través de Ganchos de Claude Code

Si le pides a Claude que realice una tarea de larga duración, es posible que te alejes de tu ordenador. Este gancho utiliza una herramienta de línea de comandos como ntfy (un servicio de notificación pub-sub simple basado en HTTP) para enviar una notificación push a tu teléfono o escritorio cuando Claude necesite tu atención.

Archivo: .claude/settings.toml

[[hooks]]
event = "Notification"

# Envía el contenido de la notificación a un tema público de ntfy.sh.
# Puedes alojar el tuyo propio para mayor privacidad.
command = 'ntfy publish my-claude-alerts "$CLAUDE_NOTIFICATION"'

4. Comprobaciones de Cordura Pre-Commit Usando Ganchos de Claude Code

Al igual que los ganchos de Git, puedes usar los Ganchos de Claude Code para asegurar la calidad antes de que se realice un commit. Este ejemplo ejecuta un script personalizado para buscar claves API o realizar otros pasos de validación justo antes de que a Claude se le permita usar la herramienta git_commit.

Archivo: .claude/settings.toml

[[hooks]]
event = "PreToolUse"

[hooks.matcher]
tool_name = "git_commit"

# Comando para ejecutar un script de comprobación pre-commit.
# El script debe salir con un código distinto de cero para detener el commit.
command = "sh ./.claude/pre-commit-checks.sh"

Configuración y Depuración de tus Ganchos de Claude Code

Empezar con los ganchos es sencillo, pero la verificación y la depuración son clave para asegurar que funcionen como se espera.

1. Crea tu Configuración: Asegúrate de tener un archivo .claude/settings.toml en el directorio raíz de tu proyecto. Añade tus configuraciones [[hooks]] allí.
2. Verifica la Configuración: Después de guardar tu archivo settings.toml, ejecuta el comando /hooks dentro de la interfaz de terminal de Claude Code. Este comando especial mostrará tus configuraciones de ganchos cargadas actualmente, permitiéndote ver instantáneamente si Claude las ha analizado correctamente.
3. Busca Errores:

• TOML Inválido: Asegúrate de que tu archivo settings.toml tenga una sintaxis válida. Un corchete o una comilla mal colocados pueden impedir que se cargue.
• Problemas de Comando: Prueba tu command directamente en tu shell para asegurarte de que funciona como se espera. Busca errores tipográficos y asegúrate de que los ejecutables necesarios (black, pytest, ntfy, etc.) estén en el PATH de tu sistema.
• Variables de Depuración: Para ver qué valores contienen las variables de entorno, usa echo para escribirlos en un archivo de registro. Por ejemplo: command = "echo 'Herramienta: $CLAUDE_TOOL_NAME, Archivos: $CLAUDE_FILE_PATHS' >> /tmp/claude_hook.log"

Conclusión: El Poder de los Ganchos de Claude Code

Los Ganchos de Claude Code elevan la herramienta de ser un asistente de codificación altamente capaz a un socio de desarrollo totalmente integrado y determinista. Al definir reglas simples y potentes, puedes automatizar las partes mundanas pero críticas de tu flujo de trabajo, liberándote para concentrarte en los aspectos complejos y creativos de la ingeniería de software. Ya sea para aplicar la calidad del código, simplificar tu ciclo TDD o integrarte con servicios de terceros, los ganchos proporcionan el marco robusto necesario para adaptar Claude Code a tus necesidades exactas.

A medida que te familiarices con las capacidades de Claude Code, comienza con un gancho de formato simple y luego explora automatizaciones más complejas. Rápidamente descubrirás que esta característica es esencial para construir un entorno de desarrollo asistido por IA predecible, eficiente y verdaderamente personalizado.