Domina los Hooks de Claude Code: Formateo automático, tests automáticos y más

¿Qué son los Hooks?

Los hooks de Claude Code te permiten ejecutar comandos personalizados automáticamente antes o después de acciones específicas. Puedes configurar formateo automático después de guardar archivos, ejecutar tests automáticamente después de cambios en el código, y mucho más.

Los hooks se definen en .claude/settings.json y ejecutan comandos de shell cuando Claude Code realiza ciertas operaciones.

Tipos de Hooks

Claude Code soporta hooks en los siguientes puntos de evento:

Evento del Hook	Cuándo se dispara
PreToolUse	Antes de que se ejecute una herramienta
PostToolUse	Después de que se ejecute una herramienta
Notification	Cuando se envía una notificación
Stop	Cuando Claude Code termina de responder

Configuración básica

Los hooks se definen en el campo hooks de .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
      }
    ]
  }
}

Estructura de la configuración

• matcher: Un patrón regex que coincide con el nombre de la herramienta que activa el hook
• command: El comando de shell a ejecutar

Caso de uso 1: Formateo automático

Ejecutar Prettier automáticamente después de cada edición de archivo:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
      }
    ]
  }
}

Con esta configuración, cada vez que Claude Code crea o edita un archivo, Prettier lo formatea automáticamente. El estilo de código de tu equipo se mantiene consistente sin esfuerzo manual.

Caso de uso 2: Linting automático

Así puedes integrar la corrección automática de ESLint:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      }
    ]
  }
}

El sufijo || true evita que los errores de lint provoquen una falla en el hook, permitiendo que Claude Code continúe procesando.

Caso de uso 3: Tests automáticos al hacer cambios

Ejecutar automáticamente los tests relacionados después de editar archivos y obtener retroalimentación:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx vitest related \"$CLAUDE_FILE_PATH\" --run 2>&1 | tail -20"
      }
    ]
  }
}

La opción related de Vitest ejecuta solo los tests relevantes al archivo modificado, proporcionando retroalimentación mucho más rápida que ejecutar toda la suite de tests.

Caso de uso 4: Verificación automática de tipos

Ejecutar la verificación de tipos de TypeScript después de cambios en archivos:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx tsc --noEmit 2>&1 | head -30"
      }
    ]
  }
}

Caso de uso 5: Bloquear comandos peligrosos

Un hook PreToolUse que previene la ejecución de comandos riesgosos:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|drop table|git push.*force'; then echo 'BLOQUEADO: Comando peligroso detectado' >&2; exit 1; fi"
      }
    ]
  }
}

Cuando el hook termina con código 1, Claude Code omite la ejecución de la herramienta por completo.

Caso de uso 6: Notificaciones al completar

Enviar una notificación cuando Claude Code termine una tarea:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "command": "notify-send 'Claude Code' 'Tarea completada' 2>/dev/null; echo 'Listo'"
      }
    ]
  }
}

En macOS, puedes usar:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "command": "osascript -e 'display notification \"Tarea completada\" with title \"Claude Code\"'"
      }
    ]
  }
}

Combinar múltiples hooks

En proyectos reales, combinar varios hooks es el enfoque más efectivo:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf /'; then exit 1; fi"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      },
      {
        "matcher": "Write|Edit",
        "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "command": "echo '✓ Tarea completada'"
      }
    ]
  }
}

Consejos para escribir hooks

1. Mantén el tiempo de ejecución corto

Los hooks se ejecutan de forma sincrónica, por lo que las operaciones pesadas ralentizarán las respuestas de Claude Code. Usa opciones como related para limitar el alcance de los tests, y head o tail para recortar la salida.

2. Maneja los errores con cuidado

Un hook que termina con un error puede interrumpir el flujo de trabajo de Claude Code. Usa || true y 2>/dev/null para mantener la estabilidad.

3. Usa variables de entorno

Aprovecha las variables de entorno disponibles en los hooks. $CLAUDE_FILE_PATH te da la ruta del archivo sobre el que se está operando.

Conclusión

Los hooks te permiten personalizar ampliamente el flujo de trabajo de Claude Code. La combinación de formateo automático y tests automáticos es especialmente poderosa para mantener la calidad del código. Comienza con el formateo automático de Prettier y expande desde ahí.